include/opencascade/ExtremaPC_OffsetCurve.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 _ExtremaPC_OffsetCurve_HeaderFile
0015 #define _ExtremaPC_OffsetCurve_HeaderFile
0016
0017 #include <Adaptor3d_Curve.hxx>
0018 #include <ExtremaPC.hxx>
0019 #include <ExtremaPC_GridEvaluator.hxx>
0020 #include <gp_Pnt.hxx>
0021 #include <NCollection_Array1.hxx>
0022 #include <Standard_DefineAlloc.hxx>
0023
0024 //! @brief Point-OffsetCurve extrema computation using grid-based approach.
0025 //!
0026 //! Computes the extrema between a 3D point and an offset curve using
0027 //! a grid-based approach with Newton refinement.
0028 //!
0029 //! The grid is cached for efficiency when performing multiple queries
0030 //! with the same parameter domain.
0031 //!
0032 //! The algorithm:
0033 //! 1. Build uniform grid using GeomGridEval
0034 //! 2. Linear scan of grid to find candidate intervals (sign changes in F(u))
0035 //! 3. Newton refinement on each candidate interval
0036 //!
0037 //! Offset curves are handled through the Adaptor3d_Curve interface,
0038 //! which provides uniform access to the offset geometry.
0039 //!
0040 //! The domain is fixed at construction time and the grid is built eagerly
0041 //! for optimal performance with multiple queries.
0042 class ExtremaPC_OffsetCurve
0043 {
0044 public:
0045   DEFINE_STANDARD_ALLOC
0046
0047   //! Constructor with curve adaptor (uses full curve domain).
0048   //! Grid is built eagerly at construction time.
0049   //! @param[in] theCurve curve adaptor for offset curve (must remain valid)
0050   Standard_EXPORT explicit ExtremaPC_OffsetCurve(const Adaptor3d_Curve& theCurve);
0051
0052   //! Constructor with curve adaptor and parameter domain.
0053   //! Grid is built eagerly at construction time for the specified domain.
0054   //! @param[in] theCurve curve adaptor for offset curve (must remain valid)
0055   //! @param[in] theDomain parameter domain (fixed for all queries)
0056   Standard_EXPORT ExtremaPC_OffsetCurve(const Adaptor3d_Curve&     theCurve,
0057                                         const ExtremaPC::Domain1D& theDomain);
0058
0059   //! Copy constructor is deleted.
0060   ExtremaPC_OffsetCurve(const ExtremaPC_OffsetCurve&) = delete;
0061
0062   //! Copy assignment operator is deleted.
0063   ExtremaPC_OffsetCurve& operator=(const ExtremaPC_OffsetCurve&) = delete;
0064
0065   //! Move constructor.
0066   ExtremaPC_OffsetCurve(ExtremaPC_OffsetCurve&&) = default;
0067
0068   //! Move assignment operator.
0069   ExtremaPC_OffsetCurve& operator=(ExtremaPC_OffsetCurve&&) = default;
0070
0071   //! Evaluates point on curve at parameter.
0072   //! @param theU parameter
0073   //! @return point on curve
0074   Standard_EXPORT gp_Pnt Value(double theU) const;
0075
0076   //! Returns true if domain is bounded.
0077   bool IsBounded() const { return true; } // Offset curves are always bounded
0078
0079   //! Returns the domain.
0080   const ExtremaPC::Domain1D& Domain() const { return myDomain; }
0081
0082   //! Compute extrema between point P and the curve.
0083   //! Uses domain specified at construction time.
0084   //! @param theP query point
0085   //! @param theTol tolerance for root finding
0086   //! @param theMode search mode (MinMax, Min, or Max)
0087   //! @return const reference to result containing extrema
0088   [[nodiscard]] Standard_EXPORT const ExtremaPC::Result& Perform(
0089     const gp_Pnt&         theP,
0090     double                theTol,
0091     ExtremaPC::SearchMode theMode = ExtremaPC::SearchMode::MinMax) const;
0092
0093   //! Compute extrema between point P and the curve including endpoints.
0094   //! Uses domain specified at construction time.
0095   //! @param theP query point
0096   //! @param theTol tolerance for root finding
0097   //! @param theMode search mode (MinMax, Min, or Max)
0098   //! @return const reference to result containing interior + endpoint extrema
0099   [[nodiscard]] Standard_EXPORT const ExtremaPC::Result& PerformWithEndpoints(
0100     const gp_Pnt&         theP,
0101     double                theTol,
0102     ExtremaPC::SearchMode theMode = ExtremaPC::SearchMode::MinMax) const;
0103
0104 private:
0105   //! Build grid for the curve.
0106   void buildGrid();
0107
0108   const Adaptor3d_Curve* myCurve;  //!< Curve adaptor (not owned)
0109   ExtremaPC::Domain1D    myDomain; //!< Parameter domain (fixed)
0110
0111   //! Grid evaluator with cached state (grid, result, temporary vectors).
0112   mutable ExtremaPC_GridEvaluator myEvaluator;
0113 };
0114
0115 #endif // _ExtremaPC_OffsetCurve_HeaderFile