InterpolatePy 3.2.0__tar.gz → 3.2.2__tar.gz

{interpolatepy-3.2.0 → interpolatepy-3.2.2}/.github/workflows/docs.yml

@@ -4,16 +4,26 @@ on:
   push:
     branches: [ main, dev ]
     paths:
+      - 'README.md'
+      - 'ALGORITHMS.md'
       - 'docs/**'
       - 'mkdocs.yml'
       - 'interpolatepy/**/*.py'  # Only Python files for API docs
+      - 'scripts/check_doc_snippets.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
       - '.github/workflows/docs.yml'
   pull_request:
     branches: [ main ]
     paths:
+      - 'README.md'
+      - 'ALGORITHMS.md'
       - 'docs/**'
       - 'mkdocs.yml'
       - 'interpolatepy/**/*.py'
+      - 'scripts/check_doc_snippets.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
   workflow_dispatch:  # Allow manual triggering
 
 permissions:
@@ -44,6 +54,12 @@ jobs:
     - name: Sync dependencies
       run: uv sync --locked --no-default-groups --group docs
 
+    - name: Check documentation snippets
+      env:
+        INTERPOLATEPY_NO_CPP: '1'
+        MPLBACKEND: Agg
+      run: uv run python -m scripts.check_doc_snippets
+
     - name: Build documentation
       run: uv run mkdocs build --clean --strict
 
@@ -69,4 +85,3 @@ jobs:
     - name: Deploy to GitHub Pages
       id: deployment
       uses: actions/deploy-pages@v5
-

interpolatepy-3.2.2/.github/workflows/test.yml

@@ -0,0 +1,87 @@
+name: ci-test
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ['3.11', '3.12', '3.13']
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Sync dependencies
+        run: uv sync --locked --no-default-groups --group test
+      - name: Testing with coverage
+        run: uv run pytest tests --cov=interpolatepy --cov-report=xml --cov-report=term-missing
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v6
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+  python-examples:
+    runs-on: ubuntu-latest
+    env:
+      UV_PYTHON: '3.12'
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Sync dependencies
+        run: uv sync --locked --no-default-groups --group test
+      - name: Run Python examples with the fallback backend
+        run: uv run python -m scripts.check_python_examples --backend python
+
+  native:
+    runs-on: ubuntu-latest
+    env:
+      UV_PYTHON: '3.12'
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Sync dependencies
+        run: uv sync --locked --no-default-groups --group test
+      - name: Configure C++ tests, examples, and Python bindings
+        run: |
+          cmake -S cpp -B build/cpp \
+            -DINTERPOLATECPP_BUILD_TESTS=ON \
+            -DINTERPOLATECPP_BUILD_EXAMPLES=ON \
+            -DINTERPOLATECPP_BUILD_BINDINGS=ON \
+            -DPython_EXECUTABLE=$(uv run python -c 'import sys; print(sys.executable)')
+      - name: Build native targets
+        run: cmake --build build/cpp --parallel 4
+      - name: Run C++ tests and examples
+        run: ctest --test-dir build/cpp --output-on-failure
+      - name: Activate the native Python backend
+        run: cp build/cpp/bindings/interpolatecpp_py*.so interpolatepy/
+      - name: Run native adapter regressions
+        run: uv run pytest tests/test_backend.py tests/test_native_adapter_api.py
+      - name: Run documentation snippets with the native backend
+        env:
+          MPLBACKEND: Agg
+        run: uv run python -m scripts.check_doc_snippets
+      - name: Run Python examples with the native backend
+        run: uv run python -m scripts.check_python_examples --backend native

interpolatepy-3.2.2/ALGORITHMS.md

@@ -0,0 +1,155 @@
+# InterpolatePy algorithm guide
+
+This page is a compact map of the algorithms exposed by InterpolatePy 3.2.1.
+For constructor signatures and complete method documentation, use the
+[API reference](docs/api-reference.md). For worked code, use the
+[tutorials](docs/user-guide.md) and [`examples/`](examples/).
+
+## Choose by problem
+
+| Problem | Start with | Why |
+| --- | --- | --- |
+| Interpolate scalar waypoints with specified endpoint velocities | `CubicSpline` | Piecewise cubic, C2 across interior knots, inexpensive evaluation |
+| Fit noisy scalar samples | `CubicSmoothingSpline` | Trades waypoint error against curvature through `mu` and weights |
+| Also constrain endpoint accelerations | `CubicSplineWithAcceleration1` or `CubicSplineWithAcceleration2` | Adds endpoint acceleration conditions with two different constructions |
+| Evaluate a curve from known B-spline control points | `BSpline` | Direct control over degree, knots, and control points |
+| Pass a B-spline through parametric samples | `BSplineInterpolator` | Degrees 3, 4, and 5; optional velocity/acceleration/cyclic constraints |
+| Approximate many points with fewer controls | `ApproximationBSpline` | Weighted least-squares curve reduction |
+| Smooth a vector-valued curve | `SmoothingCubicBSpline` | Cubic B-spline fit with a smoothness/fidelity trade-off |
+| Limit velocity, acceleration, and jerk | `DoubleSTrajectory` | Seven-phase jerk-limited Double-S profile |
+| Limit velocity and acceleration | `TrapezoidalTrajectory` | Trapezoidal or triangular velocity profile |
+| Match endpoint derivatives exactly | `PolynomialTrajectory` | Cubic, quintic, or seventh-order polynomial boundary interpolation |
+| Blend a scalar via-point sequence | `ParabolicBlendTrajectory` | Linear segments joined by parabolic blends |
+| Interpolate two orientations | `Quaternion.slerp()` | Shortest-path spherical interpolation |
+| Interpolate orientation keyframes | `QuaternionSpline` | Piecewise SLERP/SQUAD selected explicitly or automatically |
+| Require a smooth SQUAD-style orientation trajectory | `SquadC2` | Virtual endpoints and smooth angular derivative evaluation |
+| Interpolate rotations in logarithmic coordinates | `LogQuaternionInterpolation` | B-spline interpolation of continuous rotation vectors |
+| Decouple rotation angle and axis | `ModifiedLogQuaternionInterpolation` | Separate angle and unit-axis spline state |
+| Describe a 3D line or circle geometrically | `LinearPath` or `CircularPath` | Arc-length parameterized position and geometric derivatives |
+| Attach a moving frame to a parametric curve | `compute_trajectory_frames()` | Frenet tangent, normal, and binormal, with optional tool rotation |
+
+## Scalar cubic splines
+
+For times `t_i`, positions `q_i`, and segment duration `h_i`, each
+`CubicSpline` segment is a cubic polynomial. Coefficients are chosen so that it
+passes through both segment endpoints, matches waypoint velocities, and has
+continuous acceleration at interior waypoints. `v0` and `vn` are clamped
+endpoint velocities; the defaults are zero velocity, not natural (zero
+curvature) boundary conditions.
+
+`CubicSmoothingSpline` minimizes a combination of weighted data error and curve
+roughness. Its parameter follows these conventions:
+
+- `mu=1` gives exact interpolation.
+- Smaller positive `mu` values emphasize smoothness.
+- An infinite point weight pins that sample exactly.
+- `mu` must be in `(0, 1]`.
+
+Use `smoothing_spline_with_tolerance()` when the input requirement is a maximum
+waypoint error rather than a preselected `mu`. It returns the spline, selected
+`mu`, achieved maximum error, and iteration count.
+
+The acceleration variants have different APIs:
+
+- `CubicSplineWithAcceleration1(..., v0, vn, a0, an)` adds virtual endpoint
+  waypoints.
+- `CubicSplineWithAcceleration2(..., params=SplineParameters(...))` replaces
+  the first and last cubic pieces with quintic segments when acceleration
+  constraints are supplied.
+
+## B-spline curves
+
+A degree-`p` B-spline is
+
+\[
+C(u)=\sum_i N_{i,p}(u)P_i,
+\]
+
+where `P_i` are control points and `N_{i,p}` are basis functions induced by the
+knot vector. The valid domain of a `BSpline` instance is
+`[spline.u_min, spline.u_max]`. Use `evaluate_derivative(u, order)` for curve
+derivatives and `generate_curve_points()` for sampled parameters and points.
+
+`BSplineInterpolator` accepts scalar or vector-valued samples and optional
+times. Degrees 3, 4, and 5 are supported. Since version 3.2.0, all three degrees
+work with two or more samples; missing endpoint constraints are completed with
+generated natural higher-derivative rows. Explicit velocity and acceleration
+constraints take precedence.
+
+`CubicBSplineInterpolation` is a cubic curve interpolator with chord-length,
+centripetal, or equally-spaced parameterization. `ApproximationBSpline` uses a
+chosen number of control points, while `SmoothingCubicBSpline` uses
+`BSplineParams` to configure smoothing, weighting, endpoint enforcement, and
+parameterization.
+
+## Scalar motion profiles
+
+`DoubleSTrajectory` constructs a jerk-limited point-to-point motion from
+`StateParams` and `TrajectoryBounds`. The useful sampling distinction is:
+
+```python
+position = trajectory.evaluate(t)
+velocity = trajectory.evaluate_velocity(t)
+acceleration = trajectory.evaluate_acceleration(t)
+jerk = trajectory.evaluate_jerk(t)
+position, velocity, acceleration, jerk = trajectory.evaluate_full(t)
+```
+
+Scalar and NumPy-array times are supported. Times are clipped to the planned
+duration. Inspect `get_duration()` and `get_phase_durations()` for timing.
+
+`TrapezoidalTrajectory.generate_trajectory()` returns a callable and duration.
+Its `TrajectoryParams` lives in `interpolatepy.trapezoidal`; the top-level
+`interpolatepy.TrajectoryParams` is the distinct multipoint polynomial
+configuration class.
+
+`PolynomialTrajectory` returns callables whose outputs are `(position,
+velocity, acceleration, jerk)`. Cubic order matches position and velocity;
+quintic also matches acceleration; seventh order also matches jerk.
+
+`ParabolicBlendTrajectory.generate()` returns a `(position, velocity,
+acceleration)` callable and total duration for a via-point path.
+
+## Quaternion interpolation
+
+Quaternions `q` and `-q` represent the same orientation. The interpolation
+classes account for this double cover when constructing their paths. Compare
+orientations using the absolute quaternion dot product rather than component
+equality when sign is irrelevant.
+
+`QuaternionSpline` supports `"slerp"`, `"squad"`, and `"auto"`. Its
+`evaluate()`, `evaluate_velocity()`, and `evaluate_acceleration()` methods match
+the quaternion trajectory protocol. `SquadC2` adds virtual endpoints and
+derivative-aware interpolation.
+
+The logarithmic interpolators support B-spline degrees 3, 4, and 5 and, since
+3.2.0, accept as few as two quaternion waypoints. `evaluate_velocity()` and
+`evaluate_acceleration()` return derivatives of the interpolated internal
+coordinates. Use `get_physical_kinematics()` when physical angular velocity and
+angular acceleration are required.
+
+## Paths and Frenet frames
+
+`LinearPath` is parameterized by arc length from zero to `path.length`.
+`CircularPath` takes an axis `r`, a point `d` on that axis, and a point `pi` on
+the circle; one turn spans `2*pi*path.radius`. Their `velocity()` and
+`acceleration()` methods are derivatives with respect to path length, not time.
+
+`compute_trajectory_frames()` accepts a callable returning `(position,
+first_derivative, second_derivative)` for each parameter. Each returned
+`frames[i]` is a 3-by-3 rotation matrix whose columns are tangent, normal, and
+binormal. A scalar `tool_orientation` rotates about the local binormal; a
+three-tuple applies roll, pitch, and yaw.
+
+## Backend and numerical notes
+
+- Import supported APIs from `interpolatepy`, not implementation modules, to
+  allow backend selection.
+- The Python implementation is always available. `interpolatepy.HAS_CPP`
+  reports whether the optional native extension was loaded.
+- Vectorized time evaluation is supported by scalar cubic splines and
+  Double-S trajectories. General B-spline and quaternion evaluators take one
+  parameter at a time; sample them in a comprehension.
+- Validate strictly increasing time arrays and keep units consistent across
+  positions, derivatives, and bounds.
+- Do not extrapolate B-splines beyond `u_min` and `u_max`.

interpolatepy-3.2.2/InterpolatePy.egg-info/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: InterpolatePy
+Version: 3.2.2
+Summary: A comprehensive Python library for generating smooth trajectories and curves with precise control over position, velocity, acceleration, and jerk profiles
+Author-email: Giorgio Medico <giorgio.medico11@gmail.com>
+Maintainer-email: Giorgio Medico <giorgio.medico11@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GiorgioMedico/InterpolatePy
+Project-URL: Bug Tracker, https://github.com/GiorgioMedico/InterpolatePy/issues
+Keywords: interpolation,trajectory planning,motion profiles,robotics,b-splines,cubic splines,frenet frames,path generation,motion control
+Platform: unix
+Platform: linux
+Platform: osx
+Platform: cygwin
+Platform: win32
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: C++
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: scipy>=1.11
+Dynamic: license-file
+
+# InterpolatePy
+
+![Python](https://img.shields.io/badge/python-3.11+-blue)
+[![PyPI Downloads](https://static.pepy.tech/badge/interpolatepy)](https://pepy.tech/projects/interpolatepy)
+[![pre-commit](https://github.com/GiorgioMedico/InterpolatePy/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/GiorgioMedico/InterpolatePy/actions/workflows/pre-commit.yml)
+[![ci-test](https://github.com/GiorgioMedico/InterpolatePy/actions/workflows/test.yml/badge.svg)](https://github.com/GiorgioMedico/InterpolatePy/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+InterpolatePy is a trajectory-planning and interpolation library for robotics,
+animation, and scientific computing. It includes scalar splines, B-spline curve
+tools, bounded motion profiles, quaternion interpolation, and 3D path utilities.
+
+The package has a NumPy/SciPy implementation and an optional C++20 backend. Use
+the public names exported by `interpolatepy`; they select the available backend
+at import time.
+
+## Installation
+
+```bash
+python -m pip install InterpolatePy
+```
+
+InterpolatePy 3.2.1 requires Python 3.11 or newer, NumPy 1.26 or newer,
+SciPy 1.11 or newer, and Matplotlib 3.6 or newer.
+
+## Quick start
+
+```python
+import numpy as np
+
+from interpolatepy import CubicSpline
+from interpolatepy import DoubleSTrajectory
+from interpolatepy import StateParams
+from interpolatepy import TrajectoryBounds
+
+# A clamped cubic spline: v0 and vn are endpoint velocities.
+spline = CubicSpline(
+    [0.0, 1.0, 2.0, 3.0],
+    [0.0, 1.5, -0.5, 2.0],
+    v0=0.0,
+    vn=0.0,
+)
+times = np.linspace(0.0, 3.0, 100)
+positions = spline.evaluate(times)
+velocities = spline.evaluate_velocity(times)
+
+# A jerk-limited Double-S motion profile.
+state = StateParams(q_0=0.0, q_1=10.0, v_0=0.0, v_1=0.0)
+bounds = TrajectoryBounds(v_bound=5.0, a_bound=10.0, j_bound=30.0)
+motion = DoubleSTrajectory(state, bounds)
+sample_times = np.linspace(0.0, motion.get_duration(), 100)
+q, qd, qdd, qddd = motion.evaluate_full(sample_times)
+```
+
+`DoubleSTrajectory.evaluate()` returns position only. Use
+`evaluate_velocity()`, `evaluate_acceleration()`, and `evaluate_jerk()` for one
+component, or `evaluate_full()` for all four.
+
+## What is included
+
+| Area | Public APIs | Typical use |
+| --- | --- | --- |
+| Scalar splines | `CubicSpline`, `CubicSmoothingSpline`, `CubicSplineWithAcceleration1`, `CubicSplineWithAcceleration2` | Smooth scalar waypoint trajectories and noisy data |
+| B-splines | `BSpline`, `BSplineInterpolator`, `CubicBSplineInterpolation`, `ApproximationBSpline`, `SmoothingCubicBSpline` | Parametric curves, interpolation, approximation, and smoothing |
+| Motion profiles | `DoubleSTrajectory`, `TrapezoidalTrajectory`, `PolynomialTrajectory`, `ParabolicBlendTrajectory` | Bounded or boundary-conditioned scalar motion |
+| Rotations | `Quaternion`, `QuaternionSpline`, `SquadC2`, `LogQuaternionInterpolation`, `ModifiedLogQuaternionInterpolation` | Orientation interpolation without Euler-angle singularities |
+| Paths and utilities | `LinearPath`, `CircularPath`, Frenet-frame helpers, `linear_traj`, `solve_tridiagonal` | Geometric paths, moving frames, and numerical helpers |
+
+Degrees 3, 4, and 5 of `BSplineInterpolator`,
+`LogQuaternionInterpolation`, and `ModifiedLogQuaternionInterpolation` support
+as few as two waypoints in version 3.2.0.
+
+See the [algorithm selection guide](ALGORITHMS.md), the
+[full documentation](https://giorgiomedico.github.io/InterpolatePy/), and the
+[runnable examples](examples/).
+
+## Optional C++ backend
+
+The package falls back to Python automatically when the extension is absent:
+
+```python
+import interpolatepy
+
+print(interpolatepy.HAS_CPP)
+```
+
+Set `INTERPOLATEPY_NO_CPP=1` before importing the package to force the Python
+implementation. The standard Python package does not need a compiler. Building
+the native library or Python extension from a source checkout requires CMake
+3.21+, a C++20 compiler, and network access for CMake's fetched dependencies;
+see the [installation guide](docs/installation.md#optional-c-backend).
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/GiorgioMedico/InterpolatePy.git
+cd InterpolatePy
+uv sync
+uv run pytest
+uv run pre-commit run --all-files
+```
+
+Documentation dependencies are in a separate group:
+
+```bash
+uv sync --group docs
+uv run mkdocs serve
+```
+
+Every Python program in `examples/` can also be run directly, for example:
+
+```bash
+uv run python examples/double_s_ex.py
+```
+
+For the complete workflow, see [Contributing](docs/contributing.md).
+
+## License and citation
+
+InterpolatePy is distributed under the [MIT License](LICENSE).
+
+```bibtex
+@misc{InterpolatePy,
+  author = {Giorgio Medico},
+  title  = {InterpolatePy: Trajectory Planning and Interpolation for Python},
+  year   = {2026},
+  url    = {https://github.com/GiorgioMedico/InterpolatePy}
+}
+```

{interpolatepy-3.2.0 → interpolatepy-3.2.2}/InterpolatePy.egg-info/SOURCES.txt

@@ -197,6 +197,9 @@ interpolatepy/_adapters/_motion.py
 interpolatepy/_adapters/_paths.py
 interpolatepy/_adapters/_quaternion.py
 interpolatepy/_adapters/_spline.py
+scripts/__init__.py
+scripts/check_doc_snippets.py
+scripts/check_python_examples.py
 tests/__init__.py
 tests/inv_test.py
 tests/test_b_spline.py
@@ -207,6 +210,7 @@ tests/test_lin_poly_parabolic.py
 tests/test_linear.py
 tests/test_log_quat.py
 tests/test_motion_profiles.py
+tests/test_native_adapter_api.py
 tests/test_path_planning.py
 tests/test_polynomials.py
 tests/test_protocols.py

interpolatepy-3.2.2/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: InterpolatePy
+Version: 3.2.2
+Summary: A comprehensive Python library for generating smooth trajectories and curves with precise control over position, velocity, acceleration, and jerk profiles
+Author-email: Giorgio Medico <giorgio.medico11@gmail.com>
+Maintainer-email: Giorgio Medico <giorgio.medico11@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GiorgioMedico/InterpolatePy
+Project-URL: Bug Tracker, https://github.com/GiorgioMedico/InterpolatePy/issues
+Keywords: interpolation,trajectory planning,motion profiles,robotics,b-splines,cubic splines,frenet frames,path generation,motion control
+Platform: unix
+Platform: linux
+Platform: osx
+Platform: cygwin
+Platform: win32
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: C++
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: scipy>=1.11
+Dynamic: license-file
+
+# InterpolatePy
+
+![Python](https://img.shields.io/badge/python-3.11+-blue)
+[![PyPI Downloads](https://static.pepy.tech/badge/interpolatepy)](https://pepy.tech/projects/interpolatepy)
+[![pre-commit](https://github.com/GiorgioMedico/InterpolatePy/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/GiorgioMedico/InterpolatePy/actions/workflows/pre-commit.yml)
+[![ci-test](https://github.com/GiorgioMedico/InterpolatePy/actions/workflows/test.yml/badge.svg)](https://github.com/GiorgioMedico/InterpolatePy/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+InterpolatePy is a trajectory-planning and interpolation library for robotics,
+animation, and scientific computing. It includes scalar splines, B-spline curve
+tools, bounded motion profiles, quaternion interpolation, and 3D path utilities.
+
+The package has a NumPy/SciPy implementation and an optional C++20 backend. Use
+the public names exported by `interpolatepy`; they select the available backend
+at import time.
+
+## Installation
+
+```bash
+python -m pip install InterpolatePy
+```
+
+InterpolatePy 3.2.1 requires Python 3.11 or newer, NumPy 1.26 or newer,
+SciPy 1.11 or newer, and Matplotlib 3.6 or newer.
+
+## Quick start
+
+```python
+import numpy as np
+
+from interpolatepy import CubicSpline
+from interpolatepy import DoubleSTrajectory
+from interpolatepy import StateParams
+from interpolatepy import TrajectoryBounds
+
+# A clamped cubic spline: v0 and vn are endpoint velocities.
+spline = CubicSpline(
+    [0.0, 1.0, 2.0, 3.0],
+    [0.0, 1.5, -0.5, 2.0],
+    v0=0.0,
+    vn=0.0,
+)
+times = np.linspace(0.0, 3.0, 100)
+positions = spline.evaluate(times)
+velocities = spline.evaluate_velocity(times)
+
+# A jerk-limited Double-S motion profile.
+state = StateParams(q_0=0.0, q_1=10.0, v_0=0.0, v_1=0.0)
+bounds = TrajectoryBounds(v_bound=5.0, a_bound=10.0, j_bound=30.0)
+motion = DoubleSTrajectory(state, bounds)
+sample_times = np.linspace(0.0, motion.get_duration(), 100)
+q, qd, qdd, qddd = motion.evaluate_full(sample_times)
+```
+
+`DoubleSTrajectory.evaluate()` returns position only. Use
+`evaluate_velocity()`, `evaluate_acceleration()`, and `evaluate_jerk()` for one
+component, or `evaluate_full()` for all four.
+
+## What is included
+
+| Area | Public APIs | Typical use |
+| --- | --- | --- |
+| Scalar splines | `CubicSpline`, `CubicSmoothingSpline`, `CubicSplineWithAcceleration1`, `CubicSplineWithAcceleration2` | Smooth scalar waypoint trajectories and noisy data |
+| B-splines | `BSpline`, `BSplineInterpolator`, `CubicBSplineInterpolation`, `ApproximationBSpline`, `SmoothingCubicBSpline` | Parametric curves, interpolation, approximation, and smoothing |
+| Motion profiles | `DoubleSTrajectory`, `TrapezoidalTrajectory`, `PolynomialTrajectory`, `ParabolicBlendTrajectory` | Bounded or boundary-conditioned scalar motion |
+| Rotations | `Quaternion`, `QuaternionSpline`, `SquadC2`, `LogQuaternionInterpolation`, `ModifiedLogQuaternionInterpolation` | Orientation interpolation without Euler-angle singularities |
+| Paths and utilities | `LinearPath`, `CircularPath`, Frenet-frame helpers, `linear_traj`, `solve_tridiagonal` | Geometric paths, moving frames, and numerical helpers |
+
+Degrees 3, 4, and 5 of `BSplineInterpolator`,
+`LogQuaternionInterpolation`, and `ModifiedLogQuaternionInterpolation` support
+as few as two waypoints in version 3.2.0.
+
+See the [algorithm selection guide](ALGORITHMS.md), the
+[full documentation](https://giorgiomedico.github.io/InterpolatePy/), and the
+[runnable examples](examples/).
+
+## Optional C++ backend
+
+The package falls back to Python automatically when the extension is absent:
+
+```python
+import interpolatepy
+
+print(interpolatepy.HAS_CPP)
+```
+
+Set `INTERPOLATEPY_NO_CPP=1` before importing the package to force the Python
+implementation. The standard Python package does not need a compiler. Building
+the native library or Python extension from a source checkout requires CMake
+3.21+, a C++20 compiler, and network access for CMake's fetched dependencies;
+see the [installation guide](docs/installation.md#optional-c-backend).
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/GiorgioMedico/InterpolatePy.git
+cd InterpolatePy
+uv sync
+uv run pytest
+uv run pre-commit run --all-files
+```
+
+Documentation dependencies are in a separate group:
+
+```bash
+uv sync --group docs
+uv run mkdocs serve
+```
+
+Every Python program in `examples/` can also be run directly, for example:
+
+```bash
+uv run python examples/double_s_ex.py
+```
+
+For the complete workflow, see [Contributing](docs/contributing.md).
+
+## License and citation
+
+InterpolatePy is distributed under the [MIT License](LICENSE).
+
+```bibtex
+@misc{InterpolatePy,
+  author = {Giorgio Medico},
+  title  = {InterpolatePy: Trajectory Planning and Interpolation for Python},
+  year   = {2026},
+  url    = {https://github.com/GiorgioMedico/InterpolatePy}
+}
+```