1 // Created on: 1995-03-06
2 // Created by: Laurent PAINNOT
3 // Copyright (c) 1995-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
6 // This file is part of Open CASCADE Technology software library.
8 // This library is free software; you can redistribute it and/or modify it under
9 // the terms of the GNU Lesser General Public License version 2.1 as published
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.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _Poly_Triangulation_HeaderFile
18 #define _Poly_Triangulation_HeaderFile
20 #include <Bnd_Box.hxx>
21 #include <gp_Vec3f.hxx>
22 #include <Poly_HArray1OfTriangle.hxx>
23 #include <Poly_ArrayOfNodes.hxx>
24 #include <Poly_ArrayOfUVNodes.hxx>
25 #include <Poly_MeshPurpose.hxx>
26 #include <TColgp_HArray1OfPnt.hxx>
27 #include <TColgp_HArray1OfPnt2d.hxx>
28 #include <TShort_HArray1OfShortReal.hxx>
31 class Poly_Triangulation;
32 class Poly_TriangulationParameters;
34 DEFINE_STANDARD_HANDLE(Poly_Triangulation, Standard_Transient)
36 //! Provides a triangulation for a surface, a set of surfaces, or more generally a shape.
38 //! A triangulation consists of an approximate representation of the actual shape,
39 //! using a collection of points and triangles.
40 //! The points are located on the surface.
41 //! The edges of the triangles connect adjacent points with a straight line that approximates the true curve on the surface.
43 //! A triangulation comprises:
44 //! - A table of 3D nodes (3D points on the surface).
45 //! - A table of triangles.
46 //! Each triangle (Poly_Triangle object) comprises a triplet of indices in the table of 3D nodes specific to the triangulation.
47 //! - An optional table of 2D nodes (2D points), parallel to the table of 3D nodes.
48 //! 2D point are the (u, v) parameters of the corresponding 3D point on the surface approximated by the triangulation.
49 //! - An optional table of 3D vectors, parallel to the table of 3D nodes, defining normals to the surface at specified 3D point.
50 //! - An optional deflection, which maximizes the distance from a point on the surface to the corresponding point on its approximate triangulation.
52 //! In many cases, algorithms do not need to work with the exact representation of a surface.
53 //! A triangular representation induces simpler and more robust adjusting, faster performances, and the results are as good.
54 class Poly_Triangulation : public Standard_Transient
56 DEFINE_STANDARD_RTTIEXT(Poly_Triangulation, Standard_Transient)
59 //! Constructs an empty triangulation.
60 Standard_EXPORT Poly_Triangulation();
62 //! Constructs a triangulation from a set of triangles.
63 //! The triangulation is initialized without a triangle or a node,
64 //! but capable of containing specified number of nodes and triangles.
65 //! @param theNbNodes [in] number of nodes to allocate
66 //! @param theNbTriangles [in] number of triangles to allocate
67 //! @param theHasUVNodes [in] indicates whether 2D nodes will be associated with 3D ones,
68 //! (i.e. to enable a 2D representation)
69 //! @param theHasNormals [in] indicates whether normals will be given and associated with nodes
70 Standard_EXPORT Poly_Triangulation (const Standard_Integer theNbNodes,
71 const Standard_Integer theNbTriangles,
72 const Standard_Boolean theHasUVNodes,
73 const Standard_Boolean theHasNormals = false);
75 //! Constructs a triangulation from a set of triangles. The
76 //! triangulation is initialized with 3D points from Nodes and triangles
78 Standard_EXPORT Poly_Triangulation(const TColgp_Array1OfPnt& Nodes, const Poly_Array1OfTriangle& Triangles);
80 //! Constructs a triangulation from a set of triangles. The
81 //! triangulation is initialized with 3D points from Nodes, 2D points from
82 //! UVNodes and triangles from Triangles, where
83 //! coordinates of a 2D point from UVNodes are the
84 //! (u, v) parameters of the corresponding 3D point
85 //! from Nodes on the surface approximated by the
86 //! constructed triangulation.
87 Standard_EXPORT Poly_Triangulation(const TColgp_Array1OfPnt& Nodes, const TColgp_Array1OfPnt2d& UVNodes, const Poly_Array1OfTriangle& Triangles);
90 Standard_EXPORT virtual ~Poly_Triangulation();
92 //! Creates full copy of current triangulation
93 Standard_EXPORT virtual Handle(Poly_Triangulation) Copy() const;
95 //! Copy constructor for triangulation.
96 Standard_EXPORT Poly_Triangulation (const Handle(Poly_Triangulation)& theTriangulation);
98 //! Returns the deflection of this triangulation.
99 Standard_Real Deflection() const { return myDeflection; }
101 //! Sets the deflection of this triangulation to theDeflection.
102 //! See more on deflection in Polygon2D
103 void Deflection (const Standard_Real theDeflection) { myDeflection = theDeflection; }
105 //! Returns initial set of parameters used to generate this triangulation.
106 const Handle(Poly_TriangulationParameters)& Parameters() const { return myParams; }
108 //! Updates initial set of parameters used to generate this triangulation.
109 void Parameters (const Handle(Poly_TriangulationParameters)& theParams) { myParams = theParams; }
111 //! Clears internal arrays of nodes and all attributes.
112 Standard_EXPORT virtual void Clear();
114 //! Returns TRUE if triangulation has some geometry.
115 virtual Standard_Boolean HasGeometry() const { return !myNodes.IsEmpty() && !myTriangles.IsEmpty(); }
117 //! Returns the number of nodes for this triangulation.
118 Standard_Integer NbNodes() const { return myNodes.Length(); }
120 //! Returns the number of triangles for this triangulation.
121 Standard_Integer NbTriangles() const { return myTriangles.Length(); }
123 //! Returns Standard_True if 2D nodes are associated with 3D nodes for this triangulation.
124 Standard_Boolean HasUVNodes() const { return !myUVNodes.IsEmpty(); }
126 //! Returns Standard_True if nodal normals are defined.
127 Standard_Boolean HasNormals() const { return !myNormals.IsEmpty(); }
129 //! Returns a node at the given index.
130 //! @param[in] theIndex node index within [1, NbNodes()] range
131 //! @return 3D point coordinates
132 gp_Pnt Node (Standard_Integer theIndex) const { return myNodes.Value (theIndex - 1); }
134 //! Sets a node coordinates.
135 //! @param[in] theIndex node index within [1, NbNodes()] range
136 //! @param[in] thePnt 3D point coordinates
137 void SetNode (Standard_Integer theIndex,
138 const gp_Pnt& thePnt)
140 myNodes.SetValue (theIndex - 1, thePnt);
143 //! Returns UV-node at the given index.
144 //! @param[in] theIndex node index within [1, NbNodes()] range
145 //! @return 2D point defining UV coordinates
146 gp_Pnt2d UVNode (Standard_Integer theIndex) const { return myUVNodes.Value (theIndex - 1); }
148 //! Sets an UV-node coordinates.
149 //! @param[in] theIndex node index within [1, NbNodes()] range
150 //! @param[in] thePnt UV coordinates
151 void SetUVNode (Standard_Integer theIndex,
152 const gp_Pnt2d& thePnt)
154 myUVNodes.SetValue (theIndex - 1, thePnt);
157 //! Returns triangle at the given index.
158 //! @param[in] theIndex triangle index within [1, NbTriangles()] range
159 //! @return triangle node indices, with each node defined within [1, NbNodes()] range
160 const Poly_Triangle& Triangle (Standard_Integer theIndex) const { return myTriangles.Value (theIndex); }
163 //! @param[in] theIndex triangle index within [1, NbTriangles()] range
164 //! @param[in] theTriangle triangle node indices, with each node defined within [1, NbNodes()] range
165 void SetTriangle (Standard_Integer theIndex,
166 const Poly_Triangle& theTriangle)
168 myTriangles.SetValue (theIndex, theTriangle);
171 //! Returns normal at the given index.
172 //! @param[in] theIndex node index within [1, NbNodes()] range
173 //! @return normalized 3D vector defining a surface normal
174 gp_Dir Normal (Standard_Integer theIndex) const
176 const gp_Vec3f& aNorm = myNormals.Value (theIndex - 1);
177 return gp_Dir (aNorm.x(), aNorm.y(), aNorm.z());
180 //! Returns normal at the given index.
181 //! @param[in] theIndex node index within [1, NbNodes()] range
182 //! @param[out] theVec3 3D vector defining a surface normal
183 void Normal (Standard_Integer theIndex,
184 gp_Vec3f& theVec3) const
186 theVec3 = myNormals.Value (theIndex - 1);
189 //! Changes normal at the given index.
190 //! @param[in] theIndex node index within [1, NbNodes()] range
191 //! @param[in] theVec3 normalized 3D vector defining a surface normal
192 void SetNormal (const Standard_Integer theIndex,
193 const gp_Vec3f& theNormal)
195 myNormals.SetValue (theIndex - 1, theNormal);
198 //! Changes normal at the given index.
199 //! @param[in] theIndex node index within [1, NbNodes()] range
200 //! @param[in] theNormal normalized 3D vector defining a surface normal
201 void SetNormal (const Standard_Integer theIndex,
202 const gp_Dir& theNormal)
204 SetNormal (theIndex, gp_Vec3f (float(theNormal.X()),
205 float(theNormal.Y()),
206 float(theNormal.Z())));
209 //! Returns mesh purpose bits.
210 Poly_MeshPurpose MeshPurpose() const { return myPurpose; }
212 //! Sets mesh purpose bits.
213 void SetMeshPurpose (const Poly_MeshPurpose thePurpose) { myPurpose = thePurpose; }
215 //! Returns cached min - max range of triangulation data,
216 //! which is VOID by default (e.g, no cached information).
217 Standard_EXPORT const Bnd_Box& CachedMinMax() const;
219 //! Sets a cached min - max range of this triangulation.
220 //! The bounding box should exactly match actual range of triangulation data
221 //! without a gap or transformation, or otherwise undefined behavior will be observed.
222 //! Passing a VOID range invalidates the cache.
223 Standard_EXPORT void SetCachedMinMax (const Bnd_Box& theBox);
225 //! Returns TRUE if there is some cached min - max range of this triangulation.
226 Standard_EXPORT Standard_Boolean HasCachedMinMax() const { return myCachedMinMax != NULL; }
228 //! Updates cached min - max range of this triangulation with bounding box of nodal data.
229 void UpdateCachedMinMax()
232 MinMax (aBox, gp_Trsf(), true);
233 SetCachedMinMax (aBox);
236 //! Extends the passed box with bounding box of this triangulation.
237 //! Uses cached min - max range when available and:
238 //! - input transformation theTrsf has no rotation part;
239 //! - theIsAccurate is set to FALSE;
240 //! - no triangulation data available (e.g. it is deferred and not loaded).
241 //! @param theBox [in] [out] bounding box to extend by this triangulation
242 //! @param theTrsf [in] optional transformation
243 //! @param theIsAccurate [in] when FALSE, allows using a cached min - max range of this triangulation
244 //! even for non-identity transformation.
245 //! @return FALSE if there is no any data to extend the passed box (no both triangulation and cached min - max range).
246 Standard_EXPORT Standard_Boolean MinMax (Bnd_Box& theBox, const gp_Trsf& theTrsf, const bool theIsAccurate = false) const;
248 //! Dumps the content of me into the stream
249 Standard_EXPORT virtual void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
253 //! Returns TRUE if node positions are defined with double precision; TRUE by default.
254 bool IsDoublePrecision() const { return myNodes.IsDoublePrecision(); }
256 //! Set if node positions should be defined with double or single precision for 3D and UV nodes.
257 //! Raises exception if data was already allocated.
258 Standard_EXPORT void SetDoublePrecision (bool theIsDouble);
260 //! Method resizing internal arrays of nodes (synchronously for all attributes).
261 //! @param theNbNodes [in] new number of nodes
262 //! @param theToCopyOld [in] copy old nodes into the new array
263 Standard_EXPORT void ResizeNodes (Standard_Integer theNbNodes,
264 Standard_Boolean theToCopyOld);
266 //! Method resizing an internal array of triangles.
267 //! @param theNbTriangles [in] new number of triangles
268 //! @param theToCopyOld [in] copy old triangles into the new array
269 Standard_EXPORT void ResizeTriangles (Standard_Integer theNbTriangles,
270 Standard_Boolean theToCopyOld);
272 //! If an array for UV coordinates is not allocated yet, do it now.
273 Standard_EXPORT void AddUVNodes();
275 //! Deallocates the UV nodes array.
276 Standard_EXPORT void RemoveUVNodes();
278 //! If an array for normals is not allocated yet, do it now.
279 Standard_EXPORT void AddNormals();
281 //! Deallocates the normals array.
282 Standard_EXPORT void RemoveNormals();
284 //! Compute smooth normals by averaging triangle normals.
285 Standard_EXPORT void ComputeNormals();
289 //! Returns the table of 3D points for read-only access or NULL if nodes array is undefined.
290 //! Poly_Triangulation::Node() should be used instead when possible.
291 //! Returned object should not be used after Poly_Triangulation destruction.
292 Standard_EXPORT Handle(TColgp_HArray1OfPnt) MapNodeArray() const;
294 //! Returns the triangle array for read-only access or NULL if triangle array is undefined.
295 //! Poly_Triangulation::Triangle() should be used instead when possible.
296 //! Returned object should not be used after Poly_Triangulation destruction.
297 Standard_EXPORT Handle(Poly_HArray1OfTriangle) MapTriangleArray() const;
299 //! Returns the table of 2D nodes for read-only access or NULL if UV nodes array is undefined.
300 //! Poly_Triangulation::UVNode() should be used instead when possible.
301 //! Returned object should not be used after Poly_Triangulation destruction.
302 Standard_EXPORT Handle(TColgp_HArray1OfPnt2d) MapUVNodeArray() const;
304 //! Returns the table of per-vertex normals for read-only access or NULL if normals array is undefined.
305 //! Poly_Triangulation::Normal() should be used instead when possible.
306 //! Returned object should not be used after Poly_Triangulation destruction.
307 Standard_EXPORT Handle(TShort_HArray1OfShortReal) MapNormalArray() const;
311 //! Returns an internal array of triangles.
312 //! Triangle()/SetTriangle() should be used instead in portable code.
313 Poly_Array1OfTriangle& InternalTriangles() { return myTriangles; }
315 //! Returns an internal array of nodes.
316 //! Node()/SetNode() should be used instead in portable code.
317 Poly_ArrayOfNodes& InternalNodes() { return myNodes; }
319 //! Returns an internal array of UV nodes.
320 //! UBNode()/SetUVNode() should be used instead in portable code.
321 Poly_ArrayOfUVNodes& InternalUVNodes() { return myUVNodes; }
323 //! Return an internal array of normals.
324 //! Normal()/SetNormal() should be used instead in portable code.
325 NCollection_Array1<gp_Vec3f>& InternalNormals() { return myNormals; }
327 Standard_DEPRECATED("Deprecated method, SetNormal() should be used instead")
328 Standard_EXPORT void SetNormals (const Handle(TShort_HArray1OfShortReal)& theNormals);
330 Standard_DEPRECATED("Deprecated method, Triangle() should be used instead")
331 const Poly_Array1OfTriangle& Triangles() const { return myTriangles; }
333 Standard_DEPRECATED("Deprecated method, SetTriangle() should be used instead")
334 Poly_Array1OfTriangle& ChangeTriangles() { return myTriangles; }
336 Standard_DEPRECATED("Deprecated method, SetTriangle() should be used instead")
337 Poly_Triangle& ChangeTriangle (const Standard_Integer theIndex) { return myTriangles.ChangeValue (theIndex); }
339 public: //! @name late-load deferred data interface
341 //! Returns number of deferred nodes that can be loaded using LoadDeferredData().
342 //! Note: this is estimated values, which might be different from actually loaded values.
343 //! Always check triangulation size of actually loaded data in code to avoid out-of-range issues.
344 virtual Standard_Integer NbDeferredNodes() const { return 0; }
346 //! Returns number of deferred triangles that can be loaded using LoadDeferredData().
347 //! Note: this is estimated values, which might be different from actually loaded values
348 //! Always check triangulation size of actually loaded data in code to avoid out-of-range issues.
349 virtual Standard_Integer NbDeferredTriangles() const { return 0; }
351 //! Returns TRUE if there is some triangulation data that can be loaded using LoadDeferredData().
352 virtual Standard_Boolean HasDeferredData() const { return NbDeferredTriangles() > 0; }
354 //! Loads triangulation data into itself
355 //! from some deferred storage using specified shared input file system.
356 Standard_EXPORT virtual Standard_Boolean LoadDeferredData (const Handle(OSD_FileSystem)& theFileSystem = Handle(OSD_FileSystem)());
358 //! Loads triangulation data into new Poly_Triangulation object
359 //! from some deferred storage using specified shared input file system.
360 Standard_EXPORT virtual Handle(Poly_Triangulation) DetachedLoadDeferredData
361 (const Handle(OSD_FileSystem)& theFileSystem = Handle(OSD_FileSystem)()) const;
363 //! Releases triangulation data if it has connected deferred storage.
364 Standard_EXPORT virtual Standard_Boolean UnloadDeferredData();
368 //! Creates new triangulation object (can be inheritor of Poly_Triangulation).
369 virtual Handle(Poly_Triangulation) createNewEntity() const
371 return new Poly_Triangulation();
374 //! Load triangulation data from deferred storage using specified shared input file system.
375 virtual Standard_Boolean loadDeferredData (const Handle(OSD_FileSystem)& theFileSystem,
376 const Handle(Poly_Triangulation)& theDestTriangulation) const
378 (void )theFileSystem;
379 (void )theDestTriangulation;
385 //! Clears cached min - max range saved previously.
386 Standard_EXPORT void unsetCachedMinMax();
388 //! Calculates bounding box of nodal data.
389 //! @param theTrsf [in] optional transformation.
390 Standard_EXPORT virtual Bnd_Box computeBoundingBox (const gp_Trsf& theTrsf) const;
394 Bnd_Box* myCachedMinMax;
395 Standard_Real myDeflection;
396 Poly_ArrayOfNodes myNodes;
397 Poly_Array1OfTriangle myTriangles;
398 Poly_ArrayOfUVNodes myUVNodes;
399 NCollection_Array1<gp_Vec3f> myNormals;
400 Poly_MeshPurpose myPurpose;
402 Handle(Poly_TriangulationParameters) myParams;
405 #endif // _Poly_Triangulation_HeaderFile