Private analytic bounded surfaces, trim wires and closure checks behind O2BVHSurfaceSolid. More...

#include <algorithm>
#include <array>
#include <cassert>
#include <cmath>
#include <cstdint>
#include <limits>
#include <map>
#include <memory>
#include <string>
#include <tuple>
#include <utility>
#include <vector>

Classes
struct	o2::cad::surface::Vec2
	A 2D point/vector in a surface's parametric (u, v) domain. More...

struct	o2::cad::surface::Vec3
	A 3D point/vector in the solid's local frame. More...

struct	o2::cad::surface::ParametricMetric
	How a wire converts a parametric separation into a 3D length: the owning surface's first fundamental form, or the identity. More...

struct	o2::cad::surface::RayHit
	One ray/surface intersection: the ray parameter and the outward normal; a quadric patch can give several per ray. More...

struct	o2::cad::surface::SurfaceEdge
	One straight line segment of a polygon wire, in a surface's parametric (u, v) domain. More...

struct	o2::cad::surface::SurfaceWire
	One closed, oriented polygon loop in a surface's parametric domain: outer loops wind counter-clockwise, holes clockwise. More...

struct	o2::cad::surface::QuarticRoots
	The real roots of a quartic: at most four, held inline. More...

struct	o2::cad::surface::Curve2D
	One trimmed boundary curve in a surface's (u, v) domain: a line segment, a circular arc or a clamped (rational) B-spline. More...

struct	o2::cad::surface::CurveWire
	One closed, oriented boundary loop of Curve2D segments: outer loops wind counter-clockwise, holes clockwise. More...

struct	o2::cad::surface::SurfaceRim
	One trim loop of one face as an ordered 3D polyline, compared with other faces' rims as a curve. More...

class	o2::cad::surface::BoundedSurface
	Abstract analytic surface patch: one support surface plus its trim, with the kernels the navigation needs. More...

struct	o2::cad::surface::BoundedSurface::BoundaryEdgeRef

class	o2::cad::surface::PlanarBoundedSurface

class	o2::cad::surface::CurvedPlanarBoundedSurface
	A plane trimmed by curved (line/arc/B-spline) loops in an orthonormal frame: exact caps, disks and annuli. More...

class	o2::cad::surface::CylindricalBoundedSurface
	A cylinder of given radius around an axis, trimmed to a (phi, h) rectangle or by curve wires; innerWall points the normal to the axis. More...

class	o2::cad::surface::SphericalBoundedSurface
	A sphere of given radius trimmed to a (theta, phi) rectangle or by curve wires; innerWall points the normal to the centre. More...

class	o2::cad::surface::ConicalBoundedSurface
	A cone whose radius varies linearly with height, trimmed as the cylinder; one radius may be zero (an apex) and slope 0 is a cylinder. More...

class	o2::cad::surface::TorusBoundedSurface

struct	o2::cad::surface::RimRecord
	One trim loop of one face as measureRimClosure saw it, naming the rim and its worst chord. More...

struct	o2::cad::surface::ClosureReport
	Whether a set of bounded surfaces forms a closed, consistently oriented 2-manifold, by half-edges, rims and edge identities. More...

Namespaces
namespace	o2
	a couple of static helper functions to create timestamp values for CCDB queries or override obsolete objects

namespace	o2::cad

namespace	o2::cad::surface

Enumerations
enum class	o2::cad::surface::WireClassification { o2::cad::surface::Outside , o2::cad::surface::Boundary , o2::cad::surface::Inside }
	Classification of a parametric point against a closed wire. More...

enum class	o2::cad::surface::WireRole { o2::cad::surface::Outer , o2::cad::surface::Inner }

enum class	o2::cad::surface::WireStatus { o2::cad::surface::Valid , o2::cad::surface::Reversed , o2::cad::surface::NonFinite , o2::cad::surface::Open , o2::cad::surface::TooFewVertices , o2::cad::surface::DegenerateVertex , o2::cad::surface::ZeroArea }

enum class	o2::cad::surface::QuarticBranch { o2::cad::surface::NotAQuartic , o2::cad::surface::Biquadratic , o2::cad::surface::Resolvent }
	Which of solveQuarticReal's branches produced its roots, for the tests. More...

enum class	o2::cad::surface::CurveKind { o2::cad::surface::Line , o2::cad::surface::Arc , o2::cad::surface::BSpline }
	Kind of a 2D trimmed boundary curve. More...

enum class	o2::cad::surface::RimState { o2::cad::surface::Matched = 0 , o2::cad::surface::Reversed , o2::cad::surface::Boundary , o2::cad::surface::NonManifold }

Functions
Vec3	o2::cad::surface::operator+ (const Vec3 &firstVector, const Vec3 &secondVector)

Vec3	o2::cad::surface::operator- (const Vec3 &firstVector, const Vec3 &secondVector)

Vec3	o2::cad::surface::operator* (const Vec3 &vector, double scale)

Vec3	o2::cad::surface::operator* (double scale, const Vec3 &vector)

Vec2	o2::cad::surface::operator- (const Vec2 &firstPoint, const Vec2 &secondPoint)

double	o2::cad::surface::parametricLengthSq (double gUU, double gUV, double gVV, const Vec2 &delta)
	The 3D length squared of parametric displacement delta under the first fundamental form (gUU, gUV, gVV).

template<typename Surface >
ParametricMetric	o2::cad::surface::parametricMetricOf (const Surface &surface)

double	o2::cad::surface::dot (const Vec3 &firstVector, const Vec3 &secondVector)

Vec3	o2::cad::surface::cross (const Vec3 &firstVector, const Vec3 &secondVector)

double	o2::cad::surface::normSq (const Vec3 &vector)

double	o2::cad::surface::norm (const Vec3 &vector)

Vec3	o2::cad::surface::normalized (const Vec3 &vector)

double	o2::cad::surface::component (const Vec3 &vector, int dimension)

void	o2::cad::surface::assignComponent (Vec3 &vector, int dimension, double value)

bool	o2::cad::surface::finite (const Vec2 &point)

bool	o2::cad::surface::finite (const Vec3 &point)

double	o2::cad::surface::distanceSq (const Vec2 &firstPoint, const Vec2 &secondPoint)

double	o2::cad::surface::distanceSq (const Vec3 &firstPoint, const Vec3 &secondPoint)

double	o2::cad::surface::cross2D (const Vec2 &firstVector, const Vec2 &secondVector)

double	o2::cad::surface::pointSegmentDistanceSq (const Vec2 &point, const Vec2 &segmentStart, const Vec2 &segmentEnd)

double	o2::cad::surface::pointSegmentDistanceSq (const Vec3 &point, const Vec3 &segmentStart, const Vec3 &segmentEnd)

bool	o2::cad::surface::sameIntersection (double firstDistance, double secondDistance)

const char *	o2::cad::surface::wireStatusMessage (WireStatus status)
	Human-readable description of a wire status, for logging.

double	o2::cad::surface::trimLengthFloor (const ParametricMetric &metric, const Vec2 &uv)
	kTolerance as a parametric separation at uv: the floor of every trim's on-boundary band.

bool	o2::cad::surface::pointInTriangle (const Vec2 &point, const Vec2 &firstVertex, const Vec2 &secondVertex, const Vec2 &thirdVertex)

std::vector< std::array< int, 3 > >	o2::cad::surface::triangulateSimpleWire (const SurfaceWire &wire)
	Ear-clipping triangulation of a simple (non-self-intersecting) parametric wire.

double	o2::cad::surface::angularTolerance (double radius)
	Angular tolerance equivalent to a kTolerance arc length at the given radius.

int	o2::cad::surface::coverChunkCount (double span)

void	o2::cad::surface::sinusoidRange (double a, double b, double t0, double t1, double &minimum, double &maximum)
	Exact range of a cos(t) + b sin(t) over [t0, t1], at most a turn: the endpoint values, widened to the amplitude at a crest.

bool	o2::cad::surface::angleInSweepRange (double angle, double start, double sweep, double tolerance)

void	o2::cad::surface::gaussLegendre (int n, std::vector< double > &nodes, std::vector< double > &weights)
	The n-point Gauss-Legendre nodes and weights on [-1, 1], by Newton iteration on P_n.

int	o2::cad::surface::solveDepressedCubic (double coeffP, double coeffQ, std::array< double, 3 > &roots)

QuarticRoots	o2::cad::surface::solveQuarticReal (double a4, double a3, double a2, double a1, double a0, QuarticBranch *takenBranch=nullptr)

void	o2::cad::surface::assembleRims (const std::vector< std::pair< Vec3, Vec3 > > &edges, std::vector< SurfaceRim > &rims)
	Chain a face's directed chords into rims by matching endpoints within kTolerance, appending them to rims.

void	o2::cad::surface::appendArcBandCoverBoxes (const Vec3 &center, const Vec3 &axisU, const Vec3 &axisV, const Vec3 &axisW, double phiStart, double phiSweep, double heightMin, double heightMax, double radiusAtMin, double radiusAtMax, std::vector< BoundedSurface::CoverBox > &boxes)
	Cover boxes of a band of revolution between two rim circles: the phi window in chunks, each the box of its two rim arcs.

void	o2::cad::surface::measureSharedEdgeDeviation (const std::vector< std::unique_ptr< BoundedSurface > > &surfaces, ClosureReport &report)
	Measure the Hausdorff distance between the two faces of each shared edge into report; it decides nothing.

void	o2::cad::surface::measureRimClosure (const std::vector< std::unique_ptr< BoundedSurface > > &surfaces, double epsilon, ClosureReport &report)
	Measure the face-to-face gaps of surfaces as curves into report, probing chord midpoints against other faces' chords.

void	o2::cad::surface::applyEdgeIdentityClosure (const std::vector< std::unique_ptr< BoundedSurface > > &surfaces, ClosureReport &report)

ClosureReport	o2::cad::surface::validateClosure (const std::vector< std::unique_ptr< BoundedSurface > > &surfaces, double modelTolerance=0.)
	Validate closure and orientation of surfaces by half-edges, measure the rims, and count edge identities when present.

First fundamental forms by surface family, shared by the surfaces and the sidecar reader
void	o2::cad::surface::planeParametricMetric (const Vec3 &axisU, const Vec3 &axisV, double &gUU, double &gUV, double &gVV)

void	o2::cad::surface::cylinderParametricMetric (double radius, double &gUU, double &gUV, double &gVV)
	Cylinder, (u, v) = (phi[rad], h[cm]).

void	o2::cad::surface::coneParametricMetric (double radiusAtHeight, double slope, double &gUU, double &gUV, double &gVV)

void	o2::cad::surface::sphereParametricMetric (double radius, double theta, double &gUU, double &gUV, double &gVV)

void	o2::cad::surface::torusParametricMetric (double majorRadius, double minorRadius, double phiTube, double &gUU, double &gUV, double &gVV)
	Torus, (u, v) = (phiRing[rad], phiTube[rad]). The ring scale runs from R - r to R + r.


double	o2::cad::surface::sinusoidMinimum (double a, double b, double t0, double t1)

double	o2::cad::surface::sinusoidMaximum (double a, double b, double t0, double t1)

Variables
constexpr double	o2::cad::surface::kCoverChunkAngle = kPi / 4.
	Widest angular span of one cover box: pi/4, eight boxes per full turn.

Angular constants for parametric arc curves
constexpr double	o2::cad::surface::kPi = 3.14159265358979323846

constexpr double	o2::cad::surface::kTwoPi = 2. * kPi

constexpr double	o2::cad::surface::kHalfPi = 0.5 * kPi

constexpr int	o2::cad::surface::kArcSamples = 24
	Chords per full-circle arc for display and rims, shared by all surfaces so shared rims match; divisible by 4.

Numerical conventions: the tolerances shared by all bounded-surface code
constexpr double	o2::cad::surface::kTolerance = 1.e-9
	generic length tolerance

constexpr double	o2::cad::surface::kToleranceSq = kTolerance * kTolerance

constexpr double	o2::cad::surface::kAreaTolerance = 1.e-18
	degenerate (zero) parametric area

constexpr double	o2::cad::surface::kRayTolerance = 1.e-9
	minimum positive ray parameter t

constexpr double	o2::cad::surface::kIntersectionTolerance = 1.e-7
	clustering of near-equal intersections

constexpr double	o2::cad::surface::kClosureQuantum = 1.e-7

constexpr double	o2::cad::surface::kWireJoinTolerance = 1.e-6
	Wire-closure tolerance, a 3D length in cm through the surface metric: the CAD extractor's endpoint precision.

constexpr double	o2::cad::surface::kBSplineFlatness = 1.e-5
	Chord flatness of the adaptive B-spline sampler, in the curve's parametric units; a B-spline trim is this polyline.

constexpr double	o2::cad::surface::kBSplineFlatnessSq = kBSplineFlatness * kBSplineFlatness

constexpr double	o2::cad::surface::kRimMatchTolerance = 1.e-6
	Rim-matching distance in cm when the model states no tolerance: the extractor precision, as kWireJoinTolerance.

constexpr double	o2::cad::surface::kBVHBoxTolerance = 1.e-3
	Widening of the BVH leaf boxes before the outward float rounding; it dominates every navigation length tolerance.

constexpr double	o2::cad::surface::kQuarticEpsilon = 32. * 2.220446049250313e-16
	Zero threshold of solveQuarticReal's branch tests, in machine epsilons relative to the normalised terms: dimensionless.

constexpr double	o2::cad::surface::wireJoinToleranceFor (double modelTolerance)
	The wire-join band for a model with a declared tolerance: that tolerance when looser than kWireJoinTolerance, else the floor.

Curve-wire trim helpers for quadric parametric domains (u = phi, v = height or theta)
constexpr int	o2::cad::surface::kContourQuadratureOrder = 20
	Gauss-Legendre nodes per contour sub-interval, and the widest u span one sub-interval covers.

constexpr double	o2::cad::surface::kContourMaxSpanU = 0.25 * kPi

constexpr int	o2::cad::surface::kSharedEdgeSamples = 33
	Samples per trim curve when measuring a shared edge's deviation; it never enters a verdict.

double	o2::cad::surface::unwrapAngleInto (double angle, double uMin, double uMax)
	Shift angle by whole turns to lie as close as possible to the window [uMin, uMax].

bool	o2::cad::surface::curveTrimContains (const CurveWire &outerWire, const std::vector< CurveWire > &innerWires, const Vec2 &point, bool *boundary=nullptr, const ParametricMetric &metric={})
	Whether a parametric point is in a curve-wire trim (outer loop minus holes); boundary reports an on-boundary hit.

template<typename Antiderivative >
double	o2::cad::surface::contourIntegralAlongCurve (const Curve2D &curve, const Antiderivative &antiderivative, double from, double to)

template<typename Antiderivative >
double	o2::cad::surface::integrateOverCurveTrimByParts (const CurveWire &outerWire, const std::vector< CurveWire > &innerWires, const Antiderivative &antiderivative)
	Green's theorem over a wire-trimmed patch: the double integral of f is the contour integral of F dv, F the u-antiderivative of f; seams are bridged.

template<typename Integrand >
double	o2::cad::surface::integrateOverCurveTrim (const CurveWire &outerWire, const std::vector< CurveWire > &innerWires, const Integrand &integrand, int samplesPerAxis=128)
	Midpoint-rule integral of integrand over the trimmed region; kept as the independent check of the contour form.

bool	o2::cad::surface::buildCurveTrim (const std::vector< Curve2D > &outerTrim, const std::vector< std::vector< Curve2D > > &innerTrims, CurveWire &outerWire, std::vector< CurveWire > &innerWires, Vec2 &lower, Vec2 &upper, std::string &errorMessage, const ParametricMetric &metric={}, double joinTolerance=kWireJoinTolerance)
	Build validated outer and inner trim wires and the outer loop's parametric bounds; rejects a trim wider than a turn in u.

std::vector< Vec2 >	o2::cad::surface::sampleCurveWireByU (const CurveWire &wire, int segmentsPerTurn=kArcSamples)
	Sub-sample a curve-wire loop so its u span is chorded at segmentsPerTurn per turn, matching neighbouring rims.

template<typename MapUV >
void	o2::cad::surface::appendCurveTrimMesh (const CurveWire &outerWire, const MapUV &mapUV, std::vector< Vec3 > &vertices, std::vector< std::array< int, 3 > > &triangles)
	Append the display triangulation of a wire-trimmed quadric patch: the sampled outer loop, ear-clipped; holes are omitted.

template<typename MapUV >
void	o2::cad::surface::appendCurveTrimEdges (const CurveWire &outerWire, const std::vector< CurveWire > &innerWires, const MapUV &mapUV, double orientationSign, std::vector< std::pair< Vec3, Vec3 > > &edges)
	Append the directed 3D boundary edges of a wire-trimmed quadric patch; a negative orientationSign reverses them.

template<typename MapUV >
bool	o2::cad::surface::sampleTrimCurveOfCurveWires (const CurveWire &outerWire, const std::vector< CurveWire > &innerWires, size_t index, const MapUV &mapUV, std::vector< Vec3 > &samples)
	Sample input curve index of a curve-wire trim into 3D through mapUV; false when out of range or not traceable.

template<typename MapUV >
bool	o2::cad::surface::sampleTrimCurveOfSurfaceWires (const SurfaceWire &outerWire, const std::vector< SurfaceWire > &innerWires, size_t index, const MapUV &mapUV, std::vector< Vec3 > &samples)
	The same for a polygon (vertex-ring) trim, whose curves are all straight segments.

Detailed Description

Private analytic bounded surfaces, trim wires and closure checks behind O2BVHSurfaceSolid.

Author: Sandro Wenzel sandr.nosp@m.o.we.nosp@m.nzel@.nosp@m.cern.nosp@m..ch

Since: 2026-07

Definition in file BoundedSurface.h.

Classes

Namespaces

Enumerations

Functions

Variables

Numerical conventions: the tolerances shared by all bounded-surface code

Curve-wire trim helpers for quadric parametric domains (u = phi, v = height or theta)

Detailed Description