1 -- Created on: 2000-06-15
2 -- Created by: Edward AGAPOV
3 -- Copyright (c) 2000-2012 OPEN CASCADE SAS
5 -- The content of this file is subject to the Open CASCADE Technology Public
6 -- License Version 6.5 (the "License"). You may not use the content of this file
7 -- except in compliance with the License. Please obtain a copy of the License
8 -- at http://www.opencascade.org and read it completely before using this file.
10 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
11 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
13 -- The Original Code and all software distributed under the License is
14 -- distributed on an "AS IS" basis, without warranty of any kind, and the
15 -- Initial Developer hereby disclaims all such warranties, including without
16 -- limitation, any warranties of merchantability, fitness for a particular
17 -- purpose or non-infringement. Please see the License for the specific terms
18 -- and conditions governing the rights and limitations under the License.
22 class ShapeTool from XCAFDoc inherits Attribute from TDF
24 ---Purpose: A tool to store shapes in an XDE
25 -- document in the form of assembly structure, and to maintain this structure.
26 -- The API provided by this class allows to work with this
27 -- structure regardless of its low-level implementation.
28 -- All the shapes are stored on child labels of a main label which is
29 -- XCAFDoc_DocumentTool::LabelShapes(). The label for assembly also has
30 -- sub-labels, each of which represents the instance of
31 -- another shape in that assembly (component). Such sub-label
32 -- stores reference to the label of the original shape in the form
33 -- of TDataStd_TreeNode with GUID XCAFDoc::ShapeRefGUID(), and its
34 -- location encapsulated into the NamedShape.
35 -- For correct work with an XDE document, it is necessary to use
36 -- methods for analysis and methods for working with shapes.
38 -- if ( STool->IsAssembly(aLabel) )
39 -- { Standard_Boolean subchilds = Standard_False; (default)
40 -- Standard_Integer nbc = STool->NbComponents
41 -- (aLabel[,subchilds]);
43 -- If subchilds is True, commands also consider sub-levels. By
44 -- default, only level one is checked.
45 -- In this example, number of children from the first level of
46 -- assembly will be returned. Methods for creation and initialization:
48 -- XCAFDoc_ShapeTool::XCAFDoc_ShapeTool()
50 -- Standard_GUID GetID ();
51 -- Creation (if does not exist) of ShapeTool on label L:
52 -- Handle(XCAFDoc_ShapeTool) XCAFDoc_ShapeTool::Set(const TDF_Label& L)
53 -- Analyze whether shape is a simple shape or an instance or a
54 -- component of an assembly or it is an assembly ( methods of analysis).
56 -- STool->IsShape(aLabel) ;
57 -- Analyze that the label represents a shape (simple
58 -- shape, assembly or reference) or
59 -- STool->IsTopLevel(aLabel);
60 -- Analyze that the label is a label of a top-level shape.
61 -- Work with simple shapes, assemblies and instances (
62 -- methods for work with shapes).
65 -- Standard_Boolean makeAssembly;
66 -- // True to interpret a Compound as an Assembly, False to take it
68 -- aLabel = STool->AddShape(aShape, makeAssembly);
70 -- TDF_Label aLabel...
71 -- // A label must be present if
72 -- (aLabel.IsNull()) { ... no such label : abandon .. }
73 -- TopoDS_Shape aShape;
74 -- aShape = STool->GetShape(aLabel);
75 -- if (aShape.IsNull())
76 -- { ... this label is not for a Shape ... }
77 -- To get a label from shape.
78 -- Standard_Boolean findInstance = Standard_False;
79 -- (this is default value)
80 -- aLabel = STool->FindShape(aShape [,findInstance]);
81 -- if (aLabel.IsNull())
82 -- { ... no label found for this shape ... }
85 Document from TDocStd,
86 TreeNode from TDataStd,
89 LabelSequence from TDF,
92 SequenceOfShape from TopTools,
93 HAsciiString from TCollection,
94 RelocationTable from TDF,
95 SequenceOfHAsciiString from TColStd,
96 GraphNode from XCAFDoc,
97 AttributeSequence from TDF,
98 DataMapOfShapeLabel from XCAFDoc
102 ---C++: return const &
103 returns GUID from Standard;
106 Set (myclass; L : Label from TDF) returns ShapeTool from XCAFDoc;
107 ---Purpose: Create (if not exist) ShapeTool from XCAFDoc on <L>.
112 Create returns ShapeTool from XCAFDoc;
113 ---Purpose: Creates an empty tool
115 --Create (Doc: Document from TDocStd) returns ShapeTool from XCAFDoc;
116 ---Purpose: Creates a tool to work with a document <Doc>
117 -- Attaches to label XCAFDoc::LabelShapes()
123 IsTopLevel (me; L: Label from TDF) returns Boolean;
124 ---Purpose: Returns True if the label is a label of top-level shape,
125 -- as opposed to component of assembly or subshape
127 IsFree (myclass; L: Label from TDF) returns Boolean;
128 ---Purpose: Returns True if the label is not used by any assembly, i.e.
129 -- contains sublabels which are assembly components
130 -- This is relevant only if IsShape() is True
131 -- (There is no Father TreeNode on this <L>)
133 IsShape (myclass; L: Label from TDF) returns Boolean;
134 ---Purpose: Returns True if the label represents a shape (simple shape,
135 -- assembly or reference)
137 IsSimpleShape (myclass; L: Label from TDF) returns Boolean;
138 ---Purpose: Returns True if the label is a label of simple shape
140 IsReference (myclass; L: Label from TDF) returns Boolean;
141 ---Purpose: Return true if <L> is a located instance of other shape
144 IsAssembly (myclass; L: Label from TDF) returns Boolean;
145 ---Purpose: Returns True if the label is a label of assembly, i.e.
146 -- contains sublabels which are assembly components
147 -- This is relevant only if IsShape() is True
149 IsComponent (myclass; L: Label from TDF) returns Boolean;
150 ---Purpose: Return true if <L> is reference serving as component
153 IsCompound (myclass; L: Label from TDF) returns Boolean;
154 ---Purpose: Returns True if the label is a label of compound, i.e.
155 -- contains some sublabels
156 -- This is relevant only if IsShape() is True
158 IsSubShape (myclass; L: Label from TDF) returns Boolean;
159 ---Purpose: Return true if <L> is subshape of the top-level shape
161 IsSubShape (me; shapeL: Label from TDF;
162 sub: Shape from TopoDS)
164 ---Purpose: Checks whether shape <sub> is subshape of shape stored on
167 ---API: Work with top-level structure of shapes
169 SearchUsingMap (me; S: Shape from TopoDS; L: out Label from TDF;
170 findWithoutLoc: Boolean; findSubshape: Boolean)
171 returns Boolean from Standard;
173 Search (me; S: Shape from TopoDS; L: out Label from TDF;
174 findInstance: Boolean = Standard_True;
175 findComponent: Boolean = Standard_True;
176 findSubshape: Boolean = Standard_True)
177 returns Boolean from Standard;
178 ---Purpose: General tool to find a (sub) shape in the document
179 -- * If findInstance is True, and S has a non-null location,
180 -- first tries to find the shape among the top-level shapes
181 -- with this location
182 -- * If not found, and findComponent is True, tries to find the shape
183 -- among the components of assemblies
184 -- * If not found, tries to find the shape without location
185 -- among top-level shapes
186 -- * If not found and findSubshape is True, tries to find a
187 -- shape as a subshape of top-level simple shapes
188 -- Returns False if nothing is found
190 FindShape (me; S: Shape from TopoDS; L: out Label from TDF;
191 findInstance: Boolean = Standard_False)
192 returns Boolean from Standard;
193 ---Purpose: Returns the label corresponding to shape S
194 -- (searches among top-level shapes, not including subcomponents
196 -- If findInstance is False (default), searches for the
197 -- non-located shape (i.e. among original shapes)
198 -- If findInstance is True, searches for the shape with the same
199 -- location, including shape instances
200 -- Return True if <S> is found.
202 FindShape (me; S: Shape from TopoDS;
203 findInstance: Boolean = Standard_False)
204 returns Label from TDF;
205 ---Purpose: Does the same as previous method
206 -- Returns Null label if not found
208 GetShape (myclass; L: Label from TDF;
209 S: out Shape from TopoDS) returns Boolean from Standard;
210 ---Purpose: To get TopoDS_Shape from shape's label
211 -- For component, returns new shape with correct location
212 -- Returns False if label does not contain shape
214 GetShape (myclass; L: Label from TDF) returns Shape from TopoDS;
215 ---Purpose: To get TopoDS_Shape from shape's label
216 -- For component, returns new shape with correct location
217 -- Returns Null shape if label does not contain shape
219 NewShape (me) returns Label from TDF;
220 ---Purpose: Creates new (empty) top-level shape.
221 -- Initially it holds empty TopoDS_Compound
223 SetShape (me:mutable; L: Label from TDF; S: Shape from TopoDS);
224 ---Purpose: Sets representation (TopoDS_Shape) for top-level shape
226 AddShape (me:mutable; S: Shape from TopoDS;
227 makeAssembly: Boolean = Standard_True;
228 makePrepare : Boolean = Standard_True)
229 returns Label from TDF;
230 ---Purpose: Adds a new top-level (creates and returns a new label)
231 -- If makeAssembly is True, treats TopAbs_COMPOUND shapes
232 -- as assemblies (creates assembly structure).
233 -- NOTE: <makePrepare> replace components without location
234 -- in assmebly by located components to avoid some problems.
236 addShape (me:mutable; S: Shape from TopoDS;
237 makeAssembly: Boolean = Standard_True)
238 returns Label from TDF is private;
239 ---Purpose: Adds a new top-level (creates and returns a new label)
240 -- For internal use. Used by public method AddShape.
242 RemoveShape (me; L: Label from TDF) returns Boolean;
243 ---Purpose: Removes shape (whole label and all its sublabels)
244 -- Returns False (and does nothing) if shape is not free
245 -- or is not top-level shape
248 ---Purpose: set hasComponents into false
250 ComputeShapes (me: mutable; L: Label from TDF);
251 ---Purpose: recursive
253 ComputeSimpleShapes (me: mutable);
254 ---Purpose: Compute a sequence of simple shapes
256 GetShapes (me; Labels: out LabelSequence from TDF);
257 ---Purpose: Returns a sequence of all top-level shapes
259 GetFreeShapes (me; FreeLabels : out LabelSequence from TDF);
260 ---Purpose: Returns a sequence of all top-level shapes
261 -- which are free (i.e. not referred by any other)
263 GetUsers (myclass; L: Label from TDF;
264 Labels : out LabelSequence from TDF;
265 getsubchilds: Boolean from Standard = Standard_False)
267 ---Purpose: Returns list of labels which refer shape L as component
268 -- Returns number of users (0 if shape is free)
270 GetLocation (myclass; L: Label from TDF)
271 returns Location from TopLoc;
272 ---Purpose: Returns location of instance
274 GetReferredShape (myclass; L: Label from TDF;
275 Label: out Label from TDF)
277 ---Purpose: Returns label which corresponds to a shape referred by L
278 -- Returns False if label is not reference
280 ---API: Work with assembly structure
282 NbComponents (myclass; L: Label from TDF;
283 getsubchilds: Boolean from Standard = Standard_False)
285 ---Purpose: Returns number of Assembles components
287 GetComponents (myclass; L: Label from TDF;
288 Labels : out LabelSequence from TDF;
289 getsubchilds: Boolean from Standard = Standard_False)
291 ---Purpose: Returns list of components of assembly
292 -- Returns False if label is not assembly
294 AddComponent (me; assembly, comp: Label from TDF;
295 Loc: Location from TopLoc)
296 returns Label from TDF;
297 ---Purpose: Adds a component given by its label and location to the assembly
298 -- Note: assembly must be IsAssembly() or IsSimpleShape()
300 AddComponent (me:mutable; assembly: Label from TDF;
301 comp: Shape from TopoDS; expand: Boolean = Standard_False)
302 returns Label from TDF;
303 ---Purpose: Adds a shape (located) as a component to the assembly
304 -- If necessary, creates an additional top-level shape for
305 -- component and return the Label of component.
306 -- If expand is True and component is Compound, it will
307 -- be created as assembly also
308 -- Note: assembly must be IsAssembly() or IsSimpleShape()
310 RemoveComponent (me; comp: Label from TDF);
311 ---Purpose: Removes a component from its assembly
313 UpdateAssembly (me; L: Label from TDF);
314 ---Purpose: Update an assembly at label <L>
316 ---API: work with sub-shapes of shape
318 FindSubShape (me; shapeL: Label from TDF;
319 sub: Shape from TopoDS;
320 L: out Label from TDF)
322 ---Purpose: Finds a label for subshape <sub> of shape stored on
324 -- Returns Null label if it is not found
326 AddSubShape (me; shapeL: Label from TDF;
327 sub: Shape from TopoDS)
328 returns Label from TDF;
329 ---Purpose: Adds a label for subshape <sub> of shape stored on
331 -- Returns Null label if it is not subshape
333 FindMainShapeUsingMap (me; sub: Shape from TopoDS)
334 returns Label from TDF;
336 FindMainShape (me; sub: Shape from TopoDS)
337 returns Label from TDF;
338 ---Purpose: Performs a search among top-level shapes to find
339 -- the shape containing <sub> as subshape
340 -- Checks only simple shapes, and returns the first found
341 -- label (which should be the only one for valid model)
343 GetSubShapes (myclass; L: Label from TDF;
344 Labels : out LabelSequence from TDF)
346 ---Purpose: Returns list of labels identifying subshapes of the given shape
347 -- Returns False if no subshapes are placed on that label
351 BaseLabel(me) returns Label from TDF;
352 ---Purpose: returns the label under which shapes are stored
354 Dump(me; deep : Boolean from Standard = Standard_False);
356 DumpShape(myclass; L: Label from TDF;
357 level :Integer from Standard = 0;
358 deep : Boolean from Standard = Standard_False);
359 ---Purpose: Print in cout type of shape found on <L> label
360 -- and the entry of <L>, with <level> tabs before.
361 -- If <deep>, print also TShape and Location addresses
365 MakeReference (myclass; L, refL: Label from TDF; loc: Location from TopLoc)
367 ---Purpose: Makes a shape on label L to be a reference to shape refL
371 ---Category: TDF_Attribute methods
372 -- =====================
375 ---C++: return const &
376 returns GUID from Standard;
378 Restore (me: mutable; with : Attribute from TDF);
381 returns mutable Attribute from TDF;
383 Paste (me; into : mutable Attribute from TDF;
384 RT : mutable RelocationTable from TDF);
386 IsExternRef (myclass; L: Label from TDF) returns Boolean;
387 ---Purpose: Returns True if the label is a label of external references, i.e.
388 -- there are some reference on the no-step files, which are
389 -- described in document only their names
391 SetExternRefs (me; SHAS: SequenceOfHAsciiString from TColStd) returns Label from TDF;
392 ---Purpose: Sets the names of references on the no-step files
394 SetExternRefs (me; L: Label from TDF; SHAS: SequenceOfHAsciiString from TColStd);
395 ---Purpose: Sets the names of references on the no-step files
397 GetExternRefs (myclass; L: Label from TDF; SHAS: in out SequenceOfHAsciiString from TColStd);
398 ---Purpose: Gets the names of references on the no-step files
400 ---API: Work with SHUO (Specified Higher Usage Occurrance) structure
402 SetSHUO (me; Labels : LabelSequence from TDF;
403 MainSHUOAttr : in out GraphNode from XCAFDoc)
405 ---Purpose: Sets the SHUO structure between upper_usage and next_usage
406 -- create multy-level (if number of labels > 2) SHUO from first to last
407 -- Initialise out <MainSHUOAttr> by main upper_usage SHUO attribute.
408 -- Returns FALSE if some of labels in not component label
410 GetSHUO (myclass; SHUOLabel : Label from TDF;
411 aSHUOAttr : in out GraphNode from XCAFDoc)
413 ---Purpose: Returns founded SHUO GraphNode attribute <aSHUOAttr>
414 -- Returns false in other case
416 GetAllComponentSHUO (myclass; CompLabel : Label from TDF;
417 SHUOAttrs : in out AttributeSequence from TDF)
419 ---Purpose: Returns founded SHUO GraphNodes of indicated component
420 -- Returns false in other case
422 GetSHUOUpperUsage (myclass; NextUsageL: Label from TDF;
423 Labels : out LabelSequence from TDF)
425 ---Purpose: Returns the sequence of labels of SHUO attributes,
426 -- which is upper_usage for this next_usage SHUO attribute
427 -- (that indicated by label)
428 -- NOTE: returns upper_usages only on one level (not recurse)
429 -- NOTE: do not clear the sequence before filling
431 GetSHUONextUsage (myclass; UpperUsageL: Label from TDF;
432 Labels : out LabelSequence from TDF)
434 ---Purpose: Returns the sequence of labels of SHUO attributes,
435 -- which is next_usage for this upper_usage SHUO attribute
436 -- (that indicated by label)
437 -- NOTE: returns next_usages only on one level (not recurse)
438 -- NOTE: do not clear the sequence before filling
440 RemoveSHUO (me; SHUOLabel : Label from TDF)
442 ---Purpose: Remove SHUO from component sublabel,
443 -- remove all dependencies on other SHUO.
444 -- Returns FALSE if cannot remove SHUO dependencies.
445 -- NOTE: remove any styles that associated with this SHUO.
447 FindComponent (me; theShape : Shape from TopoDS;
448 Labels : out LabelSequence from TDF)
450 ---Purpose: Serach the path of labels in the document,
451 -- that corresponds the component from any assembly
452 -- Try to search the sequence of labels with location that
453 -- produce this shape as component of any assembly
454 -- NOTE: Clear sequence of labels before filling
456 GetSHUOInstance (me; theSHUO : GraphNode from XCAFDoc)
457 returns Shape from TopoDS;
458 ---Purpose: Search for the component shape that styled by shuo
459 -- Returns null shape if no any shape is found.
461 SetInstanceSHUO (me; theShape : Shape from TopoDS)
462 returns GraphNode from XCAFDoc;
463 ---Purpose: Search for the component shape by labelks path
464 -- and set SHUO structure for founded label structure
465 -- Returns null attribute if no component in any assembly found.
467 GetAllSHUOInstances (me; theSHUO : GraphNode from XCAFDoc;
468 theSHUOShapeSeq : in out SequenceOfShape from TopTools)
469 returns Boolean from Standard;
470 ---Purpose: Seaching for component shapes that styled by shuo
471 -- Returns empty sequence of shape if no any shape is found.
473 FindSHUO (myclass; Labels : LabelSequence from TDF;
474 theSHUOAttr : in out GraphNode from XCAFDoc)
475 returns Boolean from Standard;
476 ---Purpose: Searchs the SHUO by labels of components
477 -- from upper_usage componet to next_usage
478 -- Returns null attribute if no SHUO found
481 myShapeLabels : DataMapOfShapeLabel from XCAFDoc; --skl 15.10.2003
482 mySubShapes : DataMapOfShapeLabel from XCAFDoc;
483 mySimpleShapes : DataMapOfShapeLabel from XCAFDoc;
484 hasSimpleShapes : Boolean from Standard;