x4d-devkit 0.53.0rc2__tar.gz → 0.54.0rc1__tar.gz

{x4d_devkit-0.53.0rc2 → x4d_devkit-0.54.0rc1}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.53.0rc2"
+version = "0.54.0rc1"
 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.53.0rc2 → x4d_devkit-0.54.0rc1}/tests/test_image_schema_migration.py

@@ -281,3 +281,48 @@ def test_typed_client_verifies_the_exact_preview_and_receipt():
         with pytest.raises(ValueError, match="another request"):
             client.image_schemas.commit_migration(request)
     assert build_image_schema_migration_request(parsed, "k").to_dict()["preview"] == preview
+
+
+def box_object(attributes=None):
+    return {
+        "id": "box_a",
+        "image_id": "image_a",
+        "view_id": "objects",
+        "category_id": "box",
+        "geometry": {"geometry_type": "box_2d", "box": {"x_min": 10, "y_min": 20, "x_max": 40, "y_max": 60}},
+        "attributes": attributes or {},
+        "attribute_ranges": [],
+    }
+
+
+def test_box_objects_migrate_alongside_lines():
+    clip = clip_payload()
+    clip["image_annotation"]["objects"] = [line_object(), box_object()]
+    clip["identity"] = build_image_identity(clip)
+    candidate, _ = image_schema_migration_candidate(
+        clip, target(clip), mapping(VISIBLE_TO_RANGE, DISCARD_STYLE)
+    )
+    assert candidate.to_dict()["image_annotation"]["objects"][1] == box_object()
+
+
+def test_a_box_value_cannot_become_a_range():
+    clip = clip_payload()
+    body = deepcopy(clip["label_schema"]["body"])
+    body["categories"][1]["attributes"] = [
+        {"id": "flag", "display_name": "Flag", "type": "boolean", "required": False, "scopes": ["object"], "values": []}
+    ]
+    clip["label_schema"] = snapshot(body)
+    clip["image_annotation"]["objects"] = [box_object({"flag": True})]
+    clip["identity"] = build_image_identity(clip)
+    new = deepcopy(body)
+    new["version"] = "2.0.0"
+    new["categories"][1]["attributes"] = []
+    rules = mapping(
+        {
+            "match": {"category_id": "box", "scope": "object", "attribute_id": "flag", "value": True},
+            "action": {"kind": "range", "attribute_id": "flag", "value": True},
+        }
+    )
+    with pytest.raises(ImageSchemaMigrationConflict) as caught:
+        image_schema_migration_candidate(clip, snapshot(new), rules)
+    assert [row["code"] for row in caught.value.conflicts] == ["mapped_value_invalid"]

x4d_devkit-0.54.0rc1/tests/test_image_source.py

@@ -0,0 +1,237 @@
+import copy
+import hashlib
+import json
+import struct
+import subprocess
+import sys
+import zlib
+
+import pytest
+
+from x4d_devkit._image_contract import ImageContractError, fingerprint
+from x4d_devkit.image_clip import build_image_identity, parse_image_clip
+from x4d_devkit.image_source import (
+    IMAGE_SOURCE_BUNDLE_VERSION,
+    IMAGE_SOURCE_PROVENANCE_VERSION,
+    build_image_source_provenance,
+    bundle_calibrations,
+    bundles_from_images,
+    image_dimensions,
+    parse_image_source_bundle,
+    read_image_source_bundle,
+    synthetic_undistorted_pinhole,
+    time_ns_dict,
+)
+from tests.image_fixtures import clip_payload
+
+
+def jpeg(width, height, extra=b""):
+    # SOI, an APP0 segment, then a baseline SOF0 frame header.
+    app0 = b"\xff\xe0" + struct.pack(">H", 16) + b"JFIF\x00\x01\x01\x00\x00\x01\x00\x01\x00\x00"
+    sof = b"\xff\xc0" + struct.pack(">HBHHB", 11, 8, height, width, 1) + b"\x01\x11\x00"
+    return b"\xff\xd8" + app0 + sof + extra + b"\xff\xd9"
+
+
+def png(width, height):
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+    chunk = struct.pack(">I", len(ihdr)) + b"IHDR" + ihdr + struct.pack(">I", zlib.crc32(b"IHDR" + ihdr))
+    return b"\x89PNG\r\n\x1a\n" + chunk
+
+
+def manifest(images, *, channel="cam_a", width=8, height=6):
+    calibration = synthetic_undistorted_pinhole(width=width, height=height, frame_id="camera", parent_frame="base")
+    samples = []
+    for ns, data in images:
+        samples.append({"timestamp": time_ns_dict(ns), "images": {channel: {
+            "timestamp": time_ns_dict(ns), "path": f"images/{channel}/{ns}.jpg", "size": len(data),
+            "sha256": hashlib.sha256(data).hexdigest(), "width": width, "height": height, "encoding": "jpeg"}}})
+    return {
+        "contract_version": IMAGE_SOURCE_BUNDLE_VERSION,
+        "bundle_id": "bundle_a",
+        "origin": {"label": "vendor delivery", "attributes": {"batch": "1104"}},
+        "timestamp_source": "filename",
+        "channels": [{"channel": channel, "calibration": calibration, "calibration_source": "synthetic"}],
+        "reference_channel": channel,
+        "sync_window_ns": 0,
+        "samples": samples,
+    }
+
+
+def write_bundle(root, value, media):
+    root.mkdir()
+    (root / "manifest.json").write_text(json.dumps(value))
+    for path, data in media.items():
+        (root / path).parent.mkdir(parents=True, exist_ok=True)
+        (root / path).write_bytes(data)
+
+
+def test_image_dimensions_read_jpeg_and_png_headers():
+    assert image_dimensions(jpeg(1920, 1536)) == ("jpeg", 1920, 1536)
+    assert image_dimensions(png(5, 7)) == ("png", 5, 7)
+    with pytest.raises(ImageContractError):
+        image_dimensions(b"GIF89a")
+    with pytest.raises(ImageContractError):
+        image_dimensions(b"\xff\xd8\xff\xd9")
+
+
+def test_synthetic_calibration_closes_the_native_calibration_grammar():
+    value = synthetic_undistorted_pinhole(width=1920, height=1536, frame_id="cam", parent_frame="base_link")
+    assert value["intrinsics"] == {"model": "pinhole", "fx": 1920.0, "fy": 1920.0, "cx": 960.0, "cy": 768.0}
+    assert value["distortion"] == {"model": "plumb_bob", "coefficients": [0.0] * 5}
+    assert value["camera_info"]["frame_id"] == value["extrinsics"]["child_frame"] == "cam"
+
+
+def test_bundle_grammar_is_closed_and_ordered():
+    data = jpeg(8, 6)
+    bundle = parse_image_source_bundle(manifest([(10, data), (20, data)]))
+    assert len(bundle.images) == 2 and bundle.fingerprint.startswith("sha256:")
+
+    for mutate in (
+        lambda v: v.update(extra=1),
+        lambda v: v.update(contract_version="x4d-image-source-bundle-v0"),
+        lambda v: v["samples"].reverse(),
+        lambda v: v["samples"][0]["images"]["cam_a"].update(path="images/cam_a/11.jpg"),
+        lambda v: v["samples"][0]["images"]["cam_a"].update(width=9),
+        lambda v: v["channels"][0].update(calibration_source="guessed"),
+        lambda v: v["channels"][0]["calibration"].update(id="calibration_cam_a"),
+        lambda v: v.update(sync_window_ns=5),
+        lambda v: v.update(timestamp_source="exif"),
+        lambda v: v.update(reference_channel="cam_b"),
+        lambda v: v.update(samples=[]),
+    ):
+        value = manifest([(10, data), (20, data)])
+        mutate(value)
+        with pytest.raises(ImageContractError):
+            parse_image_source_bundle(value)
+
+
+def test_multi_camera_bundle_uses_reference_time_and_window():
+    data = jpeg(8, 6)
+    value = manifest([(1_000, data)])
+    second = copy.deepcopy(value["channels"][0])
+    second["channel"] = "cam_b"
+    value["channels"].append(second)
+    value["sync_window_ns"] = 50
+    value["samples"][0]["images"]["cam_b"] = {**value["samples"][0]["images"]["cam_a"],
+                                              "timestamp": time_ns_dict(1_040), "path": "images/cam_b/1040.jpg"}
+    parse_image_source_bundle(value)
+    value["samples"][0]["images"]["cam_b"].update(timestamp=time_ns_dict(1_060), path="images/cam_b/1060.jpg")
+    with pytest.raises(ImageContractError, match="synchronization window"):
+        parse_image_source_bundle(value)
+
+
+def test_directory_validation_checks_file_set_and_every_byte(tmp_path):
+    data = jpeg(8, 6)
+    value = manifest([(10, data)])
+    write_bundle(tmp_path / "ok", value, {"images/cam_a/10.jpg": data})
+    assert read_image_source_bundle(tmp_path / "ok").to_dict() == value
+
+    write_bundle(tmp_path / "extra", value, {"images/cam_a/10.jpg": data, "notes.txt": b"x"})
+    with pytest.raises(ImageContractError, match="file set"):
+        read_image_source_bundle(tmp_path / "extra")
+
+    tampered = jpeg(8, 6, b"\x00")
+    write_bundle(tmp_path / "tampered", value, {"images/cam_a/10.jpg": tampered})
+    with pytest.raises(ImageContractError, match="size"):
+        read_image_source_bundle(tmp_path / "tampered")
+    assert read_image_source_bundle(tmp_path / "tampered", verify_media=False)
+
+    resized = jpeg(9, 6)
+    value_resized = manifest([(10, resized)])
+    write_bundle(tmp_path / "resized", value_resized, {"images/cam_a/10.jpg": resized})
+    value_resized["samples"][0]["images"]["cam_a"]["sha256"] = hashlib.sha256(resized).hexdigest()
+    with pytest.raises(ImageContractError, match="dimensions"):
+        read_image_source_bundle(tmp_path / "resized")
+
+
+def test_converter_splits_by_gap_and_limit_with_explicit_synthetic_calibration(tmp_path):
+    source = tmp_path / "images"
+    source.mkdir()
+    for ns in (1_000_000_000, 2_000_000_000, 3_000_000_000, 100_000_000_000):
+        (source / f"{ns}.jpg").write_bytes(jpeg(8, 6))
+    bundles = bundles_from_images(source, tmp_path / "out", channel="cam_a", origin_label="loose images",
+                                  synthetic_pinhole=True, split_gap_s=60, max_images=2)
+    assert [len(row.images) for row in bundles] == [2, 1, 1]
+    first = bundles[0].to_dict()
+    assert first["timestamp_source"] == "filename"
+    assert first["channels"][0]["calibration_source"] == "synthetic"
+    for row in bundles:
+        assert read_image_source_bundle(tmp_path / "out" / row.to_dict()["bundle_id"]).to_dict() == row.to_dict()
+
+    with pytest.raises(ImageContractError):
+        bundles_from_images(source, tmp_path / "none", channel="cam_a", origin_label="x")
+    (source / "readme.txt").write_text("x")
+    with pytest.raises(ImageContractError):
+        bundles_from_images(source, tmp_path / "bad", channel="cam_a", origin_label="x", synthetic_pinhole=True)
+
+
+def provenance_clip():
+    data = jpeg(1920, 1536)
+    value = manifest([(10_000_000_020, data)], width=1920, height=1536)
+    value["channels"][0]["calibration"]["extrinsics"]["child_frame"] = "camera"
+    bundle = parse_image_source_bundle(value)
+    clip = clip_payload()
+    provenance = build_image_source_provenance(bundle)
+    provenance["calibrations"][0]["calibration_id"] = "calibration_a"
+    clip["meta"]["source_provenance"] = provenance
+    clip["meta"]["source_bindings"][0]["source_fingerprint"] = provenance["bundle_fingerprint"]
+    return clip, bundle
+
+
+def test_absent_provenance_keeps_existing_clips_and_identity_unchanged():
+    value = clip_payload()
+    before = copy.deepcopy(value["identity"])
+    clip = parse_image_clip(value)
+    assert clip.source_provenance is None and clip.source_kind == "bag_admission"
+    assert clip.calibration_is_measured("calibration_a") is True
+    assert build_image_identity(value) == before
+
+
+def test_provenance_fragment_marks_synthetic_calibration_and_binds_the_bundle():
+    value, bundle = provenance_clip()
+    value["identity"] = build_image_identity(value)
+    clip = parse_image_clip(value)
+    assert clip.source_kind == "external_bundle"
+    assert clip.source_provenance["contract_version"] == IMAGE_SOURCE_PROVENANCE_VERSION
+    assert clip.source_provenance["bundle_fingerprint"] == fingerprint(bundle.to_dict())
+    assert clip.calibration_is_measured("calibration_a") is False
+    with pytest.raises(KeyError):
+        clip.calibration_is_measured("missing")
+    assert value["identity"]["source_revision"] != clip_payload()["identity"]["source_revision"]
+
+    for mutate in (
+        lambda v: v["meta"]["source_provenance"].update(kind="bag"),
+        lambda v: v["meta"]["source_provenance"]["calibrations"][0].update(source="unknown"),
+        lambda v: v["meta"]["source_provenance"].update(calibrations=[]),
+        lambda v: v["meta"]["source_bindings"][0].update(source_fingerprint="sha256:" + "9" * 64),
+        lambda v: v["meta"]["source_provenance"].update(extra=True),
+    ):
+        broken = copy.deepcopy(value)
+        mutate(broken)
+        broken["identity"] = build_image_identity(broken)
+        with pytest.raises(ImageContractError):
+            parse_image_clip(broken)
+
+
+def test_bundle_calibrations_are_native_rows():
+    bundle = parse_image_source_bundle(manifest([(10, jpeg(8, 6))]))
+    rows = bundle_calibrations(bundle)
+    assert rows[0]["id"] == "calibration_cam_a" and rows[0]["channel"] == "cam_a"
+
+
+def test_cli_converts_and_validates(tmp_path):
+    source = tmp_path / "images"
+    source.mkdir()
+    (source / "5000000000.jpg").write_bytes(jpeg(8, 6))
+
+    def run(*args):
+        return subprocess.run([sys.executable, "-m", "x4d_devkit.cli", *args], capture_output=True, text=True)
+
+    built = run("image-source", "from-images", str(source), "--out", str(tmp_path / "out"),
+                "--channel", "cam_a", "--origin-label", "loose", "--synthetic-pinhole")
+    assert built.returncode == 0, built.stderr
+    path = json.loads(built.stdout)["bundles"][0]["path"]
+    checked = run("image-source", "validate", path)
+    assert checked.returncode == 0 and json.loads(checked.stdout)["image_count"] == 1
+    (tmp_path / "out" / json.loads(built.stdout)["bundles"][0]["bundle_id"] / "x.txt").write_text("x")
+    assert run("image-source", "validate", path).returncode == 1

{x4d_devkit-0.53.0rc2 → x4d_devkit-0.54.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.53.0rc2"
+    assert x4d_devkit.__version__ == "0.54.0rc1"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.53.0rc2 → x4d_devkit-0.54.0rc1}/x4d_devkit/cli.py

@@ -426,6 +426,45 @@ def cmd_validate_image_export(args):
     print_json({"ok": True, "summary": summary})
 
 
+def cmd_image_source_validate(args):
+    from x4d_devkit._image_contract import ImageContractError
+    from x4d_devkit.image_source import read_image_source_bundle
+
+    try:
+        bundle = read_image_source_bundle(args.path, verify_media=not args.metadata_only)
+    except (OSError, ValueError, ImageContractError) as exc:
+        print_json({"ok": False, "error": str(exc)})
+        raise SystemExit(1) from exc
+    value = bundle.to_dict()
+    print_json({"ok": True, "bundle_id": value["bundle_id"], "bundle_fingerprint": bundle.fingerprint,
+                "sample_count": len(value["samples"]), "image_count": len(bundle.images),
+                "bytes": sum(row["size"] for row in bundle.images), "media_verified": not args.metadata_only})
+
+
+def cmd_image_source_from_images(args):
+    from x4d_devkit._image_contract import ImageContractError
+    from x4d_devkit.image_source import bundles_from_images
+
+    calibration = None
+    try:
+        if args.calibration:
+            from x4d_devkit.json_contract import parse_i_json
+
+            calibration = parse_i_json(Path(args.calibration).read_bytes(), path=args.calibration)
+        bundles = bundles_from_images(
+            args.images_dir, args.out, channel=args.channel, origin_label=args.origin_label,
+            calibration=calibration, synthetic_pinhole=args.synthetic_pinhole, focal_px=args.focal_px,
+            frame_id=args.frame_id, parent_frame=args.parent_frame, split_gap_s=args.split_gap_s,
+            max_images=args.max_images, bundle_prefix=args.bundle_prefix,
+        )
+    except (OSError, ValueError, ImageContractError) as exc:
+        print_json({"ok": False, "error": str(exc)})
+        raise SystemExit(1) from exc
+    print_json({"ok": True, "bundles": [
+        {"bundle_id": row.to_dict()["bundle_id"], "path": str(Path(args.out) / row.to_dict()["bundle_id"]),
+         "bundle_fingerprint": row.fingerprint, "image_count": len(row.images)} for row in bundles]})
+
+
 def cmd_validate(args):
     from x4d_devkit.validation import validate_clip
 
@@ -772,6 +811,28 @@ def main():
     p_image_export.add_argument("--max-json-bytes", type=int, default=64 * 1024 * 1024)
     p_image_export.set_defaults(func=cmd_validate_image_export)
 
+    p_source = sub.add_parser("image-source", help="Platform-neutral image source bundles")
+    p_source_sub = p_source.add_subparsers(dest="subcommand")
+    p_source_validate = p_source_sub.add_parser("validate", help="Validate a bundle directory and every image byte")
+    p_source_validate.add_argument("path")
+    p_source_validate.add_argument("--metadata-only", action="store_true", help="Check manifest and file set only")
+    p_source_validate.set_defaults(func=cmd_image_source_validate)
+    p_source_build = p_source_sub.add_parser("from-images", help="Convert <epoch_ns>.jpg|png files into bundles")
+    p_source_build.add_argument("images_dir")
+    p_source_build.add_argument("--out", required=True)
+    p_source_build.add_argument("--channel", required=True)
+    p_source_build.add_argument("--origin-label", required=True)
+    group = p_source_build.add_mutually_exclusive_group(required=True)
+    group.add_argument("--calibration", help="Declared calibration JSON (calibrated_sensor body without id/channel)")
+    group.add_argument("--synthetic-pinhole", action="store_true", help="Explicit undistorted placeholder calibration")
+    p_source_build.add_argument("--focal-px", type=float)
+    p_source_build.add_argument("--frame-id")
+    p_source_build.add_argument("--parent-frame", default="base_link")
+    p_source_build.add_argument("--split-gap-s", type=float)
+    p_source_build.add_argument("--max-images", type=int, default=2000)
+    p_source_build.add_argument("--bundle-prefix")
+    p_source_build.set_defaults(func=cmd_image_source_from_images)
+
     p_val = sub.add_parser("validate", help="Validate clip directory")
     p_val.add_argument("path", help="Clip directory or parent directory")
     p_val.set_defaults(func=cmd_validate)

{x4d_devkit-0.53.0rc2 → x4d_devkit-0.54.0rc1}/x4d_devkit/image_clip.py

@@ -588,6 +588,31 @@ class ImageClip(ImageDocument):
     def images(self) -> tuple[dict, ...]:
         return tuple(self.to_dict()["sample_data"])
 
+    @property
+    def source_provenance(self) -> dict | None:
+        """External-source fragment; ``None`` means platform Bag admission."""
+
+        return self.to_dict()["meta"].get("source_provenance")
+
+    @property
+    def source_kind(self) -> str:
+        provenance = self.source_provenance
+        return "bag_admission" if provenance is None else provenance["kind"]
+
+    def calibration_is_measured(self, calibration_id: str) -> bool:
+        """False only for an explicitly synthetic calibration."""
+
+        ids = {row["id"] for row in self.to_dict()["calibrated_sensor"]}
+        if calibration_id not in ids:
+            raise KeyError(calibration_id)
+        provenance = self.source_provenance
+        if provenance is None:
+            return True
+        return next(
+            row["source"] for row in provenance["calibrations"]
+            if row["calibration_id"] == calibration_id
+        ) != "synthetic"
+
 
 def parse_image_clip(value: Any, *, expected_clip_id: str | None = None) -> ImageClip:
     canonical(value)
@@ -609,6 +634,7 @@ def parse_image_clip(value: Any, *, expected_clip_id: str | None = None) -> Imag
             "processing_fingerprint",
         },
         "meta",
+        optional={"source_provenance"},
     )
     require(
         meta["contract_version"] == IMAGE_CLIP_CONTRACT_VERSION
@@ -679,6 +705,14 @@ def parse_image_clip(value: Any, *, expected_clip_id: str | None = None) -> Imag
         "calibration channel scope mismatch",
         "calibrated_sensor",
     )
+    if "source_provenance" in meta:
+        from x4d_devkit.image_source import validate_image_source_provenance
+
+        validate_image_source_provenance(
+            meta["source_provenance"],
+            calibration_ids=set(calibrations),
+            source_bindings=meta["source_bindings"],
+        )
     samples = unique_ids(value["sample"], "sample")
     images = unique_ids(value["sample_data"], "sample_data")
     previous = None

{x4d_devkit-0.53.0rc2 → x4d_devkit-0.54.0rc1}/x4d_devkit/image_schema_migration.py

@@ -181,7 +181,7 @@ def migrate_image_annotation(annotation, *, target_schema, mapping):
     changes, removed, conflicts = [], [], []
     carried = 0
 
-    def convert(object_id, category, scope, values, range_id, base_path):
+    def convert(object_id, category, scope, values, range_id, base_path, polyline):
         nonlocal carried
         output, added = {}, []
         for attribute_id in sorted(values):
@@ -230,6 +230,11 @@ def migrate_image_annotation(annotation, *, target_schema, mapping):
                 )
                 continue
             change["after"] = {"attribute_id": action["attribute_id"], "value": action["value"]}
+            if action["kind"] == "range" and not polyline:
+                conflicts.append(
+                    _conflict("mapped_value_invalid", f"rule {index}: only a polyline can carry ranges", path, **context)
+                )
+                continue
             if action["kind"] == "range":
                 change["range_id"] = _range_id(object_id, index)
                 added.append((change["range_id"], action))
@@ -256,8 +261,9 @@ def migrate_image_annotation(annotation, *, target_schema, mapping):
                 _conflict("object_unrepresentable", "target category geometry differs", path, object_id=object_id)
             )
             continue
+        polyline = category["geometry_type"] == "polyline_2d"
         row["attributes"], added = convert(
-            object_id, category, "object", row["attributes"], None, path + ".attributes"
+            object_id, category, "object", row["attributes"], None, path + ".attributes", polyline
         )
         ranges = []
         for range_index, interval in enumerate(row["attribute_ranges"]):
@@ -268,14 +274,15 @@ def migrate_image_annotation(annotation, *, target_schema, mapping):
                 interval["attributes"],
                 interval["range_id"],
                 f"{path}.attribute_ranges[{range_index}].attributes",
+                polyline,
             )
             assert not nested  # range actions are object-scope only
             if values:
                 ranges.append({**interval, "attributes": values})
             else:
                 removed.append({"object_id": object_id, "range_id": interval["range_id"]})
-        vertices = row["geometry"]["vertices"]
         for range_id, action in added:
+            vertices = row["geometry"]["vertices"]
             ranges.append(
                 {
                     "range_id": range_id,