7fd59977 |
1 | -- File: XCAFDoc_ShapeTool.cdl |
2 | -- Created: Thu Jun 15 17:25:45 2000 |
3 | -- Author: Edward AGAPOV |
4 | -- <eap@strelox.nnov.matra-dtv.fr> |
5 | ---Copyright: Matra Datavision 2000 |
6 | |
7 | |
8 | class ShapeTool from XCAFDoc inherits Attribute from TDF |
9 | |
10 | ---Purpose: A tool to store shapes in an XDE |
11 | -- document in the form of assembly structure, and to maintain this structure. |
12 | -- The API provided by this class allows to work with this |
13 | -- structure regardless of its low-level implementation. |
14 | -- All the shapes are stored on child labels of a main label which is |
15 | -- XCAFDoc_DocumentTool::LabelShapes(). The label for assembly also has |
16 | -- sub-labels, each of which represents the instance of |
17 | -- another shape in that assembly (component). Such sub-label |
18 | -- stores reference to the label of the original shape in the form |
19 | -- of TDataStd_TreeNode with GUID XCAFDoc::ShapeRefGUID(), and its |
20 | -- location encapsulated into the NamedShape. |
21 | -- For correct work with an XDE document, it is necessary to use |
22 | -- methods for analysis and methods for working with shapes. |
23 | -- For example: |
24 | -- if ( STool->IsAssembly(aLabel) ) |
25 | -- { Standard_Boolean subchilds = Standard_False; (default) |
26 | -- Standard_Integer nbc = STool->NbComponents |
27 | -- (aLabel[,subchilds]); |
28 | -- } |
29 | -- If subchilds is True, commands also consider sub-levels. By |
30 | -- default, only level one is checked. |
31 | -- In this example, number of children from the first level of |
32 | -- assembly will be returned. Methods for creation and initialization: |
33 | -- Constructor: |
34 | -- XCAFDoc_ShapeTool::XCAFDoc_ShapeTool() |
35 | -- Getting a guid: |
36 | -- Standard_GUID GetID (); |
37 | -- Creation (if does not exist) of ShapeTool on label L: |
38 | -- Handle(XCAFDoc_ShapeTool) XCAFDoc_ShapeTool::Set(const TDF_Label& L) |
39 | -- Analyze whether shape is a simple shape or an instance or a |
40 | -- component of an assembly or it is an assembly ( methods of analysis). |
41 | -- For example: |
42 | -- STool->IsShape(aLabel) ; |
43 | -- Analyze that the label represents a shape (simple |
44 | -- shape, assembly or reference) or |
45 | -- STool->IsTopLevel(aLabel); |
46 | -- Analyze that the label is a label of a top-level shape. |
47 | -- Work with simple shapes, assemblies and instances ( |
48 | -- methods for work with shapes). |
49 | -- For example: |
50 | -- Add shape: |
51 | -- Standard_Boolean makeAssembly; |
52 | -- // True to interpret a Compound as an Assembly, False to take it |
53 | -- as a whole |
54 | -- aLabel = STool->AddShape(aShape, makeAssembly); |
55 | -- Get shape: |
56 | -- TDF_Label aLabel... |
57 | -- // A label must be present if |
58 | -- (aLabel.IsNull()) { ... no such label : abandon .. } |
59 | -- TopoDS_Shape aShape; |
60 | -- aShape = STool->GetShape(aLabel); |
61 | -- if (aShape.IsNull()) |
62 | -- { ... this label is not for a Shape ... } |
63 | -- To get a label from shape. |
64 | -- Standard_Boolean findInstance = Standard_False; |
65 | -- (this is default value) |
66 | -- aLabel = STool->FindShape(aShape [,findInstance]); |
67 | -- if (aLabel.IsNull()) |
68 | -- { ... no label found for this shape ... } |
69 | |
70 | uses |
71 | Document from TDocStd, |
72 | TreeNode from TDataStd, |
73 | Location from TopLoc, |
74 | Label from TDF, |
75 | LabelSequence from TDF, |
76 | LabelMap from TDF, |
77 | Shape from TopoDS, |
78 | SequenceOfShape from TopTools, |
79 | HAsciiString from TCollection, |
80 | RelocationTable from TDF, |
81 | SequenceOfHAsciiString from TColStd, |
82 | GraphNode from XCAFDoc, |
83 | AttributeSequence from TDF, |
84 | DataMapOfShapeLabel from XCAFDoc |
85 | |
86 | is |
87 | GetID (myclass) |
88 | ---C++: return const & |
89 | returns GUID from Standard; |
90 | |
91 | |
92 | Set (myclass; L : Label from TDF) returns ShapeTool from XCAFDoc; |
93 | ---Purpose: Create (if not exist) ShapeTool from XCAFDoc on <L>. |
94 | |
95 | |
96 | |
97 | |
98 | Create returns ShapeTool from XCAFDoc; |
99 | ---Purpose: Creates an empty tool |
100 | |
101 | --Create (Doc: Document from TDocStd) returns ShapeTool from XCAFDoc; |
102 | ---Purpose: Creates a tool to work with a document <Doc> |
103 | -- Attaches to label XCAFDoc::LabelShapes() |
104 | |
105 | |
106 | |
107 | ---API: Analysis |
108 | |
109 | IsTopLevel (me; L: Label from TDF) returns Boolean; |
110 | ---Purpose: Returns True if the label is a label of top-level shape, |
111 | -- as opposed to component of assembly or subshape |
112 | |
113 | IsFree (myclass; L: Label from TDF) returns Boolean; |
114 | ---Purpose: Returns True if the label is not used by any assembly, i.e. |
115 | -- contains sublabels which are assembly components |
116 | -- This is relevant only if IsShape() is True |
117 | -- (There is no Father TreeNode on this <L>) |
118 | |
119 | IsShape (myclass; L: Label from TDF) returns Boolean; |
120 | ---Purpose: Returns True if the label represents a shape (simple shape, |
121 | -- assembly or reference) |
122 | |
123 | IsSimpleShape (myclass; L: Label from TDF) returns Boolean; |
124 | ---Purpose: Returns True if the label is a label of simple shape |
125 | |
126 | IsReference (myclass; L: Label from TDF) returns Boolean; |
127 | ---Purpose: Return true if <L> is a located instance of other shape |
128 | -- i.e. reference |
129 | |
130 | IsAssembly (myclass; L: Label from TDF) returns Boolean; |
131 | ---Purpose: Returns True if the label is a label of assembly, i.e. |
132 | -- contains sublabels which are assembly components |
133 | -- This is relevant only if IsShape() is True |
134 | |
135 | IsComponent (myclass; L: Label from TDF) returns Boolean; |
136 | ---Purpose: Return true if <L> is reference serving as component |
137 | -- of assembly |
138 | |
139 | IsCompound (myclass; L: Label from TDF) returns Boolean; |
140 | ---Purpose: Returns True if the label is a label of compound, i.e. |
141 | -- contains some sublabels |
142 | -- This is relevant only if IsShape() is True |
143 | |
144 | IsSubShape (myclass; L: Label from TDF) returns Boolean; |
145 | ---Purpose: Return true if <L> is subshape of the top-level shape |
146 | |
147 | IsSubShape (me; shapeL: Label from TDF; |
148 | sub: Shape from TopoDS) |
149 | returns Boolean; |
150 | ---Purpose: Checks whether shape <sub> is subshape of shape stored on |
151 | -- label shapeL |
152 | |
153 | ---API: Work with top-level structure of shapes |
154 | |
155 | SearchUsingMap (me; S: Shape from TopoDS; L: out Label from TDF; |
156 | findWithoutLoc: Boolean; findSubshape: Boolean) |
157 | returns Boolean from Standard; |
158 | |
159 | Search (me; S: Shape from TopoDS; L: out Label from TDF; |
160 | findInstance: Boolean = Standard_True; |
161 | findComponent: Boolean = Standard_True; |
162 | findSubshape: Boolean = Standard_True) |
163 | returns Boolean from Standard; |
164 | ---Purpose: 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 | |
176 | FindShape (me; S: Shape from TopoDS; L: out Label from TDF; |
177 | findInstance: Boolean = Standard_False) |
178 | returns Boolean from Standard; |
179 | ---Purpose: Returns the label corresponding to shape S |
180 | -- (searches among top-level shapes, not including subcomponents |
181 | -- of assemblies) |
182 | -- If findInstance is False (default), searches for the |
183 | -- non-located shape (i.e. among original shapes) |
184 | -- If findInstance is True, searches for the shape with the same |
185 | -- location, including shape instances |
186 | -- Return True if <S> is found. |
187 | |
188 | FindShape (me; S: Shape from TopoDS; |
189 | findInstance: Boolean = Standard_False) |
190 | returns Label from TDF; |
191 | ---Purpose: Does the same as previous method |
192 | -- Returns Null label if not found |
193 | |
194 | GetShape (myclass; L: Label from TDF; |
195 | S: out Shape from TopoDS) returns Boolean from Standard; |
196 | ---Purpose: To get TopoDS_Shape from shape's label |
197 | -- For component, returns new shape with correct location |
198 | -- Returns False if label does not contain shape |
199 | |
200 | GetShape (myclass; L: Label from TDF) returns Shape from TopoDS; |
201 | ---Purpose: To get TopoDS_Shape from shape's label |
202 | -- For component, returns new shape with correct location |
203 | -- Returns Null shape if label does not contain shape |
204 | |
205 | NewShape (me) returns Label from TDF; |
206 | ---Purpose: Creates new (empty) top-level shape. |
207 | -- Initially it holds empty TopoDS_Compound |
208 | |
209 | SetShape (me:mutable; L: Label from TDF; S: Shape from TopoDS); |
210 | ---Purpose: Sets representation (TopoDS_Shape) for top-level shape |
211 | |
212 | AddShape (me:mutable; S: Shape from TopoDS; |
213 | makeAssembly: Boolean = Standard_True; |
214 | makePrepare : Boolean = Standard_True) |
215 | returns Label from TDF; |
216 | ---Purpose: Adds a new top-level (creates and returns a new label) |
217 | -- If makeAssembly is True, treats TopAbs_COMPOUND shapes |
218 | -- as assemblies (creates assembly structure). |
219 | -- NOTE: <makePrepare> replace components without location |
220 | -- in assmebly by located components to avoid some problems. |
221 | |
222 | addShape (me:mutable; S: Shape from TopoDS; |
223 | makeAssembly: Boolean = Standard_True) |
224 | returns Label from TDF is private; |
225 | ---Purpose: Adds a new top-level (creates and returns a new label) |
226 | -- For internal use. Used by public method AddShape. |
227 | |
228 | RemoveShape (me; L: Label from TDF) returns Boolean; |
229 | ---Purpose: Removes shape (whole label and all its sublabels) |
230 | -- Returns False (and does nothing) if shape is not free |
231 | -- or is not top-level shape |
232 | |
233 | Init (me: mutable); |
234 | ---Purpose: set hasComponents into false |
235 | |
236 | ComputeShapes (me: mutable; L: Label from TDF); |
237 | ---Purpose: recursive |
238 | |
239 | ComputeSimpleShapes (me: mutable); |
240 | ---Purpose: Compute a sequence of simple shapes |
241 | |
242 | GetShapes (me; Labels: out LabelSequence from TDF); |
243 | ---Purpose: Returns a sequence of all top-level shapes |
244 | |
245 | GetFreeShapes (me; FreeLabels : out LabelSequence from TDF); |
246 | ---Purpose: Returns a sequence of all top-level shapes |
247 | -- which are free (i.e. not referred by any other) |
248 | |
249 | GetUsers (myclass; L: Label from TDF; |
250 | Labels : out LabelSequence from TDF; |
251 | getsubchilds: Boolean from Standard = Standard_False) |
252 | returns Integer; |
253 | ---Purpose: Returns list of labels which refer shape L as component |
254 | -- Returns number of users (0 if shape is free) |
255 | |
256 | GetLocation (myclass; L: Label from TDF) |
257 | returns Location from TopLoc; |
258 | ---Purpose: Returns location of instance |
259 | |
260 | GetReferredShape (myclass; L: Label from TDF; |
261 | Label: out Label from TDF) |
262 | returns Boolean; |
263 | ---Purpose: Returns label which corresponds to a shape referred by L |
264 | -- Returns False if label is not reference |
265 | |
266 | ---API: Work with assembly structure |
267 | |
268 | NbComponents (myclass; L: Label from TDF; |
269 | getsubchilds: Boolean from Standard = Standard_False) |
270 | returns Integer; |
271 | ---Purpose: Returns number of Assembles components |
272 | |
273 | GetComponents (myclass; L: Label from TDF; |
274 | Labels : out LabelSequence from TDF; |
275 | getsubchilds: Boolean from Standard = Standard_False) |
276 | returns Boolean; |
277 | ---Purpose: Returns list of components of assembly |
278 | -- Returns False if label is not assembly |
279 | |
280 | AddComponent (me; assembly, comp: Label from TDF; |
281 | Loc: Location from TopLoc) |
282 | returns Label from TDF; |
283 | ---Purpose: Adds a component given by its label and location to the assembly |
284 | -- Note: assembly must be IsAssembly() or IsSimpleShape() |
285 | |
286 | AddComponent (me:mutable; assembly: Label from TDF; |
287 | comp: Shape from TopoDS; expand: Boolean = Standard_False) |
288 | returns Label from TDF; |
289 | ---Purpose: Adds a shape (located) as a component to the assembly |
290 | -- If necessary, creates an additional top-level shape for |
291 | -- component and return the Label of component. |
292 | -- If expand is True and component is Compound, it will |
293 | -- be created as assembly also |
294 | -- Note: assembly must be IsAssembly() or IsSimpleShape() |
295 | |
296 | RemoveComponent (me; comp: Label from TDF); |
297 | ---Purpose: Removes a component from its assembly |
298 | |
299 | UpdateAssembly (me; L: Label from TDF); |
300 | ---Purpose: Update an assembly at label <L> |
301 | |
302 | ---API: work with sub-shapes of shape |
303 | |
304 | FindSubShape (me; shapeL: Label from TDF; |
305 | sub: Shape from TopoDS; |
306 | L: out Label from TDF) |
307 | returns Boolean; |
308 | ---Purpose: Finds a label for subshape <sub> of shape stored on |
309 | -- label shapeL |
310 | -- Returns Null label if it is not found |
311 | |
312 | AddSubShape (me; shapeL: Label from TDF; |
313 | sub: Shape from TopoDS) |
314 | returns Label from TDF; |
315 | ---Purpose: Adds a label for subshape <sub> of shape stored on |
316 | -- label shapeL |
317 | -- Returns Null label if it is not subshape |
318 | |
319 | FindMainShapeUsingMap (me; sub: Shape from TopoDS) |
320 | returns Label from TDF; |
321 | |
322 | FindMainShape (me; sub: Shape from TopoDS) |
323 | returns Label from TDF; |
324 | ---Purpose: Performs a search among top-level shapes to find |
325 | -- the shape containing <sub> as subshape |
326 | -- Checks only simple shapes, and returns the first found |
327 | -- label (which should be the only one for valid model) |
328 | |
329 | GetSubShapes (myclass; L: Label from TDF; |
330 | Labels : out LabelSequence from TDF) |
331 | returns Boolean; |
332 | ---Purpose: Returns list of labels identifying subshapes of the given shape |
333 | -- Returns False if no subshapes are placed on that label |
334 | |
335 | ---API: Auxiliary |
336 | |
337 | BaseLabel(me) returns Label from TDF; |
338 | ---Purpose: returns the label under which shapes are stored |
339 | |
340 | Dump(me; deep : Boolean from Standard = Standard_False); |
341 | |
342 | DumpShape(myclass; L: Label from TDF; |
343 | level :Integer from Standard = 0; |
344 | deep : Boolean from Standard = Standard_False); |
345 | ---Purpose: Print in cout type of shape found on <L> label |
346 | -- and the entry of <L>, with <level> tabs before. |
347 | -- If <deep>, print also TShape and Location addresses |
348 | |
349 | --- Private |
350 | |
351 | MakeReference (myclass; L, refL: Label from TDF; loc: Location from TopLoc) |
352 | is private; |
353 | ---Purpose: Makes a shape on label L to be a reference to shape refL |
354 | -- with location loc |
355 | |
356 | |
357 | ---Category: TDF_Attribute methods |
358 | -- ===================== |
359 | |
360 | ID (me) |
361 | ---C++: return const & |
362 | returns GUID from Standard; |
363 | |
364 | Restore (me: mutable; with : Attribute from TDF); |
365 | |
366 | NewEmpty (me) |
367 | returns mutable Attribute from TDF; |
368 | |
369 | Paste (me; into : mutable Attribute from TDF; |
370 | RT : mutable RelocationTable from TDF); |
371 | |
372 | IsExternRef (myclass; L: Label from TDF) returns Boolean; |
373 | ---Purpose: Returns True if the label is a label of external references, i.e. |
374 | -- there are some reference on the no-step files, which are |
375 | -- described in document only their names |
376 | |
377 | SetExternRefs (me; SHAS: SequenceOfHAsciiString from TColStd) returns Label from TDF; |
378 | ---Purpose: Sets the names of references on the no-step files |
379 | |
380 | SetExternRefs (me; L: Label from TDF; SHAS: SequenceOfHAsciiString from TColStd); |
381 | ---Purpose: Sets the names of references on the no-step files |
382 | |
383 | GetExternRefs (myclass; L: Label from TDF; SHAS: in out SequenceOfHAsciiString from TColStd); |
384 | ---Purpose: Gets the names of references on the no-step files |
385 | |
386 | ---API: Work with SHUO (Specified Higher Usage Occurrance) structure |
387 | |
388 | SetSHUO (me; Labels : LabelSequence from TDF; |
389 | MainSHUOAttr : in out GraphNode from XCAFDoc) |
390 | returns Boolean; |
391 | ---Purpose: Sets the SHUO structure between upper_usage and next_usage |
392 | -- create multy-level (if number of labels > 2) SHUO from first to last |
393 | -- Initialise out <MainSHUOAttr> by main upper_usage SHUO attribute. |
394 | -- Returns FALSE if some of labels in not component label |
395 | |
396 | GetSHUO (myclass; SHUOLabel : Label from TDF; |
397 | aSHUOAttr : in out GraphNode from XCAFDoc) |
398 | returns Boolean; |
399 | ---Purpose: Returns founded SHUO GraphNode attribute <aSHUOAttr> |
400 | -- Returns false in other case |
401 | |
402 | GetAllComponentSHUO (myclass; CompLabel : Label from TDF; |
403 | SHUOAttrs : in out AttributeSequence from TDF) |
404 | returns Boolean; |
405 | ---Purpose: Returns founded SHUO GraphNodes of indicated component |
406 | -- Returns false in other case |
407 | |
408 | GetSHUOUpperUsage (myclass; NextUsageL: Label from TDF; |
409 | Labels : out LabelSequence from TDF) |
410 | returns Boolean; |
411 | ---Purpose: Returns the sequence of labels of SHUO attributes, |
412 | -- which is upper_usage for this next_usage SHUO attribute |
413 | -- (that indicated by label) |
414 | -- NOTE: returns upper_usages only on one level (not recurse) |
415 | -- NOTE: do not clear the sequence before filling |
416 | |
417 | GetSHUONextUsage (myclass; UpperUsageL: Label from TDF; |
418 | Labels : out LabelSequence from TDF) |
419 | returns Boolean; |
420 | ---Purpose: Returns the sequence of labels of SHUO attributes, |
421 | -- which is next_usage for this upper_usage SHUO attribute |
422 | -- (that indicated by label) |
423 | -- NOTE: returns next_usages only on one level (not recurse) |
424 | -- NOTE: do not clear the sequence before filling |
425 | |
426 | RemoveSHUO (me; SHUOLabel : Label from TDF) |
427 | returns Boolean; |
428 | ---Purpose: Remove SHUO from component sublabel, |
429 | -- remove all dependencies on other SHUO. |
430 | -- Returns FALSE if cannot remove SHUO dependencies. |
431 | -- NOTE: remove any styles that associated with this SHUO. |
432 | |
433 | FindComponent (me; theShape : Shape from TopoDS; |
434 | Labels : out LabelSequence from TDF) |
435 | returns Boolean; |
436 | ---Purpose: Serach the path of labels in the document, |
437 | -- that corresponds the component from any assembly |
438 | -- Try to search the sequence of labels with location that |
439 | -- produce this shape as component of any assembly |
440 | -- NOTE: Clear sequence of labels before filling |
441 | |
442 | GetSHUOInstance (me; theSHUO : GraphNode from XCAFDoc) |
443 | returns Shape from TopoDS; |
444 | ---Purpose: Search for the component shape that styled by shuo |
445 | -- Returns null shape if no any shape is found. |
446 | |
447 | SetInstanceSHUO (me; theShape : Shape from TopoDS) |
448 | returns GraphNode from XCAFDoc; |
449 | ---Purpose: Search for the component shape by labelks path |
450 | -- and set SHUO structure for founded label structure |
451 | -- Returns null attribute if no component in any assembly found. |
452 | |
453 | GetAllSHUOInstances (me; theSHUO : GraphNode from XCAFDoc; |
454 | theSHUOShapeSeq : in out SequenceOfShape from TopTools) |
455 | returns Boolean from Standard; |
456 | ---Purpose: Seaching for component shapes that styled by shuo |
457 | -- Returns empty sequence of shape if no any shape is found. |
458 | |
459 | FindSHUO (myclass; Labels : LabelSequence from TDF; |
460 | theSHUOAttr : in out GraphNode from XCAFDoc) |
461 | returns Boolean from Standard; |
462 | ---Purpose: Searchs the SHUO by labels of components |
463 | -- from upper_usage componet to next_usage |
464 | -- Returns null attribute if no SHUO found |
465 | |
466 | fields |
467 | myShapeLabels : DataMapOfShapeLabel from XCAFDoc; --skl 15.10.2003 |
468 | mySubShapes : DataMapOfShapeLabel from XCAFDoc; |
469 | mySimpleShapes : DataMapOfShapeLabel from XCAFDoc; |
470 | hasSimpleShapes : Boolean from Standard; |
471 | |
472 | end ShapeTool; |