src/XCAFDoc/XCAFDoc_ShapeTool.hxx

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