BREP_kernel 0.5.0

# BREP — a boundary-representation geometry kernel

A native/WASM B-rep geometry kernel for building CAD applications, written in
Rust. Published on crates.io as **`BREP_kernel`** with library name
`brep_kernel`; the manifest version is **0.5.0**, released 2026-09-11.
It is the authoritative geometry engine behind the BREP CAD application
(`BREP_app` + `BREP_render` in this repository, re-exported as `brep::kernel` by
the umbrella `BREP` crate), and is usable standalone as a
library: exact NURBS geometry, manifold B-rep topology, booleans, offsets,
fillets, sheet metal, tessellation, STEP import/export, and a feature-history
pipeline driven by JSON schemas.

Current port coverage is intentionally capability-gated:

### Curve and surface geometry

- vector math;
- clamped knot vectors and nonvanishing B-spline basis derivatives;
- exact rational NURBS curve evaluation and derivatives;
- exact line, rational quadratic circular-arc, and arbitrary-plane circle
  constructors, plus clamped-knot generation and curve interpolation helpers;
- banded linear solves with a stable public math API;
- persistent curve handles using typed-array WASM transfers;
- tensor-product rational NURBS surface evaluation, partial derivatives, and
  normals with persistent typed-array handles;
- robust point projection onto rational curves and surfaces, including
  closed parameters and pole/apex rescue;
- lazily recognized analytic carriers (plane, cylinder/cone, sphere, torus)
  cached on each exact rational surface, with closed-form point projection
  in the surface's own rational parameterization replacing grid-plus-Newton
  search, and exact analytic intersection curves (circles, generatrix line
  pairs, elliptic plane/quadric sections via homogeneous control-net maps,
  sphere/sphere circles, torus circles) that bypass surface/surface
  marching and polyline fitting entirely, with proven-empty results
  skipping the marcher;

### Topology and construction

- exact BREP topology records and structural/geometric validation;
- exact manifold box and regular-pyramid construction, including shared edges,
  coedge senses, p-curves, loops, faces, and shell ownership;
- exact cylinder, cone/frustum, sphere, and torus topology, including closed
  rational surfaces, seam edges, cap sharing, pole/apex degeneracies, and
  genus;
- exact closed-profile extrusion with orientation normalization, rational
  side surfaces, shared longitudinal edges, and planar caps;
- exact full and partial profile revolution, including axis-edge degeneracies,
  shared circle/arc edges, per-face seams, radial end caps, and genus;
- exact compatible-section lofts using shared averaged chord parameters,
  global B-spline interpolation, shared skin boundaries, and planar caps;
- exact affine BREP transforms and reflection-aware orientation reversal;

### Intersection, classification, and arrangement

- exact curve/curve and curve/surface intersection search with convex-hull
  broad phases, damped Newton correction, seam wrapping, and tangency flags;
- predictor/corrector surface/surface intersection marching with adaptive
  step control, seam wrapping, loop closure, boundary polishing, and seeds;
- trimmed-face-aware point-in-solid classification with deterministic
  boundary detection and clean-ray retry logic;
- planar segment arrangement with crossing splits, dangling-chain pruning,
  cycle extraction, and hole assignment;
- public segment-intersection and boundary-aware point-in-polygon helpers;
- exact affine and adaptive curved-surface p-curve construction with periodic
  seam unwrapping;

### Booleans, offsets, and healing

- imprint construction with cosurface boundaries, fitted SSI branches,
  global trim-edge splitting, missed-pierce recovery, and shared p-curves;
- traversal-aligned boundary-edge splitting and per-face fragmentation;
- regularized union, intersection, and subtraction with fragment
  classification, coincident-edge sewing, shell grouping, genus recovery,
  validation, and exact-volume verification;
- offset-face carriers and an intersection-built offset-shell API, including
  smooth-boundary synchronization, partial-chain reconstruction, opening-wall
  provenance, same-carrier wall coalescing, and exact manifold validation;
- exact concatenation of collinear and same-NURBS continuation edges, plus
  overlapping one-use edge conformance when adjacent faces split the same
  line or arc differently;
- exact same-carrier face grouping and affine coplanar face merging with
  boundary p-curves rebuilt on the merged planar carrier;
- persistent face/edge names carried on topology records and propagated
  exactly through booleans: split fragments get deterministic `_1`/`_2`
  suffixes, merges keep the surviving face's name, welded shared edges keep
  the first name seen, and new intersection edges are named `FACEA|FACEB`
  from their two supporting faces (the application's derived-edge-name
  convention), so the application no longer re-derives boolean face names by
  geometric support matching;

### Analysis

- surface area and volume integration for planar, untrimmed curved, and
  trimmed curved faces, plus full mass properties (volume centroid and the
  unit-density inertia tensor about the centroid) via divergence-theorem
  moment integrals with an exact Green-boundary path for affine faces;

### Tessellation and meshing

- general trimmed-face BREP tessellation with per-triangle face ownership,
  plus a watertight chord-tolerance tessellator that samples every edge once
  (both adjacent faces reuse identical sample positions, so shared edges
  coincide exactly with no cracks or T-junctions) and refines face interiors
  by conforming edge splits until chords meet the tolerance;
- public parameter-space area, sampled trim polygon, face area/volume
  contribution, and individual-face tessellation APIs;
- indexed mesh representation, validation, and signed volume;
- box and cylinder mesh generation;

### Interop and infrastructure

- exact AP242 STEP output for rational and non-rational BREP topology;
- binary STL read/write and OBJ output;
- persistent solid handles for validation, transforms, mass properties,
  tessellation, booleans, offset-shell benchmarks, and STEP
  output without repeatedly decoding the input topology;
- native Criterion benchmarks and a versioned WASM JSON ABI.

Beyond that list, the crate root also re-exports edge blending
(`fillet_edge`/`fillet_edges`, `chamfer_edge` and variants, `blend_*`), STEP
import (`import_step`), the 2D sketch and assembly constraint solvers
(`solve_sketch`, `solve_assembly`), direct editing (`move_faces`,
`delete_face_and_heal`, `delete_faces_and_heal`), sewing and repair (`sew_solid`,
`mesh_regions_to_brep`), and the JSON feature-history execution pipeline
(`execute_history_json` plus the `feature_schema_catalogue` the application's
dialogs are generated from). See `src/lib.rs` for the full public surface; the
`#[wasm_bindgen]` JSON/typed-array endpoints live under `src/abi.rs`.

This kernel is the sole exact-geometry backend for the application. No exact
operation silently falls back to a mesh.

## Using the crate

The package name and the library name differ on purpose — the crates.io package
is `BREP_kernel`, the Rust library is the idiomatic lowercase `brep_kernel`:

```toml
[dependencies]
brep_kernel = { package = "BREP_kernel", version = "0.4" }
```

```rust
use brep_kernel::{
    boolean_operation, make_box_brep, make_cylinder_brep, solid_mass_properties,
    tessellate_brep_watertight, BooleanOperation, BooleanOptions, Vec3,
};

fn main() -> Result<(), String> {
    // A 40 x 30 x 20 block with a vertical radius-8 hole through it.
    let block = make_box_brep(Vec3::new(0.0, 0.0, 0.0), 40.0, 30.0, 20.0)?;
    let hole = make_cylinder_brep(
        Vec3::new(20.0, 15.0, -1.0), // base point
        Vec3::new(0.0, 0.0, 1.0),    // axis direction
        8.0,                         // radius
        22.0,                        // height (through the block)
    )?;
    let part = boolean_operation(
        &block,
        &hole,
        BooleanOperation::Subtract,
        &BooleanOptions::default(),
    ).map_err(|error| error.to_string())?;

    // Mass properties integrated from the B-rep (no display mesh involved).
    let props = solid_mass_properties(&part)?;
    println!("volume {:.3}, area {:.3}", props.volume, props.surface_area);

    // Watertight display mesh at a 0.05 chord tolerance.
    let mesh = tessellate_brep_watertight(&part, 0.05)?;
    println!("{} triangles", mesh.indices.len() / 3);
    Ok(())
}
```

Boolean operations return `Result<_, KernelRefusal>` with a typed refusal class;
most other modeling APIs still return `Result<_, String>`. Analytic and fitted
geometry coexist, so successful construction is not a promise of zero approximation.
The feature pipeline currently converts boolean refusals to an error string. STEP text goes in and out
through `import_step(&str) -> Result<Vec<BrepSolid>, String>` and
`export_step`.

## Build and test

Build and test (from the crate directory):

```sh
../build.sh test         # private regression suite
python3 ../BREP-dev-data/testing/run.py -- cargo bench --manifest-path BREP_kernel/Cargo.toml
```

The BREP CAD application links this crate as an rlib inside its own wasm
bundle — build it with `./build.sh app` at the repository root. A standalone
kernel wasm pkg (used by the step-validation review tool) is produced by
`./build.sh kernel-wasm` (plain `wasm-pack` → `pkg-web/`).

Note for publishing: the packaged crate ships only `src/`, this README, the
license and the manifest — `include` in `Cargo.toml` is exactly that list. The
test suites, fixtures, benches and fuzz corpora are not in this repository at
all; they live in a private development submodule and are assembled over a
public checkout by its own runner. So neither the packaged crate nor a public
git checkout has a suite to run, and `cargo test` here is expected to find no
tests. Maintainers with access run the gates through `./build.sh`.

## License and links

- License: the repository's Autodrop3d [`LICENSE.md`](LICENSE.md)
  (`license-file` in the manifest).
- Repository: <https://github.com/mmiscool/NURBS_BREP_kernel> — the kernel
  lives in `BREP_kernel/`, alongside `BREP_gizmos/` (overlay widgets),
  `BREP_render/` (the wgpu render/pick engine), and `BREP_app/` (the
  application shell).
- Manifest version: `BREP_kernel` 0.5.0. The publishing guide
  `BREP-dev-data/reference/PUBLISHING.md` — in the private development
  submodule — has the crate-family order and validation story.