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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.41.0rc2
+Version: 0.42.0rc1
 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.0rc2 → x4d_devkit-0.42.0rc1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.41.0rc2"
+version = "0.42.0rc1"
 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.42.0rc1/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.0rc2 → x4d_devkit-0.42.0rc1}/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.0rc2"
+    assert x4d_devkit.__version__ == "0.42.0rc1"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

x4d_devkit-0.42.0rc1/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.0rc2 → x4d_devkit-0.42.0rc1}/x4d_devkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.41.0rc2
+Version: 0.42.0rc1
 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.0rc2 → x4d_devkit-0.42.0rc1}/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.0rc2 → x4d_devkit-0.42.0rc1}/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