first commit

SimpleCADAPI-master/docs/api/fit_cubic_bspline_control_points.md

@@ -0,0 +1,79 @@
+# fit_cubic_bspline_control_points
+
+## API Definition
+
+```python
+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
+```python
+from simplecadapi.math import fit_cubic_bspline_control_points
+```
+
+### Example 2
+```python
+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)
+```
+```