x4d-devkit 0.46.0rc3__tar.gz → 0.47.0__tar.gz

{x4d_devkit-0.46.0rc3/x4d_devkit.egg-info → x4d_devkit-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.46.0rc3
+Version: 0.47.0
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0

{x4d_devkit-0.46.0rc3 → x4d_devkit-0.47.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.46.0rc3"
+version = "0.47.0"
 description = "Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation"
 readme = "README.md"
 license = "Apache-2.0"

{x4d_devkit-0.46.0rc3 → x4d_devkit-0.47.0}/tests/test_clean_basemap.py

@@ -54,6 +54,7 @@ def fixture():
         raw_point_ordinals=[0, 1, 2],
         timestamps_ns=[100, 100, 100],
         decisions=decisions[:3],
+        intensities=[2.5, 19.0, 240.0],
     )
     profile = {
         "algorithm": {"id": "clean_static_basemap", "version": "0.6.0"},
@@ -102,6 +103,7 @@ def fixture():
                 "bounds": bounds,
                 "geometry": descriptor,
                 "mapping": mapping.descriptor("mapping"),
+                "intensity_range": [2.5, 240.0],
             }
         ],
         "diagnostics": {
@@ -139,6 +141,9 @@ def validate(manifest, assets):
         manifest,
         read_asset=assets.__getitem__,
         observation_to_world=lambda sweep, ordinals, times: original[ordinals],
+        observation_intensity=lambda sweep, ordinals, times: np.asarray(
+            [2.5, 19.0, 240.0], dtype=np.float32
+        )[ordinals],
     )
 
 
@@ -155,6 +160,7 @@ def remap(manifest, assets, **overrides):
         "raw_point_ordinals": mapping["raw_point_ordinal"],
         "timestamps_ns": mapping["timestamp_ns"],
         "decisions": mapping["decision"],
+        "intensities": mapping["intensity"],
     }
     encoded = encode_clean_basemap_mapping(
         geometry_raw_sha256=chunk["geometry"]["raw_sha256"], **(arguments | overrides)
@@ -190,6 +196,67 @@ def test_complete_scene_and_exact_original_observation_roundtrip():
         parsed.data["profile"]["voxel_size_m"] = 1
 
 
+def test_intensity_is_original_float32_and_does_not_change_geometry():
+    manifest, assets, _ = fixture()
+    before = copy.deepcopy(manifest["scene_source"])
+    assert MAPPING_DTYPE.itemsize == 24
+    remap(manifest, assets, intensities=[2.5, 20.0, 240.0])
+    assert manifest["scene_source"] == before
+    with pytest.raises(ValueError, match="intensity differs from its original"):
+        validate(manifest, assets)
+
+
+@pytest.mark.parametrize(
+    "values",
+    [
+        [1, 2],
+        [True, False, True],
+        [1, float("nan"), 3],
+        [1, float("inf"), 3],
+        [1, 1e100, 3],
+    ],
+)
+def test_invalid_intensity_cannot_be_encoded(values):
+    manifest, assets, _ = fixture()
+    with pytest.raises(ValueError, match="intensit"):
+        remap(manifest, assets, intensities=values)
+
+
+def test_intensity_range_cannot_hide_wrong_values():
+    manifest, assets, _ = fixture()
+    manifest["chunks"][0]["intensity_range"] = [0.0, 255.0]
+    manifest["basemap_revision"] = compute_clean_basemap_revision(manifest)
+    with pytest.raises(ValueError, match="intensity range"):
+        validate(manifest, assets)
+
+
+def test_old_manifest_and_mapping_are_rejected():
+    manifest, assets, _ = fixture()
+    manifest["contract_version"] = "x4d-clean-static-basemap-v4"
+    manifest["basemap_revision"] = compute_clean_basemap_revision(manifest)
+    with pytest.raises(ValueError):
+        parse_clean_basemap_manifest(manifest)
+    chunk = manifest["chunks"][0]
+    descriptor = chunk["mapping"]
+    raw = bytearray(zstandard.ZstdDecompressor().decompress(assets[descriptor["path"]]))
+    raw[:8] = b"X4DCBM2\0"
+    payload = zstandard.ZstdCompressor().compress(raw)
+    descriptor = dict(
+        descriptor,
+        path=f"generated/reconstruction/clean_basemap/mapping/{sha256_bytes(payload)[7:]}.zst",
+        sha256=sha256_bytes(payload),
+        raw_sha256=sha256_bytes(bytes(raw)),
+        size_bytes=len(payload),
+    )
+    with pytest.raises(ValueError):
+        decode_clean_basemap_mapping(
+            payload,
+            descriptor=descriptor,
+            geometry_raw_sha256=chunk["geometry"]["raw_sha256"],
+            point_count=chunk["point_count"],
+        )
+
+
 def test_decision_proof_reuse_is_within_one_validation_call(monkeypatch):
     manifest, assets, _ = fixture()
     decoded = []
@@ -229,6 +296,9 @@ def test_cached_decision_proof_still_checks_every_carrier_read(changed):
             manifest,
             read_asset=read_asset,
             observation_to_world=lambda sweep, ordinals, times: original[ordinals],
+            observation_intensity=lambda sweep, ordinals, times: np.asarray(
+                [2.5, 19.0, 240.0], dtype=np.float32
+            )[ordinals],
         )
 
 
@@ -319,6 +389,9 @@ def test_original_observation_projection_is_required(kind):
             manifest,
             read_asset=assets.__getitem__,
             observation_to_world=lambda *args: result,
+            observation_intensity=lambda sweep, ordinals, times: np.asarray(
+                [2.5, 19.0, 240.0], dtype=np.float32
+            )[ordinals],
         )
 
 
@@ -387,6 +460,7 @@ def test_every_byte_in_last_record_obeys_exact_decision_domain(family):
             raw_point_ordinals=np.arange(count),
             timestamps_ns=np.full(count, 100),
             decisions=np.full(count, KEEP_GROUND),
+            intensities=np.arange(count, dtype=np.float32),
         )
         domain, decode = KEEP_CODES, decode_clean_basemap_mapping
         arguments = dict(geometry_raw_sha256=anchor, point_count=count)

{x4d_devkit-0.46.0rc3 → x4d_devkit-0.47.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.46.0rc3"
+    assert x4d_devkit.__version__ == "0.47.0"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.46.0rc3 → x4d_devkit-0.47.0}/x4d_devkit/clean_basemap.py

@@ -36,9 +36,9 @@ from x4d_devkit.semantic_scene_contract import (
 )
 from x4d_devkit.time_contract import parse_time_ns
 
-CLEAN_BASEMAP_CONTRACT_VERSION = "x4d-clean-static-basemap-v4"
+CLEAN_BASEMAP_CONTRACT_VERSION = "x4d-clean-static-basemap-v5"
 CLEAN_BASEMAP_OPERATION = "reconstruction.prepare_clean_static_basemap"
-CLEAN_BASEMAP_MAPPING_FORMAT = "x4d-clean-static-basemap-mapping-v2"
+CLEAN_BASEMAP_MAPPING_FORMAT = "x4d-clean-static-basemap-mapping-v3"
 CLEAN_BASEMAP_DECISION_FORMAT = "x4d-clean-static-basemap-decisions-v3"
 _DECISION_CACHE_BYTES = 128 << 20
 CLEAN_BASEMAP_INPUT_FIELDS = frozenset(
@@ -55,7 +55,7 @@ DECISION_CODES = frozenset({0, 1, 3, 18, 32, 33, 34})
 KEEP_CODES = frozenset({0, 1, 3})
 _HASH = re.compile(r"^sha256:[0-9a-f]{64}$")
 _HEADER = struct.Struct("<8sI32s")
-_MAPPING_MAGIC = b"X4DCBM2\0"
+_MAPPING_MAGIC = b"X4DCBM3\0"
 _DECISION_MAGIC = b"X4DCBD3\0"
 MAPPING_DTYPE = np.dtype(
     [
@@ -63,7 +63,8 @@ MAPPING_DTYPE = np.dtype(
         ("raw_point_ordinal", "<u4"),
         ("timestamp_ns", "<u8"),
         ("decision", "u1"),
-        ("reserved", "u1", (7,)),
+        ("intensity", "<f4"),
+        ("reserved", "u1", (3,)),
     ]
 )
 _MAX_U32 = (1 << 32) - 1
@@ -108,6 +109,21 @@ def _bounds(value: Any, path: str) -> None:
         raise ValueError(f"{path} is inverted")
 
 
+def _intensity_range(value: Any, path: str) -> None:
+    if (
+        not isinstance(value, list)
+        or len(value) != 2
+        or any(
+            isinstance(v, bool)
+            or not isinstance(v, (int, float))
+            or not math.isfinite(v)
+            for v in value
+        )
+        or value[0] > value[1]
+    ):
+        raise ValueError(f"{path} must contain finite ordered intensity bounds")
+
+
 def _freeze(value: Any) -> Any:
     if isinstance(value, Mapping):
         return MappingProxyType({k: _freeze(v) for k, v in value.items()})
@@ -349,7 +365,16 @@ def parse_clean_basemap_manifest(
     for i, chunk in enumerate(chunks):
         path = f"chunks[{i}]"
         _object(
-            chunk, {"ordinal", "point_count", "bounds", "geometry", "mapping"}, path
+            chunk,
+            {
+                "ordinal",
+                "point_count",
+                "bounds",
+                "intensity_range",
+                "geometry",
+                "mapping",
+            },
+            path,
         )
         if chunk["ordinal"] != i or type(chunk["ordinal"]) is not int:
             raise ValueError("chunk ordinals must be contiguous in canonical order")
@@ -360,6 +385,7 @@ def parse_clean_basemap_manifest(
             f"{path}.point_count",
         )
         _bounds(chunk["bounds"], f"{path}.bounds")
+        _intensity_range(chunk["intensity_range"], f"{path}.intensity_range")
         bounds.append(chunk["bounds"])
         _descriptor(chunk["geometry"], "geometry", f"{path}.geometry")
         _descriptor(chunk["mapping"], "mapping", f"{path}.mapping")
@@ -467,6 +493,7 @@ def encode_clean_basemap_mapping(
     raw_point_ordinals: Any,
     timestamps_ns: Any,
     decisions: Any,
+    intensities: Any,
 ) -> CleanBasemapPayload:
     vectors = {
         "sweep_index": _vector(sweep_indices, _MAX_U32, "sweep_indices"),
@@ -487,6 +514,19 @@ def encode_clean_basemap_mapping(
     records = np.zeros(count, dtype=MAPPING_DTYPE)
     for key, vector in vectors.items():
         records[key] = vector
+    intensity = np.asarray(intensities)
+    if (
+        intensity.shape != (count,)
+        or intensity.dtype.kind not in "iuf"
+        or not np.isfinite(intensity).all()
+    ):
+        raise ValueError(
+            "intensities must contain one finite numeric value per geometry point"
+        )
+    with np.errstate(over="ignore", invalid="ignore"):
+        records["intensity"] = intensity
+    if not np.isfinite(records["intensity"]).all():
+        raise ValueError("intensities must be representable as finite float32")
     return _encode(_MAPPING_MAGIC, geometry_raw_sha256, records)
 
 
@@ -511,6 +551,7 @@ def decode_clean_basemap_mapping(
         np.any(records["reserved"] != 0)
         or np.any(~np.isin(records["decision"], tuple(KEEP_CODES)))
         or np.any(records["timestamp_ns"] > _MAX_I64)
+        or not np.isfinite(records["intensity"]).all()
     ):
         raise ValueError(
             "mapping records are noncanonical or contain removed observations"
@@ -604,6 +645,9 @@ def validate_clean_basemap_resource(
     observation_to_world: Callable[
         [Mapping[str, Any], np.ndarray, np.ndarray], np.ndarray
     ],
+    observation_intensity: Callable[
+        [Mapping[str, Any], np.ndarray, np.ndarray], np.ndarray
+    ],
 ) -> CleanBasemapManifest:
     """Verify exact original observations and byte-exact complete scene correspondence."""
     parsed = parse_clean_basemap_manifest(manifest)
@@ -681,6 +725,11 @@ def validate_clean_basemap_resource(
             geometry_raw_sha256=descriptor["raw_sha256"],
             point_count=chunk["point_count"],
         )
+        if [
+            float(mapping["intensity"].min()),
+            float(mapping["intensity"].max()),
+        ] != chunk["intensity_range"]:
+            raise ValueError("basemap intensity range differs from its actual points")
         if np.any(mapping["sweep_index"] >= len(data["sweep_sources"])):
             raise ValueError("mapping source index is outside the pinned source tables")
         for index in np.unique(mapping["sweep_index"]):
@@ -715,6 +764,16 @@ def validate_clean_basemap_resource(
                 raise ValueError(
                     "basemap geometry differs from its original observations"
                 )
+            intensity = np.asarray(observation_intensity(sweep, ordinals, times))
+            if (
+                intensity.shape != ordinals.shape
+                or intensity.dtype.kind not in "iuf"
+                or not np.isfinite(intensity).all()
+                or not np.array_equal(intensity, mapping["intensity"][selected])
+            ):
+                raise ValueError(
+                    "basemap intensity differs from its original observations"
+                )
     return parsed
 
 

{x4d_devkit-0.46.0rc3 → x4d_devkit-0.47.0}/x4d_devkit/client/reconstruction.py

@@ -307,7 +307,7 @@ class ReconstructionAPI:
                 "clean basemap chunk ordinal is outside the exact resource"
             )
         chunk = chunks[chunk_ordinal]
-        return decode_clean_basemap_mapping(
+        mapping = decode_clean_basemap_mapping(
             self._client.assets.fetch(
                 state.asset_urls[chunk["mapping"]["path"]]
             ).content,
@@ -315,6 +315,14 @@ class ReconstructionAPI:
             geometry_raw_sha256=chunk["geometry"]["raw_sha256"],
             point_count=chunk["point_count"],
         )
+        if [
+            float(mapping["intensity"].min()),
+            float(mapping["intensity"].max()),
+        ] != list(chunk["intensity_range"]):
+            raise ValueError(
+                "clean basemap intensity range differs from its descriptor"
+            )
+        return mapping
 
     def cancel_clean_basemap_task(
         self, *, project_id: int, task_id: str

{x4d_devkit-0.46.0rc3 → x4d_devkit-0.47.0/x4d_devkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.46.0rc3
+Version: 0.47.0
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0