cadSet/SimpleCADAPI/docs/api/fit_cubic_bspline_control_points.md

fit_cubic_bspline_control_points

API Definition

def fit_cubic_bspline_control_points(sample_points: Sequence[Sequence[float]], *, tolerance: float = 0.001, max_control_points: Optional[int] = None, fairing: float = 1e-06, duplicate_tolerance: float = 1e-12, knot_tolerance: float = 1e-09, raise_on_failure: bool = True) -> BSplineFitResult

Source: math.py

Import Surface

• top-level: from simplecadapi import fit_cubic_bspline_control_points

Description

Fit a minimal cubic B-spline control polygon to sampled curve points.

Uses chord-length parameterization, cubic clamped B-spline least squares, second-difference fairing regularization, and adaptive simple knot insertion until the maximum sample error is within tolerance. Only simple interior knots are inserted, so a cubic result remains C2-continuous at every interior knot.

Parameters

sample_points

• Description: Ordered 2D or 3D points sampled along the intended curve. Consecutive duplicate points within duplicate_tolerance are ignored.

tolerance

• Description: Maximum allowed Euclidean fitting error at the input samples.

max_control_points

• Description: Upper bound for fitted control points. Defaults to the cleaned sample count, with a cubic minimum of four controls.

fairing

• Description: Non-negative second-difference regularization weight. Larger values prefer smoother control polygons while still respecting the error tolerance when possible.

duplicate_tolerance

• Description: Distance threshold for removing consecutive duplicate sample points before chord-length parameterization.

knot_tolerance

• Description: Normalized parameter spacing threshold used to avoid duplicate or near-boundary interior knots.

raise_on_failure

• Description: Raise ValueError when the tolerance cannot be reached within max_control_points. If false, return the best non-converged result instead.

Returns

BSplineFitResult containing cubic degree, control points, a full clamped knot vector, knot multiplicities, sample parameters, and fitting error.

Raises

• ValueError: If inputs are invalid, or if the tolerance cannot be met and raise_on_failure=True.

Examples

Example 1

```python
from simplecadapi.math import fit_cubic_bspline_control_points

Example 2

samples = [(0.0, 0.0, 0.0), (1.0, 0.4, 0.0), (2.0, 0.0, 0.0)]
fit = fit_cubic_bspline_control_points(samples, tolerance=0.01)
print(fit.control_points)
print(fit.knots, fit.multiplicities)