x4d-devkit 0.41.0rc1__tar.gz → 0.42.0__tar.gz

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.41.0rc1
+Version: 0.42.0
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0
@@ -23,6 +23,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: httpx>=0.27
 Requires-Dist: rfc8785==0.1.4
 Requires-Dist: zstandard<1,>=0.23
+Requires-Dist: pyproj<4,>=3.6
 Provides-Extra: inference
 Requires-Dist: pydantic>=2.0; extra == "inference"
 Requires-Dist: fastapi>=0.110; extra == "inference"

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.42.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.41.0rc1"
+version = "0.42.0"
 description = "Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation"
 readme = "README.md"
 license = "Apache-2.0"
@@ -29,6 +29,7 @@ dependencies = [
     "httpx>=0.27",
     "rfc8785==0.1.4",
     "zstandard>=0.23,<1",
+    "pyproj>=3.6,<4",
 ]
 
 [project.optional-dependencies]

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.42.0}/tests/test_preannotation_client.py

@@ -50,7 +50,7 @@ def _service() -> dict:
 
 def _run(*, status: str = "queued", reused: bool = False) -> dict:
     succeeded = status == "succeeded"
-    return {
+    result = {
         "run_id": "preann-run-1",
         "request_identity": _digest("a"),
         "project_id": 7,
@@ -76,7 +76,34 @@ def _run(*, status: str = "queued", reused: bool = False) -> dict:
         "created_at": "2026-08-18T08:00:00Z",
         "updated_at": "2026-08-18T08:02:00Z",
         "reused": reused,
+        "attempt_number": 1,
+        "attempt_count": 1,
+        "latest_attempt_id": "preann-run-1",
+        "is_latest_attempt": True,
+        "retry_of_run_id": None,
     }
+    result["attempts"] = [
+        {
+            key: copy.deepcopy(result[key])
+            for key in (
+                "run_id",
+                "attempt_number",
+                "retry_of_run_id",
+                "status",
+                "progress",
+                "error",
+                "candidate_id",
+                "temporal_workflow_id",
+                "actor_id",
+                "started_at",
+                "completed_at",
+                "cancellation_requested_at",
+                "created_at",
+                "updated_at",
+            )
+        }
+    ]
+    return result
 
 
 def _portable_candidate() -> dict:
@@ -144,7 +171,10 @@ def test_control_plane_uses_typed_service_run_cancel_and_candidate_contracts():
         requests.append(request)
         if request.url.path == "/api/v1/preannotation/services":
             return httpx.Response(200, json=[_service()])
-        if request.url.path == "/api/v1/preannotation/runs" and request.method == "POST":
+        if (
+            request.url.path == "/api/v1/preannotation/runs"
+            and request.method == "POST"
+        ):
             return httpx.Response(202, json=_run())
         if request.url.path == "/api/v1/preannotation/runs" and request.method == "GET":
             return httpx.Response(200, json=[_run(status="succeeded")])
@@ -172,9 +202,7 @@ def test_control_plane_uses_typed_service_run_cancel_and_candidate_contracts():
             profile_id="centerpoint-track-v1",
             config={"score_threshold": 0.4},
         )
-        runs = client.preannotation.list_runs(
-            project_id=7, clip_id="clip-1", limit=10
-        )
+        runs = client.preannotation.list_runs(project_id=7, clip_id="clip-1", limit=10)
         fetched = client.preannotation.get_run("preann-run-1")
         cancellation = client.preannotation.cancel_run("preann-run-1")
         candidate = client.preannotation.get_candidate(_digest("d"))
@@ -260,3 +288,72 @@ def test_create_run_rejects_non_i_json_config_before_request():
                 profile_id="centerpoint-track-v1",
                 config={"threshold": float("nan")},
             )
+
+
+def _retried_run():
+    previous = _run(status="failed")["attempts"][0]
+    result = _run(status="succeeded")
+    result.update(
+        run_id="preann-run-2",
+        attempt_number=2,
+        attempt_count=2,
+        latest_attempt_id="preann-run-2",
+        retry_of_run_id="preann-run-1",
+    )
+    result["attempts"] = [
+        previous,
+        {key: copy.deepcopy(result[key]) for key in previous},
+    ]
+    return result
+
+
+def test_retry_history_round_trip_and_historical_run():
+    payload = _retried_run()
+    parsed = PlatformPreannotationRun.model_validate(payload)
+    assert parsed.attempt_count == 2
+    assert parsed.attempts[0].status == PlatformPreannotationRunStatus.FAILED
+    assert parsed.attempts[1].candidate_id == parsed.candidate_id
+    assert (
+        PlatformPreannotationRun.model_validate_json(parsed.model_dump_json()) == parsed
+    )
+    payload.update(payload["attempts"][0])
+    payload["is_latest_attempt"] = False
+    old = PlatformPreannotationRun.model_validate(payload)
+    assert old.run_id == "preann-run-1" and old.latest_attempt_id == "preann-run-2"
+    payload["attempts"] = []
+    assert PlatformPreannotationRun.model_validate(payload).attempt_count == 2
+
+
+@pytest.mark.parametrize(
+    "field,value",
+    [
+        ("attempt_count", 1),
+        ("attempt_number", 1),
+        ("attempt_number", True),
+        ("latest_attempt_id", "preann-missing"),
+        ("is_latest_attempt", False),
+        ("is_latest_attempt", 1),
+        ("retry_of_run_id", None),
+        ("attempts", [_run(status="failed")["attempts"][0]]),
+    ],
+)
+def test_inconsistent_attempt_identity_is_rejected(field, value):
+    payload = _retried_run()
+    payload[field] = value
+    with pytest.raises(ValidationError):
+        PlatformPreannotationRun.model_validate(payload)
+
+
+@pytest.mark.parametrize("mutation", ["unknown", "link", "order", "state"])
+def test_malformed_attempt_history_is_rejected(mutation):
+    payload = _retried_run()
+    if mutation == "unknown":
+        payload["attempts"][0]["unknown_field"] = True
+    elif mutation == "link":
+        payload["attempts"][1]["retry_of_run_id"] = "another-run"
+    elif mutation == "order":
+        payload["attempts"].reverse()
+    else:
+        payload["attempts"][1]["progress"]["stage"] = "different-state"
+    with pytest.raises(ValidationError):
+        PlatformPreannotationRun.model_validate(payload)

x4d_devkit-0.42.0/tests/test_roadmark_preview.py

@@ -0,0 +1,87 @@
+import copy
+import json
+
+import numpy as np
+import pytest
+
+from x4d_devkit.roadmark_preview import preview_roadmark
+
+BIG = 2024121315242816837
+LINE = [[3, 0, 4, 1], [3.00001, 0.00001, 5, 1]]
+
+
+def source():
+    return {"valid": True, "centerline": [
+        {"class": "centerline", "id": BIG, "points": LINE, "orientation": True,
+         "successor": [BIG + 1], "predecessor": [], "left_lane": [BIG + 2]},
+        {"class": "centerline", "id": BIG + 1, "points": LINE,
+         "successor": [], "predecessor": [BIG]}],
+        "lane": [{"class": "lane", "id": BIG + 2, "points": LINE, "dashtype": "dash"}],
+        "special_points": [{"class": "special_points", "id": 1, "points": [[3, 0, 8]], "type": "type"}],
+        "arrow": [{"class": "arrow", "id": 2, "subclass": "straight", "vertices": [],
+                   "points": [[3, 0, 2], [3.00001, 0, 2], [3.00001, 0.00001, 2], [3, 0.00001, 2]]}],
+        "map_labeling_area": [{"points": [[[3, 0, 2], [3.00001, 0, 2], [3, 0.00001, 2], [3, 0, 2]]]}]}
+
+
+def preview(payload, matrix=None):
+    if matrix is None:
+        matrix = [[1, 0, 0, -500000], [0, 1, 0, 0], [0, 0, 1, -1], [0, 0, 0, 1]]
+    return preview_roadmark(json.dumps(payload), source_crs="EPSG:4326", metric_crs="EPSG:32631",
+                            clip_world_from_metric=matrix)
+
+
+def test_exact_source_ids_graph_and_uninterpreted_values():
+    payload = source()
+    original = copy.deepcopy(payload)
+    view = preview(payload)
+    assert payload == original
+    assert view["features"][0]["id"] == str(BIG)
+    assert view["features"][1]["id"] == str(BIG + 1)
+    assert view["relations"] == [
+        {"type": "successor", "from_id": str(BIG), "to_id": str(BIG + 1)},
+        {"type": "left_lane", "from_id": str(BIG), "to_id": str(BIG + 2)}]
+    feature = view["features"][0]
+    assert feature["properties"]["orientation"] is True
+    assert feature["properties"]["source_point_extra"] == [[1], [1]]
+    assert view["features"][3]["properties"]["type"] == "type"
+    assert view["coverage"][0]["completeness"] == "unknown"
+
+
+def test_horizontal_projection_axis_order_height_and_rigid_transform():
+    view = preview(source())
+    point = view["features"][0]["geometry"]["points"][0]
+    np.testing.assert_allclose(point, [0, 0, 3], atol=1e-8)
+    assert view["features"][4]["geometry"]["rings"][0][0] == view["features"][4]["geometry"]["rings"][0][-1]
+    assert view["source"]["vertical_datum"] == "unspecified"
+    # Rotation acts on height too; never reduce the transform to yaw/XY.
+    matrix = [[1, 0, 0, -500000], [0, 0, -1, 0], [0, 1, 0, 0], [0, 0, 0, 1]]
+    np.testing.assert_allclose(preview(source(), matrix)["features"][0]["geometry"]["points"][0], [0, -4, 0], atol=1e-8)
+
+
+@pytest.mark.parametrize("change", [
+    lambda p: p["centerline"][0].update(id=float(BIG)),
+    lambda p: p["centerline"][0].update(successor=[0]),
+    lambda p: p["centerline"][1].update(predecessor=[]),
+    lambda p: p["centerline"][0].update(left_lane=[BIG + 1]),
+    lambda p: p["centerline"][0].update(points=[[float("nan"), 0, 0], [3, 1, 0]]),
+    lambda p: p["centerline"][0].update(points=[[3, 0, 0], [3, 0, 0]]),
+    lambda p: p["lane"][0].update(id=BIG),
+    lambda p: p.update(unknown_layer=[]),
+    lambda p: p.update(deceleration_zone=[{}]),
+])
+def test_invalid_source_is_not_repaired(change):
+    payload = source()
+    change(payload)
+    with pytest.raises(ValueError):
+        preview(payload)
+
+
+def test_no_implicit_crs_or_transform_and_duplicate_keys_rejected():
+    args = dict(source_crs="EPSG:4326", metric_crs="EPSG:32631", clip_world_from_metric=np.eye(4).tolist())
+    with pytest.raises(ValueError, match="Duplicate"):
+        preview_roadmark('{"valid":true,"valid":false}', **args)
+    with pytest.raises(ValueError, match="SE\\(3\\)"):
+        preview(source(), (np.eye(4) * 2).tolist())
+    with pytest.raises(ValueError, match="metres"):
+        preview_roadmark(json.dumps(source()), **{**args, "metric_crs": "EPSG:4326"})
+    assert preview({"valid": False})["bounds"] is None

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.42.0}/tests/test_sdk_api.py

@@ -11,7 +11,7 @@ from x4d_devkit.eval.matching import MetricData
 
 
 def test_package_version_is_current_release():
-    assert x4d_devkit.__version__ == "0.41.0rc1"
+    assert x4d_devkit.__version__ == "0.42.0"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.42.0}/x4d_devkit/client/preannotation.py

@@ -86,7 +86,53 @@ class PlatformPreannotationService(_ControlPlaneModel):
         return value
 
 
-class PlatformPreannotationRun(_ControlPlaneModel):
+class PlatformPreannotationRunAttempt(_ControlPlaneModel):
+    """One immutable attempt identity and its current execution state."""
+
+    run_id: str
+    attempt_number: int = Field(ge=1, strict=True)
+    retry_of_run_id: str | None
+    status: PlatformPreannotationRunStatus
+    progress: PreannotationRunProgress
+    error: PreannotationRunError | None
+    candidate_id: str | None
+    temporal_workflow_id: str
+    actor_id: int | None = Field(gt=0, strict=True)
+    started_at: datetime | None
+    completed_at: datetime | None
+    cancellation_requested_at: datetime | None
+    created_at: datetime
+    updated_at: datetime
+
+    @field_validator("run_id", "retry_of_run_id", mode="before")
+    @classmethod
+    def validate_attempt_id(cls, value: Any, info: Any) -> str | None:
+        if value is None and info.field_name == "retry_of_run_id":
+            return None
+        return _protocol_token(value, path="preannotation attempt identifier")
+
+    @field_validator("candidate_id", mode="before")
+    @classmethod
+    def validate_attempt_candidate(cls, value: Any) -> str | None:
+        return None if value is None else _sha256(value, path="attempt.candidate_id")
+
+    @field_validator("temporal_workflow_id", mode="before")
+    @classmethod
+    def validate_attempt_workflow(cls, value: Any) -> str:
+        return _canonical_string(value, path="attempt.temporal_workflow_id")
+
+    @model_validator(mode="after")
+    def validate_attempt_result(self) -> "PlatformPreannotationRunAttempt":
+        if (self.status == PlatformPreannotationRunStatus.SUCCEEDED) != (
+            self.candidate_id is not None
+        ):
+            raise ValueError("only succeeded attempts must contain candidate_id")
+        if (self.attempt_number == 1) != (self.retry_of_run_id is None):
+            raise ValueError("only the first attempt has no retry predecessor")
+        return self
+
+
+class PlatformPreannotationRun(PlatformPreannotationRunAttempt):
     """One durable X-4D preannotation run."""
 
     run_id: str
@@ -99,6 +145,10 @@ class PlatformPreannotationRun(_ControlPlaneModel):
     profile_id: str
     pipeline_identity: str
     checkpoint_identity: str
+    attempt_count: int = Field(ge=1, strict=True)
+    latest_attempt_id: str
+    is_latest_attempt: bool = Field(strict=True)
+    attempts: list[PlatformPreannotationRunAttempt]
     status: PlatformPreannotationRunStatus
     progress: PreannotationRunProgress
     error: PreannotationRunError | None
@@ -117,7 +167,9 @@ class PlatformPreannotationRun(_ControlPlaneModel):
     def validate_project_id(cls, value: Any) -> int:
         return _positive_int(value, path="preannotation run.project_id")
 
-    @field_validator("run_id", "service_id", "profile_id", mode="before")
+    @field_validator(
+        "run_id", "service_id", "profile_id", "latest_attempt_id", mode="before"
+    )
     @classmethod
     def validate_protocol_id(cls, value: Any) -> str:
         return _protocol_token(value, path="preannotation run identifier")
@@ -169,9 +221,48 @@ class PlatformPreannotationRun(_ControlPlaneModel):
     def succeeded_run_has_candidate(self) -> "PlatformPreannotationRun":
         if self.status == PlatformPreannotationRunStatus.SUCCEEDED:
             if self.candidate_id is None:
-                raise ValueError("succeeded preannotation run must contain candidate_id")
+                raise ValueError(
+                    "succeeded preannotation run must contain candidate_id"
+                )
         elif self.candidate_id is not None:
-            raise ValueError("only a succeeded preannotation run may contain candidate_id")
+            raise ValueError(
+                "only a succeeded preannotation run may contain candidate_id"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def validate_attempt_history(self) -> "PlatformPreannotationRun":
+        if self.attempt_number > self.attempt_count:
+            raise ValueError("attempt_number must not exceed attempt_count")
+        if self.is_latest_attempt != (self.attempt_number == self.attempt_count):
+            raise ValueError("latest attempt flag disagrees with attempt count")
+        if self.is_latest_attempt != (self.run_id == self.latest_attempt_id):
+            raise ValueError("latest attempt flag disagrees with run identity")
+        # The list endpoint explicitly omits expansion; detail includes history.
+        if not self.attempts:
+            return self
+        if len(self.attempts) != self.attempt_count:
+            raise ValueError("attempt_count must match complete attempt history")
+        ids = [attempt.run_id for attempt in self.attempts]
+        if len(set(ids)) != len(ids) or self.run_id not in ids:
+            raise ValueError("attempt history must uniquely contain this run")
+        for number, attempt in enumerate(self.attempts, 1):
+            predecessor = None if number == 1 else ids[number - 2]
+            if (
+                attempt.attempt_number != number
+                or attempt.retry_of_run_id != predecessor
+            ):
+                raise ValueError(
+                    "attempt history must be ordered with exact retry links"
+                )
+        if self.latest_attempt_id != ids[-1] or self.is_latest_attempt != (
+            self.run_id == self.latest_attempt_id
+        ):
+            raise ValueError("latest attempt identity disagrees with history")
+        current = self.attempts[ids.index(self.run_id)]
+        for field in PlatformPreannotationRunAttempt.model_fields:
+            if getattr(current, field) != getattr(self, field):
+                raise ValueError(f"current attempt disagrees with history: {field}")
         return self
 
 
@@ -384,13 +475,17 @@ class PreannotationAPI:
         payload = self._get("/preannotation/runs", params=params)
         if type(payload) is not list:
             raise TypeError("preannotation runs response must be a list")
-        results = tuple(PlatformPreannotationRun.model_validate(item) for item in payload)
+        results = tuple(
+            PlatformPreannotationRun.model_validate(item) for item in payload
+        )
         if any(
             item.project_id != project_id
             or (clip_id is not None and item.clip_id != clip_id)
             for item in results
         ):
-            raise ValueError("preannotation runs response is outside the requested scope")
+            raise ValueError(
+                "preannotation runs response is outside the requested scope"
+            )
         return results
 
     def get_run(self, run_id: str) -> PlatformPreannotationRun:
@@ -401,7 +496,9 @@ class PreannotationAPI:
             self._get(f"/preannotation/runs/{run_id}")
         )
         if result.run_id != run_id:
-            raise ValueError("preannotation run response identity does not match request")
+            raise ValueError(
+                "preannotation run response identity does not match request"
+            )
         return result
 
     def cancel_run(self, run_id: str) -> PlatformPreannotationCancellation:

x4d_devkit-0.42.0/x4d_devkit/roadmark_preview.py

@@ -0,0 +1,219 @@
+"""Explicit RoadMark source inspection; never a native Dataset compatibility reader.
+
+The caller supplies the geographic CRS and the rigid metric-to-Clip transform.
+Source layer names and unresolved properties remain source facts. This preview
+does not create native categories, lane segments, or annotation state.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from typing import Any
+
+import numpy as np
+from pyproj import CRS, Transformer
+from pyproj.exceptions import ProjError
+
+from x4d_devkit.core.transform import Transform
+from x4d_devkit.json_contract import ensure_i_json
+
+CONTRACT = "x4d-roadmark-preview-v1"
+SOURCE_LAYERS = {
+    "arrow": "polygon", "centerline": "polyline", "crosswalk": "polygon",
+    "curb": "polyline", "lane": "polyline", "special_points": "point",
+    "stop_line": "polyline",
+}
+_EMPTY_ONLY = {"construction_area", "deceleration_line", "deceleration_zone"}
+_RELATIONS = ("predecessor", "successor", "left_lane", "right_lane")
+
+
+def _source_json(raw: str) -> dict:
+    # RoadMark IDs are integers beyond I-JSON's safe range. Decode exactly once,
+    # before converting identity fields to strings. Native I-JSON is unchanged.
+    def members(pairs):
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise ValueError(f"Duplicate RoadMark field: {key}")
+            result[key] = value
+        return result
+
+    def constant(value):
+        raise ValueError(f"Non-finite RoadMark number: {value}")
+
+    if type(raw) is not str or len(raw.encode("utf-8")) > 8_000_000:
+        raise ValueError("RoadMark input must be UTF-8 text of at most 8 MB")
+    payload = json.loads(raw, object_pairs_hook=members, parse_constant=constant)
+    if type(payload) is not dict:
+        raise ValueError("RoadMark total map must be an object")
+    unknown = set(payload) - set(SOURCE_LAYERS) - _EMPTY_ONLY - {"valid", "map_labeling_area"}
+    if unknown:
+        raise ValueError(f"Unsupported RoadMark layers: {sorted(unknown)}")
+    if type(payload.get("valid")) is not bool:
+        raise ValueError("RoadMark valid must be a boolean")
+    return payload
+
+
+def _id(value: Any) -> str:
+    if type(value) is not int:
+        raise ValueError("RoadMark IDs must be JSON integers, not rounded floats")
+    return str(value)
+
+
+def _property(value: Any) -> Any:
+    if type(value) is int and abs(value) > 2**53 - 1:
+        return str(value)
+    if type(value) is list:
+        return [_property(item) for item in value]
+    if type(value) is dict:
+        return {key: _property(item) for key, item in value.items()}
+    return value
+
+
+def preview_roadmark(
+    raw: str, *, source_crs: str, metric_crs: str,
+    clip_world_from_metric: list[list[float]],
+) -> dict[str, Any]:
+    """Parse one total map into a transient, metre/XYZ, Clip-world read view.
+
+    Geographic inputs use longitude, latitude, source height. Only horizontal
+    CRS projection runs: source Z is preserved before the explicit rigid
+    transform. No vertical datum or time correction is guessed. Polygon rings
+    must already be closed; source line orientation is never reinterpreted.
+    """
+    source = _source_json(raw)
+    try:
+        geographic, metric = CRS(source_crs), CRS(metric_crs)
+    except ProjError as exc:
+        raise ValueError(f"Invalid source/metric CRS: {exc}") from exc
+    if not geographic.is_geographic or len(geographic.axis_info) != 2:
+        raise ValueError("source_crs must be an explicit two-dimensional geographic CRS")
+    if not metric.is_projected or len(metric.axis_info) != 2 or any(
+        axis.unit_conversion_factor != 1 for axis in metric.axis_info
+    ):
+        raise ValueError("metric_crs must be an explicit projected CRS in metres")
+    matrix = np.asarray(clip_world_from_metric)
+    if (matrix.shape != (4, 4) or matrix.dtype.kind not in "fiu"
+            or not np.isfinite(matrix).all()
+            or not np.allclose(matrix[3], [0, 0, 0, 1], atol=1e-9, rtol=0)
+            or not np.allclose(matrix[:3, :3].T @ matrix[:3, :3], np.eye(3), atol=1e-8, rtol=0)
+            or not np.isclose(np.linalg.det(matrix[:3, :3]), 1, atol=1e-8, rtol=0)):
+        raise ValueError("clip_world_from_metric must be a finite SE(3) matrix")
+    rigid = Transform(matrix[:3, :3], matrix[:3, 3])
+    try:
+        projector = Transformer.from_crs(geographic, metric, always_xy=True, allow_ballpark=False)
+    except ProjError as exc:
+        raise ValueError(f"No supported horizontal projection: {exc}") from exc
+    all_points: list[list[float]] = []
+
+    def points(rows: Any, kind: str) -> list[list[float]]:
+        if type(rows) is not list or not rows:
+            raise ValueError("Geometry must contain points")
+        for row in rows:
+            if (type(row) is not list or len(row) not in (3, 4)
+                    or any(type(n) not in (int, float) or not math.isfinite(n) for n in row)
+                    or abs(row[0]) > 180 or abs(row[1]) > 90):
+                raise ValueError("RoadMark points must be finite longitude/latitude/height[/source extra]")
+        minimum = {"point": 1, "polyline": 2, "polygon": 3}[kind]
+        if len({tuple(row[:3]) for row in rows}) < minimum or (kind == "point" and len(rows) != 1):
+            raise ValueError(f"Invalid {kind} vertex count")
+        if kind == "polygon" and rows[0][:3] != rows[-1][:3]:
+            raise ValueError("RoadMark polygon rings must be explicitly closed")
+        xyz = np.array([row[:3] for row in rows], dtype=float)
+        try:
+            xyz[:, 0], xyz[:, 1] = projector.transform(xyz[:, 0], xyz[:, 1], errcheck=True)
+        except ProjError as exc:
+            raise ValueError(f"Source coordinates cannot be projected: {exc}") from exc
+        converted = rigid.apply(xyz)
+        if not np.isfinite(converted).all():
+            raise ValueError("Non-finite projected geometry")
+        result = converted.tolist()
+        all_points.extend(result)
+        return result
+
+    features, relations, coverage = [], [], []
+    records: dict[str, dict] = {}
+    for layer, rows in source.items():
+        if layer == "valid":
+            continue
+        if type(rows) is not list:
+            raise ValueError(f"RoadMark {layer} must be an array")
+        if layer in _EMPTY_ONLY:
+            if rows:
+                raise ValueError(f"Non-empty {layer} has no verified source geometry mapping")
+            continue
+        if layer == "map_labeling_area":
+            for area in rows:
+                if (type(area) is not dict or set(area) != {"points"}
+                        or type(area["points"]) is not list or len(area["points"]) != 1):
+                    raise ValueError("Invalid RoadMark map_labeling_area")
+                coverage.append({"geometry": {"type": "polygon", "rings": [
+                    points(ring, "polygon") for ring in area["points"]]}, "completeness": "unknown"})
+            continue
+        for row in rows:
+            if type(row) is not dict or row.get("class") != layer:
+                raise ValueError(f"RoadMark class must match layer {layer}")
+            identity = _id(row.get("id"))
+            if identity in records:
+                raise ValueError(f"Duplicate RoadMark ID: {identity}")
+            records[identity] = row
+            kind = SOURCE_LAYERS[layer]
+            if layer == "arrow":
+                # This source uses four ordered corners for the marked region,
+                # not a closed silhouette of the painted arrow itself.
+                converted = points(row.get("points"), "polyline")
+                if len(converted) != 4 or len({tuple(p) for p in converted}) != 4:
+                    raise ValueError("RoadMark arrow regions require four distinct corners")
+                converted = [*converted, converted[0]]
+            else:
+                converted = points(row.get("points"), kind)
+            geometry = {"type": kind}
+            geometry.update({"point": converted[0]} if kind == "point" else
+                            {"rings": [converted]} if kind == "polygon" else {"points": converted})
+            properties = {key: _property(value) for key, value in row.items()
+                          if key not in {"id", "class", "points", *_RELATIONS}}
+            if any(len(point) == 4 for point in row["points"]):
+                properties["source_point_extra"] = [point[3:] for point in row["points"]]
+            features.append({"id": identity, "layer": layer, "geometry": geometry, "properties": properties})
+    for identity, row in records.items():
+        for name in _RELATIONS:
+            refs = row.get(name, [])
+            if type(refs) is not list:
+                raise ValueError(f"RoadMark {name} must be an array")
+            targets = [_id(value) for value in refs]
+            if len(set(targets)) != len(targets):
+                raise ValueError(f"Duplicate {name} relation on {identity}")
+            for target in targets:
+                other = records.get(target)
+                if other is None:
+                    raise ValueError(f"Dangling RoadMark reference: {identity} -> {target}")
+                if name in ("left_lane", "right_lane"):
+                    if row["class"] != "centerline" or other["class"] != "lane":
+                        raise ValueError("RoadMark boundary references must connect centerline to lane")
+                else:
+                    reverse = "predecessor" if name == "successor" else "successor"
+                    if (row["class"] != other["class"] or type(other.get(reverse, [])) is not list
+                            or int(identity) not in other.get(reverse, [])):
+                        raise ValueError("RoadMark predecessor/successor must be reciprocal within a source layer")
+                if name != "predecessor":
+                    relations.append({"type": name, "from_id": identity, "to_id": target})
+    bounds = [np.min(all_points, axis=0).tolist(), np.max(all_points, axis=0).tolist()] if all_points else None
+    result = {
+        "contract_version": CONTRACT, "frame_id": "clip_world", "features": features,
+        "relations": relations, "coverage": coverage, "bounds": bounds,
+        "source": {"format": "roadmark-lb-all", "sha256": hashlib.sha256(raw.encode("utf-8")).hexdigest(),
+                   "valid": source["valid"], "source_crs": geographic.to_string(), "metric_crs": metric.to_string(),
+                   "clip_world_from_metric": matrix.tolist(), "vertical_datum": "unspecified"},
+        "limitations": ["Source layers and relation names are not native Label Schema categories.",
+                        "Source height is retained; the vertical datum is unspecified.",
+                        "Source orientation, extra point values and special-point types remain uninterpreted.",
+                        "Coverage completeness is unknown; source valid does not establish completeness.",
+                        "No per-frame visibility or pose-time correction is inferred."],
+    }
+    ensure_i_json(result)
+    return result
+
+
+__all__ = ["CONTRACT", "preview_roadmark"]

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.42.0}/x4d_devkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.41.0rc1
+Version: 0.42.0
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0
@@ -23,6 +23,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: httpx>=0.27
 Requires-Dist: rfc8785==0.1.4
 Requires-Dist: zstandard<1,>=0.23
+Requires-Dist: pyproj<4,>=3.6
 Provides-Extra: inference
 Requires-Dist: pydantic>=2.0; extra == "inference"
 Requires-Dist: fastapi>=0.110; extra == "inference"

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.42.0}/x4d_devkit.egg-info/SOURCES.txt

@@ -34,6 +34,7 @@ tests/test_platform_pose.py
 tests/test_preannotation_client.py
 tests/test_reconstruction_client.py
 tests/test_release_gate.py
+tests/test_roadmark_preview.py
 tests/test_sdk_api.py
 tests/test_semantic_scene_authoring.py
 tests/test_semantic_scene_client.py
@@ -63,6 +64,7 @@ x4d_devkit/json_contract.py
 x4d_devkit/label_schema.py
 x4d_devkit/lidar_materialization.py
 x4d_devkit/materialize.py
+x4d_devkit/roadmark_preview.py
 x4d_devkit/semantic_scene_authoring.py
 x4d_devkit/semantic_scene_contract.py
 x4d_devkit/time_contract.py

{x4d_devkit-0.41.0rc1 → x4d_devkit-0.42.0}/x4d_devkit.egg-info/requires.txt

@@ -2,6 +2,7 @@ numpy>=1.24
 httpx>=0.27
 rfc8785==0.1.4
 zstandard<1,>=0.23
+pyproj<4,>=3.6
 
 [dev]
 pytest>=7.0