include/opencascade/GeomGridEval_Surface.hxx

0001 // Copyright (c) 2025 OPEN CASCADE SAS
0002 //
0003 // This file is part of Open CASCADE Technology software library.
0004 //
0005 // This library is free software; you can redistribute it and/or modify it under
0006 // the terms of the GNU Lesser General Public License version 2.1 as published
0007 // by the Free Software Foundation, with special exception defined in the file
0008 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0009 // distribution for complete text of the license and disclaimer of any warranty.
0010 //
0011 // Alternatively, this file may be used under the terms of Open CASCADE
0012 // commercial license or contractual agreement.
0013
0014 #ifndef _GeomGridEval_Surface_HeaderFile
0015 #define _GeomGridEval_Surface_HeaderFile
0016
0017 #include <Adaptor3d_Surface.hxx>
0018 #include <GeomAbs_SurfaceType.hxx>
0019 #include <Geom_Surface.hxx>
0020 #include <GeomGridEval_BSplineSurface.hxx>
0021 #include <GeomGridEval_BezierSurface.hxx>
0022 #include <GeomGridEval_Cone.hxx>
0023 #include <GeomGridEval_Cylinder.hxx>
0024 #include <GeomGridEval_OffsetSurface.hxx>
0025 #include <GeomGridEval_OtherSurface.hxx>
0026 #include <GeomGridEval_Plane.hxx>
0027 #include <GeomGridEval_Sphere.hxx>
0028 #include <GeomGridEval_SurfaceOfExtrusion.hxx>
0029 #include <GeomGridEval_SurfaceOfRevolution.hxx>
0030 #include <GeomGridEval_Torus.hxx>
0031 #include <gp_Pnt.hxx>
0032 #include <gp_Pnt2d.hxx>
0033 #include <gp_Trsf.hxx>
0034 #include <NCollection_Array1.hxx>
0035 #include <NCollection_Array2.hxx>
0036 #include <Standard.hxx>
0037 #include <Standard_DefineAlloc.hxx>
0038
0039 #include <optional>
0040 #include <variant>
0041
0042 //! @brief Unified grid evaluator for any 3D surface.
0043 //!
0044 //! Uses std::variant for compile-time type safety and zero heap allocation
0045 //! for the evaluator itself. Automatically detects surface type from
0046 //! Adaptor3d_Surface and dispatches to the appropriate specialized evaluator.
0047 //!
0048 //! Supported surface types with optimized evaluation:
0049 //! - Plane: Direct analytical formula
0050 //! - Cylinder: Analytical formula
0051 //! - Sphere: Trigonometric formula
0052 //! - Cone: Analytical formula
0053 //! - Torus: Analytical formula
0054 //! - BezierSurface: Optimized batch evaluation via BSplSLib
0055 //! - BSplineSurface: Optimized batch evaluation with span-based caching
0056 //! - OffsetSurface: Optimized batch evaluation using basis surface derivatives
0057 //! - SurfaceOfRevolution: Batch evaluation using basis curve
0058 //! - SurfaceOfExtrusion: Batch evaluation using basis curve
0059 //! - Other: Fallback using Adaptor3d_Surface::D0
0060 //!
0061 //! Usage:
0062 //! @code
0063 //!   GeomGridEval_Surface anEval(myAdaptorSurface);
0064 //!   // OR
0065 //!   GeomGridEval_Surface anEval(myGeomSurface);
0066 //!   // Grid evaluation
0067 //!   NCollection_Array2<gp_Pnt> aGrid = anEval.EvaluateGrid(myUParams, myVParams);
0068 //! @endcode
0069 class GeomGridEval_Surface
0070 {
0071 public:
0072   DEFINE_STANDARD_ALLOC
0073
0074   //! Variant type holding all possible surface evaluators.
0075   using EvaluatorVariant = std::variant<std::monostate,                   // Uninitialized state
0076                                         GeomGridEval_Plane,               // Plane surface
0077                                         GeomGridEval_Cylinder,            // Cylindrical surface
0078                                         GeomGridEval_Sphere,              // Spherical surface
0079                                         GeomGridEval_Cone,                // Conical surface
0080                                         GeomGridEval_Torus,               // Toroidal surface
0081                                         GeomGridEval_BezierSurface,       // Bezier surface
0082                                         GeomGridEval_BSplineSurface,      // B-spline surface
0083                                         GeomGridEval_OffsetSurface,       // Offset surface
0084                                         GeomGridEval_SurfaceOfRevolution, // Surface of revolution
0085                                         GeomGridEval_SurfaceOfExtrusion,  // Surface of extrusion
0086                                         GeomGridEval_OtherSurface>; // Fallback for other types
0087
0088   //! Construct from adaptor reference (auto-detects surface type).
0089   //! For GeomAdaptor_Surface, extracts underlying Geom_Surface for optimized evaluation.
0090   //! For other adaptors, stores reference for fallback evaluation.
0091   //! @note The surface adaptor reference must remain valid during the lifetime
0092   //!       of this evaluator when using fallback evaluation.
0093   //! @param[in] theSurface surface adaptor reference to evaluate
0094   Standard_EXPORT GeomGridEval_Surface(const Adaptor3d_Surface& theSurface);
0095
0096   //! Construct from geometry handle (auto-detects surface type).
0097   //! @param[in] theSurface geometry to evaluate
0098   Standard_EXPORT GeomGridEval_Surface(const occ::handle<Geom_Surface>& theSurface);
0099
0100   //! Non-copyable and non-movable.
0101   GeomGridEval_Surface(const GeomGridEval_Surface&)            = delete;
0102   GeomGridEval_Surface& operator=(const GeomGridEval_Surface&) = delete;
0103   GeomGridEval_Surface(GeomGridEval_Surface&&)                 = delete;
0104   GeomGridEval_Surface& operator=(GeomGridEval_Surface&&)      = delete;
0105
0106   //! Evaluate grid points at all specified parameters.
0107   //! @param[in] theUParams array of U parameter values
0108   //! @param[in] theVParams array of V parameter values
0109   //! @return 2D array of 3D points (1-based indexing)
0110   Standard_EXPORT NCollection_Array2<gp_Pnt> EvaluateGrid(
0111     const NCollection_Array1<double>& theUParams,
0112     const NCollection_Array1<double>& theVParams) const;
0113
0114   //! Evaluate grid points with first partial derivatives.
0115   //! @param[in] theUParams array of U parameter values
0116   //! @param[in] theVParams array of V parameter values
0117   //! @return 2D array of SurfD1 (1-based indexing)
0118   Standard_EXPORT NCollection_Array2<GeomGridEval::SurfD1> EvaluateGridD1(
0119     const NCollection_Array1<double>& theUParams,
0120     const NCollection_Array1<double>& theVParams) const;
0121
0122   //! Evaluate grid points with first and second partial derivatives.
0123   //! @param[in] theUParams array of U parameter values
0124   //! @param[in] theVParams array of V parameter values
0125   //! @return 2D array of SurfD2 (1-based indexing)
0126   Standard_EXPORT NCollection_Array2<GeomGridEval::SurfD2> EvaluateGridD2(
0127     const NCollection_Array1<double>& theUParams,
0128     const NCollection_Array1<double>& theVParams) const;
0129
0130   //! Evaluate grid points with derivatives up to third order.
0131   //! @param[in] theUParams array of U parameter values
0132   //! @param[in] theVParams array of V parameter values
0133   //! @return 2D array of SurfD3 (1-based indexing)
0134   Standard_EXPORT NCollection_Array2<GeomGridEval::SurfD3> EvaluateGridD3(
0135     const NCollection_Array1<double>& theUParams,
0136     const NCollection_Array1<double>& theVParams) const;
0137
0138   //! Evaluate partial derivative d^(NU+NV)S/(dU^NU dV^NV) at all grid points.
0139   //! @param[in] theUParams array of U parameter values
0140   //! @param[in] theVParams array of V parameter values
0141   //! @param[in] theNU derivative order in U direction
0142   //! @param[in] theNV derivative order in V direction
0143   //! @return 2D array of derivative vectors (1-based indexing)
0144   Standard_EXPORT NCollection_Array2<gp_Vec> EvaluateGridDN(
0145     const NCollection_Array1<double>& theUParams,
0146     const NCollection_Array1<double>& theVParams,
0147     int                               theNU,
0148     int                               theNV) const;
0149
0150   //! Returns the detected surface type.
0151   GeomAbs_SurfaceType GetType() const { return mySurfaceType; }
0152
0153   //! Returns true if a transformation is applied.
0154   bool HasTransformation() const { return myTrsf.has_value(); }
0155
0156   //! Returns the transformation (empty if not set).
0157   const std::optional<gp_Trsf>& GetTransformation() const { return myTrsf; }
0158
0159 protected:
0160   //! Initialize from adaptor reference (auto-detects surface type).
0161   //! @param[in] theSurface surface adaptor reference to evaluate
0162   Standard_EXPORT void initialization(const Adaptor3d_Surface& theSurface);
0163
0164   //! Initialize from geometry handle (auto-detects surface type).
0165   //! @param[in] theSurface geometry to evaluate
0166   Standard_EXPORT void initialization(const occ::handle<Geom_Surface>& theSurface);
0167
0168 private:
0169   //! Apply transformation to grid of points.
0170   void applyTransformation(NCollection_Array2<gp_Pnt>& theGrid) const;
0171
0172   //! Apply transformation to grid of D1 results.
0173   void applyTransformation(NCollection_Array2<GeomGridEval::SurfD1>& theGrid) const;
0174
0175   //! Apply transformation to grid of D2 results.
0176   void applyTransformation(NCollection_Array2<GeomGridEval::SurfD2>& theGrid) const;
0177
0178   //! Apply transformation to grid of D3 results.
0179   void applyTransformation(NCollection_Array2<GeomGridEval::SurfD3>& theGrid) const;
0180
0181   //! Apply transformation to grid of vectors.
0182   void applyTransformation(NCollection_Array2<gp_Vec>& theGrid) const;
0183
0184   EvaluatorVariant       myEvaluator;
0185   GeomAbs_SurfaceType    mySurfaceType;
0186   std::optional<gp_Trsf> myTrsf; //!< Optional transformation for BRepAdaptor surfaces
0187 };
0188
0189 #endif // _GeomGridEval_Surface_HeaderFile