hypercurve

Hypercurve

Exact, evidence-carrying planar curves, paths, contours, and regions for CAD topology.

Hypercurve is the two-dimensional curve kernel in the Hyper geometry stack. It models lines, circular arcs, Bézier curves, B-splines, and NURBS with hyperreal::Real coordinates, then builds intersection, classification, regularized Boolean, offset, reconstruction, and finite-projection operations on those carriers.

The crate owns planar curve geometry and topology. It deliberately does not own solid modeling or mesh topology: CSG grammar and operations such as extrusion, revolve, sweep, and loft belong in CSGRS, while triangle-mesh Boolean work belongs in Hypermesh.

This README describes crate version 0.3.1.

Primary types

Type Role
Point2, Aabb2, Similarity2 Exact planar coordinates, bounds, and similarity transforms
CurvePoint2 Exact curve point retaining coordinates or selected geometric evidence
LineSeg2, CircularArc2, Segment2 Native line/arc primitives and their common enum
QuadraticBezier2, CubicBezier2, RationalQuadraticBezier2, RationalBezier2 Polynomial and rational Bézier carriers
PolynomialSplineCurve2, NurbsCurve2 Validated B-spline and NURBS curves
Curve2 Shared exact curve carrier with borrowed operations
CurveString2, CurvePath2, Contour2 Connected open strings, general paths, and closed line/arc contours
CurveRegion2 Native mixed-family filled planar region
provisional, evaluate_under, Provisional<T>, CurvePreviewOptions, Classification<T> Explicitly qualified approximate evaluation, its certainty-carrying result, lossy preview adapter, and decided/uncertain result
CurveError, ExactCurveError Construction and exact-topology failure information

CurveRegion2 is the sole public filled-region carrier. Native line/arc specializations remain private fast paths inside the unified kernel.

Region and closed-path point queries accept CurvePoint2, preserving selected roots and generated contact evidence. Convert authored coordinates with Point2::into(); coordinates() is an optional stored-coordinate view. Region batches accept &[CurvePoint2] and share query preparation across scalar and generated points. Closed paths retain their trace and even-odd interior; filled regions classify their regularized boundary, including holes and nested islands.

CurveRegion2::try_from_boundary_paths(paths, fill_rule) applies one fill rule to the total signed winding of all closed paths, then publishes the regularized set. NonZero preserves equally oriented overlaps and cancels opposite winding; EvenOdd selects odd winding. SVG compound fills use this same admission path. Explicit material/hole constructors instead combine each loop’s filled membership by its supplied role. Interior sides are certified by the arrangement from winding; authoring does not require orientation hints.

Install

[dependencies]
hypercurve = "0.3.1"

Hyperreal, Hypersolve, and Hyperlimit are mandatory parts of the exact kernel; feature flags select only optional adapters and instrumentation.

Quick start

This builds a quadratic Bézier, constructs a square region from exact line segments, and classifies an interior point.

use hypercurve::{
    BezierDegree, Contour2, CurveRegion2, LineSeg2, Point2, QuadraticBezier2, RegionPointLocation,
    Segment2,
};
use hyperreal::Real;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let p = |x, y| Point2::new(Real::from(x), Real::from(y));
    let bezier = QuadraticBezier2::new(p(0, 0), p(1, 2), p(2, 0));
    assert_eq!(bezier.structural_facts().degree, BezierDegree::Quadratic);

    let boundary = [
        ((0, 0), (2, 0)),
        ((2, 0), (2, 2)),
        ((2, 2), (0, 2)),
        ((0, 2), (0, 0)),
    ]
    .into_iter()
    .map(|(start, end)| LineSeg2::try_new(p(start.0, start.1), p(end.0, end.1)).map(Segment2::Line))
    .collect::<hypercurve::CurveResult<Vec<_>>>()?;

    let contour = Contour2::try_new(boundary)?;
    let region = CurveRegion2::try_from_native_material_contours(vec![contour])?;
    assert_eq!(
        region.classify_point(&p(1, 1).into())?,
        RegionPointLocation::Inside
    );
    Ok(())
}

Run the checked copy:

cargo run --example basic

How the model fits together

Point2
  ├─ LineSeg2 / CircularArc2 ── Segment2 ── CurveString2 / Contour2
  └─ Bézier / B-spline / NURBS ── Curve2 ── CurvePath2
                                      │
                     arrange / classify / regularize
                                      │
                                CurveRegion2
                                      │
                  Boolean / offset / project / triangulate

A Contour2 is a closed, connected line/arc boundary with a fill rule. CurvePath2 generalizes connected paths to every supported curve family. CurveRegion2 stores filled topology as oriented exact boundary curves and is the main input to mixed-family region operations. Curve operations emit boundary provenance for inspection; authored input supplies geometry and fill semantics.

API guide

The following list covers the useful public front doors. Result and evidence types have accessors for inspecting counts, sources, blockers, and retained topology; consult docs.rs for those fields and exact signatures.

Coordinates, primitives, and transforms

Bézier curves

Splines and unified curves

Strings, paths, contours, and regions

Conversion, finite output, and adapters

Precision, guarantees, and boundaries

Hypercurve separates exact values from decisions about them:

Support is deliberately operation-specific. A curve family being representable does not imply that every topology operation is decidable for every symbolic input. Inspect returned status and blocker evidence instead of treating uncertainty as empty geometry.

Feature flags

Feature Default Purpose
dispatch-trace no Hyperreal/Hyperlimit dispatch instrumentation
triangulation no Finite-region triangulation through Hypertri
svg no SVG import/export and exact round-trip extension
hershey no Compiled Hershey stroke fonts and native curve-string text
comparative-benchmarks no Third-party benchmark adapters only

Common configurations:

cargo check
cargo test --all-features
cargo run --example arrangement
cargo check --features svg

The browser demo lives in examples/hypercurve_ui and is built separately with Trunk. It is not part of the library API.

Validation and performance

The quick start is compiled as examples/basic.rs and checked byte-for-byte against this README. The test suite also covers adversarial exact predicates, mixed-family region Booleans, regression corpora, and finite adapters.

The rank-independent public-Boolean matrix, recursive radial/projective regressions (including fourth-generation offsets), and release-scale PCB corpora run in the normal suite. Longer selected-fiber and source-cusp stroke corpora can also be run explicitly:

cargo test --release --locked --all-features --lib selected_fiber_genuinely_analytic_contacts_complete_region_booleans -- --ignored
cargo test --release --locked --all-features --test hypercurve_curve_region_stroke -- --ignored

Detailed benchmark definitions and interpretation live in PERFORMANCE.md and COMPARATIVE_BENCHMARKS.md. Fuzz target ownership and replay instructions live in fuzz/README.md. These are maintainer validation resources, not API guarantees.

References

These sources describe algorithms or numerical principles used by the crate; they are not claims of source-code derivation.

Acknowledgements

Hypercurve builds on Hyperreal, Hyperlimit, and Hypersolve, with optional Hypertri integration. The wider Hyper ecosystem provides the three-dimensional and engineering layers.

The bibliography above acknowledges the research traditions that inform the implementation. Optional comparison dependencies are benchmark or validation peers and do not provide Hypercurve’s native topology.

The optional compiled single-stroke font catalog was created by Dr. A. V. Hershey at the U.S. National Bureau of Standards. Its source distribution format was created by James Hurt of Cognition, Inc.; the integrated Rust representation is not the U.S. NTIS distribution format. The complete required acknowledgement is available as hypercurve::hershey::FONT_DATA_NOTICE.

License and contributing

Licensed under the Apache License 2.0.

Bug reports should include the smallest exact input, selected features, policy, operation, and returned blocker or uncertainty evidence. Before proposing a change, run cargo fmt --all -- --check, the relevant focused test, and cargo test --all-features.