cloudanalyzer 0.1.0__tar.gz → 0.3.0__tar.gz

{cloudanalyzer-0.1.0/cloudanalyzer.egg-info → cloudanalyzer-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudanalyzer
-Version: 0.1.0
+Version: 0.3.0
 Summary: CLI-first QA toolkit for point cloud, trajectory, and 3D perception outputs
 Author: rsasaki0109
 License-Expression: MIT
@@ -27,6 +27,9 @@ Requires-Dist: numpy>=1.24.0
 Requires-Dist: typer>=0.9.0
 Requires-Dist: matplotlib>=3.7.0
 Requires-Dist: PyYAML>=6.0
+Requires-Dist: laspy>=2.5.0
+Requires-Dist: lazrs>=0.6.0
+Requires-Dist: scipy>=1.6.0
 Provides-Extra: dev
 Requires-Dist: build>=1.2.2; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
@@ -39,7 +42,7 @@ Dynamic: license-file
 
 AI-friendly CLI tool for point cloud analysis and evaluation.
 
-For the full product overview (Japanese), demos, and tutorials, see the [repository root README](https://github.com/rsasaki0109/CloudAnalyzer/blob/main/README.md).
+For the full product overview, demos, and tutorials, see the [repository root README](https://github.com/rsasaki0109/CloudAnalyzer/blob/main/README.md).
 
 ## Install
 
@@ -68,24 +71,27 @@ python3 -m twine check dist/*
 
 ## Commands
 
-There are **31** CLI subcommands (see `ca --help`). Summary:
+There are **35** CLI subcommands (see `ca --help`). Summary:
 
 ### Analysis & Evaluation
 
 | Command | Description |
 |---|---|
 | `ca compare` | Compare two point clouds with ICP/GICP registration |
+| `ca scan-match-debug` | Debug one scan-to-map ICP/GICP attempt with before/after distances and artifacts |
 | `ca diff` | Quick distance stats (no registration) |
 | `ca evaluate` | F1, Chamfer, Hausdorff, AUC evaluation |
 | `ca check` | Config-driven unified QA (`cloudanalyzer.yaml`) |
 | `ca init-check` | Emit a starter `cloudanalyzer.yaml` profile |
+| `ca detection-evaluate` | 3D object detection QA for axis-aligned boxes (mAP, precision/recall/F1, reports) |
 | `ca ground-evaluate` | Ground segmentation QA (precision/recall/F1/IoU, optional gates) |
+| `ca tracking-evaluate` | 3D multi-object tracking QA (MOTA, ID switches, precision/recall/F1, reports) |
 | `ca traj-evaluate` | ATE, translational RPE, drift evaluation for trajectories |
 | `ca traj-batch` | Batch trajectory benchmark with coverage, gate, and reports |
 | `ca run-evaluate` | Combined map + trajectory QA for one run |
 | `ca run-batch` | Combined map + trajectory benchmark across multiple runs |
-| `ca info` | Point cloud metadata (points, BBox, centroid) |
-| `ca stats` | Detailed statistics (density, spacing distribution) |
+| `ca info` | Point cloud metadata (points, BBox, robust BBox, centroid) |
+| `ca stats` | Detailed statistics (density, robust density, spacing distribution) |
 | `ca batch` | Run info on all files in a directory |
 
 ### Processing
@@ -141,6 +147,20 @@ ca traj-evaluate estimated.csv reference.csv \
   --report trajectory_report.html
 # report also writes sibling trajectory overlay and error timeline PNGs
 
+# Ground segmentation evaluation with report output
+ca ground-evaluate estimated_ground.pcd estimated_nonground.pcd \
+  reference_ground.pcd reference_nonground.pcd \
+  --min-f1 0.9 --min-iou 0.8 --report ground_report.html
+
+# 3D object detection evaluation from JSON box sequences
+ca detection-evaluate estimated_detection.json reference_detection.json \
+  --iou-thresholds 0.25,0.5 --min-map 0.9 --report detection_report.html
+
+# 3D multi-object tracking evaluation from JSON box sequences
+ca tracking-evaluate estimated_tracking.json reference_tracking.json \
+  --iou-threshold 0.5 --min-mota 0.8 --max-id-switches 2 \
+  --report tracking_report.html
+
 # Ignore constant initial translation offset
 ca traj-evaluate estimated.csv reference.csv --align-origin
 
@@ -185,10 +205,10 @@ ca web estimated.pcd reference.pcd --heatmap
 # Browser run viewer: map heatmap + trajectory overlay
 ca web map.pcd map_ref.pcd --heatmap \
   --trajectory traj.csv --trajectory-reference traj_ref.csv
-# paired trajectory があると worst ATE pose と worst RPE segment を viewer 上で強調する
-# marker / segment をクリックすると timestamp と error summary を inspection panel に表示する
-# click 時は camera も選択箇所へ寄り、Reset View で全景に戻せる
-# trajectory error timeline も viewer 内に出て、point click で 3D selection と同期する
+# With paired trajectories, the viewer also highlights the worst ATE pose and worst RPE segment.
+# Clicking a marker or segment shows the timestamp and error summary in the inspection panel.
+# The camera also moves toward the selected location, and Reset View returns to the full scene.
+# The trajectory error timeline is shown in the same viewer and stays synced with 3D point selections.
 
 # === Compare ===
 ca compare source.pcd target.pcd \
@@ -226,6 +246,11 @@ ca batch /path/to/results/ --evaluate reference.pcd --min-auc 0.95 --max-chamfer
 ca density-map cloud.pcd -o density.png -r 1.0 -a z
 ```
 
+`ca info` and `ca stats` also report p01-p99 robust extents and the number/ratio
+of points outside that robust bounding box. These fields are useful for SLAM maps
+where a small number of far outliers can dominate the ordinary axis-aligned
+extent and hide whether the main map body is stable.
+
 ## Global Options
 
 ```bash
@@ -238,7 +263,7 @@ ca --quiet ...      # Suppress non-error output
 - `--output-json <path>` — Dump result as JSON file
 - `--format-json` — Print JSON to stdout for piping
 - `--plot <path>` — F1 curve plot (evaluate only)
-- `--report <path>` — Markdown/HTML report (`batch`, `traj-evaluate`, `traj-batch`, `run-evaluate`, `run-batch`)
+- `--report <path>` — Markdown/HTML report (`batch`, `detection-evaluate`, `ground-evaluate`, `tracking-evaluate`, `traj-evaluate`, `traj-batch`, `run-evaluate`, `run-batch`)
 
 ```bash
 # Pipe JSON to jq
@@ -250,6 +275,40 @@ ca evaluate a.pcd b.pcd --format-json | jq '.auc'
 
 Point cloud / trajectory / perception QA is usually driven by `ca check` and a `cloudanalyzer.yaml` config (see [docs/ci.md](https://github.com/rsasaki0109/CloudAnalyzer/blob/main/docs/ci.md) and the [map quality gate tutorial](https://github.com/rsasaki0109/CloudAnalyzer/blob/main/docs/tutorial-map-quality-gate.md)).
 
+For object detection / tracking, the current stable contract is a JSON sequence:
+
+```json
+{
+  "frames": [
+    {
+      "frame_id": "000001",
+      "boxes": [
+        {
+          "label": "car",
+          "center": [0.0, 0.0, 0.0],
+          "size": [4.0, 1.8, 1.6],
+          "score": 0.97,
+          "track_id": "pred-17"
+        }
+      ]
+    }
+  ]
+}
+```
+
+`ca detection-evaluate` uses `label`, `center`, `size`, and optional `score`; `ca tracking-evaluate` also requires `track_id`. Geometry is currently evaluated as **axis-aligned 3D boxes** and ignores yaw if present in the source JSON.
+
+Checked-in public sample JSONs live under `demo_assets/public/rellis3d-frame-000001/object_eval/`:
+
+- `detection_reference.json`
+- `detection_estimated_good.json`
+- `detection_estimated_regressed.json`
+- `tracking_reference.json`
+- `tracking_estimated_good.json`
+- `tracking_estimated_regressed.json`
+
+Those examples are generated from the public RELLIS-3D seed frame; the tracking files are deterministic synthetic 3-frame sequences seeded from that public frame so the contract can be demonstrated without bundling a full public MOT dataset.
+
 In **this** GitHub repo, reusable workflows run the same gates in CI. Pin to a **tag or SHA** when calling them from another repository (not floating `@main`).
 
 ```yaml
@@ -300,4 +359,5 @@ result = split("large.pcd", "tiles/", grid_size=100.0)
 
 - `.pcd` (Point Cloud Data)
 - `.ply` (Polygon File Format)
-- `.las` (LiDAR)
+- `.las` / `.laz` (LiDAR)
+- `.csv` (`x,y,z` or GLIM-style `x_m,y_m,z_m`)

{cloudanalyzer-0.1.0 → cloudanalyzer-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 AI-friendly CLI tool for point cloud analysis and evaluation.
 
-For the full product overview (Japanese), demos, and tutorials, see the [repository root README](https://github.com/rsasaki0109/CloudAnalyzer/blob/main/README.md).
+For the full product overview, demos, and tutorials, see the [repository root README](https://github.com/rsasaki0109/CloudAnalyzer/blob/main/README.md).
 
 ## Install
 
@@ -31,24 +31,27 @@ python3 -m twine check dist/*
 
 ## Commands
 
-There are **31** CLI subcommands (see `ca --help`). Summary:
+There are **35** CLI subcommands (see `ca --help`). Summary:
 
 ### Analysis & Evaluation
 
 | Command | Description |
 |---|---|
 | `ca compare` | Compare two point clouds with ICP/GICP registration |
+| `ca scan-match-debug` | Debug one scan-to-map ICP/GICP attempt with before/after distances and artifacts |
 | `ca diff` | Quick distance stats (no registration) |
 | `ca evaluate` | F1, Chamfer, Hausdorff, AUC evaluation |
 | `ca check` | Config-driven unified QA (`cloudanalyzer.yaml`) |
 | `ca init-check` | Emit a starter `cloudanalyzer.yaml` profile |
+| `ca detection-evaluate` | 3D object detection QA for axis-aligned boxes (mAP, precision/recall/F1, reports) |
 | `ca ground-evaluate` | Ground segmentation QA (precision/recall/F1/IoU, optional gates) |
+| `ca tracking-evaluate` | 3D multi-object tracking QA (MOTA, ID switches, precision/recall/F1, reports) |
 | `ca traj-evaluate` | ATE, translational RPE, drift evaluation for trajectories |
 | `ca traj-batch` | Batch trajectory benchmark with coverage, gate, and reports |
 | `ca run-evaluate` | Combined map + trajectory QA for one run |
 | `ca run-batch` | Combined map + trajectory benchmark across multiple runs |
-| `ca info` | Point cloud metadata (points, BBox, centroid) |
-| `ca stats` | Detailed statistics (density, spacing distribution) |
+| `ca info` | Point cloud metadata (points, BBox, robust BBox, centroid) |
+| `ca stats` | Detailed statistics (density, robust density, spacing distribution) |
 | `ca batch` | Run info on all files in a directory |
 
 ### Processing
@@ -104,6 +107,20 @@ ca traj-evaluate estimated.csv reference.csv \
   --report trajectory_report.html
 # report also writes sibling trajectory overlay and error timeline PNGs
 
+# Ground segmentation evaluation with report output
+ca ground-evaluate estimated_ground.pcd estimated_nonground.pcd \
+  reference_ground.pcd reference_nonground.pcd \
+  --min-f1 0.9 --min-iou 0.8 --report ground_report.html
+
+# 3D object detection evaluation from JSON box sequences
+ca detection-evaluate estimated_detection.json reference_detection.json \
+  --iou-thresholds 0.25,0.5 --min-map 0.9 --report detection_report.html
+
+# 3D multi-object tracking evaluation from JSON box sequences
+ca tracking-evaluate estimated_tracking.json reference_tracking.json \
+  --iou-threshold 0.5 --min-mota 0.8 --max-id-switches 2 \
+  --report tracking_report.html
+
 # Ignore constant initial translation offset
 ca traj-evaluate estimated.csv reference.csv --align-origin
 
@@ -148,10 +165,10 @@ ca web estimated.pcd reference.pcd --heatmap
 # Browser run viewer: map heatmap + trajectory overlay
 ca web map.pcd map_ref.pcd --heatmap \
   --trajectory traj.csv --trajectory-reference traj_ref.csv
-# paired trajectory があると worst ATE pose と worst RPE segment を viewer 上で強調する
-# marker / segment をクリックすると timestamp と error summary を inspection panel に表示する
-# click 時は camera も選択箇所へ寄り、Reset View で全景に戻せる
-# trajectory error timeline も viewer 内に出て、point click で 3D selection と同期する
+# With paired trajectories, the viewer also highlights the worst ATE pose and worst RPE segment.
+# Clicking a marker or segment shows the timestamp and error summary in the inspection panel.
+# The camera also moves toward the selected location, and Reset View returns to the full scene.
+# The trajectory error timeline is shown in the same viewer and stays synced with 3D point selections.
 
 # === Compare ===
 ca compare source.pcd target.pcd \
@@ -189,6 +206,11 @@ ca batch /path/to/results/ --evaluate reference.pcd --min-auc 0.95 --max-chamfer
 ca density-map cloud.pcd -o density.png -r 1.0 -a z
 ```
 
+`ca info` and `ca stats` also report p01-p99 robust extents and the number/ratio
+of points outside that robust bounding box. These fields are useful for SLAM maps
+where a small number of far outliers can dominate the ordinary axis-aligned
+extent and hide whether the main map body is stable.
+
 ## Global Options
 
 ```bash
@@ -201,7 +223,7 @@ ca --quiet ...      # Suppress non-error output
 - `--output-json <path>` — Dump result as JSON file
 - `--format-json` — Print JSON to stdout for piping
 - `--plot <path>` — F1 curve plot (evaluate only)
-- `--report <path>` — Markdown/HTML report (`batch`, `traj-evaluate`, `traj-batch`, `run-evaluate`, `run-batch`)
+- `--report <path>` — Markdown/HTML report (`batch`, `detection-evaluate`, `ground-evaluate`, `tracking-evaluate`, `traj-evaluate`, `traj-batch`, `run-evaluate`, `run-batch`)
 
 ```bash
 # Pipe JSON to jq
@@ -213,6 +235,40 @@ ca evaluate a.pcd b.pcd --format-json | jq '.auc'
 
 Point cloud / trajectory / perception QA is usually driven by `ca check` and a `cloudanalyzer.yaml` config (see [docs/ci.md](https://github.com/rsasaki0109/CloudAnalyzer/blob/main/docs/ci.md) and the [map quality gate tutorial](https://github.com/rsasaki0109/CloudAnalyzer/blob/main/docs/tutorial-map-quality-gate.md)).
 
+For object detection / tracking, the current stable contract is a JSON sequence:
+
+```json
+{
+  "frames": [
+    {
+      "frame_id": "000001",
+      "boxes": [
+        {
+          "label": "car",
+          "center": [0.0, 0.0, 0.0],
+          "size": [4.0, 1.8, 1.6],
+          "score": 0.97,
+          "track_id": "pred-17"
+        }
+      ]
+    }
+  ]
+}
+```
+
+`ca detection-evaluate` uses `label`, `center`, `size`, and optional `score`; `ca tracking-evaluate` also requires `track_id`. Geometry is currently evaluated as **axis-aligned 3D boxes** and ignores yaw if present in the source JSON.
+
+Checked-in public sample JSONs live under `demo_assets/public/rellis3d-frame-000001/object_eval/`:
+
+- `detection_reference.json`
+- `detection_estimated_good.json`
+- `detection_estimated_regressed.json`
+- `tracking_reference.json`
+- `tracking_estimated_good.json`
+- `tracking_estimated_regressed.json`
+
+Those examples are generated from the public RELLIS-3D seed frame; the tracking files are deterministic synthetic 3-frame sequences seeded from that public frame so the contract can be demonstrated without bundling a full public MOT dataset.
+
 In **this** GitHub repo, reusable workflows run the same gates in CI. Pin to a **tag or SHA** when calling them from another repository (not floating `@main`).
 
 ```yaml
@@ -263,4 +319,5 @@ result = split("large.pcd", "tiles/", grid_size=100.0)
 
 - `.pcd` (Point Cloud Data)
 - `.ply` (Polygon File Format)
-- `.las` (LiDAR)
+- `.las` / `.laz` (LiDAR)
+- `.csv` (`x,y,z` or GLIM-style `x_m,y_m,z_m`)

{cloudanalyzer-0.1.0 → cloudanalyzer-0.3.0}/ca/__init__.py

@@ -1,3 +1,3 @@
 """CloudAnalyzer - AI-friendly CLI tool for point cloud analysis."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"

{cloudanalyzer-0.1.0 → cloudanalyzer-0.3.0}/ca/align.py

@@ -2,7 +2,7 @@
 
 import open3d as o3d
 
-from ca.io import load_point_cloud
+from ca.io import load_point_cloud, save_point_cloud
 from ca.registration import register
 
 
@@ -49,7 +49,7 @@ def align(
         })
         accumulated += transformed
 
-    o3d.io.write_point_cloud(output_path, accumulated)
+    save_point_cloud(output_path, accumulated)
 
     return {
         "output": output_path,