0031939: Coding - correction of spelling errors in comments [part 3]
[occt.git] / src / GeomAPI / GeomAPI_PointsToBSplineSurface.hxx
1 // Created on: 1995-01-16
2 // Created by: Remi LEQUETTE
3 // Copyright (c) 1995-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
5 //
6 // This file is part of Open CASCADE Technology software library.
7 //
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.
13 //
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
16
17 #ifndef _GeomAPI_PointsToBSplineSurface_HeaderFile
18 #define _GeomAPI_PointsToBSplineSurface_HeaderFile
19
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
23
24 #include <Standard_Boolean.hxx>
25 #include <TColgp_Array2OfPnt.hxx>
26 #include <Standard_Integer.hxx>
27 #include <GeomAbs_Shape.hxx>
28 #include <Standard_Real.hxx>
29 #include <Approx_ParametrizationType.hxx>
30 #include <TColStd_Array2OfReal.hxx>
31 class Geom_BSplineSurface;
32 class StdFail_NotDone;
33
34
35 //! This class is used to approximate or interpolate
36 //! a BSplineSurface passing through an  Array2 of
37 //! points, with a given continuity.
38 //! Describes functions for building a BSpline
39 //! surface which approximates or interpolates a set of points.
40 //! A PointsToBSplineSurface object provides a framework for:
41 //! -   defining the data of the BSpline surface to be built,
42 //! -   implementing the approximation algorithm
43 //! or the interpolation algorithm, and consulting the results.
44 //! In fact, class contains 3 algorithms, 2 for approximation and 1
45 //! for interpolation.
46 //! First approximation algorithm is based on usual least square criterium:
47 //! minimization of square distance between samplimg points and result surface.
48 //! Second approximation algorithm uses least square criterium and additional 
49 //! minimization of some local characteristic of surface (first, second and third
50 //! partial derivative), which allows managing shape of surface. 
51 //! Interpolation algorithm produces surface, which passes through sampling points.
52 //!
53 //! There is accordance between parametrization of result surface S(U, V) and
54 //! indexes of array Points(i, j): first index corresponds U parameter of surface, 
55 //! second - V parameter of surface.
56 //! So, points of any j-th column Points(*, j) represent any V isoline of surface,
57 //! points of any i-th row Point(i, *) represent any U isoline of surface.
58 //! 
59 //! For each sampling point parameters U, V are calculated according to 
60 //! type of parametrization, which can be Approx_ChordLength, Approx_Centripetal 
61 //! or Approx_IsoParametric. Default value is Approx_ChordLength.
62 //! For ChordLength parametrisation U(i) = U(i-1) + P(i).Distance(P(i-1)),
63 //! For Centripetal type  U(i) = U(i-1) + Sqrt(P(i).Distance(P(i-1))).
64 //! Centripetal type can get better result for irregular distances between points.
65 //!
66 //! Approximation and interpolation algorithms can build periodical surface along U
67 //! direction, which corresponds columns of array Points(i, j), 
68 //! if corresponding parameter (thePeriodic, see comments below) of called 
69 //! methods is set to True. Algorithm uses first row Points(1, *) as periodic boundary,
70 //! so to avoid getting wrong surface it is necessary to keep distance between 
71 //! corresponding points of first and last rows of Points:
72 //! Points(1, *) != Points(Upper, *).
73
74 class GeomAPI_PointsToBSplineSurface
75 {
76 public:
77
78   DEFINE_STANDARD_ALLOC
79
80   
81   //! Constructs an empty algorithm for
82   //! approximation or interpolation of a surface.
83   //! Use:
84   //! -   an Init function to define and build the
85   //! BSpline surface by approximation, or
86   //! -   an Interpolate function to define and build
87   //! the BSpline surface by interpolation.
88   Standard_EXPORT GeomAPI_PointsToBSplineSurface();
89   
90   //! Approximates  a BSpline  Surface passing  through  an
91   //! array of  Points.  The resulting BSpline will  have
92   //! the following properties:
93   //! 1- his degree will be in the range [Degmin,Degmax]
94   //! 2- his  continuity will be  at  least <Continuity>
95   //! 3- the distance from the point <Points> to the
96   //! BSpline will be lower to Tol3D.
97
98   Standard_EXPORT GeomAPI_PointsToBSplineSurface(const TColgp_Array2OfPnt& Points, 
99     const Standard_Integer DegMin = 3, const Standard_Integer DegMax = 8, 
100     const GeomAbs_Shape Continuity = GeomAbs_C2, const Standard_Real Tol3D = 1.0e-3);
101   
102   //! Approximates  a BSpline  Surface passing  through  an
103   //! array of  Points.  The resulting BSpline will  have
104   //! the following properties:
105   //! 1- his degree will be in the range [Degmin,Degmax]
106   //! 2- his  continuity will be  at  least <Continuity>
107   //! 3- the distance from the point <Points> to the
108   //! BSpline will be lower to Tol3D.
109
110   Standard_EXPORT GeomAPI_PointsToBSplineSurface(const TColgp_Array2OfPnt& Points, 
111     const Approx_ParametrizationType ParType, 
112     const Standard_Integer DegMin = 3, const Standard_Integer DegMax = 8, 
113     const GeomAbs_Shape Continuity = GeomAbs_C2, const Standard_Real Tol3D = 1.0e-3);
114   
115   //! Approximates  a BSpline  Surface passing  through  an
116   //! array of  points using variational smoothing algorithm,
117   //! which tries to minimize additional criterium:
118   //! Weight1*CurveLength + Weight2*Curvature + Weight3*Torsion.
119
120   Standard_EXPORT GeomAPI_PointsToBSplineSurface(const TColgp_Array2OfPnt& Points, 
121     const Standard_Real Weight1, const Standard_Real Weight2, const Standard_Real Weight3, 
122     const Standard_Integer DegMax = 8, const GeomAbs_Shape Continuity = GeomAbs_C2, 
123     const Standard_Real Tol3D = 1.0e-3);
124   
125   //! Approximates  a BSpline  Surface passing  through  an
126   //! array of  Points.
127   //!
128   //! The points will be constructed as follow:
129   //! P(i,j) = gp_Pnt( X0 + (i-1)*dX ,
130   //! Y0 + (j-1)*dY ,
131   //! ZPoints(i,j)   )
132   //!
133   //! The resulting BSpline will  have the following
134   //! properties:
135   //! 1- his degree will be in the range [Degmin,Degmax]
136   //! 2- his  continuity will be  at  least <Continuity>
137   //! 3- the distance from the point <Points> to the
138   //! BSpline will be lower to Tol3D
139   //! 4- the parametrization of the surface will verify:
140   //! S->Value( U, V) = gp_Pnt( U, V, Z(U,V) );
141
142   Standard_EXPORT GeomAPI_PointsToBSplineSurface(const TColStd_Array2OfReal& ZPoints, 
143     const Standard_Real X0, const Standard_Real dX, 
144     const Standard_Real Y0, const Standard_Real dY,
145     const Standard_Integer DegMin = 3, const Standard_Integer DegMax = 8, 
146     const GeomAbs_Shape Continuity = GeomAbs_C2, const Standard_Real Tol3D = 1.0e-3);
147   
148   //! Approximates  a BSpline Surface passing  through  an
149   //! array of  Point.  The resulting BSpline will  have
150   //! the following properties:
151   //! 1- his degree will be in the range [Degmin,Degmax]
152   //! 2- his  continuity will be  at  least <Continuity>
153   //! 3- the distance from the point <Points> to the
154   //! BSpline will be lower to Tol3D.
155
156   Standard_EXPORT void Init (const TColgp_Array2OfPnt& Points, 
157     const Standard_Integer DegMin = 3, const Standard_Integer DegMax = 8, 
158     const GeomAbs_Shape Continuity = GeomAbs_C2, const Standard_Real Tol3D = 1.0e-3);
159   
160   //! Interpolates  a BSpline Surface passing  through  an
161   //! array of  Point.  The resulting BSpline will  have
162   //! the following properties:
163   //! 1- his degree will be 3.
164   //! 2- his  continuity will be  C2.
165
166   Standard_EXPORT void Interpolate (const TColgp_Array2OfPnt& Points,  
167                                     const Standard_Boolean thePeriodic = Standard_False);
168   
169   //! Interpolates  a BSpline Surface passing  through  an
170   //! array of  Point.  The resulting BSpline will  have
171   //! the following properties:
172   //! 1- his degree will be 3.
173   //! 2- his  continuity will be  C2.
174
175   Standard_EXPORT void Interpolate (const TColgp_Array2OfPnt& Points, const Approx_ParametrizationType ParType,
176                                     const Standard_Boolean thePeriodic = Standard_False);
177   
178   //! Approximates  a BSpline  Surface passing  through  an
179   //! array of  Points.
180   //!
181   //! The points will be constructed as follow:
182   //! P(i,j) = gp_Pnt( X0 + (i-1)*dX ,
183   //! Y0 + (j-1)*dY ,
184   //! ZPoints(i,j)   )
185   //!
186   //! The resulting BSpline will  have the following
187   //! properties:
188   //! 1- his degree will be in the range [Degmin,Degmax]
189   //! 2- his  continuity will be  at  least <Continuity>
190   //! 3- the distance from the point <Points> to the
191   //! BSpline will be lower to Tol3D
192   //! 4- the parametrization of the surface will verify:
193   //! S->Value( U, V) = gp_Pnt( U, V, Z(U,V) );
194
195   Standard_EXPORT void Init (const TColStd_Array2OfReal& ZPoints, 
196     const Standard_Real X0, const Standard_Real dX, 
197     const Standard_Real Y0, const Standard_Real dY, 
198     const Standard_Integer DegMin = 3, const Standard_Integer DegMax = 8, 
199     const GeomAbs_Shape Continuity = GeomAbs_C2, const Standard_Real Tol3D = 1.0e-3);
200   
201   //! Interpolates  a BSpline  Surface passing  through  an
202   //! array of  Points.
203   //!
204   //! The points will be constructed as follow:
205   //! P(i,j) = gp_Pnt( X0 + (i-1)*dX ,
206   //! Y0 + (j-1)*dY ,
207   //! ZPoints(i,j)   )
208   //!
209   //! The resulting BSpline will  have the following
210   //! properties:
211   //! 1- his degree will be 3
212   //! 2- his  continuity will be  C2.
213   //! 4- the parametrization of the surface will verify:
214   //! S->Value( U, V) = gp_Pnt( U, V, Z(U,V) );
215
216   Standard_EXPORT void Interpolate (const TColStd_Array2OfReal& ZPoints, 
217     const Standard_Real X0, const Standard_Real dX, const Standard_Real Y0, const Standard_Real dY);
218   
219   //! Approximates  a BSpline Surface passing  through  an
220   //! array of  Point.  The resulting BSpline will  have
221   //! the following properties:
222   //! 1- his degree will be in the range [Degmin,Degmax]
223   //! 2- his  continuity will be  at  least <Continuity>
224   //! 3- the distance from the point <Points> to the
225   //! BSpline will be lower to Tol3D.
226
227   Standard_EXPORT void Init (const TColgp_Array2OfPnt& Points, 
228     const Approx_ParametrizationType ParType, 
229     const Standard_Integer DegMin = 3, const Standard_Integer DegMax = 8,
230     const GeomAbs_Shape Continuity = GeomAbs_C2, 
231     const Standard_Real Tol3D = 1.0e-3, const Standard_Boolean thePeriodic = Standard_False);
232   
233   //! Approximates  a BSpline Surface passing  through  an
234   //! array of  point using variational smoothing algorithm,
235   //! which tries to minimize additional criterium:
236   //! Weight1*CurveLength + Weight2*Curvature + Weight3*Torsion.
237
238   Standard_EXPORT void Init (const TColgp_Array2OfPnt& Points, 
239     const Standard_Real Weight1, const Standard_Real Weight2, const Standard_Real Weight3, 
240     const Standard_Integer DegMax = 8, 
241     const GeomAbs_Shape Continuity = GeomAbs_C2, const Standard_Real Tol3D = 1.0e-3);
242   
243   //! Returns the approximate BSpline Surface
244   Standard_EXPORT const Handle(Geom_BSplineSurface)& Surface() const;
245   Standard_EXPORT operator Handle(Geom_BSplineSurface)() const;
246   
247   Standard_EXPORT Standard_Boolean IsDone() const;
248
249
250
251
252 protected:
253
254
255
256
257
258 private:
259
260
261
262   Standard_Boolean myIsDone;
263   Handle(Geom_BSplineSurface) mySurface;
264
265
266 };
267
268
269
270
271
272
273
274 #endif // _GeomAPI_PointsToBSplineSurface_HeaderFile