figaroh 1.0.1

Free dynamics Identification and Geometrical cAlibration of RObot and Human

FIGAROH is a Python toolbox for geometric calibration and dynamic parameter identification of rigid multi-body systems described by a URDF. It handles serial manipulators and tree-structured systems such as humanoids and mobile manipulators, and covers the whole loop: design the experiment, fit the parameters, validate them on held-out data, and export an updated model.

Install

pip install figaroh

Optimal trajectory generation also needs cyipopt, which is not pip-installable. Use the conda environment for that, or for development:

git clone https://github.com/thanhndv212/figaroh-plus.git
cd figaroh-plus
conda env create -f environment.yml
conda activate figaroh-dev
pip install -e .

Quickstart

FIGAROH's workflow classes are subclassed once per robot. The figaroh-examples repository ships those subclasses, configs and data for each supported robot. The fastest way to see a complete run is its UR10 identification reference, which takes a few seconds:

git clone https://github.com/thanhndv212/figaroh-examples.git
cd figaroh-examples/examples/ur10
python identification_reference.py

It fits the UR10 dynamic parameters on a simulated training log, checks the prediction error on a separate held-out log, computes a physically consistent estimate, exports an identified URDF, and archives the run with its config, revisions and an HTML report under results/runs/.

To use your own robot, follow the Getting Started guide and the Configuration System page; the examples repository has a new-example guide and a scaffold script.

What it does

Geometric calibration (figaroh.calibration) estimates joint offsets and frame transforms from end-effector measurements: motion capture, cameras, laser trackers, or contact with a plane when there is no external metrology. Identifiable parameters are found by QR decomposition, and the fit is a Levenberg–Marquardt solve with outlier removal.

Dynamic identification (figaroh.identification) fits masses, inertias, friction and actuator inertia from joint positions and measured effort. A run goes through up to three stages:

• fit: base parameters by least squares, with optional weighted least squares and decimation. Base-parameter selection is deterministic across platforms.
• reconstruction: a full standard-parameter set recovered from the base fit.
• physical_fit: a direct LMI fit constrained to physically consistent inertias.

identification.select_stage chooses which stage is reported, validated and exported; a requested stage that fails is rejected rather than replaced. problem.torque_fit_joints restricts the fit to the joints whose effort you trust.

Optimal experiment design (figaroh.optimal) selects well-conditioned calibration postures and generates exciting identification trajectories (cubic splines optimised with IPOPT under joint, velocity, torque and collision limits).

Reporting and verification. Every run can write a self-contained HTML report (solve(html_report=True)) and a machine-readable verdict (verify()). The verdict states its scope: an execution PASS means the numerics are sound, while a prediction PASS needs separate validation data and per-joint limits that you declare. generate_compare_page() diffs two archived runs offline. See Reporting & Verification.

Backends. Pinocchio is the default dynamics backend; MuJoCo is available as an optional backend (pip install mujoco). See Backends.

Outputs

Both tasks write the result back into a copy of your URDF (figaroh.tools.urdf_exporter.export_urdf), but they change different parts of it:

The exporter refuses inertias that are not physically consistent unless you pass allow_infeasible=True. Identification exports only an accepted estimate and reloads the written URDF with Pinocchio as a check.

Every run can also write:

• the estimated parameters as YAML, CSV or NPZ (save_results());
• a self-contained HTML report (export_html_report());
• a JSON verdict with the scope, per-stage status and each check (export_verification_report()).

What's new in 1.0

• A declared public API with a stability policy: the Public API and stability page lists what is supported, what is experimental and what is internal. Deprecated names now warn for at least one minor release and are removed only in a major release.
• Features deprecated before 1.0 are removed, including the legacy flat config format. Convert old files once with python -m figaroh.utils.config_migration --input old.yaml --output new.yaml.
• Calibration refuses to export a fit whose solver failed, as identification already did. Pass allow_failed_fit=True to export one for diagnosis.
• Python 3.10 to 3.14 are supported; 3.8 and 3.9 users stay on 0.7.x.

The full list, including fixes and behaviour changes, is in the CHANGELOG.

Supported platforms

Install Pinocchio and ndcurves together so their native libraries match. Other versions within pin>=3.7,<5 may work but have no CI profile; see the version support decision.

Documentation

Working with an AI coding agent? skills/ holds agent skills that set up a calibration, identification, optimal-design or new-robot task end to end. Start with figaroh-start, which routes to the right one, and figaroh-setup-env, whose doctor.sh checks your environment first.

Citation

If you use FIGAROH in your research, please cite:

@inproceedings{nguyen2023figaroh,
  title={FIGAROH: a Python toolbox for dynamic identification and geometric calibration of robots and humans},
  author={Nguyen, Dinh Vinh Thanh and Bonnet, Vincent and Maxime, Sabbah and Gautier, Maxime and Fernbach, Pierre and others},
  booktitle={IEEE-RAS International Conference on Humanoid Robots},
  pages={1--8},
  year={2023},
  address={Austin, TX, United States},
  doi={10.1109/Humanoids57100.2023.10375232},
  url={https://hal.science/hal-04234676v2}
}

@inproceedings{nguyen2024improving,
  title={Improving Operational Accuracy of a Mobile Manipulator by Modeling Geometric and Non-Geometric Parameters},
  author={Nguyen, Thanh D. V. and Bonnet, V. and Fernbach, P. and Flayols, T. and Lamiraux, F.},
  booktitle={2024 IEEE-RAS 23rd International Conference on Humanoid Robots (Humanoids)},
  pages={965--972},
  year={2024},
  address={Nancy, France},
  doi={10.1109/Humanoids58906.2024.10769790}
}

@techreport{nguyen2025humanoid,
  title={Humanoid Robot Whole-body Geometric Calibration with Embedded Sensors and a Single Plane},
  author={Nguyen, Thanh D V and Bonnet, Vincent and Fernbach, Pierre and Daney, David and Lamiraux, Florent},
  year={2025},
  institution={HAL},
  url={https://hal.science/hal-05169055}
}

License

Apache License 2.0; see LICENSE.

FIGAROH started at LAAS-CNRS (original GitLab repository); this repository is its maintained continuation.