[occt.git] / src / Poly / Poly_Triangulation.cdl

-- Created on: 1995-03-06
-- Created by: Laurent PAINNOT
-- Copyright (c) 1995-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 Triangulation from Poly inherits TShared from MMgt

        ---Purpose: Provides a triangulation for a surface, a set of surfaces, or
        -- more generally a shape.
        -- A triangulation consists of an approximate representation
        -- of the actual shape, using a collection of points and
        -- triangles. The points are located on the surface. The
        -- edges of the triangles connect adjacent points with a
        -- straight line that approximates the true curve on the surface.
        -- A triangulation comprises:
        -- -   A table of 3D nodes (3D points on the surface).
        -- -   A table of triangles. Each triangle (Poly_Triangle
        --   object) comprises a triplet of indices in the table of 3D
        --   nodes specific to the triangulation.
        -- -   A table of 2D nodes (2D points), parallel to the table of
        --   3D nodes. This table is optional. If it exists, the
        --   coordinates of a 2D point are the (u, v) parameters
        --   of the corresponding 3D point on the surface
        --   approximated by the triangulation.
        -- -   A deflection (optional), which maximizes the distance
        --   from a point on the surface to the corresponding point
        --   on its approximate triangulation.
        -- In many cases, algorithms do not need to work with the
        -- exact representation of a surface. A triangular
        -- representation induces simpler and more robust adjusting,
        -- faster performances, and the results are as good.
        -- This is a Transient class.

uses
   HArray1OfPnt2d    from TColgp,
   Array1OfPnt       from TColgp,
   Array1OfPnt2d     from TColgp,
   Array1OfTriangle  from Poly, 
   HArray1OfShortReal  from  TShort,
   Array1OfShortReal  from  TShort

raises
    DomainError from Standard,
    NullObject  from Standard

is

    Create(nbNodes, nbTriangles: Integer; UVNodes: Boolean)
    returns Triangulation from Poly;
        ---Purpose: Constructs a triangulation from a set of triangles. The
        -- triangulation is initialized without a triangle or a node, but capable of
        --   containing nbNodes nodes, and nbTriangles
        --   triangles. Here the UVNodes flag indicates whether
        --   2D nodes will be associated with 3D ones, (i.e. to
        --   enable a 2D representation).

    Create(Nodes:      Array1OfPnt      from TColgp;
           Triangles:  Array1OfTriangle from Poly)
    returns Triangulation from Poly;
        ---Purpose: Constructs a triangulation from a set of triangles. The
        -- triangulation is initialized with 3D points from Nodes and triangles
        --  from Triangles.

    Create(Nodes:      Array1OfPnt      from TColgp;
           UVNodes:    Array1OfPnt2d    from TColgp;
           Triangles:  Array1OfTriangle from Poly)
    returns Triangulation from Poly;
        ---Purpose:  Constructs a triangulation from a set of triangles. The
        -- triangulation is initialized with 3D points from Nodes, 2D points from
        --   UVNodes and triangles from Triangles, where
        --   coordinates of a 2D point from UVNodes are the
        --   (u, v) parameters of the corresponding 3D point
        --   from Nodes on the surface approximated by the
        --   constructed triangulation.

    Deflection(me) returns Real;
        ---Purpose: Returns the deflection of this triangulation.    
    Deflection(me : mutable; D : Real);
        ---Purpose: Sets the deflection of this triangulation to D.
        --    See more on deflection in Polygon2D
    RemoveUVNodes(me : mutable);
        ---Purpose: Deallocates the UV nodes.

    NbNodes(me) returns Integer;
        ---Purpose: Returns the number of nodes for this triangulation.
        -- Null if the nodes are not yet defined.
        ---C++: inline
          
    
    NbTriangles(me) returns Integer;
        ---Purpose: Returns the number of triangles for this triangulation.
        -- Null if the Triangles are not yet defined.
        ---C++: inline

    HasUVNodes(me) returns Boolean;
        ---Purpose: Returns true if 2D nodes are associated with 3D nodes for
        -- this triangulation.
        ---C++: inline


    Nodes(me) returns Array1OfPnt from TColgp
        ---Purpose:  Returns the table of 3D nodes (3D points) for this triangulation.
        ---C++: return const &
    raises NullObject from Standard;

    ChangeNodes(me : mutable) returns Array1OfPnt from TColgp
        ---Purpose:  Returns the table of 3D nodes (3D points) for this triangulation.
        --        The returned array is
        -- shared. Therefore if the table is selected by reference, you
        -- can, by simply modifying it, directly modify the data
        -- structure of this triangulation.
        ---C++: return &
     raises NullObject from Standard;

    UVNodes(me) returns Array1OfPnt2d from TColgp
        ---Purpose: Returns the table of 2D nodes (2D points) associated with
        -- each 3D node of this triangulation.
        -- The function HasUVNodes  checks if 2D nodes
        -- are associated with the 3D nodes of this triangulation.
        -- Const reference on the 2d nodes values.
        ---C++: return const &
    raises NullObject from Standard;

    ChangeUVNodes(me : mutable) returns Array1OfPnt2d from TColgp
        ---Purpose: Returns the table of 2D nodes (2D points) associated with
        -- each 3D node of this triangulation.
        -- Function ChangeUVNodes shares  the returned array.
        --   Therefore if the table is selected by reference,
        --   you can, by simply modifying it, directly modify the data
        --   structure of this triangulation.
        ---C++: return &
    raises NullObject from Standard;

    Triangles(me) returns Array1OfTriangle from Poly
        ---Purpose: Returns the table of triangles for this triangulation.
        ---C++: return const &
    raises NullObject from Standard;

    ChangeTriangles(me : mutable) returns Array1OfTriangle from Poly
        ---Purpose:  Returns the table of triangles for this triangulation.       
        -- Function ChangeUVNodes shares  the returned array.
        --   Therefore if the table is selected by reference,
        --   you can, by simply modifying it, directly modify the data
        --   structure of this triangulation.
        ---C++: return &
    raises NullObject from Standard; 
     
    SetNormals(me :  mutable;  theNormals : HArray1OfShortReal from TShort) 
        ---Purpose:  Sets the table of node normals. 
        -- raises exception if length of theNormals != 3*NbNodes 
    raises DomainError from Standard; 
     
    Normals(me) returns Array1OfShortReal from TShort
        ---C++: return const & 
        --  raises exception if array of normals is empty or   
        --  its length  != 3*NbNodes
    raises NullObject from Standard;

    ChangeNormals(me : mutable) returns Array1OfShortReal from TShort
        ---C++: return & 
        --  raises exception if array of normals is empty or   
        --  its length  != 3*NbNodes
    raises NullObject from Standard; 
     
    HasNormals(me)  returns  Boolean  from  Standard;

fields

    myDeflection  : Real;
    myNbNodes     : Integer;
    myNbTriangles : Integer;
    myNodes       : Array1OfPnt      from TColgp;
    myUVNodes     : HArray1OfPnt2d   from TColgp;
    myTriangles   : Array1OfTriangle from Poly; 
     
    ----  Optional normals  --- 
    myNormals     : HArray1OfShortReal from TShort;

end Triangulation;
Commit	Line	Data
b311480e	1	-- Created on: 1995-03-06
	2	-- Created by: Laurent PAINNOT
	3	-- Copyright (c) 1995-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 Triangulation from Poly inherits TShared from MMgt
	18
	19	---Purpose: Provides a triangulation for a surface, a set of surfaces, or
	20	-- more generally a shape.
	21	-- A triangulation consists of an approximate representation
	22	-- of the actual shape, using a collection of points and
	23	-- triangles. The points are located on the surface. The
	24	-- edges of the triangles connect adjacent points with a
	25	-- straight line that approximates the true curve on the surface.
	26	-- A triangulation comprises:
	27	-- - A table of 3D nodes (3D points on the surface).
	28	-- - A table of triangles. Each triangle (Poly_Triangle
	29	-- object) comprises a triplet of indices in the table of 3D
	30	-- nodes specific to the triangulation.
	31	-- - A table of 2D nodes (2D points), parallel to the table of
	32	-- 3D nodes. This table is optional. If it exists, the
	33	-- coordinates of a 2D point are the (u, v) parameters
	34	-- of the corresponding 3D point on the surface
	35	-- approximated by the triangulation.
	36	-- - A deflection (optional), which maximizes the distance
	37	-- from a point on the surface to the corresponding point
	38	-- on its approximate triangulation.
	39	-- In many cases, algorithms do not need to work with the
	40	-- exact representation of a surface. A triangular
	41	-- representation induces simpler and more robust adjusting,
	42	-- faster performances, and the results are as good.
ff8178ef	43	-- This is a Transient class.
7fd59977	44
	45	uses
	46	HArray1OfPnt2d from TColgp,
	47	Array1OfPnt from TColgp,
	48	Array1OfPnt2d from TColgp,
	49	Array1OfTriangle from Poly,
	50	HArray1OfShortReal from TShort,
	51	Array1OfShortReal from TShort
	52
	53	raises
	54	DomainError from Standard,
	55	NullObject from Standard
	56
	57	is
	58
	59	Create(nbNodes, nbTriangles: Integer; UVNodes: Boolean)
6e33d3ce	60	returns Triangulation from Poly;
7fd59977	61	---Purpose: Constructs a triangulation from a set of triangles. The
	62	-- triangulation is initialized without a triangle or a node, but capable of
	63	-- containing nbNodes nodes, and nbTriangles
	64	-- triangles. Here the UVNodes flag indicates whether
	65	-- 2D nodes will be associated with 3D ones, (i.e. to
	66	-- enable a 2D representation).
	67
	68	Create(Nodes: Array1OfPnt from TColgp;
	69	Triangles: Array1OfTriangle from Poly)
6e33d3ce	70	returns Triangulation from Poly;
7fd59977	71	---Purpose: Constructs a triangulation from a set of triangles. The
	72	-- triangulation is initialized with 3D points from Nodes and triangles
	73	-- from Triangles.
	74
	75	Create(Nodes: Array1OfPnt from TColgp;
	76	UVNodes: Array1OfPnt2d from TColgp;
	77	Triangles: Array1OfTriangle from Poly)
6e33d3ce	78	returns Triangulation from Poly;
7fd59977	79	---Purpose: Constructs a triangulation from a set of triangles. The
	80	-- triangulation is initialized with 3D points from Nodes, 2D points from
	81	-- UVNodes and triangles from Triangles, where
	82	-- coordinates of a 2D point from UVNodes are the
	83	-- (u, v) parameters of the corresponding 3D point
	84	-- from Nodes on the surface approximated by the
	85	-- constructed triangulation.
	86
	87	Deflection(me) returns Real;
	88	---Purpose: Returns the deflection of this triangulation.
	89	Deflection(me : mutable; D : Real);
	90	---Purpose: Sets the deflection of this triangulation to D.
	91	-- See more on deflection in Polygon2D
	92	RemoveUVNodes(me : mutable);
	93	---Purpose: Deallocates the UV nodes.
	94
	95	NbNodes(me) returns Integer;
	96	---Purpose: Returns the number of nodes for this triangulation.
	97	-- Null if the nodes are not yet defined.
	98	---C++: inline
	99
	100
	101	NbTriangles(me) returns Integer;
	102	---Purpose: Returns the number of triangles for this triangulation.
	103	-- Null if the Triangles are not yet defined.
	104	---C++: inline
	105
	106	HasUVNodes(me) returns Boolean;
	107	---Purpose: Returns true if 2D nodes are associated with 3D nodes for
	108	-- this triangulation.
	109	---C++: inline
	110
	111
	112	Nodes(me) returns Array1OfPnt from TColgp
	113	---Purpose: Returns the table of 3D nodes (3D points) for this triangulation.
	114	---C++: return const &
	115	raises NullObject from Standard;
	116
	117	ChangeNodes(me : mutable) returns Array1OfPnt from TColgp
	118	---Purpose: Returns the table of 3D nodes (3D points) for this triangulation.
	119	-- The returned array is
	120	-- shared. Therefore if the table is selected by reference, you
	121	-- can, by simply modifying it, directly modify the data
	122	-- structure of this triangulation.
	123	---C++: return &
	124	raises NullObject from Standard;
	125
	126	UVNodes(me) returns Array1OfPnt2d from TColgp
	127	---Purpose: Returns the table of 2D nodes (2D points) associated with
	128	-- each 3D node of this triangulation.
	129	-- The function HasUVNodes checks if 2D nodes
	130	-- are associated with the 3D nodes of this triangulation.
	131	-- Const reference on the 2d nodes values.
	132	---C++: return const &
	133	raises NullObject from Standard;
	134
	135	ChangeUVNodes(me : mutable) returns Array1OfPnt2d from TColgp
	136	---Purpose: Returns the table of 2D nodes (2D points) associated with
	137	-- each 3D node of this triangulation.
	138	-- Function ChangeUVNodes shares the returned array.
	139	-- Therefore if the table is selected by reference,
	140	-- you can, by simply modifying it, directly modify the data
	141	-- structure of this triangulation.
	142	---C++: return &
143	raises NullObject from Standard;
144
145	Triangles(me) returns Array1OfTriangle from Poly
146	---Purpose: Returns the table of triangles for this triangulation.
147	---C++: return const &
148	raises NullObject from Standard;
149
150	ChangeTriangles(me : mutable) returns Array1OfTriangle from Poly
151	---Purpose: Returns the table of triangles for this triangulation.
152	-- Function ChangeUVNodes shares the returned array.
153	-- Therefore if the table is selected by reference,
154	-- you can, by simply modifying it, directly modify the data
155	-- structure of this triangulation.
156	---C++: return &
157	raises NullObject from Standard;
158
159	SetNormals(me : mutable; theNormals : HArray1OfShortReal from TShort)
160	---Purpose: Sets the table of node normals.
161	-- raises exception if length of theNormals != 3*NbNodes
162	raises DomainError from Standard;
163
164	Normals(me) returns Array1OfShortReal from TShort
165	---C++: return const &
166	-- raises exception if array of normals is empty or
167	-- its length != 3*NbNodes
168	raises NullObject from Standard;
169
170	ChangeNormals(me : mutable) returns Array1OfShortReal from TShort
171	---C++: return &
172	-- raises exception if array of normals is empty or
173	-- its length != 3*NbNodes
174	raises NullObject from Standard;
175
176	HasNormals(me) returns Boolean from Standard;
177
178	fields
179
180	myDeflection : Real;
181	myNbNodes : Integer;
182	myNbTriangles : Integer;
183	myNodes : Array1OfPnt from TColgp;
184	myUVNodes : HArray1OfPnt2d from TColgp;
185	myTriangles : Array1OfTriangle from Poly;
186
187	---- Optional normals ---
188	myNormals : HArray1OfShortReal from TShort;
189
190	end Triangulation;