修正基线系标定默认：机械初值、地面ROI与航向偏移可配，并补充G90窗导出与契约测试

Co-authored-by: Cursor <cursoragent@cursor.com>

code/finalize_direct_rtk_lidar.py

@@ -34,7 +34,50 @@ def delta(a: np.ndarray, b: np.ndarray) -> dict:
     }
 
 
-def corrected(raw: dict, backend: str, reference_height: float) -> dict:
+def coordinate_contract_audit(raw: dict) -> dict:
+    """Compare the data-driven solution with the declared mechanical initial.
+
+    A near-180-degree disagreement is not auto-corrected: it normally means
+    that one physical forward-axis statement is reversed. Silently rotating
+    the point cloud would preserve residuals while changing the frame contract.
+    """
+    path_text = raw.get("solver_initial_extrinsic")
+    if not path_text:
+        return {
+            "status": "mechanical_initial_not_available",
+            "requires_physical_axis_confirmation": False,
+        }
+    path = Path(path_text)
+    if not path.exists():
+        return {
+            "status": "mechanical_initial_file_missing",
+            "requires_physical_axis_confirmation": False,
+            "mechanical_initial_path": str(path),
+        }
+    initial_document = load(path)
+    initial = np.asarray(initial_document["matrix_4x4"], float)
+    solution = np.asarray(raw["matrix_4x4"], float)
+    comparison = delta(initial, solution)
+    near_180 = abs(comparison["rotation_deg"] - 180.0) <= 15.0
+    return {
+        "status": "near_180_degree_axis_conflict" if near_180 else "no_near_180_degree_axis_conflict",
+        "requires_physical_axis_confirmation": near_180,
+        "mechanical_initial_path": str(path.resolve()),
+        "solution_relative_to_mechanical_initial": comparison,
+        "note": (
+            "No automatic 180-degree point-cloud flip was applied. Confirm the Helios "
+            "aviation-connector side and the G90 vehicle-forward definition before deployment."
+        ),
+    }
+
+
+def corrected(raw: dict, backend: str, reference_height: float, heading_offset_deg: float) -> dict:
+    baseline_frame = abs(heading_offset_deg) <= 1e-12
+    x_axis = (
+        "horizontal projection of the rawHeading baseline direction reported by the receiver"
+        if baseline_frame else
+        "vehicle forward after applying the configured G90 heading offset"
+    )
     return {
         "schema_version": 1,
         "success": bool(raw["success"]),
@@ -43,20 +86,24 @@ def corrected(raw: dict, backend: str, reference_height: float) -> dict:
         "frames": {
             "RTK": {
                 "origin": "GGA positioning reference point; confirm ANT1/reference antenna in receiver configuration",
-                "x_axis": "horizontal projection of the rawHeading baseline direction reported by the receiver",
+                "x_axis": x_axis,
                 "y_axis": "left",
                 "z_axis": "up",
-                "yaw_enu_deg": "90 - rawHeadingDeg",
+                "yaw_enu_deg": f"90 - (rawHeadingDeg + {heading_offset_deg:g})",
+                "frame_mode": "baseline_raw_heading" if baseline_frame else "vehicle_forward_heading_offset",
             },
             "LiDAR": "raw LiDAR sensor frame",
         },
         "backend": backend,
-        "measured_lidar_extrinsic_used_as_initial": False,
-        "body_heading_offset_used": False,
+        "measured_lidar_extrinsic_used_as_initial": bool(raw.get("measured_extrinsic_used_as_initial")),
+        "solver_initial_extrinsic": raw.get("solver_initial_extrinsic"),
+        "body_heading_offset_deg": heading_offset_deg,
+        "body_heading_offset_used": abs(heading_offset_deg) > 1e-12,
         "body_antenna_lever_xy_used": False,
         "translation_m": raw["translation_m"],
         "rotation_rpy_deg_xyz": raw["rotation_rpy_deg_xyz"],
         "quaternion_xyzw": raw["quaternion_xyzw"],
+        "coordinate_contract_audit": coordinate_contract_audit(raw),
         "matrix_4x4": raw["matrix_4x4"],
         "quality": {
             "stations": raw["estimation"]["stations"],
@@ -80,6 +127,7 @@ def main() -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument("--result-root", type=Path, required=True)
     parser.add_argument("--reference-height", type=float, required=True)
+    parser.add_argument("--heading-offset-deg", type=float, required=True)
     args = parser.parse_args()
 
     def solver_output(directory: str) -> Path:
@@ -94,16 +142,26 @@ def main() -> None:
     }
     docs = {}
     for backend, path in paths.items():
-        document = corrected(load(path), backend, args.reference_height)
+        document = corrected(
+            load(path), backend, args.reference_height, args.heading_offset_deg
+        )
         write(path.with_name("extrinsic_rtk_lidar.json"), document)
         docs[backend] = document
 
     open_t = np.asarray(docs["open3d_gicp"]["matrix_4x4"], float)
     small_t = np.asarray(docs["small_gicp"]["matrix_4x4"], float)
     final = dict(docs["consensus"])
+    needs_axis_confirmation = bool(
+        final["coordinate_contract_audit"]["requires_physical_axis_confirmation"]
+    )
     final["selection"] = {
-        "recommended": True,
-        "reason": "Uses only motion pairs accepted independently by both Open3D GICP and small_gicp",
+        "recommended": not needs_axis_confirmation,
+        "reason": (
+            "Physical axis confirmation is required because the data-driven solution differs "
+            "from the declared mechanical initial by approximately 180 degrees"
+            if needs_axis_confirmation else
+            "Uses only motion pairs accepted independently by both Open3D GICP and small_gicp"
+        ),
         "open3d_vs_small_gicp": delta(open_t, small_t),
     }
 
@@ -117,6 +175,8 @@ def main() -> None:
             "translation_rms_m": final["quality"]["residuals"]["translation_m"]["rms"],
             "rotation_rms_deg": final["quality"]["residuals"]["rotation_deg"]["rms"],
             "condition_number": final["quality"]["weighted_jacobian_condition_number"],
+            "coordinate_contract_status": final["coordinate_contract_audit"]["status"],
+            "recommended_for_deployment": final["selection"]["recommended"],
         },
         "backend_difference": delta(open_t, small_t),
     }