SmApiQueries.h

Fully qualified name: SM_API/inc/SmApiQueries.h

File members: SM_API/inc/SmApiQueries.h

// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

/**********************************************************************
FILE NAME: SmApiQueries.h

PURPOSE:
    Read-only geometric / topological queries on Brep / Face / Edge /
    Vertex / Surface / Curve.  Three loose subgroups, all answer
    "tell me X about this object":

      * Closest-point and topology search:
          SmApiBrepClosestPoint / -All, SmApiCurveClosestPoint / -All,
          SmApiSurfaceClosestPoint, SmApiGetClosestPoint,
          SmApiFindEdge, SmApiFindFaces.
      * Topology accessors:
          SmApiGetEdges, SmApiGetFaces, SmApiFaceGetBoundaryLoops,
          SmApiVertexGetPoint.
      * Geometric / topological properties:
          SmApiBrepIsManifoldSolid, SmApiBrepMaterialCensus,
          SmApiBrepComputeVolume, SmApiBrepComputeArea,
          SmApiBrepBoundingBox, SmApiBrepCopy,
          SmApiFaceBoundingBox, SmApiFaceComputeArea,
          SmApiEdgeBoundingBox, SmApiEdgeComputeLength.

**********************************************************************/

#ifndef __SM_API_QUERIES_H__
#define __SM_API_QUERIES_H__

#ifndef __SmApiTypes_H__
#include <SmApiTypes.h>
#endif

#include <SmTArray.h>

class SmPoint3d;
class SmPoint2d;
class SmCurve;
class SmSurface;
class SmBrep;
class SmEdge;
class SmFace;
class SmVertex;

SMAPI_EXPORT SmApiStatus SmApiGetClosestPoint
(
    const SmBrep* pBrep,
    const SmPoint3d& crPoint,
    SmPoint3d& rClosestPoint,
    double& rdDistance
);

SMAPI_EXPORT SmApiStatus SmApiBrepRelationship
(
    const SmBrep* pBrepA,
    const SmBrep* pBrepB,
    int&    rRelationship,
    double& rdDistance
);

SMAPI_EXPORT SmApiStatus SmApiBrepDistance
(
    const SmBrep* pBrepA,
    const SmBrep* pBrepB,
    double& rdDistance
);

SMAPI_EXPORT SmApiStatus SmApiGetEdges
(
    SmBrep* pBrep,
    SmTArray<SmEdge*>& rEdges
);

SMAPI_EXPORT SmApiStatus SmApiGetFaces
(
    SmBrep* pBrep,
    SmTArray<SmFace*>& rFaces
);

SMAPI_EXPORT SmApiStatus SmApiFaceGetBoundaryLoops
(
    SmFace* pFace,
    SmTArray<ULONG>& rEdgeCountsPerLoop,
    SmTArray<SmEdge*>& rEdges,
    SmTArray<SmOrientType>& rOrientations
);

SMAPI_EXPORT SmApiStatus SmApiFindEdge
(
    SmBrep* pBrep,
    const SmPoint3d& crPoint,
    ULONG& rlEdgeIndex,
    double& rdParam
);

SMAPI_EXPORT SmApiStatus SmApiFindFaces
(
    SmBrep* pBrep,
    const SmPoint3d& crPoint,
    SmFace*& rpFace
);

SMAPI_EXPORT SmApiStatus SmApiCurveClosestPoint
(
    const SmCurve* pCurve,
    const SmPoint3d& crPoint,
    SmPoint3d& rClosestPoint,
    double& rdParameter,
    double& rdDistance
);

SMAPI_EXPORT SmApiStatus SmApiCurveClosestPointAll
(
    const SmCurve* pCurve,
    const SmPoint3d& crPoint,
    SmTArray<SmPoint3d>& rPoints,
    SmTArray<double>& rParameters,
    SmTArray<double>& rDistances
);

SMAPI_EXPORT SmApiStatus SmApiSurfaceClosestPoint
(
    const SmSurface* pSurface,
    const SmPoint3d& crPoint,
    SmPoint3d& rClosestPoint,
    SmTArray<SmPoint2d>& rUVs,
    double& rdDistance
);

SMAPI_EXPORT SmApiStatus SmApiBrepClosestPoint
(
    const SmBrep* pBrep,
    const SmPoint3d& crPoint,
    SmPoint3d& rClosestPoint,
    double& rdDistance
);

SMAPI_EXPORT SmApiStatus SmApiBrepClosestPointAll
(
    const SmBrep* pBrep,
    const SmPoint3d& crPoint,
    SmTArray<SmPoint3d>& rPoints,
    SmTArray<double>& rDistances
);

// ============================================================================
//   Geometric / topological properties
// ============================================================================
//
// Read-only properties of a Brep / Face / Edge / Vertex.  None of these
// modify their input.  Bounding boxes wrap SmObject::CalculateBoundingBox
// (and CalculateTightBoundingBox when bTight=TRUE).  Area and length wrap
// the kernel's numerical-integration entry points.  Area uses a
// [1e-4, 1e-1] relative-accuracy envelope; volume uses [1e-8, 1e-1].
// SmApiBrepCopy uses SmBrep's copy constructor allocated against the
// SM_API context, with analytic recognition disabled so geometry types
// are preserved (including an explicit conversion to NURBS).
//
// For whole-solid area+volume+mass+centroid+inertia use one
// SmApiBrepComputeMassProperties call (SmApiBrepComputeVolume shares its
// core). Mass properties integrate all quantities in one pass; per-face
// area and centroid queries integrate only the quantities needed for their
// results. Cost is governed by dRelativeAccuracy. For interactive preview,
// use a coarse dRelativeAccuracy (~1e-1 is much cheaper than 1e-3),
// or skip exact integration entirely: the SmApiTessellate PolyBrep you already
// build for rendering yields an approximate volume for a fraction of the cost
// (closed manifold mesh only -- meaningless for open/partial tessellations).
// SmApiBrepBoundingBox bTight=FALSE is a cheap loose box (bTight=TRUE is
// expensive).

SMAPI_EXPORT SmApiStatus SmApiBrepIsManifoldSolid(
    const SmBrep* pBrep,
    SmBoolean & rbIsManifoldSolid
);

SMAPI_EXPORT SmApiStatus SmApiBrepMaterialCensus(
    const SmBrep*  pBrep,
    long &   rlSolidCount,
    long &   rlVoidCount
);

SMAPI_EXPORT SmApiStatus SmApiBrepComputeVolume(
    const SmBrep*  pBrep,
    double   dRelativeAccuracy,
    double & rdVolume
);

SMAPI_EXPORT SmApiStatus SmApiBrepComputeArea(
    SmBrep*  pBrep,
    double   dRelativeAccuracy,
    double & rdArea
);

SMAPI_EXPORT SmApiStatus SmApiBrepComputeMassProperties(
    const SmBrep* pBrep,
    double       dRelativeAccuracy,
    double       dDensity,
    const SmPoint3d & crOrigin,
    double &     rdArea,
    double &     rdVolume,
    double &     rdMass,
    SmPoint3d &  rCentroid,
    SmVector3d & rMomentsOfInertia,
    SmVector3d & rProductsOfInertia
);

SMAPI_EXPORT SmApiStatus SmApiBrepBoundingBox(
    const SmBrep* pBrep,
    SmBoolean   bTight,
    SmPoint3d & rMin,
    SmPoint3d & rMax
);

SMAPI_EXPORT SmApiStatus SmApiBrepCopy(
    const SmBrep*  pBrep,
    SmBrep*& rpResult
);

SMAPI_EXPORT SmApiStatus SmApiFaceBoundingBox(
    const SmFace* pFace,
    SmBoolean   bTight,
    SmPoint3d & rMin,
    SmPoint3d & rMax
);

SMAPI_EXPORT SmApiStatus SmApiFaceComputeArea(
    const SmFace*  pFace,
    double   dRelativeAccuracy,
    double & rdArea
);

SMAPI_EXPORT SmApiStatus SmApiFaceInternalPoint(
    const SmFace*     pFace,
    SmPoint3d & rPoint
);

SMAPI_EXPORT SmApiStatus SmApiFaceClassifyUV(
    const SmFace*           pFace,
    const SmPoint2d & crUV,
    int &             rClassification
);

SMAPI_EXPORT SmApiStatus SmApiFaceClosestPoint(
    SmFace*           pFace,
    const SmPoint3d & crPoint,
    SmPoint3d &       rClosestPoint,
    double &          rdDistance
);

SMAPI_EXPORT SmApiStatus SmApiFaceComputeCentroid(
    const SmFace*     pFace,
    double      dRelativeAccuracy,
    double &    rdArea,
    SmPoint3d & rCentroid
);

SMAPI_EXPORT SmApiStatus SmApiEdgeBoundingBox(
    const SmEdge* pEdge,
    SmBoolean   bTight,
    SmPoint3d & rMin,
    SmPoint3d & rMax
);

SMAPI_EXPORT SmApiStatus SmApiEdgeComputeLength(
    const SmEdge*  pEdge,
    double   dDesiredAccuracy,
    double & rdLength
);

SMAPI_EXPORT SmApiStatus SmApiEdgeClosestPoint(
    SmEdge*           pEdge,
    const SmPoint3d & crPoint,
    SmPoint3d &       rClosestPoint,
    double &          rdParameter,
    double &          rdDistance
);

SMAPI_EXPORT SmApiStatus SmApiEdgeParameterRange(
    const SmEdge*  pEdge,
    double & rdMin,
    double & rdMax
);

SMAPI_EXPORT SmApiStatus SmApiEdgeClassifyParameter(
    const SmEdge*  pEdge,
    double   dParameter,
    int &    rClassification
);

SMAPI_EXPORT SmApiStatus SmApiEdgeTangent(
    const SmEdge*      pEdge,
    double       dParameter,
    SmVector3d & rTangent
);

SMAPI_EXPORT SmApiStatus SmApiVertexGetPoint(
    const SmVertex*   pVertex,
    SmPoint3d & rPoint
);

#endif // __SM_API_QUERIES_H__