1 // Created on: 2000-06-15
2 // Created by: Edward AGAPOV
3 // Copyright (c) 2000-2014 OPEN CASCADE SAS
5 // This file is part of Open CASCADE Technology software library.
7 // This library is free software; you can redistribute it and/or modify it under
8 // the terms of the GNU Lesser General Public License version 2.1 as published
9 // by the Free Software Foundation, with special exception defined in the file
10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11 // distribution for complete text of the license and disclaimer of any warranty.
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
16 #ifndef _XCAFDoc_ShapeTool_HeaderFile
17 #define _XCAFDoc_ShapeTool_HeaderFile
19 #include <Standard.hxx>
20 #include <Standard_Type.hxx>
22 #include <XCAFDoc_DataMapOfShapeLabel.hxx>
23 #include <Standard_Boolean.hxx>
24 #include <TDF_Attribute.hxx>
25 #include <TDF_LabelSequence.hxx>
26 #include <Standard_Integer.hxx>
27 #include <Standard_OStream.hxx>
28 #include <TColStd_SequenceOfHAsciiString.hxx>
29 #include <TDF_AttributeSequence.hxx>
30 #include <TopTools_SequenceOfShape.hxx>
34 class TopLoc_Location;
36 class TDF_RelocationTable;
37 class XCAFDoc_GraphNode;
40 class XCAFDoc_ShapeTool;
41 DEFINE_STANDARD_HANDLE(XCAFDoc_ShapeTool, TDF_Attribute)
43 //! A tool to store shapes in an XDE
44 //! document in the form of assembly structure, and to maintain this structure.
45 //! Attribute containing Shapes section of DECAF document.
46 //! Provide tools for management of Shapes section.
47 //! The API provided by this class allows to work with this
48 //! structure regardless of its low-level implementation.
49 //! All the shapes are stored on child labels of a main label which is
50 //! XCAFDoc_DocumentTool::LabelShapes(). The label for assembly also has
51 //! sub-labels, each of which represents the instance of
52 //! another shape in that assembly (component). Such sub-label
53 //! stores reference to the label of the original shape in the form
54 //! of TDataStd_TreeNode with GUID XCAFDoc::ShapeRefGUID(), and its
55 //! location encapsulated into the NamedShape.
56 //! For correct work with an XDE document, it is necessary to use
57 //! methods for analysis and methods for working with shapes.
59 //! if ( STool->IsAssembly(aLabel) )
60 //! { Standard_Boolean subchilds = Standard_False; (default)
61 //! Standard_Integer nbc = STool->NbComponents
62 //! (aLabel[,subchilds]);
64 //! If subchilds is True, commands also consider sub-levels. By
65 //! default, only level one is checked.
66 //! In this example, number of children from the first level of
67 //! assembly will be returned. Methods for creation and initialization:
69 //! XCAFDoc_ShapeTool::XCAFDoc_ShapeTool()
71 //! Standard_GUID GetID ();
72 //! Creation (if does not exist) of ShapeTool on label L:
73 //! Handle(XCAFDoc_ShapeTool) XCAFDoc_ShapeTool::Set(const TDF_Label& L)
74 //! Analyze whether shape is a simple shape or an instance or a
75 //! component of an assembly or it is an assembly ( methods of analysis).
77 //! STool->IsShape(aLabel) ;
78 //! Analyze that the label represents a shape (simple
79 //! shape, assembly or reference) or
80 //! STool->IsTopLevel(aLabel);
81 //! Analyze that the label is a label of a top-level shape.
82 //! Work with simple shapes, assemblies and instances (
83 //! methods for work with shapes).
86 //! Standard_Boolean makeAssembly;
87 //! // True to interpret a Compound as an Assembly, False to take it
89 //! aLabel = STool->AddShape(aShape, makeAssembly);
91 //! TDF_Label aLabel...
92 //! // A label must be present if
93 //! (aLabel.IsNull()) { ... no such label : abandon .. }
94 //! TopoDS_Shape aShape;
95 //! aShape = STool->GetShape(aLabel);
96 //! if (aShape.IsNull())
97 //! { ... this label is not for a Shape ... }
98 //! To get a label from shape.
99 //! Standard_Boolean findInstance = Standard_False;
100 //! (this is default value)
101 //! aLabel = STool->FindShape(aShape [,findInstance]);
102 //! if (aLabel.IsNull())
103 //! { ... no label found for this shape ... }
104 class XCAFDoc_ShapeTool : public TDF_Attribute
110 Standard_EXPORT static const Standard_GUID& GetID();
112 //! Create (if not exist) ShapeTool from XCAFDoc on <L>.
113 Standard_EXPORT static Handle(XCAFDoc_ShapeTool) Set (const TDF_Label& L);
115 //! Creates an empty tool
116 //! Creates a tool to work with a document <Doc>
117 //! Attaches to label XCAFDoc::LabelShapes()
118 Standard_EXPORT XCAFDoc_ShapeTool();
120 //! Returns True if the label is a label of top-level shape,
121 //! as opposed to component of assembly or subshape
122 Standard_EXPORT Standard_Boolean IsTopLevel (const TDF_Label& L) const;
124 //! Returns True if the label is not used by any assembly, i.e.
125 //! contains sublabels which are assembly components
126 //! This is relevant only if IsShape() is True
127 //! (There is no Father TreeNode on this <L>)
128 Standard_EXPORT static Standard_Boolean IsFree (const TDF_Label& L);
130 //! Returns True if the label represents a shape (simple shape,
131 //! assembly or reference)
132 Standard_EXPORT static Standard_Boolean IsShape (const TDF_Label& L);
134 //! Returns True if the label is a label of simple shape
135 Standard_EXPORT static Standard_Boolean IsSimpleShape (const TDF_Label& L);
137 //! Return true if <L> is a located instance of other shape
139 Standard_EXPORT static Standard_Boolean IsReference (const TDF_Label& L);
141 //! Returns True if the label is a label of assembly, i.e.
142 //! contains sublabels which are assembly components
143 //! This is relevant only if IsShape() is True
144 Standard_EXPORT static Standard_Boolean IsAssembly (const TDF_Label& L);
146 //! Return true if <L> is reference serving as component
148 Standard_EXPORT static Standard_Boolean IsComponent (const TDF_Label& L);
150 //! Returns True if the label is a label of compound, i.e.
151 //! contains some sublabels
152 //! This is relevant only if IsShape() is True
153 Standard_EXPORT static Standard_Boolean IsCompound (const TDF_Label& L);
155 //! Return true if <L> is subshape of the top-level shape
156 Standard_EXPORT static Standard_Boolean IsSubShape (const TDF_Label& L);
158 //! Checks whether shape <sub> is subshape of shape stored on
160 Standard_EXPORT Standard_Boolean IsSubShape (const TDF_Label& shapeL, const TopoDS_Shape& sub) const;
162 Standard_EXPORT Standard_Boolean SearchUsingMap (const TopoDS_Shape& S, TDF_Label& L, const Standard_Boolean findWithoutLoc, const Standard_Boolean findSubshape) const;
164 //! General tool to find a (sub) shape in the document
165 //! * If findInstance is True, and S has a non-null location,
166 //! first tries to find the shape among the top-level shapes
167 //! with this location
168 //! * If not found, and findComponent is True, tries to find the shape
169 //! among the components of assemblies
170 //! * If not found, tries to find the shape without location
171 //! among top-level shapes
172 //! * If not found and findSubshape is True, tries to find a
173 //! shape as a subshape of top-level simple shapes
174 //! Returns False if nothing is found
175 Standard_EXPORT Standard_Boolean Search (const TopoDS_Shape& S, TDF_Label& L, const Standard_Boolean findInstance = Standard_True, const Standard_Boolean findComponent = Standard_True, const Standard_Boolean findSubshape = Standard_True) const;
177 //! Returns the label corresponding to shape S
178 //! (searches among top-level shapes, not including subcomponents
179 //! of assemblies and subshapes)
180 //! If findInstance is False (default), seach for the
181 //! input shape without location
182 //! If findInstance is True, searches for the
183 //! input shape as is.
184 //! Return True if <S> is found.
185 Standard_EXPORT Standard_Boolean FindShape (const TopoDS_Shape& S, TDF_Label& L, const Standard_Boolean findInstance = Standard_False) const;
187 //! Does the same as previous method
188 //! Returns Null label if not found
189 Standard_EXPORT TDF_Label FindShape (const TopoDS_Shape& S, const Standard_Boolean findInstance = Standard_False) const;
191 //! To get TopoDS_Shape from shape's label
192 //! For component, returns new shape with correct location
193 //! Returns False if label does not contain shape
194 Standard_EXPORT static Standard_Boolean GetShape (const TDF_Label& L, TopoDS_Shape& S);
196 //! To get TopoDS_Shape from shape's label
197 //! For component, returns new shape with correct location
198 //! Returns Null shape if label does not contain shape
199 Standard_EXPORT static TopoDS_Shape GetShape (const TDF_Label& L);
201 //! Creates new (empty) top-level shape.
202 //! Initially it holds empty TopoDS_Compound
203 Standard_EXPORT TDF_Label NewShape() const;
205 //! Sets representation (TopoDS_Shape) for top-level shape.
206 Standard_EXPORT void SetShape (const TDF_Label& L, const TopoDS_Shape& S);
208 //! Adds a new top-level (creates and returns a new label)
209 //! If makeAssembly is True, treats TopAbs_COMPOUND shapes
210 //! as assemblies (creates assembly structure).
211 //! NOTE: <makePrepare> replace components without location
212 //! in assmebly by located components to avoid some problems.
213 //! If AutoNaming() is True then automatically attaches names.
214 Standard_EXPORT TDF_Label AddShape (const TopoDS_Shape& S, const Standard_Boolean makeAssembly = Standard_True, const Standard_Boolean makePrepare = Standard_True);
216 //! Removes shape (whole label and all its sublabels)
217 //! If removeCompletely is true, removes complete shape
218 //! If removeCompletely is false, removes instance(location) only
219 //! Returns False (and does nothing) if shape is not free
220 //! or is not top-level shape
221 Standard_EXPORT Standard_Boolean RemoveShape (const TDF_Label& L, const Standard_Boolean removeCompletely = Standard_True) const;
223 //! set hasComponents into false
224 Standard_EXPORT void Init();
226 //! Sets auto-naming mode to <V>. If True then for added
227 //! shapes, links, assemblies and SHUO's, the TDataStd_Name attribute
228 //! is automatically added. For shapes it contains a shape type
229 //! (e.g. "SOLID", "SHELL", etc); for links it has a form
230 //! "=>[0:1:1:2]" (where a tag is a label containing a shape
231 //! without a location); for assemblies it is "ASSEMBLY", and
232 //! "SHUO" for SHUO's.
233 //! This setting is global; it cannot be made a member function
234 //! as it is used by static methods as well.
235 //! By default, auto-naming is enabled.
236 //! See also AutoNaming().
237 Standard_EXPORT static void SetAutoNaming (const Standard_Boolean V);
239 //! Returns current auto-naming mode. See SetAutoNaming() for
241 Standard_EXPORT static Standard_Boolean AutoNaming();
244 Standard_EXPORT void ComputeShapes (const TDF_Label& L);
246 //! Compute a sequence of simple shapes
247 Standard_EXPORT void ComputeSimpleShapes();
249 //! Returns a sequence of all top-level shapes
250 Standard_EXPORT void GetShapes (TDF_LabelSequence& Labels) const;
252 //! Returns a sequence of all top-level shapes
253 //! which are free (i.e. not referred by any other)
254 Standard_EXPORT void GetFreeShapes (TDF_LabelSequence& FreeLabels) const;
256 //! Returns list of labels which refer shape L as component
257 //! Returns number of users (0 if shape is free)
258 Standard_EXPORT static Standard_Integer GetUsers (const TDF_Label& L, TDF_LabelSequence& Labels, const Standard_Boolean getsubchilds = Standard_False);
260 //! Returns location of instance
261 Standard_EXPORT static TopLoc_Location GetLocation (const TDF_Label& L);
263 //! Returns label which corresponds to a shape referred by L
264 //! Returns False if label is not reference
265 Standard_EXPORT static Standard_Boolean GetReferredShape (const TDF_Label& L, TDF_Label& Label);
267 //! Returns number of Assembles components
268 Standard_EXPORT static Standard_Integer NbComponents (const TDF_Label& L, const Standard_Boolean getsubchilds = Standard_False);
270 //! Returns list of components of assembly
271 //! Returns False if label is not assembly
272 Standard_EXPORT static Standard_Boolean GetComponents (const TDF_Label& L, TDF_LabelSequence& Labels, const Standard_Boolean getsubchilds = Standard_False);
274 //! Adds a component given by its label and location to the assembly
275 //! Note: assembly must be IsAssembly() or IsSimpleShape()
276 Standard_EXPORT TDF_Label AddComponent (const TDF_Label& assembly, const TDF_Label& comp, const TopLoc_Location& Loc);
278 //! Adds a shape (located) as a component to the assembly
279 //! If necessary, creates an additional top-level shape for
280 //! component and return the Label of component.
281 //! If expand is True and component is Compound, it will
282 //! be created as assembly also
283 //! Note: assembly must be IsAssembly() or IsSimpleShape()
284 Standard_EXPORT TDF_Label AddComponent (const TDF_Label& assembly, const TopoDS_Shape& comp, const Standard_Boolean expand = Standard_False);
286 //! Removes a component from its assembly
287 Standard_EXPORT void RemoveComponent (const TDF_Label& comp) const;
289 //! Top-down update for all assembly compounds stored in the document.
290 Standard_EXPORT void UpdateAssemblies();
292 //! Finds a label for subshape <sub> of shape stored on
294 //! Returns Null label if it is not found
295 Standard_EXPORT Standard_Boolean FindSubShape (const TDF_Label& shapeL, const TopoDS_Shape& sub, TDF_Label& L) const;
297 //! Adds a label for subshape <sub> of shape stored on
299 //! Returns Null label if it is not subshape
300 Standard_EXPORT TDF_Label AddSubShape (const TDF_Label& shapeL, const TopoDS_Shape& sub) const;
302 //! Adds (of finds already existed) a label for subshape <sub> of shape stored on
303 //! label shapeL. Label addedSubShapeL returns added (found) label or empty in case of wrong subshape.
304 //! Returns True, if new shape was added, False in case of already existed subshape/wrong subshape
305 Standard_EXPORT Standard_Boolean AddSubShape(const TDF_Label& shapeL, const TopoDS_Shape& sub, TDF_Label& addedSubShapeL) const;
307 Standard_EXPORT TDF_Label FindMainShapeUsingMap (const TopoDS_Shape& sub) const;
309 //! Performs a search among top-level shapes to find
310 //! the shape containing <sub> as subshape
311 //! Checks only simple shapes, and returns the first found
312 //! label (which should be the only one for valid model)
313 Standard_EXPORT TDF_Label FindMainShape (const TopoDS_Shape& sub) const;
315 //! Returns list of labels identifying subshapes of the given shape
316 //! Returns False if no subshapes are placed on that label
317 Standard_EXPORT static Standard_Boolean GetSubShapes (const TDF_Label& L, TDF_LabelSequence& Labels);
319 //! returns the label under which shapes are stored
320 Standard_EXPORT TDF_Label BaseLabel() const;
322 Standard_EXPORT Standard_OStream& Dump (Standard_OStream& theDumpLog, const Standard_Boolean deep) const;
324 Standard_EXPORT virtual Standard_OStream& Dump (Standard_OStream& theDumpLog) const Standard_OVERRIDE;
326 //! Print to std::ostream <theDumpLog> type of shape found on <L> label
327 //! and the entry of <L>, with <level> tabs before.
328 //! If <deep>, print also TShape and Location addresses
329 Standard_EXPORT static void DumpShape (Standard_OStream& theDumpLog, const TDF_Label& L, const Standard_Integer level = 0, const Standard_Boolean deep = Standard_False);
331 Standard_EXPORT const Standard_GUID& ID() const Standard_OVERRIDE;
333 Standard_EXPORT void Restore (const Handle(TDF_Attribute)& with) Standard_OVERRIDE;
335 Standard_EXPORT Handle(TDF_Attribute) NewEmpty() const Standard_OVERRIDE;
337 Standard_EXPORT void Paste (const Handle(TDF_Attribute)& into, const Handle(TDF_RelocationTable)& RT) const Standard_OVERRIDE;
339 //! Returns True if the label is a label of external references, i.e.
340 //! there are some reference on the no-step files, which are
341 //! described in document only their names
342 Standard_EXPORT static Standard_Boolean IsExternRef (const TDF_Label& L);
344 //! Sets the names of references on the no-step files
345 Standard_EXPORT TDF_Label SetExternRefs (const TColStd_SequenceOfHAsciiString& SHAS) const;
347 //! Sets the names of references on the no-step files
348 Standard_EXPORT void SetExternRefs (const TDF_Label& L, const TColStd_SequenceOfHAsciiString& SHAS) const;
350 //! Gets the names of references on the no-step files
351 Standard_EXPORT static void GetExternRefs (const TDF_Label& L, TColStd_SequenceOfHAsciiString& SHAS);
353 //! Sets the SHUO structure between upper_usage and next_usage
354 //! create multy-level (if number of labels > 2) SHUO from first to last
355 //! Initialise out <MainSHUOAttr> by main upper_usage SHUO attribute.
356 //! Returns FALSE if some of labels in not component label
357 Standard_EXPORT Standard_Boolean SetSHUO (const TDF_LabelSequence& Labels, Handle(XCAFDoc_GraphNode)& MainSHUOAttr) const;
359 //! Returns founded SHUO GraphNode attribute <aSHUOAttr>
360 //! Returns false in other case
361 Standard_EXPORT static Standard_Boolean GetSHUO (const TDF_Label& SHUOLabel, Handle(XCAFDoc_GraphNode)& aSHUOAttr);
363 //! Returns founded SHUO GraphNodes of indicated component
364 //! Returns false in other case
365 Standard_EXPORT static Standard_Boolean GetAllComponentSHUO (const TDF_Label& CompLabel, TDF_AttributeSequence& SHUOAttrs);
367 //! Returns the sequence of labels of SHUO attributes,
368 //! which is upper_usage for this next_usage SHUO attribute
369 //! (that indicated by label)
370 //! NOTE: returns upper_usages only on one level (not recurse)
371 //! NOTE: do not clear the sequence before filling
372 Standard_EXPORT static Standard_Boolean GetSHUOUpperUsage (const TDF_Label& NextUsageL, TDF_LabelSequence& Labels);
374 //! Returns the sequence of labels of SHUO attributes,
375 //! which is next_usage for this upper_usage SHUO attribute
376 //! (that indicated by label)
377 //! NOTE: returns next_usages only on one level (not recurse)
378 //! NOTE: do not clear the sequence before filling
379 Standard_EXPORT static Standard_Boolean GetSHUONextUsage (const TDF_Label& UpperUsageL, TDF_LabelSequence& Labels);
381 //! Remove SHUO from component sublabel,
382 //! remove all dependencies on other SHUO.
383 //! Returns FALSE if cannot remove SHUO dependencies.
384 //! NOTE: remove any styles that associated with this SHUO.
385 Standard_EXPORT Standard_Boolean RemoveSHUO (const TDF_Label& SHUOLabel) const;
387 //! Serach the path of labels in the document,
388 //! that corresponds the component from any assembly
389 //! Try to search the sequence of labels with location that
390 //! produce this shape as component of any assembly
391 //! NOTE: Clear sequence of labels before filling
392 Standard_EXPORT Standard_Boolean FindComponent (const TopoDS_Shape& theShape, TDF_LabelSequence& Labels) const;
394 //! Search for the component shape that styled by shuo
395 //! Returns null shape if no any shape is found.
396 Standard_EXPORT TopoDS_Shape GetSHUOInstance (const Handle(XCAFDoc_GraphNode)& theSHUO) const;
398 //! Search for the component shape by labelks path
399 //! and set SHUO structure for founded label structure
400 //! Returns null attribute if no component in any assembly found.
401 Standard_EXPORT Handle(XCAFDoc_GraphNode) SetInstanceSHUO (const TopoDS_Shape& theShape) const;
403 //! Seaching for component shapes that styled by shuo
404 //! Returns empty sequence of shape if no any shape is found.
405 Standard_EXPORT Standard_Boolean GetAllSHUOInstances (const Handle(XCAFDoc_GraphNode)& theSHUO, TopTools_SequenceOfShape& theSHUOShapeSeq) const;
407 //! Searchs the SHUO by labels of components
408 //! from upper_usage componet to next_usage
409 //! Returns null attribute if no SHUO found
410 Standard_EXPORT static Standard_Boolean FindSHUO (const TDF_LabelSequence& Labels, Handle(XCAFDoc_GraphNode)& theSHUOAttr);
412 //! Convert Shape (compound/compsolid/shell/wire) to assembly
413 Standard_EXPORT Standard_Boolean Expand (const TDF_Label& Shape) ;
416 DEFINE_STANDARD_RTTIEXT(XCAFDoc_ShapeTool,TDF_Attribute)
425 //! Checks recursively if the given assembly item is modified. If so, its
426 //! associated compound is updated. Returns true if the assembly item is
427 //! modified, false -- otherwise.
428 Standard_EXPORT Standard_Boolean updateComponent(const TDF_Label& theAssmLabel,
429 TopoDS_Shape& theUpdatedShape) const;
431 //! Adds a new top-level (creates and returns a new label)
432 //! For internal use. Used by public method AddShape.
433 Standard_EXPORT TDF_Label addShape (const TopoDS_Shape& S, const Standard_Boolean makeAssembly = Standard_True);
435 //! Makes a shape on label L to be a reference to shape refL
436 //! with location loc
437 Standard_EXPORT static void MakeReference (const TDF_Label& L, const TDF_Label& refL, const TopLoc_Location& loc);
439 //! Auxiliary method for Expand
440 //! Add declared under expanded theMainShapeL subshapes to new part label thePart
441 //! Recursively iterate all subshapes of shape from thePart, current shape to iterate its subshapes is theShape.
442 Standard_EXPORT void makeSubShape(const TDF_Label& theMainShapeL, const TDF_Label& thePart, const TopoDS_Shape& theShape, const TopLoc_Location& theLoc);
444 XCAFDoc_DataMapOfShapeLabel myShapeLabels;
445 XCAFDoc_DataMapOfShapeLabel mySubShapes;
446 XCAFDoc_DataMapOfShapeLabel mySimpleShapes;
447 Standard_Boolean hasSimpleShapes;
458 #endif // _XCAFDoc_ShapeTool_HeaderFile