src/XCAFDoc/XCAFDoc_ShapeTool.cdl

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