Metadata-Version: 2.4
Name: servo-py
Version: 0.3.0
Summary: ROS-independent C++ online joint and Cartesian servoing with Python bindings
Keywords: robotics,servo,kinematics,mujoco,motion-control
License-Expression: MIT
License-File: LICENSE
License-File: LICENSES/Eigen-MPL2.txt
License-File: LICENSES/pybind11-BSD.txt
License-File: NOTICE
License-File: examples/assets/PANDA-LICENSE.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Project-URL: Documentation, https://openghz.github.io/servopy/
Project-URL: Repository, https://github.com/OpenGHz/servopy
Project-URL: Issues, https://github.com/OpenGHz/servopy/issues
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Provides-Extra: pinocchio
Requires-Dist: pin>=3.0; extra == "pinocchio"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: mujoco
Requires-Dist: mujoco<4,>=3.2; extra == "mujoco"
Requires-Dist: imageio>=2.34; extra == "mujoco"
Requires-Dist: imageio-ffmpeg>=0.4.9; extra == "mujoco"
Provides-Extra: ruckig
Requires-Dist: ruckig==0.19.4; extra == "ruckig"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.6; extra == "docs"
Requires-Dist: jieba<1,>=0.42.1; extra == "docs"
Description-Content-Type: text/markdown

# ServoPy

**From robot targets to controlled motion.** A ROS-independent C++ core with a Python API for online joint and Cartesian servoing.

[Documentation](https://openghz.github.io/servopy/) · [Source](https://github.com/OpenGHz/servopy) · [中文介绍](https://github.com/OpenGHz/servopy/blob/main/README.zh-CN.md)

ServoPy turns joint or Cartesian targets and measured feedback into bounded motion references. It supports position, velocity, pose and twist commands; native URDF or optional Pinocchio kinematics; DLS or bounded QP solvers; and optional Ruckig jerk control. NumPy is the only required third-party Python runtime dependency.

## Install on Ubuntu

Prebuilt Linux wheels target **CPython 3.10–3.14**, **x86_64 / ARM64**, and **glibc 2.28 or newer**. A matching wheel needs no C++ compiler, CMake, Eigen installation or ROS. Ubuntu 22.04 and 24.04 provide suitable default Python versions; on Ubuntu 20.04, install Python 3.10 or newer in a separate environment first. Python 3.8/3.9, 32-bit and free-threaded builds are outside this wheel matrix.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --only-binary=:all: servo-py
python -m servo_py.examples.track_pose
```

If Ubuntu reports that `venv` is missing, install its matching `python3-venv` package. The example uses bundled URDF data, runs without a checkout or display, and finishes in `HOLD` with a position error of about `9.8e-5 m`.

## Panda simulation

```bash
python -m pip install --only-binary=:all: 'servo-py[mujoco]'
servo-py-panda --control-mode joint-position
```

For a machine without a desktop, run `servo-py-panda --headless`. The default demo runs an 18-second simulation. Choose `torque`, `joint-position` or `ik-position`; press Space to pause the viewer. Video recording also needs a working graphics backend.

The wheel and source distribution **do not contain Panda model assets**. On first use the demo downloads a fixed, approximately 5 MB archive, verifies its SHA-256, and caches it under `~/.cache/servo-py` (or `$XDG_CACHE_HOME/servo-py`). Further runs reuse the cache offline. Installing or importing ServoPy, the basic URDF example and `servo-py-panda --help` do not download this model. For offline setup, supply the pinned archive via `SERVO_PY_PANDA_ARCHIVE=/path/to/panda.zip`; see the [model setup guide](https://openghz.github.io/servopy/mujoco-panda/#模型下载与离线运行). The small provenance manifest and license are included in the package.

## Optional dependencies

- `servo-py[mujoco]`: simulation, viewer and video recording.
- `servo-py[pinocchio]`: Pinocchio kinematics.
- `servo-py[ruckig]`: Ruckig 0.19.4 trajectory smoothing. Its upstream Linux wheels currently cover x86_64; installing this extra on ARM64 requires an upstream source build.

Extras can be combined, for example `python -m pip install 'servo-py[mujoco,ruckig]'` on x86_64. See the [installation guide](https://openghz.github.io/servopy/getting-started/) and [Panda tutorial](https://openghz.github.io/servopy/mujoco-panda/).

## Source builds and scope

Source builds require Python 3.10 or newer, a compiler and standard library supporting C++17 or newer, CMake 3.20 or newer, and Eigen headers (provided by `cmeel-eigen>=3.4,<4` during isolated pip builds). C++17 is the minimum language standard.

ServoPy generates references; your application owns feedback, actuator commands and device stopping. Physical-robot validation, geometric collision checking and hard real-time execution are outside the current verified scope. See the [design contract](https://openghz.github.io/servopy/design/) and [validation record](https://openghz.github.io/servopy/validation/).

ServoPy is [MIT-licensed](https://github.com/OpenGHz/servopy/blob/main/LICENSE). The separately downloaded Panda assets are Apache-2.0; see [NOTICE](https://github.com/OpenGHz/servopy/blob/main/NOTICE). This is an independent project and does not claim MoveIt compatibility.
