0025076: Hidden overloaded virtual functions
[occt.git] / src / XCAFDoc / XCAFDoc_ShapeTool.hxx
1 // Created on: 2000-06-15
2 // Created by: Edward AGAPOV
3 // Copyright (c) 2000-2014 OPEN CASCADE SAS
4 //
5 // This file is part of Open CASCADE Technology software library.
6 //
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.
12 //
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
15
16 #ifndef _XCAFDoc_ShapeTool_HeaderFile
17 #define _XCAFDoc_ShapeTool_HeaderFile
18
19 #include <Standard.hxx>
20 #include <Standard_Type.hxx>
21
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>
31 class Standard_GUID;
32 class TDF_Label;
33 class TopoDS_Shape;
34 class TopLoc_Location;
35 class TDF_Attribute;
36 class TDF_RelocationTable;
37 class XCAFDoc_GraphNode;
38
39
40 class XCAFDoc_ShapeTool;
41 DEFINE_STANDARD_HANDLE(XCAFDoc_ShapeTool, TDF_Attribute)
42
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.
58 //! For example:
59 //! if ( STool->IsAssembly(aLabel) )
60 //! { Standard_Boolean subchilds = Standard_False; (default)
61 //! Standard_Integer nbc = STool->NbComponents
62 //! (aLabel[,subchilds]);
63 //! }
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:
68 //! Constructor:
69 //! XCAFDoc_ShapeTool::XCAFDoc_ShapeTool()
70 //! Getting a guid:
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).
76 //! For example:
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).
84 //! For example:
85 //! Add shape:
86 //! Standard_Boolean makeAssembly;
87 //! // True to interpret a Compound as an Assembly, False to take it
88 //! as a whole
89 //! aLabel = STool->AddShape(aShape, makeAssembly);
90 //! Get shape:
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
105 {
106
107 public:
108
109   
110   Standard_EXPORT static const Standard_GUID& GetID();
111   
112   //! Create (if not exist) ShapeTool from XCAFDoc on <L>.
113   Standard_EXPORT static Handle(XCAFDoc_ShapeTool) Set (const TDF_Label& L);
114   
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();
119   
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;
123   
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);
129   
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);
133   
134   //! Returns True if the label is a label of simple shape
135   Standard_EXPORT static Standard_Boolean IsSimpleShape (const TDF_Label& L);
136   
137   //! Return true if <L> is a located instance of other shape
138   //! i.e. reference
139   Standard_EXPORT static Standard_Boolean IsReference (const TDF_Label& L);
140   
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);
145   
146   //! Return true if <L> is reference serving as component
147   //! of assembly
148   Standard_EXPORT static Standard_Boolean IsComponent (const TDF_Label& L);
149   
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);
154   
155   //! Return true if <L> is subshape of the top-level shape
156   Standard_EXPORT static Standard_Boolean IsSubShape (const TDF_Label& L);
157   
158   //! Checks whether shape <sub> is subshape of shape stored on
159   //! label shapeL
160   Standard_EXPORT Standard_Boolean IsSubShape (const TDF_Label& shapeL, const TopoDS_Shape& sub) const;
161   
162   Standard_EXPORT Standard_Boolean SearchUsingMap (const TopoDS_Shape& S, TDF_Label& L, const Standard_Boolean findWithoutLoc, const Standard_Boolean findSubshape) const;
163   
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;
176   
177   //! Returns the label corresponding to shape S
178   //! (searches among top-level shapes, not including subcomponents
179   //! of assemblies)
180   //! If findInstance is False (default), searches for the
181   //! non-located shape (i.e. among original shapes)
182   //! If findInstance is True, searches for the shape with the same
183   //! location, including shape instances
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;
186   
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;
190   
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);
195   
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);
200   
201   //! Creates new (empty) top-level shape.
202   //! Initially it holds empty TopoDS_Compound
203   Standard_EXPORT TDF_Label NewShape() const;
204   
205   //! Sets representation (TopoDS_Shape) for top-level shape.
206   //! If S has location(location.IsIdentity() is false),
207   //! command will be skipped. Sub-shapes of S which is
208   //! subshape of old shape, will be stored ( all atributes will be stored).
209   //! If a sub-label of L is not a sub-shape of the new shape,
210   //! it will be removed.
211   Standard_EXPORT void SetShape (const TDF_Label& L, const TopoDS_Shape& S);
212   
213   //! Adds a new top-level (creates and returns a new label)
214   //! If makeAssembly is True, treats TopAbs_COMPOUND shapes
215   //! as assemblies (creates assembly structure).
216   //! NOTE: <makePrepare> replace components without location
217   //! in assmebly by located components to avoid some problems.
218   //! If AutoNaming() is True then automatically attaches names.
219   Standard_EXPORT TDF_Label AddShape (const TopoDS_Shape& S, const Standard_Boolean makeAssembly = Standard_True, const Standard_Boolean makePrepare = Standard_True);
220   
221   //! Removes shape (whole label and all its sublabels)
222   //! If removeCompletely is true, removes complete shape
223   //! If removeCompletely is false, removes instance(location) only
224   //! Returns False (and does nothing) if shape is not free
225   //! or is not top-level shape
226   Standard_EXPORT Standard_Boolean RemoveShape (const TDF_Label& L, const Standard_Boolean removeCompletely = Standard_True) const;
227   
228   //! set hasComponents into false
229   Standard_EXPORT void Init();
230   
231   //! Sets auto-naming mode to <V>. If True then for added
232   //! shapes, links, assemblies and SHUO's, the TDataStd_Name attribute
233   //! is automatically added. For shapes it contains a shape type
234   //! (e.g. "SOLID", "SHELL", etc); for links it has a form
235   //! "=>[0:1:1:2]" (where a tag is a label containing a shape
236   //! without a location); for assemblies it is "ASSEMBLY", and
237   //! "SHUO" for SHUO's.
238   //! This setting is global; it cannot be made a member function
239   //! as it is used by static methods as well.
240   //! By default, auto-naming is enabled.
241   //! See also AutoNaming().
242   Standard_EXPORT static void SetAutoNaming (const Standard_Boolean V);
243   
244   //! Returns current auto-naming mode. See SetAutoNaming() for
245   //! description.
246   Standard_EXPORT static Standard_Boolean AutoNaming();
247   
248   //! recursive
249   Standard_EXPORT void ComputeShapes (const TDF_Label& L);
250   
251   //! Compute a sequence of simple shapes
252   Standard_EXPORT void ComputeSimpleShapes();
253   
254   //! Returns a sequence of all top-level shapes
255   Standard_EXPORT void GetShapes (TDF_LabelSequence& Labels) const;
256   
257   //! Returns a sequence of all top-level shapes
258   //! which are free (i.e. not referred by any other)
259   Standard_EXPORT void GetFreeShapes (TDF_LabelSequence& FreeLabels) const;
260   
261   //! Returns list of labels which refer shape L as component
262   //! Returns number of users (0 if shape is free)
263   Standard_EXPORT static Standard_Integer GetUsers (const TDF_Label& L, TDF_LabelSequence& Labels, const Standard_Boolean getsubchilds = Standard_False);
264   
265   //! Returns location of instance
266   Standard_EXPORT static TopLoc_Location GetLocation (const TDF_Label& L);
267   
268   //! Returns label which corresponds to a shape referred by L
269   //! Returns False if label is not reference
270   Standard_EXPORT static Standard_Boolean GetReferredShape (const TDF_Label& L, TDF_Label& Label);
271   
272   //! Returns number of Assembles components
273   Standard_EXPORT static Standard_Integer NbComponents (const TDF_Label& L, const Standard_Boolean getsubchilds = Standard_False);
274   
275   //! Returns list of components of assembly
276   //! Returns False if label is not assembly
277   Standard_EXPORT static Standard_Boolean GetComponents (const TDF_Label& L, TDF_LabelSequence& Labels, const Standard_Boolean getsubchilds = Standard_False);
278   
279   //! Adds a component given by its label and location to the assembly
280   //! Note: assembly must be IsAssembly() or IsSimpleShape()
281   Standard_EXPORT TDF_Label AddComponent (const TDF_Label& assembly, const TDF_Label& comp, const TopLoc_Location& Loc) const;
282   
283   //! Adds a shape (located) as a component to the assembly
284   //! If necessary, creates an additional top-level shape for
285   //! component and return the Label of component.
286   //! If expand is True and component is Compound, it will
287   //! be created as assembly also
288   //! Note: assembly must be IsAssembly() or IsSimpleShape()
289   Standard_EXPORT TDF_Label AddComponent (const TDF_Label& assembly, const TopoDS_Shape& comp, const Standard_Boolean expand = Standard_False);
290   
291   //! Removes a component from its assembly
292   Standard_EXPORT void RemoveComponent (const TDF_Label& comp) const;
293   
294   //! Update labels associated with Label <L>
295   Standard_EXPORT void UpdateAssociatedAssembly (const TDF_Label& L) const;
296   
297   //! Update an assembly at label <L>
298   Standard_EXPORT void UpdateAssembly (const TDF_Label& L) const;
299   
300   //! Finds a label for subshape <sub> of shape stored on
301   //! label shapeL
302   //! Returns Null label if it is not found
303   Standard_EXPORT Standard_Boolean FindSubShape (const TDF_Label& shapeL, const TopoDS_Shape& sub, TDF_Label& L) const;
304   
305   //! Adds a label for subshape <sub> of shape stored on
306   //! label shapeL
307   //! Returns Null label if it is not subshape
308   Standard_EXPORT TDF_Label AddSubShape (const TDF_Label& shapeL, const TopoDS_Shape& sub) const;
309   
310   Standard_EXPORT TDF_Label FindMainShapeUsingMap (const TopoDS_Shape& sub) const;
311   
312   //! Performs a search among top-level shapes to find
313   //! the shape containing <sub> as subshape
314   //! Checks only simple shapes, and returns the first found
315   //! label (which should be the only one for valid model)
316   Standard_EXPORT TDF_Label FindMainShape (const TopoDS_Shape& sub) const;
317   
318   //! Returns list of labels identifying subshapes of the given shape
319   //! Returns False if no subshapes are placed on that label
320   Standard_EXPORT static Standard_Boolean GetSubShapes (const TDF_Label& L, TDF_LabelSequence& Labels);
321   
322   //! returns the label under which shapes are stored
323   Standard_EXPORT TDF_Label BaseLabel() const;
324   
325   Standard_EXPORT Standard_OStream& Dump (Standard_OStream& theDumpLog, const Standard_Boolean deep) const;
326
327   Standard_EXPORT virtual Standard_OStream& Dump (Standard_OStream& theDumpLog) const Standard_OVERRIDE;
328
329   //! Print to ostream <theDumpLog> type of shape found on <L> label
330   //! and the entry of <L>, with <level> tabs before.
331   //! If <deep>, print also TShape and Location addresses
332   Standard_EXPORT static void DumpShape (Standard_OStream& theDumpLog, const TDF_Label& L, const Standard_Integer level = 0, const Standard_Boolean deep = Standard_False);
333   
334   Standard_EXPORT const Standard_GUID& ID() const Standard_OVERRIDE;
335   
336   Standard_EXPORT void Restore (const Handle(TDF_Attribute)& with) Standard_OVERRIDE;
337   
338   Standard_EXPORT Handle(TDF_Attribute) NewEmpty() const Standard_OVERRIDE;
339   
340   Standard_EXPORT void Paste (const Handle(TDF_Attribute)& into, const Handle(TDF_RelocationTable)& RT) const Standard_OVERRIDE;
341   
342   //! Returns True if the label is a label of external references, i.e.
343   //! there are some reference on the no-step files, which are
344   //! described in document only their names
345   Standard_EXPORT static Standard_Boolean IsExternRef (const TDF_Label& L);
346   
347   //! Sets the names of references on the no-step files
348   Standard_EXPORT TDF_Label SetExternRefs (const TColStd_SequenceOfHAsciiString& SHAS) const;
349   
350   //! Sets the names of references on the no-step files
351   Standard_EXPORT void SetExternRefs (const TDF_Label& L, const TColStd_SequenceOfHAsciiString& SHAS) const;
352   
353   //! Gets the names of references on the no-step files
354   Standard_EXPORT static void GetExternRefs (const TDF_Label& L, TColStd_SequenceOfHAsciiString& SHAS);
355   
356   //! Sets the SHUO structure between upper_usage and next_usage
357   //! create multy-level (if number of labels > 2) SHUO from first to last
358   //! Initialise out <MainSHUOAttr> by main upper_usage SHUO attribute.
359   //! Returns FALSE if some of labels in not component label
360   Standard_EXPORT Standard_Boolean SetSHUO (const TDF_LabelSequence& Labels, Handle(XCAFDoc_GraphNode)& MainSHUOAttr) const;
361   
362   //! Returns founded SHUO GraphNode attribute <aSHUOAttr>
363   //! Returns false in other case
364   Standard_EXPORT static Standard_Boolean GetSHUO (const TDF_Label& SHUOLabel, Handle(XCAFDoc_GraphNode)& aSHUOAttr);
365   
366   //! Returns founded SHUO GraphNodes of indicated component
367   //! Returns false in other case
368   Standard_EXPORT static Standard_Boolean GetAllComponentSHUO (const TDF_Label& CompLabel, TDF_AttributeSequence& SHUOAttrs);
369   
370   //! Returns the sequence of labels of SHUO attributes,
371   //! which is upper_usage for this next_usage SHUO attribute
372   //! (that indicated by label)
373   //! NOTE: returns upper_usages only on one level (not recurse)
374   //! NOTE: do not clear the sequence before filling
375   Standard_EXPORT static Standard_Boolean GetSHUOUpperUsage (const TDF_Label& NextUsageL, TDF_LabelSequence& Labels);
376   
377   //! Returns the sequence of labels of SHUO attributes,
378   //! which is next_usage for this upper_usage SHUO attribute
379   //! (that indicated by label)
380   //! NOTE: returns next_usages only on one level (not recurse)
381   //! NOTE: do not clear the sequence before filling
382   Standard_EXPORT static Standard_Boolean GetSHUONextUsage (const TDF_Label& UpperUsageL, TDF_LabelSequence& Labels);
383   
384   //! Remove SHUO from component sublabel,
385   //! remove all dependencies on other SHUO.
386   //! Returns FALSE if cannot remove SHUO dependencies.
387   //! NOTE: remove any styles that associated with this SHUO.
388   Standard_EXPORT Standard_Boolean RemoveSHUO (const TDF_Label& SHUOLabel) const;
389   
390   //! Serach the path of labels in the document,
391   //! that corresponds the component from any assembly
392   //! Try to search the sequence of labels with location that
393   //! produce this shape as component of any assembly
394   //! NOTE: Clear sequence of labels before filling
395   Standard_EXPORT Standard_Boolean FindComponent (const TopoDS_Shape& theShape, TDF_LabelSequence& Labels) const;
396   
397   //! Search for the component shape that styled by shuo
398   //! Returns null shape if no any shape is found.
399   Standard_EXPORT TopoDS_Shape GetSHUOInstance (const Handle(XCAFDoc_GraphNode)& theSHUO) const;
400   
401   //! Search for the component shape by labelks path
402   //! and set SHUO structure for founded label structure
403   //! Returns null attribute if no component in any assembly found.
404   Standard_EXPORT Handle(XCAFDoc_GraphNode) SetInstanceSHUO (const TopoDS_Shape& theShape) const;
405   
406   //! Seaching for component shapes that styled by shuo
407   //! Returns empty sequence of shape if no any shape is found.
408   Standard_EXPORT Standard_Boolean GetAllSHUOInstances (const Handle(XCAFDoc_GraphNode)& theSHUO, TopTools_SequenceOfShape& theSHUOShapeSeq) const;
409   
410   //! Searchs the SHUO by labels of components
411   //! from upper_usage componet to next_usage
412   //! Returns null attribute if no SHUO found
413   Standard_EXPORT static Standard_Boolean FindSHUO (const TDF_LabelSequence& Labels, Handle(XCAFDoc_GraphNode)& theSHUOAttr);
414   
415   //! Convert Shape (compound) to assembly
416   Standard_EXPORT Standard_Boolean Expand (const TDF_Label& Shape) ;
417
418     //! Make subshape for Part from Shape
419   Standard_EXPORT void makeSubShape (const TDF_Label& Part, const TopoDS_Shape& Shape) ;
420
421
422
423   DEFINE_STANDARD_RTTIEXT(XCAFDoc_ShapeTool,TDF_Attribute)
424
425 protected:
426
427
428
429
430 private:
431
432   
433   //! Adds a new top-level (creates and returns a new label)
434   //! For internal use. Used by public method AddShape.
435   Standard_EXPORT TDF_Label addShape (const TopoDS_Shape& S, const Standard_Boolean makeAssembly = Standard_True);
436   
437   //! Makes a shape on label L to be a reference to shape refL
438   //! with location loc
439   Standard_EXPORT static void MakeReference (const TDF_Label& L, const TDF_Label& refL, const TopLoc_Location& loc);
440
441   XCAFDoc_DataMapOfShapeLabel myShapeLabels;
442   XCAFDoc_DataMapOfShapeLabel mySubShapes;
443   XCAFDoc_DataMapOfShapeLabel mySimpleShapes;
444   Standard_Boolean hasSimpleShapes;
445
446
447 };
448
449
450
451
452
453
454
455 #endif // _XCAFDoc_ShapeTool_HeaderFile