[Paper Notes] FIGAROH: a Python toolbox for dynamic identification and geometric calibration of robots and humans
Published:
FIGAROH is a Python toolbox for two closely related model-correction problems: geometric calibration, which estimates errors in robot kinematics, and dynamic identification, which estimates inertial, friction, actuator, and sensor parameters. Its most useful systems idea is the complete experimental loop: construct the identification model from URDF, determine which parameter combinations are observable, design informative postures or motions, estimate parameters, validate the result, and update the robot model.
This note reads the original paper together with the current figaroh-plus codebase. The distinction matters. The paper describes the unified scientific workflow demonstrated on robots and a human subject. The current v0.4.5 repository has grown into a more modular library with robust calibration, additional solvers, physical-consistency projection, URDF export, multi-backend interfaces, and reporting/verification tools.
Paper Info
The paper is “FIGAROH: a Python toolbox for dynamic identification and geometric calibration of robots and humans” by Dinh Vinh Thanh Nguyen, Vincent Bonnet, Maxime Sabbah, Maxime Gautier, Pierre Fernbach, and Florent Lamiraux. The provided PDF is the HAL version of the paper published at the 2023 IEEE-RAS International Conference on Humanoid Robots, DOI 10.1109/Humanoids57100.2023.10375232. Despite the local filename FIGAROH_IROS_2022-5.pdf, it is a Humanoids 2023 paper.
The current GitHub repository is a maintained fork of the original LAAS GitLab project. It publishes the figaroh Python package, while runnable robot examples live in a separate figaroh-examples repository.
Two Problems in One Toolbox
Geometric and dynamic identification use similar mathematics and experimental logic, although they correct different parts of the model.
Geometric calibration
A URDF gives each joint a nominal transform. Real assembly introduces small translation and rotation errors. FIGAROH parameterizes the local variation of joint (j) as
[ \Phi_{g,j} = [\delta p_x,\delta p_y,\delta p_z, \delta\phi_x,\delta\phi_y,\delta\phi_z]^T. ]
The forward-kinematics residual is locally linearized:
[ \Delta P=R_g(q,p)\Phi_g, ]
where (R_g) is a geometric regressor or kinematic Jacobian connecting parameter errors to measured pose errors. Measurements can be full poses, positions, orientations, camera observations, motion-capture markers, or geometric constraints such as contact with a plane.
The six-parameter representation does not mean that all six parameters of every joint can be independently recovered. The paper notes that a revolute joint has at most four independently identifiable geometric parameters and a prismatic joint at most two; collinear axes introduce additional dependencies. FIGAROH uses rank analysis to keep the observable parameter combinations.
Dynamic identification
Rigid-body inverse dynamics is linear in inertial and several extended mechanical parameters:
[ D=R_d(q,\dot q,\ddot q)\Phi_d. ]
Here (D) is a stack of measured torques, motor currents, or external wrenches; (R_d) is the dynamic regressor; and (\Phi_d) can include:
- ten inertial parameters per body: mass, first moment, and six inertia-tensor terms;
- joint viscous and Coulomb friction;
- torque-sensor offsets;
- actuator rotor inertia and drive-chain friction;
- current-to-torque or sensor gains.
The identifiable set depends on available measurements. Joint torques can identify inertial and joint parameters. Combining joint torque with motor current exposes drive-chain terms. External wrench measurements identify a different subset. FIGAROH builds the regressor according to this measurement contract.
Rank Deficiency and Base Parameters
Robot regressors are generally rank deficient. Some physical parameters always appear together in the equations, so data cannot separate them regardless of sample count. FIGAROH numerically applies QR decomposition with column pivoting to rewrite the original regressor in terms of full-rank base parameters:
[ Y=R\Phi=R_b\Phi_b, \qquad \operatorname{rank}(R_b)=\dim(\Phi_b). ]
This step is central. A least-squares solver can produce numbers for an underdetermined parameterization, but those numbers are not uniquely supported by the measurements. Base-parameter reduction makes the estimation problem honest: the solver estimates only independent combinations that the experiment can observe.
The paper emphasizes the interpretability of numerical QR. It can expose which original columns combine into each base parameter, and it can produce different static and dynamic base sets. For example, static data removes velocity and acceleration terms, leaving mass and center-of-mass combinations.
Parameter Estimation
Once the base regressor is full rank, the simplest estimate is ordinary least squares:
[ \hat\Phi_b = (R_b^TR_b)^{-1}R_b^TY. ]
Weighted least squares compensates for measurement channels with different noise levels or units. The paper also covers total least squares for experiments with loaded and unloaded configurations, iterative least squares and Levenberg-Marquardt for nonlinear geometric calibration, and constrained optimization for physically plausible inertial parameters.
The current code retains the regressor/QR workflow and broadens solver support. BaseIdentification.solve() runs the standard identification path, while solve_with_custom_solver() can invoke least squares, QR/SVD-style methods, Ridge, Lasso, Elastic Net, robust regression, and constrained variants through figaroh.tools.LinearSolver.
Physical consistency deserves separate treatment. An unconstrained fit can yield negative mass or an impossible inertia tensor while still minimizing torque error. The paper uses quadratic constrained programming to recover individually meaningful parameters. The current code additionally provides optional pseudo-inertia SDP/LMI projection and full-parameter reconstruction from base parameters, with CAD-derived mass, center-of-mass, and symmetry constraints. These paths require an SDP solver and are disabled by default.
Optimal Experiment Design
FIGAROH treats data collection as part of identification. Random postures may leave the regressor poorly conditioned; random motions can waste robot time and become unsafe for humanoids. The toolbox therefore designs Optimal Exciting Postures (OEP) for calibration and static identification, and Optimal Exciting Motions (OEM) for dynamic identification.
The paper uses singular-value criteria derived from the regressor, including determinant-like information volume, condition number, and minimum singular value. Informally, a useful experiment makes the regressor columns distinguishable:
[ \text{good excitation} \Longrightarrow \sigma_{\min}(R)\text{ increases and } \kappa(R)=\frac{\sigma_{\max}(R)}{\sigma_{\min}(R)} \text{ decreases}. ]
Selecting calibration postures
Candidate postures receive information matrices (\Sigma_i) and continuous weights (\omega_i). FIGAROH solves
[ \max_{\omega} \Psi!\left(\sum_i\omega_i\Sigma_i\right), \qquad \sum_i\omega_i=1, ]
then ranks candidates by weight. The excitation score eventually reaches a peak or plateau, which gives a data-driven stopping point for the number of postures. The paper illustrates a case where the criterion peaks near 40 postures.
Postures are optimized under joint limits, torque limits, workspace bounds, and self-collision constraints. The paper uses Pinocchio/hpp-fcl geometry and IPOPT-based nonlinear optimization.
Generating exciting motions
OEM generation connects consecutive OEP using cubic splines. The optimizer adjusts spline waypoints while respecting endpoint positions, zero endpoint velocity, joint/velocity/torque limits, workspace constraints, and collision avoidance. The objective improves the accumulated dynamic base regressor over the trajectory.
This design closes a loop that many system-identification scripts leave manual:
URDF + measurement setup
-> identifiable regressor
-> optimal postures/motions
-> robot data collection
-> parameter estimation
-> cross-validation and model update
What the Paper Demonstrates
The paper evaluates the workflow across human, humanoid, mobile-manipulator, and serial-arm cases.
For a 43-DoF human model, motion capture and force-plate data are used for geometry and dynamics. Compared with anthropometric-table parameters, identified parameters reduce average external-wrench RMSE from 19.47 N to 16.84 N for force and from 33.22 N·m to 16.77 N·m for moment.
For TALOS and TIAGo torso-arm geometric calibration, end-effector position RMSE drops from 14.1 mm to 0.3 mm on TALOS and from 16.9 mm to 1.5 mm on TIAGo. TALOS whole-body calibration with three-point planar contact and 31 automatically generated OEP reduces RMSE from 10.4 mm to 3.3 mm.
TIAGo dynamic identification includes drive-chain parameters and its differential wrist transmission; the identified model predicts measured motor current within 1%. The toolbox also reproduces published Stäubli TX40 inertial identification results and obtains 1.76 mm end-effector position RMSE for UR10 eye-in-hand calibration.
These examples show the toolbox’s breadth. They are heterogeneous case studies with different sensors and metrics, so they do not form one standardized benchmark.
Reading the Current figaroh-plus Code
The current source follows three practical layers.
Workflow layer
figaroh.calibration.BaseCalibration orchestrates configuration loading, measurement validation, QR-based parameter selection, nonlinear optimization, iterative outlier removal, metrics, plots, reports, and verification. Robot-specific behavior can be provided through a subclass cost function. The implementation uses SE(3) log-map residuals for pose calibration and can apply separate weights to position and orientation channels.
figaroh.identification.BaseIdentification loads trajectory data, computes and reduces the dynamic regressor, performs filtering/decimation, solves for base parameters, reconstructs predictions, evaluates RMSE/correlation/condition number, and optionally applies physical-consistency or full-parameter reconstruction.
BaseOptimalCalibration and BaseOptimalTrajectory provide the optimization framework for posture selection and spline trajectory design. IPOPT support relies on cyipopt, which is intentionally omitted from the simple pip dependency set; the repository recommends its Conda environment for this path.
Tools layer
The reusable tools include RegressorBuilder, QRDecomposer, LinearSolver, collision utilities, IPOPT wrappers, URDF export, visualization, result provenance, and report generation. The current library can emit self-contained HTML diagnostics, machine-readable pass/fail verification reports, and static comparisons between two runs.
This V&V layer is a meaningful extension beyond the paper. Calibration quality is more than a fitted RMSE: the code reports per-DoF residuals, held-out before/after validation, parameter uncertainty, strongly correlated parameters, and regressor conditioning. verify() converts configured thresholds into a CI-friendly verdict.
Backend layer
The source currently contains real PinocchioBackend and MuJoCoBackend implementations. Pinocchio remains the default and provides the most complete URDF/regressor path. MuJoCo implements mass, bias, kinematics, and contact-related computations, but its analytical parameter regressor delegates to a lazily loaded Pinocchio model because MuJoCo does not expose the same runtime inertial-parameter regressor.
The architecture document also discusses Genesis and Isaac Sim backends, marked as future work. There are no genesis.py or isaacsim.py implementations in the checked v0.4.5 source tree, so users should currently treat backend support as Pinocchio plus optional MuJoCo.
Paper Versus Current Repository
The scientific spine remains stable:
- URDF-based rigid multi-body modeling;
- geometric and dynamic regressors;
- numerical base-parameter extraction;
- least-squares or constrained estimation;
- OEP/OEM experiment design;
- statistical validation and model export.
The plus repository modernizes the engineering surface. It uses a src/ package layout, abstract workflow classes, unified YAML parsing with legacy conversion, Python packaging on PyPI, broader regression solvers, optional physically consistent reconstruction, model-export validation, richer reports, and an explicit backend interface.
Several practical boundaries are visible in the code:
- The package has no registered command-line entry point; users work through Python classes and project scripts.
- Robot examples and some datasets are maintained in the separate examples repository.
BaseCalibrationis extensible by design and may require a task-specific subclass or cost function.- Advanced OEP/OEM and SDP workflows bring native optimization dependencies that are more involved than
pip install figaroh. - Documentation describes a broader backend roadmap than the checked source currently implements.
This is a research toolbox that has accumulated production-oriented checks, not a black-box auto-calibration service. Users still need to define the measurement model, frame conventions, active parameters, excitation constraints, and validation protocol correctly.
Strengths
FIGAROH’s strongest quality is end-to-end consistency. The same robot model drives regressor construction, observability analysis, experiment design, estimation, collision checking, and final model update. This reduces the chance that each stage uses subtly different joint ordering, frames, or parameter conventions.
The second strength is support for tree-structured and floating-base systems. The workflow covers industrial manipulators, mobile manipulators, humanoids, and human biomechanical models. Optimal excitation is especially valuable for these systems because manually selected configurations become unsafe or uninformative as kinematic complexity grows.
The current code’s validation tooling is also well chosen. A parameter fit should be judged on held-out measurements and physical plausibility, with uncertainty and conditioning made visible. HTML reports and machine-readable verdicts make that discipline easier to repeat.
Limitations and Cautions
Identification quality remains bounded by the assumed model. Unmodeled flexibility, backlash, temperature-dependent friction, cable effects, timing errors, and sensor bias can leak into the estimated rigid-body parameters. Numerical differentiation of positions to obtain velocity and acceleration amplifies noise, making filtering and excitation design essential.
Geometric calibration starts from local linearization, while the nonlinear solve still depends on a reasonable initial model and correct frame conventions. Base parameters are identifiable combinations; recovering every URDF inertial term requires priors or physical constraints and may remain ambiguous.
The original paper leaves joint geometric-dynamic identification and nonlinear flexibility as future directions. The current repository improves physical reconstruction and calibration validation, but it still separates the primary calibration and identification workflows. Documentation and APIs are evolving quickly, and v0.4.5 is classified as beta software.
Takeaway
FIGAROH is best understood as an experiment-design and model-identification framework, not simply a least-squares implementation. Its key chain is:
[ \text{measurement contract} \rightarrow \text{regressor and observability} \rightarrow \text{optimal excitation} \rightarrow \text{parameter estimation} \rightarrow \text{held-out validation} \rightarrow \text{updated model}. ]
The paper establishes that this chain can serve very different robots and humans. The current figaroh-plus code turns it into a cleaner library with stronger verification and export support. For serious calibration work, the value is precisely this integration: the toolbox helps decide what can be identified, which experiment will identify it, and whether the resulting model actually improved.