src/XCAFDoc/XCAFDoc_ShapeTool.cdl

   1 -- Created on: 2000-06-15
   2 -- Created by: Edward AGAPOV
   3 -- Copyright (c) 2000-2012 OPEN CASCADE SAS
   4 --
   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.
   9 --
  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.
  12 --
  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.
  19
  20
  21
  22 class ShapeTool from XCAFDoc inherits Attribute from TDF
  23
  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.
  37 -- For example:
  38 -- if ( STool->IsAssembly(aLabel) )
  39 -- { Standard_Boolean subchilds = Standard_False; (default)
  40 -- Standard_Integer nbc = STool->NbComponents
  41 -- (aLabel[,subchilds]);
  42 -- }
  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:
  47 -- Constructor:
  48 -- XCAFDoc_ShapeTool::XCAFDoc_ShapeTool()
  49 -- Getting a guid:
  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).
  55 -- For example:
  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).
  63 -- For example:
  64 --   Add shape:
  65 -- Standard_Boolean makeAssembly;
  66 -- // True to interpret a Compound as an Assembly, False to take it
  67 -- as a whole
  68 -- aLabel = STool->AddShape(aShape, makeAssembly);
  69 --        Get shape:
  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 ... }
  83
  84 uses
  85     Document from TDocStd,
  86     TreeNode from TDataStd,
  87     Location from TopLoc,
  88     Label from TDF,
  89     LabelSequence from TDF,
  90     LabelMap from TDF,
  91     Shape from TopoDS,
  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
  99
 100 is
 101     GetID (myclass)
 102     ---C++: return const &
 103     returns GUID from Standard;
 104
 105
 106     Set (myclass; L : Label from TDF) returns ShapeTool from XCAFDoc;
 107     ---Purpose: Create (if not exist) ShapeTool from XCAFDoc on <L>.
 108
 109
 110
 111
 112     Create returns ShapeTool from XCAFDoc;
 113         ---Purpose: Creates an empty tool
 114
 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()
 118
 119
 120
 121     ---API: Analysis
 122
 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
 126
 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>)
 132
 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)
 136
 137     IsSimpleShape (myclass; L: Label from TDF) returns Boolean;
 138         ---Purpose: Returns True if the label is a label of simple shape
 139
 140     IsReference (myclass; L: Label from TDF) returns Boolean;
 141         ---Purpose: Return true if <L> is a located instance of other shape
 142         --          i.e. reference
 143
 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
 148
 149     IsComponent (myclass; L: Label from TDF) returns Boolean;
 150         ---Purpose: Return true if <L> is reference serving as component
 151         --          of assembly
 152
 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
 157
 158     IsSubShape (myclass; L: Label from TDF) returns Boolean;
 159         ---Purpose: Return true if <L> is subshape of the top-level shape
 160
 161     IsSubShape (me; shapeL: Label from TDF;
 162                     sub: Shape from TopoDS)
 163     returns Boolean;
 164         ---Purpose: Checks whether shape <sub> is subshape of shape stored on
 165         --          label shapeL
 166
 167     ---API: Work with top-level structure of shapes
 168
 169     SearchUsingMap (me; S: Shape from TopoDS; L: out Label from TDF;
 170                         findWithoutLoc: Boolean; findSubshape: Boolean)
 171     returns Boolean from Standard;
 172
 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
 189
 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
 195         --          of assemblies)
 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.
 201
 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
 207
 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
 213
 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
 218
 219     NewShape (me) returns Label from TDF;
 220         ---Purpose: Creates new (empty) top-level shape.
 221         --          Initially it holds empty TopoDS_Compound
 222
 223     SetShape (me:mutable; L: Label from TDF; S: Shape from TopoDS);
 224         ---Purpose: Sets representation (TopoDS_Shape) for top-level shape
 225
 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.
 235
 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.
 241
 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
 246
 247     Init (me: mutable);
 248         ---Purpose: set hasComponents into false
 249
 250     ComputeShapes (me: mutable; L: Label from TDF);
 251         ---Purpose: recursive
 252
 253     ComputeSimpleShapes (me: mutable);
 254         ---Purpose: Compute a sequence of simple shapes
 255
 256     GetShapes (me; Labels: out LabelSequence from TDF);
 257         ---Purpose: Returns a sequence of all top-level shapes
 258
 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)
 262
 263     GetUsers (myclass; L: Label from TDF;
 264                        Labels : out LabelSequence from TDF;
 265                        getsubchilds: Boolean from Standard = Standard_False)
 266     returns Integer;
 267         ---Purpose: Returns list of labels which refer shape L as component
 268         --          Returns number of users (0 if shape is free)
 269
 270     GetLocation (myclass; L: Label from TDF)
 271     returns Location from TopLoc;
 272         ---Purpose: Returns location of instance
 273
 274     GetReferredShape (myclass; L: Label from TDF;
 275                                Label: out Label from TDF)
 276     returns Boolean;
 277         ---Purpose: Returns label which corresponds to a shape referred by L
 278         --          Returns False if label is not reference
 279
 280     ---API: Work with assembly structure
 281
 282     NbComponents (myclass; L: Label from TDF;
 283                        getsubchilds: Boolean from Standard = Standard_False)
 284     returns Integer;
 285         ---Purpose: Returns number of Assembles components
 286
 287     GetComponents (myclass; L: Label from TDF;
 288                             Labels : out LabelSequence from TDF;
 289                             getsubchilds: Boolean from Standard = Standard_False)
 290     returns Boolean;
 291         ---Purpose: Returns list of components of assembly
 292         --          Returns False if label is not assembly
 293
 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()
 299
 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()
 309
 310     RemoveComponent (me; comp: Label from TDF);
 311         ---Purpose: Removes a component from its assembly
 312
 313     UpdateAssembly (me; L: Label from TDF);
 314         ---Purpose: Update an assembly at label <L>
 315
 316     ---API: work with sub-shapes of shape
 317
 318     FindSubShape (me; shapeL: Label from TDF;
 319                       sub: Shape from TopoDS;
 320                       L: out Label from TDF)
 321     returns Boolean;
 322         ---Purpose: Finds a label for subshape <sub> of shape stored on
 323         --          label shapeL
 324         --          Returns Null label if it is not found
 325
 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
 330         --          label shapeL
 331         --          Returns Null label if it is not subshape
 332
 333     FindMainShapeUsingMap (me; sub: Shape from TopoDS)
 334     returns Label from TDF;
 335
 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)
 342
 343     GetSubShapes (myclass; L: Label from TDF;
 344                            Labels : out LabelSequence from TDF)
 345     returns Boolean;
 346         ---Purpose: Returns list of labels identifying subshapes of the given shape
 347         --          Returns False if no subshapes are placed on that label
 348
 349     ---API: Auxiliary
 350
 351     BaseLabel(me) returns Label from TDF;
 352         ---Purpose: returns the label under which shapes are stored
 353
 354     Dump(me; deep : Boolean from Standard = Standard_False);
 355
 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
 362
 363     --- Private
 364
 365     MakeReference (myclass; L, refL: Label from TDF; loc: Location from TopLoc)
 366     is private;
 367         ---Purpose: Makes a shape on label L to be a reference to shape refL
 368         --          with location loc
 369
 370
 371             ---Category: TDF_Attribute methods
 372     --           =====================
 373
 374     ID (me)
 375         ---C++: return const &
 376     returns GUID from Standard;
 377
 378     Restore (me: mutable; with : Attribute from TDF);
 379
 380     NewEmpty (me)
 381     returns mutable Attribute from TDF;
 382
 383     Paste (me; into : mutable Attribute from TDF;
 384                RT   : mutable RelocationTable from TDF);
 385
 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
 390
 391     SetExternRefs (me; SHAS: SequenceOfHAsciiString from TColStd) returns Label from TDF;
 392         ---Purpose: Sets the names of references on the no-step files
 393
 394     SetExternRefs (me; L: Label from TDF; SHAS: SequenceOfHAsciiString from TColStd);
 395         ---Purpose: Sets the names of references on the no-step files
 396
 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
 399
 400     ---API: Work with SHUO (Specified Higher Usage Occurrance) structure
 401
 402     SetSHUO (me; Labels : LabelSequence from TDF;
 403              MainSHUOAttr : in out GraphNode from XCAFDoc)
 404     returns Boolean;
 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
 409
 410     GetSHUO (myclass; SHUOLabel : Label from TDF;
 411              aSHUOAttr : in out GraphNode from XCAFDoc)
 412     returns Boolean;
 413         ---Purpose: Returns founded SHUO GraphNode attribute <aSHUOAttr>
 414         --          Returns false in other case
 415
 416     GetAllComponentSHUO (myclass; CompLabel : Label from TDF;
 417                          SHUOAttrs : in out AttributeSequence from TDF)
 418     returns Boolean;
 419         ---Purpose: Returns founded SHUO GraphNodes of indicated component
 420         --          Returns false in other case
 421
 422     GetSHUOUpperUsage (myclass; NextUsageL: Label from TDF;
 423                        Labels : out LabelSequence from TDF)
 424     returns Boolean;
 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
 430
 431     GetSHUONextUsage (myclass; UpperUsageL: Label from TDF;
 432                        Labels : out LabelSequence from TDF)
 433     returns Boolean;
 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
 439
 440     RemoveSHUO (me; SHUOLabel : Label from TDF)
 441     returns Boolean;
 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.
 446
 447     FindComponent (me; theShape : Shape from TopoDS;
 448                    Labels : out LabelSequence from TDF)
 449     returns Boolean;
 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
 455
 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.
 460
 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.
 466
 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.
 472
 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
 479
 480 fields
 481     myShapeLabels   : DataMapOfShapeLabel from XCAFDoc; --skl 15.10.2003
 482     mySubShapes     : DataMapOfShapeLabel from XCAFDoc;
 483     mySimpleShapes  : DataMapOfShapeLabel from XCAFDoc;
 484     hasSimpleShapes : Boolean from Standard;
 485
 486 end ShapeTool;