Algorithm Overview

📚 Complete Algorithms Reference →
Detailed technical documentation, mathematical foundations, and implementation details for all 22 algorithms

Spline Interpolation

• CubicSpline – Natural cubic splines with boundary conditions
• CubicSmoothingSpline – Noise-robust splines with smoothing parameter
• CubicSplineWithAcceleration1/2 – Bounded acceleration constraints
• BSpline – General B-spline curves with configurable degree
• ApproximationBSpline, CubicBSpline, InterpolationBSpline, SmoothingCubicBSpline

Motion Profiles

• DoubleSTrajectory – S-curve profiles with bounded jerk
• TrapezoidalTrajectory – Classic trapezoidal velocity profiles
• PolynomialTrajectory – 3rd, 5th, 7th order polynomials
• LinearPolyParabolicTrajectory – Linear segments with parabolic blends

Quaternion Interpolation

• Quaternion – Core quaternion operations with SLERP
• QuaternionSpline – C²-continuous rotation trajectories
• SquadC2 – Enhanced SQUAD with zero-clamped boundaries
• LogQuaternion – Logarithmic quaternion methods

Path Planning & Utilities

• SimpleLinearPath, SimpleCircularPath – 3D geometric primitives
• FrenetFrame – Frenet-Serret frame computation along curves
• LinearInterpolation – Basic linear interpolation
• TridiagonalInverse – Efficient tridiagonal system solver

Advanced Examples

import matplotlib.pyplot as plt
from interpolatepy import QuaternionSpline, Quaternion

# Define rotation waypoints
orientations = [
    Quaternion.identity(),
    Quaternion.from_euler_angles(0.5, 0.3, 0.1),
    Quaternion.from_euler_angles(1.0, -0.2, 0.8)
]
times = [0.0, 2.0, 5.0]

# Smooth quaternion trajectory with C² continuity
quat_spline = QuaternionSpline(times, orientations, interpolation_method="squad")

# Evaluate at any time
orientation, segment = quat_spline.interpolate_at_time(3.5)
# For angular velocity, use interpolate_with_velocity
orientation_with_vel, angular_velocity, segment = quat_spline.interpolate_with_velocity(3.5)

# QuaternionSpline doesn't have built-in plotting - manual visualization needed
plt.show()

import numpy as np
import matplotlib.pyplot as plt
from interpolatepy import CubicSmoothingSpline

# Fit smooth curve to noisy data
t = np.linspace(0, 10, 50)
q = np.sin(t) + 0.1 * np.random.randn(50)

# Use CubicSmoothingSpline with correct parameter name 'mu'
spline = CubicSmoothingSpline(t, q, mu=0.01)
spline.plot()
plt.show()

import numpy as np
import matplotlib.pyplot as plt
from interpolatepy import DoubleSTrajectory, StateParams, TrajectoryBounds

# Jerk-limited S-curve for smooth industrial motion
state = StateParams(q_0=0.0, q_1=50.0, v_0=0.0, v_1=0.0)
bounds = TrajectoryBounds(v_bound=10.0, a_bound=5.0, j_bound=2.0)

trajectory = DoubleSTrajectory(state, bounds)
print(f"Duration: {trajectory.get_duration():.2f}s")

# Evaluate trajectory
t_eval = np.linspace(0, trajectory.get_duration(), 1000)
results = [trajectory.evaluate(t) for t in t_eval]
positions = [r[0] for r in results]
velocities = [r[1] for r in results]

# Manual plotting
plt.figure(figsize=(12, 8))
plt.subplot(2, 1, 1)
plt.plot(t_eval, positions)
plt.ylabel('Position')
plt.title('Industrial S-Curve Motion Profile')
plt.grid(True)
plt.subplot(2, 1, 2)
plt.plot(t_eval, velocities)
plt.ylabel('Velocity')
plt.xlabel('Time')
plt.grid(True)
plt.show()

Who Should Use InterpolatePy?

🤖 Robotics Engineers: Motion planning, trajectory optimization, smooth control
🎬 Animation Artists: Smooth keyframe interpolation, camera paths, character motion
🔬 Scientists: Data smoothing, curve fitting, experimental trajectory analysis
🏭 Automation Engineers: Industrial motion control, CNC machining, conveyor systems

Performance & Quality

• Fast: Optional C++ backend (Eigen + pybind11) for maximum performance; pure-Python fallback uses vectorized NumPy
• Reliable: 85%+ test coverage, continuous integration, 142 additional C++ unit tests
• Modern: Python 3.11+, strict typing, dataclass-based APIs
• Research-grade: Peer-reviewed algorithms from robotics literature

C++ Backend:

InterpolatePy includes an optional compiled C++ extension for performance-critical workloads. The API is identical regardless of backend:

import interpolatepy
print(f"C++ backend: {interpolatepy.HAS_CPP}")  # True if extension is available

Set INTERPOLATEPY_NO_CPP=1 to force pure-Python mode.

Typical Performance (pure-Python):

• Cubic spline (1000 points): ~1ms
• B-spline evaluation (10k points): ~5ms
• S-curve trajectory planning: ~0.5ms

Development

git clone https://github.com/GiorgioMedico/InterpolatePy.git
cd InterpolatePy
uv sync                       # creates .venv with dev + test groups
uv run pre-commit install

# Run tests
uv run pytest tests/

# Run tests with coverage
uv run pytest tests/ --cov=interpolatepy --cov-report=html --cov-report=term

# Code quality
uv run ruff format interpolatepy/
uv run ruff check interpolatepy/
uv run mypy interpolatepy/

# Run all pre-commit hooks
uv run pre-commit run --all-files

Contributing

Contributions welcome! Please:

1. Fork the repo and create a feature branch
2. Install dev dependencies: uv sync
3. Follow existing patterns and add tests
4. Run uv run pre-commit run --all-files before submitting
5. Open a pull request with clear description

For major changes, open an issue first to discuss the approach.

Support the Project

⭐ Star the repo if InterpolatePy helps your work!
🐛 Report issues on GitHub Issues
💬 Join discussions to share your use cases and feedback

License & Citation

MIT License – Free for commercial and academic use. See LICENSE for details.

If you use InterpolatePy in research, please cite:

@misc{InterpolatePy,
  author = {Giorgio Medico},
  title  = {InterpolatePy: Trajectory Planning and Interpolation for Python},
  year   = {2025},
  url    = {https://github.com/GiorgioMedico/InterpolatePy}
}

This library implements algorithms from:

Robotics & Trajectory Planning:

• Biagiotti & Melchiorri (2008). Trajectory Planning for Automatic Machines and Robots
• Siciliano et al. (2010). Robotics: Modelling, Planning and Control

Quaternion Interpolation:

• Parker et al. (2023). "Logarithm-Based Methods for Interpolating Quaternion Time Series"
• Wittmann et al. (2023). "Spherical Cubic Blends: C²-Continuous Quaternion Interpolation"
• Dam, E. B., Koch, M., & Lillholm, M. (1998). "Quaternions, Interpolation and Animation"

Built with ❤️ for the robotics and scientific computing community.