[occt.git] / src / ShapeFix / ShapeFix_ComposeShell.cdl

-- Created on: 1999-04-26
-- Created by: Andrey BETENEV
-- Copyright (c) 1999 Matra Datavision
-- Copyright (c) 1999-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 ComposeShell from ShapeFix inherits Root from ShapeFix

	---Purpose: This class is intended to create a shell from the composite
	--          surface (grid of surfaces) and set of wires.
	--          It may be either division of the supporting surface of the 
        --          face, or creating a shape corresponding to face on composite
	--          surface which is missing in CAS.CADE but exists in some other 
        --          systems.
	--
	--          It splits (if necessary) original face to several ones by
	--          splitting lines which are joint lines on a supplied grid of
	--          surfaces (U- and V- isolines of the  composite surface).
	--          There are two modes of work, which differ in the way of 
	--          handling faces on periodic surfaces:
	--
	--        - if ClosedMode is False (default), when splitting itself is
	--          done as if surface were not periodic. The periodicity of the 
	--          underlying surface is taken into account by duplicating splitting
	--          lines in the periodic direction, as necessary to split all
	--          the wires (whole parametrical range of a face)
	--          In this mode, some regularization procedures are performed
	--          (indexation of splitted segments by patch numbers), and it is 
        --          expected to be more reliable and robust in case of bad shapes
	--
	--        - if ClosedMode is True, when everything on a periodic surfaces
        --          is considered as modulo period. This allows to deal with wires
	--          which are closed in 3d but not in 2d, with wires which may be
        --          shifted on several periods in 2d etc. However, this mode is 
        --          less reliable since some regularizations do not work for it.
	--
	--          The work is made basing on pcurves of the edges. These pcurves
	--          should already exist (for example, in the case of division of 
	--          existing face), then they are taken as is. The existing pcurves
	--          should be assigned to one surface (face) for all edges,
	--          this surface (face) will be used only for accessing pcurves,
	--          and it may have any geometry.
    	--
        --          All the modifications are recorded in the context tool
        --          (ShapeBuild_ReShape).

uses
    Lin2d    from gp,
    Curve    from Geom2d,
    Surface  from Geom,
    Location from TopLoc,
    Edge     from TopoDS,
    Face     from TopoDS,
    Shape    from TopoDS, 
    Status   from ShapeExtend,
    WireData from ShapeExtend,
    CompositeSurface from ShapeExtend,
    WireSegment      from ShapeFix,
    Orientation      from TopAbs,
    SequenceOfReal        from TColStd,
    SequenceOfInteger     from TColStd,
    SequenceOfShape       from TopTools,
    SequenceOfWireSegment from ShapeFix,
    TransferParameters    from ShapeAnalysis
is
    Create returns ComposeShell from ShapeFix;
        ---Purpose: Creates empty tool.
    
    Init (me: mutable; Grid: CompositeSurface from ShapeExtend;
    	    	       L   : Location from TopLoc;
                       Face: Face from TopoDS;
    	    	       Prec: Real);
        ---Purpose: Initializes with composite surface, face and precision.
	--          Here face defines both set of wires and way of getting
	--          pcurves. Precision is used (together with tolerance of edges)
	--          for handling subtle cases, such as tangential intersections.

    ClosedMode (me: mutable) returns Boolean;
    	---Purpose: Returns (modifiable) flag for special 'closed'
	--          mode which forces ComposeShell to consider
	--          all pcurves on closed surface as modulo period.
	--          This can reduce reliability, but allows to deal
	--          with wires closed in 3d but open in 2d (missing seam)
	--          Default is False
	---C++: return &
		      
    Perform (me: mutable) 
    returns Boolean is virtual;
        ---Purpose: Performs the work on already loaded data.

    SplitEdges (me: mutable);
    	---Purpose: Splits edges in the original shape by grid.
	--          This is a part of Perform() which does not produce any
        --          resulting shape; the only result is filled context
	--          where splittings are recorded.
	--
	--          NOTE: If edge is splitted, it is replaced by wire, and 
	--          order of edges in the wire corresponds to FORWARD orientation
	--          of the edge.
    
    Result (me) returns Shape from TopoDS;
        ---Purpose: Returns resulting shell or face (or Null shape if not done)
    	---C++: return const &
    
    Status (me; status: Status from ShapeExtend) returns Boolean;
        ---Purpose: Queries status of last call to Perform()
	-- OK   : nothing done (some kind of error)
	-- DONE1: splitting is done, at least one new face created
	-- DONE2: splitting is done, several new faces obtained
	-- FAIL1: misoriented wire encountered (handled)
	-- FAIL2: recoverable parity error
	-- FAIL3: edge with no pcurve on supporting face
	-- FAIL4: unrecoverable algorithm error (parity check)
    
    ---Protected methods:
    
    LoadWires (me; seqw: out SequenceOfWireSegment from ShapeFix)
    is protected;
    	---Purpose: Fill sequence of wire segments by wires from myFace
	--          (pre-loaded). It performs reorder so that edges in segments
	--          are well-ordered. The context is applied to all wires
	--          before using them.
    
    ComputeCode (me: mutable; wire  : WireData from ShapeExtend;
			      line  : Lin2d from gp;
		    	      begInd: Integer;
		    	      endInd: Integer;
       		    	      begPar: Real;
		    	      endPar: Real;
    	    	    	      IsInternal : Boolean = Standard_False)
    returns Integer is protected;
    	---Purpose: Analyze tangencies and compute orientation code for wire segment 
    	--          between two intersections: tells if segment is on left or right side 
	--          of cutting line, or tangent to it (by several points recomputed to 3d, 
	--          distance is compared with tolerance of corresponding edge).

    SplitWire (me: mutable; wire    : in out WireSegment from ShapeFix;
    	    	            indexes : in out SequenceOfInteger from TColStd;
		            values  : SequenceOfReal    from TColStd;
    	    	            vertices: out SequenceOfShape from TopTools;
			    segcodes: SequenceOfInteger from TColStd;
			    cutbyu  : Boolean;
			    cutindex: Integer)
    returns WireSegment from ShapeFix is protected;
    	---Purpose: Splits edges in the wire by given indices of edges and 
	--          parameters on them. Returns resulting wire and vertices 
	--          corresponding to splitting parameters. If two consequtive
	--          splitting points are too near one to another (with tolerance 
	--          of edge), edge is divided in single point. In the same way,
	--          splitting which is too near to end of edge, is not applied
	--          (end vertex is returned instead).
	--
	--          NOTE: If edge is splitted, it is replaced by wire, and 
	--          order of edges in the wire corresponds to FORWARD orientation
	--          of the edge.
	
    SplitByLine (me: mutable; wire           : in out WireSegment from ShapeFix;
    	    	              line           : Lin2d from gp;
			      cutbyu  : Boolean;
			      cutindex: Integer;
		     	      SplitLinePar   : out SequenceOfReal from TColStd;
		     	      SplitLineCode  : out SequenceOfInteger from TColStd;
		      	      SplitLineVertex: out SequenceOfShape from TopTools)
    returns Boolean is protected;
        ---Purpose: Split edges in the wire by cutting line.
	--          Wires with FORWARD or REVERSED orientation are considered
	--          as closed.
	--
	--          All modifications (splitting) are recorded in context, 
        --          except splitting of wires marked as EXTERNAL
	--          (they are supposed to be former cutting lines).
	--
	--          Method fills sequences of parameters of intersection points 
	--          of cutting line with all edges, their types, and corresponding
	--          vertices (including ones created during splitting edges).
    
    SplitByLine (me: mutable; seqw: in out SequenceOfWireSegment from ShapeFix;
                              line: Lin2d from gp;
			      cutbyu  : Boolean;
			      cutindex: Integer)
    is protected;
        ---Purpose: Split edges in the sequence of wires by cutting line.
	--          Wires with FORWARD or REVERSED orientation are considered
	--          as closed.
	--
	--          Parts of cutting line which get inside the face (defined by 
        --          parity check of intersections with all wires) are added 
        --          into that sequence (with orientation EXTERNAL). Each part
	--          is represented by one-edge wire segment with no 3d curve.
	--          They share common vertices with all wires they intersect.
        --          
	--          All modifications (splitting) are recorded in context, 
        --          except splitting of wires marked as EXTERNAL
	--          (they are supposed to be former cutting lines).
    
    SplitByGrid (me: mutable; seqw: in out SequenceOfWireSegment from ShapeFix)
    is protected;
        ---Purpose: Split initial set of (closed) wires by grid of lines corresponding 
	--          to joints between patches on the composite surface.
	--          Parts of joint lines which get inside the face are also added
	--          into the sequence as wires with orientation EXTERNAL.
	--          They share common vertices with all wires they intersect.
	--          All modifications (splitting) are recorded in context, 
        --          except splitting of joint edge itself and wires marked as
	--          EXTERNAL (they supposed to be another joint edges).
    
    BreakWires (me: mutable; seqw: in out SequenceOfWireSegment from ShapeFix)
    is protected;
        ---Purpose: Break wires into open wire segments by common vertices
	--          (splitting points), so that each segment is either closed and 
	--          not touching others, or touches others at ends (have common 
	--          vertices). 
        --          After that, each wire segment lies on its own patch of grid.
    
    CollectWires (me: mutable; wires: out SequenceOfWireSegment from ShapeFix;
    	    	               seqw : in out SequenceOfWireSegment from ShapeFix )
    is protected;
        ---Purpose: Collect set of wire segments (already splitted) into closed 
	--          wires. This is done by traversing all the segments in allowed
	--          directions, starting only from the REVERSED and FORWARD and
	--          taking EXTERNAL as necessary in fork points. Forks are detected
	--          by common vertices. In fork point, most left way is seleccted
        --          among all possible ways.
  
    MakeFacesOnPatch (me; faces: out SequenceOfShape from TopTools;
    	    	    	  surf : Surface from Geom;
			  loops: in out SequenceOfShape from TopTools)
    is protected;
    	---Purpose: Creates new faces on one path of grid. It dispatches given loops
	--          (wires) into one or several faces depending on their mutual
	--          position.
    
    DispatchWires (me; faces  : out SequenceOfShape from TopTools;
    	    	       wires  : in out SequenceOfWireSegment from ShapeFix);
        ---Purpose: Creates new faces from the set of (closed) wires. Each wire 
	--          is put on corresponding patch in the composite surface,
	--          and all pcurves on the initial (pseudo)face are reassigned to
	--          that surface. If several wires are one inside another, single
	--          face is created.
    
    SetTransferParamTool(me: mutable; TransferParam : TransferParameters from ShapeAnalysis);
    ---Purpose: Sets tool for transfer parameters from 3d to 2d and vice versa.
	
    GetTransferParamTool(me) returns TransferParameters from ShapeAnalysis; 
    ---Purpose: Gets tool for transfer parameters from 3d to 2d and vice versa.

fields

    myGrid     : CompositeSurface from ShapeExtend;
    myLoc      : Location from TopLoc;
    myFace     : Face from TopoDS;  -- underlying face for pcurves (real or pseudo)
    myOrient   : Orientation from TopAbs is protected;  -- orientation of face
    myResult   : Shape from TopoDS is protected;
    myStatus   : Integer is protected;
    myUResolution: Real;  -- summary resolution on grid (minimum on patches)
    myVResolution: Real;
    myTransferParamTool: TransferParameters from ShapeAnalysis;
    myInvertEdgeStatus : Boolean;
    myClosedMode       : Boolean;
    myUClosed  : Boolean;
    myVClosed  : Boolean;
    myUPeriod  : Real;
    myVPeriod  : Real;
    
end ComposeShell;
Commit	Line	Data
b311480e	1	-- Created on: 1999-04-26
	2	-- Created by: Andrey BETENEV
	3	-- Copyright (c) 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
d5f74e42	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
973c2be1	15	-- commercial license or contractual agreement.
7fd59977	16
	17	class ComposeShell from ShapeFix inherits Root from ShapeFix
	18
	19	---Purpose: This class is intended to create a shell from the composite
	20	-- surface (grid of surfaces) and set of wires.
	21	-- It may be either division of the supporting surface of the
	22	-- face, or creating a shape corresponding to face on composite
	23	-- surface which is missing in CAS.CADE but exists in some other
	24	-- systems.
	25	--
	26	-- It splits (if necessary) original face to several ones by
	27	-- splitting lines which are joint lines on a supplied grid of
	28	-- surfaces (U- and V- isolines of the composite surface).
	29	-- There are two modes of work, which differ in the way of
	30	-- handling faces on periodic surfaces:
	31	--
	32	-- - if ClosedMode is False (default), when splitting itself is
	33	-- done as if surface were not periodic. The periodicity of the
	34	-- underlying surface is taken into account by duplicating splitting
	35	-- lines in the periodic direction, as necessary to split all
	36	-- the wires (whole parametrical range of a face)
	37	-- In this mode, some regularization procedures are performed
	38	-- (indexation of splitted segments by patch numbers), and it is
	39	-- expected to be more reliable and robust in case of bad shapes
	40	--
	41	-- - if ClosedMode is True, when everything on a periodic surfaces
	42	-- is considered as modulo period. This allows to deal with wires
	43	-- which are closed in 3d but not in 2d, with wires which may be
	44	-- shifted on several periods in 2d etc. However, this mode is
	45	-- less reliable since some regularizations do not work for it.
	46	--
	47	-- The work is made basing on pcurves of the edges. These pcurves
	48	-- should already exist (for example, in the case of division of
	49	-- existing face), then they are taken as is. The existing pcurves
	50	-- should be assigned to one surface (face) for all edges,
	51	-- this surface (face) will be used only for accessing pcurves,
	52	-- and it may have any geometry.
	53	--
	54	-- All the modifications are recorded in the context tool
	55	-- (ShapeBuild_ReShape).
	56
	57	uses
	58	Lin2d from gp,
	59	Curve from Geom2d,
	60	Surface from Geom,
	61	Location from TopLoc,
	62	Edge from TopoDS,
	63	Face from TopoDS,
	64	Shape from TopoDS,
	65	Status from ShapeExtend,
	66	WireData from ShapeExtend,
	67	CompositeSurface from ShapeExtend,
	68	WireSegment from ShapeFix,
	69	Orientation from TopAbs,
	70	SequenceOfReal from TColStd,
	71	SequenceOfInteger from TColStd,
	72	SequenceOfShape from TopTools,
	73	SequenceOfWireSegment from ShapeFix,
	74	TransferParameters from ShapeAnalysis
	75	is
	76	Create returns ComposeShell from ShapeFix;
	77	---Purpose: Creates empty tool.
	78
	79	Init (me: mutable; Grid: CompositeSurface from ShapeExtend;
80	L : Location from TopLoc;
81	Face: Face from TopoDS;
82	Prec: Real);
83	---Purpose: Initializes with composite surface, face and precision.
84	-- Here face defines both set of wires and way of getting
85	-- pcurves. Precision is used (together with tolerance of edges)
86	-- for handling subtle cases, such as tangential intersections.
87
88	ClosedMode (me: mutable) returns Boolean;
89	---Purpose: Returns (modifiable) flag for special 'closed'
90	-- mode which forces ComposeShell to consider
91	-- all pcurves on closed surface as modulo period.
92	-- This can reduce reliability, but allows to deal
93	-- with wires closed in 3d but open in 2d (missing seam)
94	-- Default is False
95	---C++: return &
96
97	Perform (me: mutable)
98	returns Boolean is virtual;
99	---Purpose: Performs the work on already loaded data.
100
101	SplitEdges (me: mutable);
102	---Purpose: Splits edges in the original shape by grid.
103	-- This is a part of Perform() which does not produce any
104	-- resulting shape; the only result is filled context
105	-- where splittings are recorded.
106	--
107	-- NOTE: If edge is splitted, it is replaced by wire, and
108	-- order of edges in the wire corresponds to FORWARD orientation
109	-- of the edge.
110
111	Result (me) returns Shape from TopoDS;
112	---Purpose: Returns resulting shell or face (or Null shape if not done)
113	---C++: return const &
114
115	Status (me; status: Status from ShapeExtend) returns Boolean;
116	---Purpose: Queries status of last call to Perform()
117	-- OK : nothing done (some kind of error)
118	-- DONE1: splitting is done, at least one new face created
119	-- DONE2: splitting is done, several new faces obtained
120	-- FAIL1: misoriented wire encountered (handled)
121	-- FAIL2: recoverable parity error
122	-- FAIL3: edge with no pcurve on supporting face
123	-- FAIL4: unrecoverable algorithm error (parity check)
124
125	---Protected methods:
126
127	LoadWires (me; seqw: out SequenceOfWireSegment from ShapeFix)
128	is protected;
129	---Purpose: Fill sequence of wire segments by wires from myFace
130	-- (pre-loaded). It performs reorder so that edges in segments
131	-- are well-ordered. The context is applied to all wires
132	-- before using them.
133
134	ComputeCode (me: mutable; wire : WireData from ShapeExtend;
135	line : Lin2d from gp;
136	begInd: Integer;
137	endInd: Integer;
138	begPar: Real;
139	endPar: Real;
140	IsInternal : Boolean = Standard_False)
141	returns Integer is protected;
142	---Purpose: Analyze tangencies and compute orientation code for wire segment
143	-- between two intersections: tells if segment is on left or right side
144	-- of cutting line, or tangent to it (by several points recomputed to 3d,
145	-- distance is compared with tolerance of corresponding edge).
146
147	SplitWire (me: mutable; wire : in out WireSegment from ShapeFix;
148	indexes : in out SequenceOfInteger from TColStd;
149	values : SequenceOfReal from TColStd;
150	vertices: out SequenceOfShape from TopTools;
151	segcodes: SequenceOfInteger from TColStd;
152	cutbyu : Boolean;
153	cutindex: Integer)
154	returns WireSegment from ShapeFix is protected;
155	---Purpose: Splits edges in the wire by given indices of edges and
156	-- parameters on them. Returns resulting wire and vertices
157	-- corresponding to splitting parameters. If two consequtive
158	-- splitting points are too near one to another (with tolerance
159	-- of edge), edge is divided in single point. In the same way,
160	-- splitting which is too near to end of edge, is not applied
161	-- (end vertex is returned instead).
162	--
163	-- NOTE: If edge is splitted, it is replaced by wire, and
164	-- order of edges in the wire corresponds to FORWARD orientation
165	-- of the edge.
166
167	SplitByLine (me: mutable; wire : in out WireSegment from ShapeFix;
168	line : Lin2d from gp;
169	cutbyu : Boolean;
170	cutindex: Integer;
171	SplitLinePar : out SequenceOfReal from TColStd;
172	SplitLineCode : out SequenceOfInteger from TColStd;
173	SplitLineVertex: out SequenceOfShape from TopTools)
174	returns Boolean is protected;
175	---Purpose: Split edges in the wire by cutting line.
176	-- Wires with FORWARD or REVERSED orientation are considered
177	-- as closed.
178	--
179	-- All modifications (splitting) are recorded in context,
180	-- except splitting of wires marked as EXTERNAL
181	-- (they are supposed to be former cutting lines).
182	--
183	-- Method fills sequences of parameters of intersection points
184	-- of cutting line with all edges, their types, and corresponding
185	-- vertices (including ones created during splitting edges).
186
187	SplitByLine (me: mutable; seqw: in out SequenceOfWireSegment from ShapeFix;
188	line: Lin2d from gp;
189	cutbyu : Boolean;
190	cutindex: Integer)
191	is protected;
192	---Purpose: Split edges in the sequence of wires by cutting line.
193	-- Wires with FORWARD or REVERSED orientation are considered
194	-- as closed.
195	--
196	-- Parts of cutting line which get inside the face (defined by
197	-- parity check of intersections with all wires) are added
198	-- into that sequence (with orientation EXTERNAL). Each part
199	-- is represented by one-edge wire segment with no 3d curve.
200	-- They share common vertices with all wires they intersect.
201	--
202	-- All modifications (splitting) are recorded in context,
203	-- except splitting of wires marked as EXTERNAL
204	-- (they are supposed to be former cutting lines).
205
206	SplitByGrid (me: mutable; seqw: in out SequenceOfWireSegment from ShapeFix)
207	is protected;
208	---Purpose: Split initial set of (closed) wires by grid of lines corresponding
209	-- to joints between patches on the composite surface.
210	-- Parts of joint lines which get inside the face are also added
211	-- into the sequence as wires with orientation EXTERNAL.
212	-- They share common vertices with all wires they intersect.
213	-- All modifications (splitting) are recorded in context,
214	-- except splitting of joint edge itself and wires marked as
215	-- EXTERNAL (they supposed to be another joint edges).
216
217	BreakWires (me: mutable; seqw: in out SequenceOfWireSegment from ShapeFix)
218	is protected;
219	---Purpose: Break wires into open wire segments by common vertices
220	-- (splitting points), so that each segment is either closed and
221	-- not touching others, or touches others at ends (have common
222	-- vertices).
223	-- After that, each wire segment lies on its own patch of grid.
224
225	CollectWires (me: mutable; wires: out SequenceOfWireSegment from ShapeFix;
226	seqw : in out SequenceOfWireSegment from ShapeFix )
227	is protected;
228	---Purpose: Collect set of wire segments (already splitted) into closed
229	-- wires. This is done by traversing all the segments in allowed
230	-- directions, starting only from the REVERSED and FORWARD and
231	-- taking EXTERNAL as necessary in fork points. Forks are detected
232	-- by common vertices. In fork point, most left way is seleccted
233	-- among all possible ways.
234
235	MakeFacesOnPatch (me; faces: out SequenceOfShape from TopTools;
236	surf : Surface from Geom;
237	loops: in out SequenceOfShape from TopTools)
238	is protected;
239	---Purpose: Creates new faces on one path of grid. It dispatches given loops
240	-- (wires) into one or several faces depending on their mutual
241	-- position.
242
243	DispatchWires (me; faces : out SequenceOfShape from TopTools;
244	wires : in out SequenceOfWireSegment from ShapeFix);
245	---Purpose: Creates new faces from the set of (closed) wires. Each wire
246	-- is put on corresponding patch in the composite surface,
247	-- and all pcurves on the initial (pseudo)face are reassigned to
248	-- that surface. If several wires are one inside another, single
249	-- face is created.
250
251	SetTransferParamTool(me: mutable; TransferParam : TransferParameters from ShapeAnalysis);
252	---Purpose: Sets tool for transfer parameters from 3d to 2d and vice versa.
253
254	GetTransferParamTool(me) returns TransferParameters from ShapeAnalysis;
255	---Purpose: Gets tool for transfer parameters from 3d to 2d and vice versa.
256
257	fields
258
259	myGrid : CompositeSurface from ShapeExtend;
260	myLoc : Location from TopLoc;
261	myFace : Face from TopoDS; -- underlying face for pcurves (real or pseudo)
262	myOrient : Orientation from TopAbs is protected; -- orientation of face
263	myResult : Shape from TopoDS is protected;
264	myStatus : Integer is protected;
265	myUResolution: Real; -- summary resolution on grid (minimum on patches)
266	myVResolution: Real;
267	myTransferParamTool: TransferParameters from ShapeAnalysis;
268	myInvertEdgeStatus : Boolean;
269	myClosedMode : Boolean;
270	myUClosed : Boolean;
271	myVClosed : Boolean;
272	myUPeriod : Real;
273	myVPeriod : Real;
274
275	end ComposeShell;