-- Created on: 2000-06-15 -- Created by: Edward AGAPOV -- Copyright (c) 2000-2014 OPEN CASCADE SAS -- -- This file is part of Open CASCADE Technology software library. -- -- This library is free software; you can redistribute it and/or modify it under -- the terms of the GNU Lesser General Public License version 2.1 as published -- by the Free Software Foundation, with special exception defined in the file -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT -- distribution for complete text of the license and disclaimer of any warranty. -- -- Alternatively, this file may be used under the terms of Open CASCADE -- commercial license or contractual agreement. class ShapeTool from XCAFDoc inherits Attribute from TDF ---Purpose: A tool to store shapes in an XDE -- document in the form of assembly structure, and to maintain this structure. -- Attribute containing Shapes section of DECAF document. -- Provide tools for management of Shapes section. -- The API provided by this class allows to work with this -- structure regardless of its low-level implementation. -- All the shapes are stored on child labels of a main label which is -- XCAFDoc_DocumentTool::LabelShapes(). The label for assembly also has -- sub-labels, each of which represents the instance of -- another shape in that assembly (component). Such sub-label -- stores reference to the label of the original shape in the form -- of TDataStd_TreeNode with GUID XCAFDoc::ShapeRefGUID(), and its -- location encapsulated into the NamedShape. -- For correct work with an XDE document, it is necessary to use -- methods for analysis and methods for working with shapes. -- For example: -- if ( STool->IsAssembly(aLabel) ) -- { Standard_Boolean subchilds = Standard_False; (default) -- Standard_Integer nbc = STool->NbComponents -- (aLabel[,subchilds]); -- } -- If subchilds is True, commands also consider sub-levels. By -- default, only level one is checked. -- In this example, number of children from the first level of -- assembly will be returned. Methods for creation and initialization: -- Constructor: -- XCAFDoc_ShapeTool::XCAFDoc_ShapeTool() -- Getting a guid: -- Standard_GUID GetID (); -- Creation (if does not exist) of ShapeTool on label L: -- Handle(XCAFDoc_ShapeTool) XCAFDoc_ShapeTool::Set(const TDF_Label& L) -- Analyze whether shape is a simple shape or an instance or a -- component of an assembly or it is an assembly ( methods of analysis). -- For example: -- STool->IsShape(aLabel) ; -- Analyze that the label represents a shape (simple -- shape, assembly or reference) or -- STool->IsTopLevel(aLabel); -- Analyze that the label is a label of a top-level shape. -- Work with simple shapes, assemblies and instances ( -- methods for work with shapes). -- For example: -- Add shape: -- Standard_Boolean makeAssembly; -- // True to interpret a Compound as an Assembly, False to take it -- as a whole -- aLabel = STool->AddShape(aShape, makeAssembly); -- Get shape: -- TDF_Label aLabel... -- // A label must be present if -- (aLabel.IsNull()) { ... no such label : abandon .. } -- TopoDS_Shape aShape; -- aShape = STool->GetShape(aLabel); -- if (aShape.IsNull()) -- { ... this label is not for a Shape ... } -- To get a label from shape. -- Standard_Boolean findInstance = Standard_False; -- (this is default value) -- aLabel = STool->FindShape(aShape [,findInstance]); -- if (aLabel.IsNull()) -- { ... no label found for this shape ... } uses Document from TDocStd, TreeNode from TDataStd, Location from TopLoc, Label from TDF, LabelSequence from TDF, LabelMap from TDF, Shape from TopoDS, SequenceOfShape from TopTools, HAsciiString from TCollection, RelocationTable from TDF, SequenceOfHAsciiString from TColStd, GraphNode from XCAFDoc, AttributeSequence from TDF, DataMapOfShapeLabel from XCAFDoc is GetID (myclass) ---C++: return const & returns GUID from Standard; Set (myclass; L : Label from TDF) returns ShapeTool from XCAFDoc; ---Purpose: Create (if not exist) ShapeTool from XCAFDoc on . Create returns ShapeTool from XCAFDoc; ---Purpose: Creates an empty tool --Create (Doc: Document from TDocStd) returns ShapeTool from XCAFDoc; ---Purpose: Creates a tool to work with a document -- Attaches to label XCAFDoc::LabelShapes() ---API: Analysis IsTopLevel (me; L: Label from TDF) returns Boolean; ---Purpose: Returns True if the label is a label of top-level shape, -- as opposed to component of assembly or subshape IsFree (myclass; L: Label from TDF) returns Boolean; ---Purpose: Returns True if the label is not used by any assembly, i.e. -- contains sublabels which are assembly components -- This is relevant only if IsShape() is True -- (There is no Father TreeNode on this ) IsShape (myclass; L: Label from TDF) returns Boolean; ---Purpose: Returns True if the label represents a shape (simple shape, -- assembly or reference) IsSimpleShape (myclass; L: Label from TDF) returns Boolean; ---Purpose: Returns True if the label is a label of simple shape IsReference (myclass; L: Label from TDF) returns Boolean; ---Purpose: Return true if is a located instance of other shape -- i.e. reference IsAssembly (myclass; L: Label from TDF) returns Boolean; ---Purpose: Returns True if the label is a label of assembly, i.e. -- contains sublabels which are assembly components -- This is relevant only if IsShape() is True IsComponent (myclass; L: Label from TDF) returns Boolean; ---Purpose: Return true if is reference serving as component -- of assembly IsCompound (myclass; L: Label from TDF) returns Boolean; ---Purpose: Returns True if the label is a label of compound, i.e. -- contains some sublabels -- This is relevant only if IsShape() is True IsSubShape (myclass; L: Label from TDF) returns Boolean; ---Purpose: Return true if is subshape of the top-level shape IsSubShape (me; shapeL: Label from TDF; sub: Shape from TopoDS) returns Boolean; ---Purpose: Checks whether shape is subshape of shape stored on -- label shapeL ---API: Work with top-level structure of shapes SearchUsingMap (me; S: Shape from TopoDS; L: out Label from TDF; findWithoutLoc: Boolean; findSubshape: Boolean) returns Boolean from Standard; Search (me; S: Shape from TopoDS; L: out Label from TDF; findInstance: Boolean = Standard_True; findComponent: Boolean = Standard_True; findSubshape: Boolean = Standard_True) returns Boolean from Standard; ---Purpose: General tool to find a (sub) shape in the document -- * If findInstance is True, and S has a non-null location, -- first tries to find the shape among the top-level shapes -- with this location -- * If not found, and findComponent is True, tries to find the shape -- among the components of assemblies -- * If not found, tries to find the shape without location -- among top-level shapes -- * If not found and findSubshape is True, tries to find a -- shape as a subshape of top-level simple shapes -- Returns False if nothing is found FindShape (me; S: Shape from TopoDS; L: out Label from TDF; findInstance: Boolean = Standard_False) returns Boolean from Standard; ---Purpose: Returns the label corresponding to shape S -- (searches among top-level shapes, not including subcomponents -- of assemblies) -- If findInstance is False (default), searches for the -- non-located shape (i.e. among original shapes) -- If findInstance is True, searches for the shape with the same -- location, including shape instances -- Return True if is found. FindShape (me; S: Shape from TopoDS; findInstance: Boolean = Standard_False) returns Label from TDF; ---Purpose: Does the same as previous method -- Returns Null label if not found GetShape (myclass; L: Label from TDF; S: out Shape from TopoDS) returns Boolean from Standard; ---Purpose: To get TopoDS_Shape from shape's label -- For component, returns new shape with correct location -- Returns False if label does not contain shape GetShape (myclass; L: Label from TDF) returns Shape from TopoDS; ---Purpose: To get TopoDS_Shape from shape's label -- For component, returns new shape with correct location -- Returns Null shape if label does not contain shape NewShape (me) returns Label from TDF; ---Purpose: Creates new (empty) top-level shape. -- Initially it holds empty TopoDS_Compound SetShape (me:mutable; L: Label from TDF; S: Shape from TopoDS); ---Purpose: Sets representation (TopoDS_Shape) for top-level shape AddShape (me:mutable; S: Shape from TopoDS; makeAssembly: Boolean = Standard_True; makePrepare : Boolean = Standard_True) returns Label from TDF; ---Purpose: Adds a new top-level (creates and returns a new label) -- If makeAssembly is True, treats TopAbs_COMPOUND shapes -- as assemblies (creates assembly structure). -- NOTE: replace components without location -- in assmebly by located components to avoid some problems. -- If AutoNaming() is True then automatically attaches names. addShape (me:mutable; S: Shape from TopoDS; makeAssembly: Boolean = Standard_True) returns Label from TDF is private; ---Purpose: Adds a new top-level (creates and returns a new label) -- For internal use. Used by public method AddShape. RemoveShape (me; L: Label from TDF; removeCompletely: Boolean = Standard_True) returns Boolean; ---Purpose: Removes shape (whole label and all its sublabels) -- If removeCompletely is true, removes complete shape -- If removeCompletely is false, removes instance(location) only -- Returns False (and does nothing) if shape is not free -- or is not top-level shape Init (me: mutable); ---Purpose: set hasComponents into false SetAutoNaming (myclass; V: Boolean); ---Purpose: Sets auto-naming mode to . If True then for added -- shapes, links, assemblies and SHUO's, the TDataStd_Name attribute -- is automatically added. For shapes it contains a shape type -- (e.g. "SOLID", "SHELL", etc); for links it has a form -- "=>[0:1:1:2]" (where a tag is a label containing a shape -- without a location); for assemblies it is "ASSEMBLY", and -- "SHUO" for SHUO's. -- This setting is global; it cannot be made a member function -- as it is used by static methods as well. -- By default, auto-naming is enabled. -- See also AutoNaming(). AutoNaming (myclass) returns Boolean; ---Purpose: Returns current auto-naming mode. See SetAutoNaming() for -- description. ComputeShapes (me: mutable; L: Label from TDF); ---Purpose: recursive ComputeSimpleShapes (me: mutable); ---Purpose: Compute a sequence of simple shapes GetShapes (me; Labels: out LabelSequence from TDF); ---Purpose: Returns a sequence of all top-level shapes GetFreeShapes (me; FreeLabels : out LabelSequence from TDF); ---Purpose: Returns a sequence of all top-level shapes -- which are free (i.e. not referred by any other) GetUsers (myclass; L: Label from TDF; Labels : out LabelSequence from TDF; getsubchilds: Boolean from Standard = Standard_False) returns Integer; ---Purpose: Returns list of labels which refer shape L as component -- Returns number of users (0 if shape is free) GetLocation (myclass; L: Label from TDF) returns Location from TopLoc; ---Purpose: Returns location of instance GetReferredShape (myclass; L: Label from TDF; Label: out Label from TDF) returns Boolean; ---Purpose: Returns label which corresponds to a shape referred by L -- Returns False if label is not reference ---API: Work with assembly structure NbComponents (myclass; L: Label from TDF; getsubchilds: Boolean from Standard = Standard_False) returns Integer; ---Purpose: Returns number of Assembles components GetComponents (myclass; L: Label from TDF; Labels : out LabelSequence from TDF; getsubchilds: Boolean from Standard = Standard_False) returns Boolean; ---Purpose: Returns list of components of assembly -- Returns False if label is not assembly AddComponent (me; assembly, comp: Label from TDF; Loc: Location from TopLoc) returns Label from TDF; ---Purpose: Adds a component given by its label and location to the assembly -- Note: assembly must be IsAssembly() or IsSimpleShape() AddComponent (me:mutable; assembly: Label from TDF; comp: Shape from TopoDS; expand: Boolean = Standard_False) returns Label from TDF; ---Purpose: Adds a shape (located) as a component to the assembly -- If necessary, creates an additional top-level shape for -- component and return the Label of component. -- If expand is True and component is Compound, it will -- be created as assembly also -- Note: assembly must be IsAssembly() or IsSimpleShape() RemoveComponent (me; comp: Label from TDF); ---Purpose: Removes a component from its assembly UpdateAssembly (me; L: Label from TDF); ---Purpose: Update an assembly at label ---API: work with sub-shapes of shape FindSubShape (me; shapeL: Label from TDF; sub: Shape from TopoDS; L: out Label from TDF) returns Boolean; ---Purpose: Finds a label for subshape of shape stored on -- label shapeL -- Returns Null label if it is not found AddSubShape (me; shapeL: Label from TDF; sub: Shape from TopoDS) returns Label from TDF; ---Purpose: Adds a label for subshape of shape stored on -- label shapeL -- Returns Null label if it is not subshape FindMainShapeUsingMap (me; sub: Shape from TopoDS) returns Label from TDF; FindMainShape (me; sub: Shape from TopoDS) returns Label from TDF; ---Purpose: Performs a search among top-level shapes to find -- the shape containing as subshape -- Checks only simple shapes, and returns the first found -- label (which should be the only one for valid model) GetSubShapes (myclass; L: Label from TDF; Labels : out LabelSequence from TDF) returns Boolean; ---Purpose: Returns list of labels identifying subshapes of the given shape -- Returns False if no subshapes are placed on that label ---API: Auxiliary BaseLabel(me) returns Label from TDF; ---Purpose: returns the label under which shapes are stored Dump(me; deep : Boolean from Standard = Standard_False); DumpShape(myclass; L: Label from TDF; level :Integer from Standard = 0; deep : Boolean from Standard = Standard_False); ---Purpose: Print in cout type of shape found on label -- and the entry of , with tabs before. -- If , print also TShape and Location addresses --- Private MakeReference (myclass; L, refL: Label from TDF; loc: Location from TopLoc) is private; ---Purpose: Makes a shape on label L to be a reference to shape refL -- with location loc ---Category: TDF_Attribute methods -- ===================== ID (me) ---C++: return const & returns GUID from Standard; Restore (me: mutable; with : Attribute from TDF); NewEmpty (me) returns Attribute from TDF; Paste (me; into : Attribute from TDF; RT : RelocationTable from TDF); IsExternRef (myclass; L: Label from TDF) returns Boolean; ---Purpose: Returns True if the label is a label of external references, i.e. -- there are some reference on the no-step files, which are -- described in document only their names SetExternRefs (me; SHAS: SequenceOfHAsciiString from TColStd) returns Label from TDF; ---Purpose: Sets the names of references on the no-step files SetExternRefs (me; L: Label from TDF; SHAS: SequenceOfHAsciiString from TColStd); ---Purpose: Sets the names of references on the no-step files GetExternRefs (myclass; L: Label from TDF; SHAS: in out SequenceOfHAsciiString from TColStd); ---Purpose: Gets the names of references on the no-step files ---API: Work with SHUO (Specified Higher Usage Occurrance) structure SetSHUO (me; Labels : LabelSequence from TDF; MainSHUOAttr : in out GraphNode from XCAFDoc) returns Boolean; ---Purpose: Sets the SHUO structure between upper_usage and next_usage -- create multy-level (if number of labels > 2) SHUO from first to last -- Initialise out by main upper_usage SHUO attribute. -- Returns FALSE if some of labels in not component label GetSHUO (myclass; SHUOLabel : Label from TDF; aSHUOAttr : in out GraphNode from XCAFDoc) returns Boolean; ---Purpose: Returns founded SHUO GraphNode attribute -- Returns false in other case GetAllComponentSHUO (myclass; CompLabel : Label from TDF; SHUOAttrs : in out AttributeSequence from TDF) returns Boolean; ---Purpose: Returns founded SHUO GraphNodes of indicated component -- Returns false in other case GetSHUOUpperUsage (myclass; NextUsageL: Label from TDF; Labels : out LabelSequence from TDF) returns Boolean; ---Purpose: Returns the sequence of labels of SHUO attributes, -- which is upper_usage for this next_usage SHUO attribute -- (that indicated by label) -- NOTE: returns upper_usages only on one level (not recurse) -- NOTE: do not clear the sequence before filling GetSHUONextUsage (myclass; UpperUsageL: Label from TDF; Labels : out LabelSequence from TDF) returns Boolean; ---Purpose: Returns the sequence of labels of SHUO attributes, -- which is next_usage for this upper_usage SHUO attribute -- (that indicated by label) -- NOTE: returns next_usages only on one level (not recurse) -- NOTE: do not clear the sequence before filling RemoveSHUO (me; SHUOLabel : Label from TDF) returns Boolean; ---Purpose: Remove SHUO from component sublabel, -- remove all dependencies on other SHUO. -- Returns FALSE if cannot remove SHUO dependencies. -- NOTE: remove any styles that associated with this SHUO. FindComponent (me; theShape : Shape from TopoDS; Labels : out LabelSequence from TDF) returns Boolean; ---Purpose: Serach the path of labels in the document, -- that corresponds the component from any assembly -- Try to search the sequence of labels with location that -- produce this shape as component of any assembly -- NOTE: Clear sequence of labels before filling GetSHUOInstance (me; theSHUO : GraphNode from XCAFDoc) returns Shape from TopoDS; ---Purpose: Search for the component shape that styled by shuo -- Returns null shape if no any shape is found. SetInstanceSHUO (me; theShape : Shape from TopoDS) returns GraphNode from XCAFDoc; ---Purpose: Search for the component shape by labelks path -- and set SHUO structure for founded label structure -- Returns null attribute if no component in any assembly found. GetAllSHUOInstances (me; theSHUO : GraphNode from XCAFDoc; theSHUOShapeSeq : in out SequenceOfShape from TopTools) returns Boolean from Standard; ---Purpose: Seaching for component shapes that styled by shuo -- Returns empty sequence of shape if no any shape is found. FindSHUO (myclass; Labels : LabelSequence from TDF; theSHUOAttr : in out GraphNode from XCAFDoc) returns Boolean from Standard; ---Purpose: Searchs the SHUO by labels of components -- from upper_usage componet to next_usage -- Returns null attribute if no SHUO found fields myShapeLabels : DataMapOfShapeLabel from XCAFDoc; --skl 15.10.2003 mySubShapes : DataMapOfShapeLabel from XCAFDoc; mySimpleShapes : DataMapOfShapeLabel from XCAFDoc; hasSimpleShapes : Boolean from Standard; end ShapeTool;