x4d-devkit 0.49.0__tar.gz → 0.51.0__tar.gz

{x4d_devkit-0.49.0 → x4d_devkit-0.51.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.49.0
+Version: 0.51.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.49.0 → x4d_devkit-0.51.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.49.0"
+version = "0.51.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.51.0/tests/test_annotation_document_hash.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import random
+
+import pytest
+import rfc8785
+
+from tests.test_annotation_contract import _annotation
+from x4d_devkit.annotation_contract import (
+    ANNOTATION_CONTRACT_VERSION,
+    AnnotationContractError,
+    ClipAnnotationDocument,
+    build_clip_annotations,
+    parse_clip_annotations,
+)
+
+_EDGE_FLOATS = (0.0, -0.0, 1e21, 1e-7, 5e-324, 1.7976931348623157e308, 0.1 + 0.2, -123.456)
+_EDGE_TEXT = ("", "é", "雪", "\U0001f697", "a\"b\\c", "
", "\x7f")
+
+
+def _sha(payload) -> str:
+    return f"sha256:{hashlib.sha256(rfc8785.dumps(payload)).hexdigest()}"
+
+
+def _random_rows(rng: random.Random, count: int) -> list[dict]:
+    rows = []
+    for index in range(count):
+        row = _annotation(
+            f"ann-{rng.randrange(10**9):09d}-{index}",
+            f"sample-{rng.randrange(5)}",
+            instance=f"instance-{rng.randrange(4)}",
+        )
+        row["bbox_3d"]["translation"]["x"] = rng.choice(_EDGE_FLOATS)
+        row["bbox_3d"]["size"]["width"] = rng.random() * 10
+        row["attributes"] = {rng.choice(_EDGE_TEXT) or "k": rng.choice(_EDGE_TEXT)}
+        if rng.random() < 0.5:
+            row["velocity"] = {"vx": rng.choice(_EDGE_FLOATS), "vy": 0.0, "vz": -1.5}
+        rows.append(row)
+    for instance in {row["instance_token"] for row in rows}:
+        motion = rng.choice(("auto", "static", "dynamic"))
+        for row in rows:
+            if row["instance_token"] == instance:
+                row["motion"] = motion
+    return rows
+
+
+def test_single_pass_digests_match_full_rfc8785_canonicalization():
+    rng = random.Random(8785)
+    for count in (0, 1, 2, 17, 120):
+        document = build_clip_annotations("clip-a", "base_link", _random_rows(rng, count))
+        payload = document.to_dict()
+        revision_payload = {key: value for key, value in payload.items() if key != "annotation_revision"}
+        assert document.annotation_revision == _sha(revision_payload)
+        assert document.document_hash() == _sha(payload)
+
+        parsed = parse_clip_annotations(payload)
+        assert parsed.annotation_revision == document.annotation_revision
+        assert parsed.document_hash() == _sha(payload)
+
+
+def test_document_hash_is_derived_for_directly_constructed_and_replaced_documents():
+    document = build_clip_annotations("clip-a", "base_link", _random_rows(random.Random(1), 9))
+    direct = ClipAnnotationDocument(
+        clip_id=document.clip_id,
+        annotation_frame_id=document.annotation_frame_id,
+        annotation_revision=document.annotation_revision,
+        annotations=document.annotations,
+    )
+    assert direct.document_hash() == document.document_hash()
+
+    replaced = dataclasses.replace(document, annotations=document.annotations[:3])
+    assert replaced.document_hash() == _sha(replaced.to_dict())
+    assert replaced.document_hash() != document.document_hash()
+
+
+def test_document_hash_is_not_part_of_document_equality():
+    rows = _random_rows(random.Random(2), 5)
+    built = build_clip_annotations("clip-a", "base_link", rows)
+    parsed = parse_clip_annotations(built.to_dict())
+    plain = ClipAnnotationDocument(
+        clip_id=built.clip_id,
+        annotation_frame_id=built.annotation_frame_id,
+        annotation_revision=built.annotation_revision,
+        annotations=built.annotations,
+    )
+    assert built == parsed == plain
+    assert "_document_hash" not in {field.name for field in dataclasses.fields(built)}
+    assert built.to_dict()["contract_version"] == ANNOTATION_CONTRACT_VERSION
+
+
+def test_parse_reuses_only_documents_this_module_verified():
+    built = build_clip_annotations("clip-a", "base_link", _random_rows(random.Random(3), 4))
+    assert parse_clip_annotations(built) is built
+    assert parse_clip_annotations(parse_clip_annotations(built.to_dict())) is not built
+
+    forged = ClipAnnotationDocument(
+        clip_id=built.clip_id,
+        annotation_frame_id=built.annotation_frame_id,
+        annotation_revision="sha256:" + "0" * 64,
+        annotations=built.annotations,
+    )
+    forged.document_hash()  # caching the hash must not mark the document verified
+    with pytest.raises(AnnotationContractError) as error:
+        parse_clip_annotations(forged)
+    assert error.value.code == "annotation_revision_mismatch"
+
+    replaced = dataclasses.replace(built, annotation_revision="sha256:" + "1" * 64)
+    with pytest.raises(AnnotationContractError):
+        parse_clip_annotations(replaced)

x4d_devkit-0.51.0/tests/test_image_groups.py

@@ -0,0 +1,249 @@
+from copy import deepcopy
+
+import pytest
+
+from tests.image_fixtures import clip_payload, line_object
+from x4d_devkit._image_contract import canonical
+from x4d_devkit.image_clip import build_image_identity, parse_image_clip
+from x4d_devkit.image_groups import (
+    IMAGE_OBJECT_GROUPS_VERSION,
+    parse_image_object_groups,
+)
+from x4d_devkit.image_schema import parse_image_schema_body
+from x4d_devkit.image_schema_upgrade import additive_image_schema_changes
+from x4d_devkit.image_work_session import (
+    IMAGE_WORK_SESSION_VERSION,
+    build_image_submit,
+    image_candidate,
+    parse_image_submit,
+    parse_image_work_session,
+)
+
+
+def grouped_payload():
+    value = clip_payload()
+    body = value["label_schema"]["body"]
+    body["categories"][0]["groupable"] = True
+    value["label_schema"]["identity"] = parse_image_schema_body(body).identity.to_dict()
+    first = line_object()
+    second = deepcopy(first)
+    second["id"] = "line_b"
+    second["attributes"] = {"visible": True}
+    second["attribute_ranges"][0]["attributes"] = {"style": "b"}
+    value["image_annotation"]["objects"] = [first, second]
+    value["image_annotation"]["object_groups"] = {
+        "contract_version": IMAGE_OBJECT_GROUPS_VERSION,
+        "groups": [
+            {
+                "id": "group_1",
+                "image_id": "image_a",
+                "view_id": "objects",
+                "object_ids": ["line_a", "line_b"],
+            }
+        ],
+    }
+    value["identity"] = build_image_identity(value)
+    return value
+
+
+def test_relations_preserve_independent_objects_and_all_source_components():
+    value = grouped_payload()
+    original = deepcopy(value)
+    clip = parse_image_clip(value)
+    assert clip.to_dict() == original
+    session = parse_image_work_session(
+        {"contract_version": IMAGE_WORK_SESSION_VERSION, "clip": value}
+    )
+    request = build_image_submit(session, value["image_annotation"]).to_dict()
+    assert (
+        parse_image_submit(request).to_dict()["image_annotation"]
+        == original["image_annotation"]
+    )
+    candidate = image_candidate(session.clip, request["image_annotation"]).to_dict()
+    assert candidate == original
+    value["image_annotation"]["object_groups"]["groups"][0]["object_ids"].clear()
+    assert clip.to_dict() == original
+
+
+def test_relation_changes_enter_revision_without_changing_geometry_or_source():
+    value = grouped_payload()
+    before = parse_image_clip(value)
+    annotation = deepcopy(value["image_annotation"])
+    annotation["object_groups"]["groups"][0]["id"] = "changed_group_identity"
+    after = image_candidate(before, annotation).to_dict()
+    for name in ("source_revision", "schema_fingerprint"):
+        assert after["identity"][name] == value["identity"][name]
+    for name in ("annotation_revision", "clip_revision"):
+        assert after["identity"][name] != value["identity"][name]
+    assert after["image_annotation"]["objects"] == value["image_annotation"]["objects"]
+    assert (
+        after["image_annotation"]["completion"]
+        == value["image_annotation"]["completion"]
+    )
+    annotation["object_groups"]["groups"] = []
+    ungrouped = image_candidate(before, annotation).to_dict()
+    assert (
+        ungrouped["image_annotation"]["objects"] == value["image_annotation"]["objects"]
+    )
+    assert ungrouped["image_annotation"]["object_groups"]["groups"] == []
+
+
+def test_existing_documents_remain_byte_identical_and_do_not_infer_groups():
+    old = clip_payload()
+    assert canonical(parse_image_clip(old).to_dict()) == canonical(old)
+    assert (
+        "groupable"
+        not in parse_image_schema_body(old["label_schema"]["body"]).to_dict()[
+            "categories"
+        ][0]
+    )
+    value = grouped_payload()
+    del value["image_annotation"]["object_groups"]
+    value["identity"] = build_image_identity(value)
+    parsed = parse_image_clip(value).to_dict()
+    assert "object_groups" not in parsed["image_annotation"]
+    assert (
+        parsed["image_annotation"]["objects"][0]["geometry"]
+        == parsed["image_annotation"]["objects"][1]["geometry"]
+    )
+    assert canonical(parsed) == canonical(value)
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "unknown_member",
+        "one_member",
+        "empty_members",
+        "duplicate_member",
+        "duplicate_group",
+        "duplicate_membership",
+        "cross_image",
+        "cross_view",
+        "disallowed_category",
+        "missing_permission",
+        "false_permission",
+        "colliding_id",
+        "unknown_version",
+        "null_fragment",
+        "extra_fragment",
+        "extra_group",
+        "object_provenance",
+        "geometry_mismatch",
+        "removed_member",
+        "non_array_members",
+    ],
+)
+def test_invalid_relations_fail_with_paths_without_repair(change):
+    value = grouped_payload()
+    annotation = value["image_annotation"]
+    fragment = annotation["object_groups"]
+    group = fragment["groups"][0]
+    if change == "unknown_member":
+        group["object_ids"][1] = "missing"
+    elif change == "one_member":
+        group["object_ids"].pop()
+    elif change == "empty_members":
+        group["object_ids"] = []
+    elif change == "duplicate_member":
+        group["object_ids"][1] = "line_a"
+    elif change == "duplicate_group":
+        fragment["groups"].append(deepcopy(group))
+    elif change == "duplicate_membership":
+        fragment["groups"].append({**group, "id": "group_2"})
+    elif change == "cross_image":
+        group["image_id"] = "another_image"
+    elif change == "cross_view":
+        group["view_id"] = "semantics"
+    elif change == "disallowed_category":
+        annotation["objects"][1].update(
+            category_id="box",
+            attributes={},
+            attribute_ranges=[],
+            geometry={
+                "geometry_type": "box_2d",
+                "box": {"x_min": 1, "y_min": 2, "x_max": 10, "y_max": 20},
+            },
+        )
+    elif change == "missing_permission":
+        del value["label_schema"]["body"]["categories"][0]["groupable"]
+    elif change == "false_permission":
+        value["label_schema"]["body"]["categories"][0]["groupable"] = False
+    elif change == "colliding_id":
+        group["id"] = "line_a"
+    elif change == "unknown_version":
+        fragment["contract_version"] = "unknown"
+    elif change == "null_fragment":
+        annotation["object_groups"] = None
+    elif change == "extra_fragment":
+        fragment["origin"] = "split"
+    elif change == "extra_group":
+        group["origin"] = "split"
+    elif change == "object_provenance":
+        annotation["objects"][0]["split_from"] = "original"
+    elif change == "geometry_mismatch":
+        annotation["objects"][1]["geometry"]["geometry_type"] = "box_2d"
+    elif change == "removed_member":
+        annotation["objects"].pop()
+    elif change == "non_array_members":
+        group["object_ids"] = "line_a,line_b"
+    body = value["label_schema"]["body"]
+    value["label_schema"]["identity"] = parse_image_schema_body(body).identity.to_dict()
+    value["identity"] = build_image_identity(value)
+    original = deepcopy(value)
+    with pytest.raises(ValueError) as caught:
+        parse_image_clip(value)
+    assert caught.value.path
+    assert value == original
+
+
+@pytest.mark.parametrize("value", [None, 0, 1, "true", [], {}])
+def test_grouping_permission_is_an_explicit_boolean(value):
+    body = clip_payload()["label_schema"]["body"]
+    body["categories"][0]["groupable"] = value
+    with pytest.raises(ValueError) as caught:
+        parse_image_schema_body(body)
+    assert caught.value.path.endswith("groupable")
+
+
+def test_unknown_business_category_can_use_groups_without_a_catalogue():
+    value = grouped_payload()
+    body = value["label_schema"]["body"]
+    body["categories"][0]["id"] = "new_business_after_sdk_release"
+    body["task_views"][0]["category_ids"][0] = "new_business_after_sdk_release"
+    for row in value["image_annotation"]["objects"]:
+        row["category_id"] = "new_business_after_sdk_release"
+    value["label_schema"]["identity"] = parse_image_schema_body(body).identity.to_dict()
+    value["identity"] = build_image_identity(value)
+    assert parse_image_clip(value).to_dict() == value
+
+
+def test_empty_fragment_is_valid_and_is_not_injected_when_absent():
+    assert (
+        parse_image_object_groups(
+            {"contract_version": IMAGE_OBJECT_GROUPS_VERSION, "groups": []}
+        ).to_dict()["groups"]
+        == []
+    )
+    value = clip_payload()
+    annotation = deepcopy(value["image_annotation"])
+    annotation["object_groups"] = {
+        "contract_version": IMAGE_OBJECT_GROUPS_VERSION,
+        "groups": [],
+    }
+    assert (
+        image_candidate(parse_image_clip(value), annotation).to_dict()[
+            "image_annotation"
+        ]
+        == annotation
+    )
+    assert "object_groups" not in parse_image_clip(value).to_dict()["image_annotation"]
+
+
+def test_grouping_permission_changes_are_not_silently_additive_upgrades():
+    old = clip_payload()["label_schema"]["body"]
+    new = deepcopy(old)
+    new["version"] = "2.0.0"
+    new["categories"][0]["groupable"] = True
+    with pytest.raises(ValueError):
+        additive_image_schema_changes(old, new)