0024784: Move documentation in CDL files to proper location
[occt.git] / src / TNaming / TNaming.cdl
CommitLineData
b311480e 1-- Created on: 1997-03-17
2-- Created by: Yves FRICAUD
3-- Copyright (c) 1997-1999 Matra Datavision
973c2be1 4-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e 5--
973c2be1 6-- This file is part of Open CASCADE Technology software library.
b311480e 7--
d5f74e42 8-- This library is free software; you can redistribute it and/or modify it under
9-- the terms of the GNU Lesser General Public License version 2.1 as published
973c2be1 10-- by the Free Software Foundation, with special exception defined in the file
11-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12-- distribution for complete text of the license and disclaimer of any warranty.
b311480e 13--
973c2be1 14-- Alternatively, this file may be used under the terms of Open CASCADE
15-- commercial license or contractual agreement.
7fd59977 16
17package TNaming
18
19 ---Purpose: A topological attribute can be seen as a hook
20 -- into the topological structure. To this hook,
21 -- data can be attached and references defined.
22 -- It is used for keeping and access to
23 -- topological objects and their evolution. All
24 -- topological objects are stored in the one
25 -- user-protected TNaming_UsedShapes
26 -- attribute at the root label of the data
27 -- framework. This attribute contains map with all
28 -- topological shapes, used in this document.
29 -- To all other labels TNaming_NamedShape
30 -- attribute can be added. This attribute contains
31 -- references (hooks) to shapes from the
32 -- TNaming_UsedShapes attribute and evolution
33 -- of these shapes. TNaming_NamedShape
34 -- attribute contains a set of pairs of hooks: old
35 -- shape and new shape (see the figure below).
36 -- It allows not only get the topological shapes by
37 -- the labels, but also trace evolution of the
38 -- shapes and correctly resolve dependent
39 -- shapes by the changed one.
40 -- If shape is just-created, then the old shape for
41 -- accorded named shape is an empty shape. If
42 -- a shape is deleted, then the new shape in this named shape is empty.
43 -- Different algorithms may dispose sub-shapes
44 -- of the result shape at the individual label depending on necessity:
45 -- - If a sub-shape must have some extra attributes (material of
46 -- each face or color of each edge). In this case a specific sub-shape is
47 -- placed to the separate label (usually, sub-label of the result shape label)
48 -- with all attributes of this sub-shape.
49 -- - If topological naming is needed, a necessary and sufficient
50 -- (for selected sub-shapes identification) set of sub-shapes is
51 -- placed to the child labels of the result
52 -- shape label. As usual, as far as basic solids and closed shells are
53 -- concerned, all faces of the shape are disposed. Edges and vertices
54 -- sub-shapes can be identified as intersection of contiguous faces.
55 -- Modified/generated shapes may be placed to one named shape and
56 -- identified as this named shape and source named shape that also can be
57 -- identified with used algorithms.
58 -- TNaming_NamedShape may contain a few
59 -- pairs of hooks with the same evolution. In this
60 -- case topology shape, which belongs to the
61 -- named shape, is a compound of new shapes.
62 -- The data model contains both the topology
63 -- and the hooks, and functions handle both
64 -- topological entities and hooks. Consider the
65 -- case of a box function, which creates a solid
66 -- with six faces and six hooks. Each hook is
67 -- attached to a face. If you want, you can also
68 -- have this function create hooks for edges and
69 -- vertices as well as for faces. For the sake of
70 -- simplicity though, let's limit the example.
71 -- Not all functions can define explicit hooks for
72 -- all topological entities they create, but all
73 -- topological entities can be turned into hooks
74 -- when necessary. This is where topological naming is necessary.
75
76
77 ---Category: GUID
78 -- c4ef4200-568f-11d1-8940-080009dc3333 TNaming_NamedShape
79 -- c4ef4201-568f-11d1-8940-080009dc3333 TNaming_UsedShapes
80
81
82uses Standard,
83 TCollection,
84 TColStd,
85 TopLoc,
86 TopTools,
87 TopoDS,
88 TDF,
89 TopAbs,
90 gp
91
92
93is
94 ---Category: classes to copy shapes
95 -- ======================
96
97 class CopyShape;
98
99 class TranslateTool;
7fd59977 100
101 private class Translator;
ff8178ef 102
7fd59977 103
104 ---Category: classes to store shapes and their evolution in the framework
105 -- ============================================================
106
107 enumeration Evolution is
108 PRIMITIVE,
109 GENERATED,
110 MODIFY,
111 DELETE,
112 REPLACE,
113 SELECTED
114 end Evolution;
115 ---Purpose: Defines the type of evolution in old shape - new shape pairs.
116 -- The definitions - in the form of the terms of
117 -- the enumeration - are needed by the
118 -- TNaming_NamedShape attribute and
119 -- indicate what entities this attribute records as follows:
120 -- - PRIMITIVE
121 -- - New entities; in each pair, old shape is a
122 -- null shape and new shape is a created
123 -- entity.
124 -- - GENERATED
125 -- - Entities created from other entities; in
126 -- each pair, old shape is the generator and
127 -- new shape is the created entity.
128 -- - MODIFY
129 -- - Split or merged entities, in each pair, old
130 -- shape is the entity before the operation
131 -- and new shape is the new entity after the
132 -- operation.
133 -- - DELETE
134 -- - Deletion of entities; in each pair, old
135 -- shape is a deleted entity and new shape is null.
136 -- - SELECTED
137 -- - Named topological entities; in each pair,
138 -- the new shape is a named entity and the
139 -- old shape is not used.
140 --
141 -- For a split which generates multiple faces, the
142 -- attribute will contain many pairs with the same
143 -- old shape; for a merge, it will contain many
144 -- pairs with the same new shape.
145 -- Finally, an example of delete would be a face
146 -- removed by a Boolean operation.
147
148 class NamedShape;
ff8178ef 149
7fd59977 150
151 private class UsedShapes;
ff8178ef 152
7fd59977 153
154
155
156 class Builder;
7fd59977 157
158 class Tool;
7fd59977 159
160 class Iterator;
7fd59977 161
162 class NewShapeIterator;
7fd59977 163
164 class OldShapeIterator;
7fd59977 165
166 class SameShapeIterator;
ff8178ef 167
7fd59977 168
169
170 class NamedShapeHasher instantiates MapHasher from TCollection(NamedShape from TNaming) ;
171
172 class MapOfNamedShape instantiates Map from TCollection(NamedShape from TNaming,
173 NamedShapeHasher from TNaming) ;
174
175 class ListOfNamedShape instantiates List from TCollection (NamedShape from TNaming);
176
177
ff8178ef 178 ---Category: classes to store selected shape (involve naming algorithm)
179 -- ==========================================================
7fd59977 180
181
182 enumeration NameType is
183 ---Purpose: to store naming characteristcs
184 UNKNOWN,
185 IDENTITY,
186 MODIFUNTIL,
187 GENERATION,
188 INTERSECTION,
189 UNION,
190 SUBSTRACTION,
191 CONSTSHAPE,
192 FILTERBYNEIGHBOURGS,
193 ORIENTATION,
1ec8a59e 194 WIREIN,
195 SHELLIN
7fd59977 196 end NameType;
197
198 class Name;
7fd59977 199
200 class Naming;
7fd59977 201
202 class Selector;
7fd59977 203
204
205
206 ---Category: Private classes for TNaming
207 -- ===========================
208
209 private class DeltaOnRemoval;
210
211 private class DeltaOnModification;
212
213
214 pointer PtrAttribute to NamedShape from TNaming;
215
216 imported Node;
217
218 pointer PtrNode to Node from TNaming;
219
220 private class RefShape;
221
222 pointer PtrRefShape to RefShape from TNaming;
223
224 private class DataMapOfShapePtrRefShape instantiates
225 DataMap from TCollection (Shape from TopoDS,
226 PtrRefShape from TNaming,
227 ShapeMapHasher from TopTools);
228
229
230 pointer PtrDataMapOfShapePtrRefShape to DataMapOfShapePtrRefShape from TNaming;
231
232
233 ---Category: private classes for ANaming
234 -- ===========================
235
236
237 private class Scope;
238
239 private class Identifier;
240
241 private class Localizer;
242
243 private class ShapesSet;
244
245 private class IteratorOnShapesSet;
246
247 private class DataMapOfShapeShapesSet instantiates DataMap from TCollection
248 (Shape from TopoDS,
249 ShapesSet from TNaming,
250 ShapeMapHasher from TopTools);
251
252 private class ListOfMapOfShape instantiates List from TCollection (MapOfShape from TopTools);
253 private class ListOfIndexedDataMapOfShapeListOfShape instantiates List from TCollection
254 (IndexedDataMapOfShapeListOfShape from TopTools);
255
256
257 private class NamingTool;
258
259
260 ---Category: package methods for NamedShape
261 -- ==============================
262
263 Substitute (labelsource : Label from TDF;
264 labelcible : Label from TDF;
265 mapOldNew : in out DataMapOfShapeShape from TopTools);
266 ---Purpose: Subtituter les shapes sur les structures de source
267 -- vers cible
268
269
270 Update (label : Label from TDF;
271 mapOldNew : in out DataMapOfShapeShape from TopTools);
272 ---Purpose: Mise a jour des shapes du label et de ses fils en
273 -- tenant compte des substitutions decrite par
274 -- mapOldNew.
275 --
276 -- Warning: le remplacement du shape est fait dans tous
277 -- les attributs qui le contiennent meme si ceux
278 -- ci ne sont pas associees a des sous-labels de <Label>.
279
280 Displace (label : Label from TDF;
281 aLocation : Location from TopLoc;
282 WithOld : Boolean from Standard = Standard_True);
283 ---Purpose: Application de la Location sur les shapes du label
284 -- et de ses sous labels.
285
286 ChangeShapes (label : Label from TDF;
287 M : in out DataMapOfShapeShape from TopTools);
288 ---Purpose: Remplace les shapes du label et des sous-labels
289 -- par des copies.
290
291 Transform (label : Label from TDF;
292 aTransformation : Trsf from gp);
293 ---Purpose: Application de la transformation sur les shapes du
294 -- label et de ses sous labels.
295 -- Warning: le remplacement du shape est fait dans tous
296 -- les attributs qui le contiennent meme si ceux
297 -- ci ne sont pas associees a des sous-labels de <Label>.
298
299
300 Replicate (NS : NamedShape from TNaming;
301 T : Trsf from gp;
302 L : Label from TDF);
303 ---Purpose: Replicates the named shape with the transformation <T>
304 -- on the label <L> (and sub-labels if necessary)
305 -- (TNaming_GENERATED is set)
306
307 Replicate (SH : Shape from TopoDS;
308 T : Trsf from gp;
309 L : Label from TDF);
310 ---Purpose: Replicates the shape with the transformation <T>
311 -- on the label <L> (and sub-labels if necessary)
312 -- (TNaming_GENERATED is set)
313
314
315 MakeShape(MS : MapOfShape from TopTools)
316 returns Shape from TopoDS;
317 ---Purpose: Builds shape from map content
318
319 FindUniqueContext(S : Shape from TopoDS; Context : Shape from TopoDS)
320 returns Shape from TopoDS;
321 ---Purpose: Find unique context of shape <S>
322
323 FindUniqueContextSet(S : Shape from TopoDS; Context : Shape from TopoDS;
324 Arr : in out HArray1OfShape from TopTools)
325 returns Shape from TopoDS;
326 ---Purpose: Find unique context of shape <S>,which is pure concatenation
327 -- of atomic shapes (Compound). The result is concatenation of
328 -- single contexts
329
330 SubstituteSShape(accesslabel : Label from TDF;
331 From : Shape from TopoDS;
332 To : in out Shape from TopoDS)
333 returns Boolean from Standard;
334 ---Purpose: Subtitutes shape in source structure
1ec8a59e 335
336
337 OuterWire(theFace: Face from TopoDS; theWire: out Wire from TopoDS)
338 returns Boolean from Standard;
339 --- Purpose: Returns True if outer wire is found and the found wire in <theWire>.
7fd59977 340
1ec8a59e 341 OuterShell(theSolid: Solid from TopoDS; theShell: out Shell from TopoDS)
342 returns Boolean from Standard;
343 --- Purpose: Returns True if outer Shell is found and the found shell in <theShell>.
344
345
7fd59977 346
347 ---Purpose: Print of TNaming enumeration
348 -- =============================
349
350 IDList(anIDList : in out IDList from TDF);
351 ---Purpose: Appends to <anIDList> the list of the attributes
352 -- IDs of this package. CAUTION: <anIDList> is NOT
353 -- cleared before use.
354
355
356 Print (EVOL : Evolution from TNaming; S : in out OStream)
357 ---Purpose: Prints the evolution <EVOL> as a String on the
358 -- Stream <S> and returns <S>.
359 ---C++: return &
360 returns OStream;
361
362 Print (NAME : NameType from TNaming; S : in out OStream)
363 ---Purpose: Prints the name of name type <NAME> as a String on
364 -- the Stream <S> and returns <S>.
365 ---C++: return &
366 returns OStream;
367
368 Print (ACCESS : Label from TDF; S : in out OStream)
369 ---Purpose: Prints the content of UsedShapes private attribute as a String Table on
370 -- the Stream <S> and returns <S>.
371 ---C++: return &
372 returns OStream;
373
374
375end TNaming;
376