StrideLIO

中文说明 · 中文用户手册

A point cloud can look clean while a legged robot is standing still, then grow double walls and blurred edges as soon as the robot starts walking. The bag usually contains clues, but rates and topic lists alone do not explain which part of the walking cycle is associated with the damage.

StrideLIO reads a recorded LiDAR, IMU, and LIO run and works backward from that question. It estimates a locomotion-cycle proxy from the IMU, measures scan consistency with trimmed ICP, searches for a LiDAR-to-IMU time offset, and puts scan residuals and pose disturbances back onto the cycle phase. Each finding keeps its raw metrics, confidence, time range, and the next check worth doing. When the bag is too short or the evidence is weak, the report says so.

The tool stays offline and read only. It does not connect to a live ROS graph, send motion commands, change FAST-LIO settings, or upload robot data.

The current public release is 0.1.1 alpha. Synthetic tests cover a 2 Hz cycle, a 25 ms time offset, dropped messages, TF gaps, and missing per-point time fields. Repeated on-robot validation is still in progress.

Why this exists

bagx covers broad ROS bag readiness, including topic health, synchronization, framework checks, anomaly discovery, and tuning assistance. StrideLIO keeps a much narrower scope. It studies whether scan residuals and pose disturbances repeat at particular phases of a legged robot's IMU-derived locomotion cycle, then compares that evidence across runs.

Findings are evidence-ranked hypotheses, not claims of proven causality.

Install

Python 3.10 or newer is required.

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

On Windows PowerShell, activate with .venv\Scripts\Activate.ps1.

Quick start

stridelio inspect /data/run_01

stridelio analyze /data/run_01 \
  --profile unitree-l2 \
  --pose-topic /Odometry \
  --out reports/run_01

stridelio baseline fit \
  /data/healthy_01 /data/healthy_02 /data/healthy_03 \
  --pose-topic /Odometry \
  --out healthy-baseline.json

stridelio analyze /data/test_run \
  --pose-topic /Odometry \
  --baseline healthy-baseline.json \
  --out reports/test_run

stridelio compare \
  reports/run_5s/report.json \
  reports/run_10s/report.json \
  reports/run_120s/report.json \
  --out reports/duration-comparison.html

Unitree L2 defaults are unilidar/cloud and unilidar/imu. Topic options are required when automatic discovery finds more than one plausible source.

What gets checked

• topic rate, gaps, non-monotonic stamps, non-finite values, extreme points, and IMU extremes;
• PointCloud2 per-point time fields used for deskewing;
• an IMU cycle proxy estimated by Welch PSD plus autocorrelation;
• deterministic, downsampled, trimmed point-to-point ICP on at most 300 scan pairs;
• an IMU-to-scan lag search over +/-100 ms;
• pose/TF discontinuities and cycle-conditioned scan or pose residuals;
• an optional tiny robust baseline model stored as plain JSON.

Every analysis writes report.json and a self-contained report.html. No CDN, server, or network connection is used.

The stable v1 JSON contract includes source SHA-256, topic selection, cycle proxy, metrics, findings, anomaly windows, and model status. The packaged schema is stridelio/data/report-v1.schema.json.

Healthy baseline requirements

Baseline fitting requires at least three healthy bags and at least 120 valid feature windows. The model stores medians, median absolute deviations, and a 99th-percentile robust anomaly threshold. If a run lacks the model's required features, analysis continues without a model score.

Supported inputs

StrideLIO uses rosbags and supports ROS 2 SQLite3/MCAP and ROS 1 bag files. The first release targets standard sensor_msgs/PointCloud2, sensor_msgs/Imu, nav_msgs/Odometry, geometry_msgs/PoseStamped, and tf2_msgs/TFMessage messages. Custom messages need to be registered with rosbags before they can be decoded.

Absolute trajectory drift is not labeled without ground truth or a known loop closure. StrideLIO reports path and endpoint displacement, jumps, and attitude jitter while keeping drift assessment explicitly unavailable in that case.

Public benchmark policy

The repository does not redistribute robot datasets. See benchmarks/README.md for the Leg-KILO validation procedure and record dataset provenance in generated reports.

Development

python -m pip install -e ".[dev]"
ruff check .
mypy src/stridelio
pytest
python -m build

License

Apache-2.0. See LICENSE.

StrideLIO is the first public project listed by HexaModelLab. Use GitHub Issues for ordinary reports and SECURITY.md for security-sensitive findings.