feat: initial commit - massive-cloud point cloud processing system
This commit is contained in:
@@ -0,0 +1,307 @@
|
||||
"""End-to-end orchestration for *research / validation* runs.
|
||||
|
||||
Composition::
|
||||
|
||||
data_prep.prepare_cloud_from_cad / from_scan (Phase A)
|
||||
api.compute_coupler_measurement (Phase B)
|
||||
|
||||
Phase A is the validation / data-preparation part: STP → mesh → sample
|
||||
→ noise → transform → denoise → register. Phase B is the public
|
||||
measurement algorithm. This module saves every intermediate artifact
|
||||
under a structured run directory so engineers can debug and so the
|
||||
sweep runner can compare runs.
|
||||
|
||||
Production callers should *not* use this module — they should call
|
||||
:func:`coupler_panel.api.compute_coupler_measurement` directly with
|
||||
their own clean point cloud.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import numpy as np
|
||||
|
||||
from .api import compute_coupler_measurement, ProgressCallback
|
||||
from .config import load_config, resolve_auto
|
||||
from .data_prep import (
|
||||
PreparedCloud,
|
||||
denoise_cloud,
|
||||
parse_cad,
|
||||
prepare_cloud_from_cad,
|
||||
prepare_cloud_from_scan,
|
||||
register_cloud,
|
||||
synthesize_cloud,
|
||||
)
|
||||
from .io_utils import (
|
||||
Artifacts,
|
||||
load_point_cloud,
|
||||
write_json,
|
||||
write_point_cloud,
|
||||
write_yaml,
|
||||
)
|
||||
from .metrics import compute_deflection_metrics
|
||||
from .roi_select import ROISpec, apply_roi, default_roi_spec, load_roi_json
|
||||
from .structures import CouplerMeasurement
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Cloud-only research entry point
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def run_coupler_measurement_pipeline(
|
||||
input_cloud: str | Path,
|
||||
out_dir: str | Path,
|
||||
*,
|
||||
config_path: str | Path | None = None,
|
||||
profile: str = "auto",
|
||||
cad_stp_path: str | Path | None = None,
|
||||
roi_spec: ROISpec | None = None,
|
||||
roi_json: str | Path | None = None,
|
||||
progress: ProgressCallback | None = None,
|
||||
) -> CouplerMeasurement:
|
||||
"""Main measurement entry: cloud (in CAD frame) → ROI → denoise → measure.
|
||||
|
||||
**No registration step.** The input cloud is assumed to already live
|
||||
in the CAD / world frame (scanner extrinsics calibrated upstream).
|
||||
If it doesn't, 4-hole Kabsch against nominal CAD holes would also
|
||||
cancel the panel-deflection signal we want to measure — so this
|
||||
pipeline deliberately does not register. For the research path that
|
||||
*does* register (using oracle deflected GT), see
|
||||
:func:`run_from_cad_pipeline`.
|
||||
|
||||
Inputs:
|
||||
|
||||
- ``cad_stp_path`` — optional STEP file. Parsed for the analytical
|
||||
panel-normal seed (speeds up + stabilises hole detection's
|
||||
in-plane projection); the parsed GT is written as ``01_gt.json``
|
||||
to ``out_dir`` for auditing.
|
||||
- ``roi_spec`` / ``roi_json`` — ROI selector applied to the cloud
|
||||
*before* denoising. If both omitted, the default ``mode='all'``
|
||||
spec (pass-through) is used. ``roi_spec`` wins over ``roi_json``.
|
||||
|
||||
Writes every intermediate to ``out_dir``. Returns a
|
||||
:class:`CouplerMeasurement`.
|
||||
"""
|
||||
art = Artifacts(out_dir)
|
||||
cfg = load_config(config_path, profile=profile)
|
||||
cfg = resolve_auto(cfg)
|
||||
write_yaml(cfg, art.resolved_config)
|
||||
|
||||
# ---- Load + ROI clip --------------------------------------------------
|
||||
raw_pts = load_point_cloud(input_cloud)
|
||||
if roi_spec is None:
|
||||
roi_spec = load_roi_json(roi_json) if roi_json is not None else default_roi_spec()
|
||||
pts, roi_diag = apply_roi(raw_pts, roi_spec)
|
||||
write_point_cloud(pts, art.path("sampled", ext="ply"))
|
||||
write_json({"spec": roi_spec.to_dict(), "diagnostics": roi_diag}, art.root / "roi.json")
|
||||
|
||||
# ---- Optional CAD parse (panel_normal_seed + audit GT JSON) ----------
|
||||
panel_seed: np.ndarray | None = None
|
||||
if cad_stp_path is not None:
|
||||
parsed = parse_cad(cad_stp_path, cfg["cad"])
|
||||
write_json(parsed.gt.to_dict(), art.path("gt", ext="json"))
|
||||
panel_seed = np.asarray(parsed.gt.plane.normal, dtype=np.float64)
|
||||
|
||||
# ---- Denoise (no Kabsch, no prepare_cloud_from_scan) -----------------
|
||||
denoised = denoise_cloud(pts, cfg.get("denoise", {}))
|
||||
write_point_cloud(denoised.points, art.path("denoised", ext="ply"))
|
||||
|
||||
# ---- Measurement ------------------------------------------------------
|
||||
result = compute_coupler_measurement(
|
||||
denoised.points,
|
||||
config=cfg,
|
||||
profile="custom",
|
||||
panel_normal_seed=panel_seed,
|
||||
progress=progress,
|
||||
)
|
||||
|
||||
write_json(result.to_dict(), art.report_json)
|
||||
write_json(result.to_dict()["report"], art.path("metrics", ext="json"))
|
||||
return result
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# CAD-driven research entry point
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def run_from_cad_pipeline(
|
||||
stp_path: str | Path,
|
||||
out_dir: str | Path,
|
||||
*,
|
||||
config_path: str | Path | None = None,
|
||||
profile: str = "auto",
|
||||
progress: ProgressCallback | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""End-to-end research run: STP → synthesise → prepare → measure → diff GT.
|
||||
|
||||
Returns a summary dict containing the measurement, GT metrics, and
|
||||
measured-minus-GT differences. Writes every intermediate cloud and
|
||||
JSON to ``out_dir``.
|
||||
"""
|
||||
art = Artifacts(out_dir)
|
||||
cfg = load_config(config_path, profile=profile)
|
||||
cfg = resolve_auto(cfg)
|
||||
write_yaml(cfg, art.resolved_config)
|
||||
|
||||
# ---- Phase A.1 — parse + GT -------------------------------------------
|
||||
parsed = parse_cad(stp_path, cfg["cad"])
|
||||
write_point_cloud(parsed.mesh.vertices, art.path("cad_mesh", ext="ply"))
|
||||
write_json(parsed.gt.to_dict(), art.path("gt", ext="json"))
|
||||
|
||||
# ---- Phase A.2 — synthesise --------------------------------------------
|
||||
synth = synthesize_cloud(
|
||||
parsed,
|
||||
sampling_cfg=cfg["sampling"],
|
||||
noise_cfg=cfg.get("noise", {}),
|
||||
transform_cfg=cfg.get("transform", {}),
|
||||
scan_cfg=cfg.get("scan_simulator", {}),
|
||||
deflection_cfg=cfg.get("panel_deflection", {}),
|
||||
)
|
||||
write_point_cloud(synth.sampled, art.path("sampled", ext="ply"))
|
||||
write_point_cloud(synth.noisy, art.path("noisy", ext="ply"))
|
||||
write_point_cloud(synth.transformed, art.path("transformed", ext="ply"))
|
||||
|
||||
# ---- Phase A.3 — denoise ----------------------------------------------
|
||||
denoised = denoise_cloud(synth.transformed, cfg.get("denoise", {}))
|
||||
write_point_cloud(denoised.points, art.path("denoised", ext="ply"))
|
||||
|
||||
# ---- Phase A.4 — register ---------------------------------------------
|
||||
# Use PCA on the cloud itself for the projection seed (the cloud is
|
||||
# still in the pre-Kabsch frame here; using the CAD normal would
|
||||
# cause foreshortening bias). Register against the *deflected* GT
|
||||
# holes so Kabsch only cancels scanner-pose jitter, not the panel
|
||||
# deflection signal we want to measure.
|
||||
registered = register_cloud(
|
||||
denoised.points,
|
||||
target_holes=synth.gt_holes_after_deflection,
|
||||
detection_cfg=cfg["detection"],
|
||||
cad_cfg=cfg["cad"],
|
||||
registration_cfg=cfg["registration"],
|
||||
panel_normal_seed=None,
|
||||
)
|
||||
write_point_cloud(registered.points, art.path("registered", ext="ply"))
|
||||
|
||||
# ---- Phase B — measurement algorithm ----------------------------------
|
||||
result = compute_coupler_measurement(
|
||||
registered.points,
|
||||
config=cfg,
|
||||
profile="custom",
|
||||
panel_normal_seed=np.asarray(parsed.gt.plane.normal, dtype=np.float64),
|
||||
progress=progress,
|
||||
)
|
||||
|
||||
# ---- GT metrics --------------------------------------------------------
|
||||
# GT for the metrics is the *deflected* panel: angles equal the
|
||||
# injection, and the maximum-distance / maximum-x-deviation values are
|
||||
# computed over the deflected 4-hole rectangle (the same primitive the
|
||||
# algorithm later sees through the noise + jitter chain).
|
||||
gt_normal = synth.gt_normal_after_deflection
|
||||
centers = synth.gt_holes_after_deflection.locating_centers()
|
||||
gt_metrics = compute_deflection_metrics(
|
||||
normal=gt_normal,
|
||||
center_C=tuple(centers.mean(axis=0).tolist()),
|
||||
panel_points=centers,
|
||||
right_axis_sign=int(cfg["metrics"].get("right_axis_sign", 1)),
|
||||
angle_clamp_deg=float(cfg["metrics"].get("angle_clamp_deg", 0.0)),
|
||||
)
|
||||
|
||||
diff = {
|
||||
"theta_right_deg": result.theta_right_deg - gt_metrics.theta_right_deg,
|
||||
"theta_ref_deg": result.theta_ref_deg - gt_metrics.theta_ref_deg,
|
||||
"D_y_max_mm": result.D_y_max_mm - gt_metrics.D_y_max_mm,
|
||||
"D_z_max_mm": result.D_z_max_mm - gt_metrics.D_z_max_mm,
|
||||
"dx_y_max_mm": result.dx_y_max_mm - gt_metrics.dx_y_max_mm,
|
||||
"dx_z_max_mm": result.dx_z_max_mm - gt_metrics.dx_z_max_mm,
|
||||
}
|
||||
|
||||
summary = {
|
||||
"stp": str(stp_path),
|
||||
"panel_deflection_injected": {
|
||||
"theta_right_deg": synth.panel_deflection_theta_right_deg,
|
||||
"theta_ref_deg": synth.panel_deflection_theta_ref_deg,
|
||||
"R": synth.panel_deflection_R.tolist(),
|
||||
},
|
||||
"scan_pose_perturbation": synth.gt_transform_4x4.tolist(),
|
||||
"registration": {
|
||||
"matrix": registered.transform_4x4.tolist(),
|
||||
"rmse_mm": registered.rmse_mm,
|
||||
"max_residual_mm": registered.max_residual_mm,
|
||||
},
|
||||
"measured": result.to_dict(),
|
||||
"gt_cad": parsed.gt.to_dict(),
|
||||
"gt_after_deflection": {
|
||||
"normal": gt_normal.tolist(),
|
||||
"locating_centers": centers.tolist(),
|
||||
},
|
||||
"gt_metrics": gt_metrics.to_dict(),
|
||||
"diff": diff,
|
||||
"config": cfg,
|
||||
}
|
||||
write_json(summary, art.path("metrics", ext="json"))
|
||||
write_json(summary, art.report_json)
|
||||
|
||||
return summary
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _try_load_normal_from_gt_json(path: str | Path) -> np.ndarray | None:
|
||||
"""Read ``plane.normal`` from a GT JSON if present. Returns ``None`` otherwise."""
|
||||
import json
|
||||
|
||||
try:
|
||||
with Path(path).open("r", encoding="utf-8") as fh:
|
||||
d = json.load(fh)
|
||||
except Exception:
|
||||
return None
|
||||
n = d.get("plane", {}).get("normal")
|
||||
if n is None or len(n) != 3:
|
||||
return None
|
||||
arr = np.asarray(n, dtype=np.float64)
|
||||
norm = float(np.linalg.norm(arr))
|
||||
if norm < 1e-9:
|
||||
return None
|
||||
return arr / norm
|
||||
|
||||
|
||||
def _load_holeset_from_json(path: str | Path):
|
||||
"""Reconstruct a HoleSet from the JSON written by ``GroundTruth.to_dict``."""
|
||||
import json
|
||||
|
||||
from .structures import Hole, HoleSet
|
||||
|
||||
with Path(path).open("r", encoding="utf-8") as fh:
|
||||
d = json.load(fh)
|
||||
holes = d["holes"]
|
||||
locating = tuple(
|
||||
Hole(
|
||||
center=tuple(h["center"]),
|
||||
radius_mm=float(h["radius_mm"]),
|
||||
fit_residual_rms_mm=float(h.get("fit_residual_rms_mm", 0.0)),
|
||||
role=h.get("role", "locating"),
|
||||
)
|
||||
for h in holes["locating"]
|
||||
)
|
||||
central = None
|
||||
if holes.get("central") is not None:
|
||||
c = holes["central"]
|
||||
central = Hole(
|
||||
center=tuple(c["center"]),
|
||||
radius_mm=float(c["radius_mm"]),
|
||||
fit_residual_rms_mm=float(c.get("fit_residual_rms_mm", 0.0)),
|
||||
role="central",
|
||||
)
|
||||
return HoleSet(locating=locating, central=central)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"run_coupler_measurement_pipeline",
|
||||
"run_from_cad_pipeline",
|
||||
]
|
||||
Reference in New Issue
Block a user