x4d-devkit 0.12.0__tar.gz → 0.14.3__tar.gz

{x4d_devkit-0.12.0 → x4d_devkit-0.14.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.12.0
+Version: 0.14.3
 Summary: X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets
 Author: windzu
 License-Expression: Apache-2.0
@@ -50,6 +50,34 @@ pip install x4d-devkit[client]
 
 ## Quick Start
 
+### Connect to an X-4D platform
+
+The CLI can authenticate with a bearer token passed explicitly, through
+environment variables, or from the user config written by `x4d login`.
+
+```bash
+x4d --base-url http://host:8000 --api-key <token> projects list
+x4d --base-url http://host:8000 --api-key <token> clips list --project-id 1
+x4d --base-url http://host:8000 --api-key <token> clips download --clip-ids clip_a,clip_b --output /data/x4d/clips
+```
+
+```bash
+export X4D_BASE_URL=http://host:8000
+export X4D_API_KEY=<token>
+x4d projects list
+x4d clips list --project-name nuscenes-mini --has-archive true --format json
+x4d clips download --project-name nuscenes-mini --output /data/x4d/nuscenes-mini/clips --workers 8
+```
+
+```bash
+x4d --base-url http://host:8000 login --username <user> --password <password>
+```
+
+`login` stores `base_url` and the returned access token in
+`~/.config/x4d/config.toml`. Archive downloads go through the platform file
+proxy and extract standard X4D clip directories; training containers do not
+need database or MinIO access.
+
 ### Load a clip
 
 ```python

{x4d_devkit-0.12.0 → x4d_devkit-0.14.3}/README.md

@@ -20,6 +20,34 @@ pip install x4d-devkit[client]
 
 ## Quick Start
 
+### Connect to an X-4D platform
+
+The CLI can authenticate with a bearer token passed explicitly, through
+environment variables, or from the user config written by `x4d login`.
+
+```bash
+x4d --base-url http://host:8000 --api-key <token> projects list
+x4d --base-url http://host:8000 --api-key <token> clips list --project-id 1
+x4d --base-url http://host:8000 --api-key <token> clips download --clip-ids clip_a,clip_b --output /data/x4d/clips
+```
+
+```bash
+export X4D_BASE_URL=http://host:8000
+export X4D_API_KEY=<token>
+x4d projects list
+x4d clips list --project-name nuscenes-mini --has-archive true --format json
+x4d clips download --project-name nuscenes-mini --output /data/x4d/nuscenes-mini/clips --workers 8
+```
+
+```bash
+x4d --base-url http://host:8000 login --username <user> --password <password>
+```
+
+`login` stores `base_url` and the returned access token in
+`~/.config/x4d/config.toml`. Archive downloads go through the platform file
+proxy and extract standard X4D clip directories; training containers do not
+need database or MinIO access.
+
 ### Load a clip
 
 ```python

{x4d_devkit-0.12.0 → x4d_devkit-0.14.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.12.0"
+version = "0.14.3"
 description = "X-4D dataset format SDK — load, validate, evaluate, and convert autonomous driving datasets"
 readme = "README.md"
 license = "Apache-2.0"

x4d_devkit-0.14.3/tests/test_cli_auth.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import argparse
+
+from x4d_devkit import cli
+
+
+def test_config_round_trip(tmp_path):
+    path = tmp_path / "config.toml"
+    cli.save_config(
+        {"base_url": "http://host:8000", "api_key": 'tok"en\\value'},
+        path=path,
+    )
+
+    assert cli.load_config(path) == {
+        "base_url": "http://host:8000",
+        "api_key": 'tok"en\\value',
+    }
+
+
+def test_resolve_prefers_explicit_over_env_and_config(tmp_path, monkeypatch):
+    path = tmp_path / "config.toml"
+    cli.save_config({"base_url": "http://config", "api_key": "config-token"}, path)
+    monkeypatch.setenv(cli.CONFIG_ENV, str(path))
+    monkeypatch.setenv(cli.BASE_URL_ENV, "http://env")
+    monkeypatch.setenv(cli.API_KEY_ENV, "env-token")
+
+    args = argparse.Namespace(base_url="http://explicit", api_key="explicit-token", token=None)
+
+    assert cli.resolve_base_url(args) == "http://explicit"
+    assert cli.resolve_api_key(args) == "explicit-token"
+
+
+def test_resolve_prefers_env_over_config(tmp_path, monkeypatch):
+    path = tmp_path / "config.toml"
+    cli.save_config({"base_url": "http://config", "api_key": "config-token"}, path)
+    monkeypatch.setenv(cli.CONFIG_ENV, str(path))
+    monkeypatch.setenv(cli.BASE_URL_ENV, "http://env")
+    monkeypatch.setenv(cli.API_KEY_ENV, "env-token")
+
+    args = argparse.Namespace(base_url=None, api_key=None, token=None)
+
+    assert cli.resolve_base_url(args) == "http://env"
+    assert cli.resolve_api_key(args) == "env-token"
+
+
+def test_resolve_reads_config_when_env_absent(tmp_path, monkeypatch):
+    path = tmp_path / "config.toml"
+    cli.save_config({"base_url": "http://config", "api_key": "config-token"}, path)
+    monkeypatch.setenv(cli.CONFIG_ENV, str(path))
+    monkeypatch.delenv(cli.BASE_URL_ENV, raising=False)
+    monkeypatch.delenv(cli.API_KEY_ENV, raising=False)
+
+    args = argparse.Namespace(base_url=None, api_key=None, token=None)
+
+    assert cli.resolve_base_url(args) == "http://config"
+    assert cli.resolve_api_key(args) == "config-token"
+
+
+def test_parse_bool():
+    assert cli.parse_bool("true") is True
+    assert cli.parse_bool("0") is False

x4d_devkit-0.14.3/tests/test_client_projects.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import pytest
+
+from x4d_devkit.client.projects import ProjectsAPI
+
+
+class FakeClient:
+    def __init__(self, pages):
+        self.pages = pages
+        self.calls = []
+
+    def get(self, path, params=None):
+        assert path == "/projects"
+        self.calls.append(params)
+        return self.pages[params["page"] - 1]
+
+
+def test_get_project_by_exact_name():
+    api = ProjectsAPI(
+        FakeClient(
+            [
+                {
+                    "items": [{"id": 1, "name": "nuscenes"}, {"id": 2, "name": "nuscenes-mini"}],
+                    "total": 2,
+                    "page": 1,
+                    "page_size": 100,
+                }
+            ]
+        )
+    )
+
+    assert api.get_by_name("nuscenes-mini")["id"] == 2
+
+
+def test_get_project_by_name_requires_match():
+    api = ProjectsAPI(
+        FakeClient([{"items": [], "total": 0, "page": 1, "page_size": 100}])
+    )
+
+    with pytest.raises(ValueError, match="Project not found"):
+        api.get_by_name("missing")

{x4d_devkit-0.12.0 → x4d_devkit-0.14.3}/tests/test_coordinate_frames.py

@@ -42,7 +42,7 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
         "keyframe_count": 2,
         "sweep_count": 0,
         "sensors": {
-            "LIDAR_TOP": {
+            "lidar_top": {
                 "modality": "lidar",
                 "point_format": {
                     "fields": ["x", "y", "z", "intensity"],
@@ -50,7 +50,7 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
                     "bytes_per_point": 16,
                 },
             },
-            "CAM_FRONT": {
+            "cam_front": {
                 "modality": "camera",
             }
         }
@@ -62,7 +62,7 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
     (clip_dir / "calibrated_sensor.json").write_text(json.dumps([
         {
             "calibrated_sensor_token": "cs-lidar",
-            "channel": "LIDAR_TOP",
+            "channel": "lidar_top",
             "translation": {"x": 0.0, "y": 0.0, "z": 1.0},
             "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
             "intrinsics": None,
@@ -70,7 +70,7 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
         },
         {
             "calibrated_sensor_token": "cs-cam",
-            "channel": "CAM_FRONT",
+            "channel": "cam_front",
             "translation": {"x": 0.5, "y": 0.0, "z": 0.8},
             "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
             "intrinsics": {"camera_model": "pinhole",
@@ -117,16 +117,16 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
     ]))
 
     # -- sample_data.json --
-    lidar_dir = clip_dir / "LIDAR_TOP"
+    lidar_dir = clip_dir / "lidar_top"
     lidar_dir.mkdir()
 
     (clip_dir / "sample_data.json").write_text(json.dumps([
         {
             "sample_data_token": "sd-lidar-0",
             "sample_token": "s-0",
-            "channel": "LIDAR_TOP",
+            "channel": "lidar_top",
             "timestamp_us": 1000000,
-            "file_path": "LIDAR_TOP/frame0.bin",
+            "file_path": "lidar_top/frame0.bin",
             "ego_pose_token": "ep-0",
             "calibrated_sensor_token": "cs-lidar",
             "is_keyframe": True,
@@ -138,9 +138,9 @@ def _make_synthetic_clip(tmp_path: Path) -> Path:
         {
             "sample_data_token": "sd-lidar-1",
             "sample_token": "s-1",
-            "channel": "LIDAR_TOP",
+            "channel": "lidar_top",
             "timestamp_us": 1500000,
-            "file_path": "LIDAR_TOP/frame1.bin",
+            "file_path": "lidar_top/frame1.bin",
             "ego_pose_token": "ep-1",
             "calibrated_sensor_token": "cs-lidar",
             "is_keyframe": True,
@@ -242,9 +242,9 @@ class TestFrameIdHelpers:
         assert loader.annotation_frame_id == "base_link"
 
     def test_sensor_frame_id_returns_channel_frame(self, loader):
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         # v0.2 has no per-sensor frame_id, falls back to channel name.
-        assert loader.sensor_frame_id(sd) == "LIDAR_TOP"
+        assert loader.sensor_frame_id(sd) == "lidar_top"
 
     def test_clip_world_constant_is_string_literal(self):
         # The spec pins this name. Any consumer can pass it as a regular frame.
@@ -259,62 +259,62 @@ class TestFrameIdHelpers:
 class TestLoadPointCloudFrames:
     def test_no_frame_returns_raw_sensor(self, loader):
         """Default (no frame=) returns the raw sensor data unchanged."""
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         pts = loader.load_point_cloud(sd)
         assert pts.shape == (4, 4)
         np.testing.assert_allclose(pts[0, :3], [1.0, 0.0, 0.0], atol=1e-6)
 
     def test_frame_equal_to_sensor_frame_is_noop(self, loader):
         """Passing the sensor's own frame_id matches the no-frame default."""
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         pts_default = loader.load_point_cloud(sd)
         pts_explicit = loader.load_point_cloud(sd, frame=loader.sensor_frame_id(sd))
         np.testing.assert_array_equal(pts_default, pts_explicit)
 
     def test_frame_equal_to_ego_applies_calibration(self, loader):
-        """frame=ego_pose_frame_id applies sensor-to-ego (z+1 for LIDAR_TOP)."""
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        """frame=ego_pose_frame_id applies sensor-to-ego (z+1 for lidar_top)."""
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         pts = loader.load_point_cloud(sd, frame=loader.ego_pose_frame_id)
         np.testing.assert_allclose(pts[0, :3], [1.0, 0.0, 1.0], atol=1e-5)
         np.testing.assert_allclose(pts[2, :3], [0.0, 0.0, 2.0], atol=1e-5)
 
     def test_frame_clip_world_first_ego(self, loader):
         """frame='clip_world' for the first ego pose (at origin) ≡ ego frame."""
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]  # ep-0 at origin
+        sd = loader.sample_data_for_channel("lidar_top")[0]  # ep-0 at origin
         pts_ego = loader.load_point_cloud(sd, frame=loader.ego_pose_frame_id)
         pts_world = loader.load_point_cloud(sd, frame=CLIP_WORLD)
         np.testing.assert_allclose(pts_world[:, :3], pts_ego[:, :3], atol=1e-5)
 
     def test_frame_clip_world_second_ego(self, loader):
         """frame='clip_world' for the second ego pose adds the ego offset."""
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[1]  # ep-1 at x=10
+        sd = loader.sample_data_for_channel("lidar_top")[1]  # ep-1 at x=10
         pts = loader.load_point_cloud(sd, frame=CLIP_WORLD)
         np.testing.assert_allclose(pts[0, :3], [11.0, 0.0, 1.0], atol=1e-5)
 
     def test_intensity_preserved(self, loader):
         """Non-xyz columns are passed through unchanged."""
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         pts = loader.load_point_cloud(sd, frame=CLIP_WORLD)
         np.testing.assert_allclose(pts[:, 3], 0.5, atol=1e-6)
 
     def test_magic_string_world_rejected(self, loader):
         """The legacy magic string 'world' must be rejected with a hint."""
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         with pytest.raises(ValueError, match=r"clip_world"):
             loader.load_point_cloud(sd, frame="world")
 
     def test_magic_string_ego_rejected(self, loader):
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         with pytest.raises(ValueError, match=r"ego_pose_frame_id"):
             loader.load_point_cloud(sd, frame="ego")
 
     def test_magic_string_sensor_rejected(self, loader):
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         with pytest.raises(ValueError, match=r"sensor_frame_id"):
             loader.load_point_cloud(sd, frame="sensor")
 
     def test_unknown_frame_id_raises_keyerror(self, loader):
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         with pytest.raises(KeyError, match=r"not_a_real_frame"):
             loader.load_point_cloud(sd, frame="not_a_real_frame")
 
@@ -367,9 +367,9 @@ class TestAnnotationsForSampleFrames:
 
     def test_frame_sensor_id_transforms_to_that_sensor(self, loader):
         """Passing a sensor's frame_id transforms annotations into that sensor's frame."""
-        # LIDAR_TOP is at (0,0,1) in ego frame. Annotation at ego (5,3,0) →
-        # LIDAR_TOP frame: subtract z=1 → (5,3,-1).
-        anns = loader.annotations_for_sample("s-0", frame="LIDAR_TOP")
+        # lidar_top is at (0,0,1) in ego frame. Annotation at ego (5,3,0) →
+        # lidar_top frame: subtract z=1 → (5,3,-1).
+        anns = loader.annotations_for_sample("s-0", frame="lidar_top")
         np.testing.assert_allclose(anns[0].translation, [5.0, 3.0, -1.0], atol=1e-5)
 
     def test_magic_string_sensor_rejected(self, loader):
@@ -399,51 +399,51 @@ class TestAnnotationsForSampleFrames:
 
 class TestGetTransform:
     def test_identity_same_frame(self, loader):
-        T = loader.get_transform("LIDAR_TOP", "LIDAR_TOP")
+        T = loader.get_transform("lidar_top", "lidar_top")
         np.testing.assert_allclose(T.as_matrix, np.eye(4), atol=1e-10)
 
     def test_static_sensor_to_ego(self, loader):
         # Static-only: no sd needed.
-        T = loader.get_transform("LIDAR_TOP", loader.ego_pose_frame_id)
+        T = loader.get_transform("lidar_top", loader.ego_pose_frame_id)
         np.testing.assert_allclose(T.translation, [0.0, 0.0, 1.0], atol=1e-10)
 
     def test_static_sensor_to_sensor(self, loader):
-        # LIDAR_TOP at (0,0,1) and CAM_FRONT at (0.5,0,0.8) in ego frame.
+        # lidar_top at (0,0,1) and cam_front at (0.5,0,0.8) in ego frame.
         # T_CAM_from_LIDAR = T_CAM_from_ego @ T_ego_from_LIDAR
         #   = (-0.5, 0, -0.8) ∘ (0, 0, +1) = (-0.5, 0, +0.2)
-        T = loader.get_transform("LIDAR_TOP", "CAM_FRONT")
+        T = loader.get_transform("lidar_top", "cam_front")
         np.testing.assert_allclose(T.translation, [-0.5, 0.0, 0.2], atol=1e-10)
 
     def test_dynamic_sensor_to_clip_world_requires_sd(self, loader):
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[1]  # ego at x=10
-        T = loader.get_transform("LIDAR_TOP", CLIP_WORLD, sd=sd)
+        sd = loader.sample_data_for_channel("lidar_top")[1]  # ego at x=10
+        T = loader.get_transform("lidar_top", CLIP_WORLD, sd=sd)
         # sensor → ego (z+1) → world (x+10)  →  (10, 0, 1)
         np.testing.assert_allclose(T.translation, [10.0, 0.0, 1.0], atol=1e-10)
 
     def test_clip_world_without_sd_raises(self, loader):
         with pytest.raises(ValueError, match=r"clip_world"):
-            loader.get_transform("LIDAR_TOP", CLIP_WORLD)
+            loader.get_transform("lidar_top", CLIP_WORLD)
 
     def test_round_trip_through_clip_world(self, loader):
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[1]
-        T_fwd = loader.get_transform("LIDAR_TOP", CLIP_WORLD, sd=sd)
-        T_rev = loader.get_transform(CLIP_WORLD, "LIDAR_TOP", sd=sd)
+        sd = loader.sample_data_for_channel("lidar_top")[1]
+        T_fwd = loader.get_transform("lidar_top", CLIP_WORLD, sd=sd)
+        T_rev = loader.get_transform(CLIP_WORLD, "lidar_top", sd=sd)
         np.testing.assert_allclose((T_fwd @ T_rev).as_matrix, np.eye(4), atol=1e-10)
 
     def test_magic_string_rejected(self, loader):
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[0]
+        sd = loader.sample_data_for_channel("lidar_top")[0]
         with pytest.raises(ValueError, match=r"clip_world"):
             loader.get_transform("sensor", "world", sd=sd)
 
     def test_unknown_frame_id_raises_keyerror(self, loader):
         with pytest.raises(KeyError, match=r"not_a_real_frame"):
-            loader.get_transform("LIDAR_TOP", "not_a_real_frame")
+            loader.get_transform("lidar_top", "not_a_real_frame")
 
     def test_consistency_with_load_point_cloud(self, loader):
-        sd = loader.sample_data_for_channel("LIDAR_TOP")[1]
+        sd = loader.sample_data_for_channel("lidar_top")[1]
         pts_sensor = loader.load_point_cloud(sd)
         pts_world = loader.load_point_cloud(sd, frame=CLIP_WORLD)
-        T = loader.get_transform("LIDAR_TOP", CLIP_WORLD, sd=sd)
+        T = loader.get_transform("lidar_top", CLIP_WORLD, sd=sd)
         pts_manual = T.apply(pts_sensor[:, :3].astype(np.float64)).astype(np.float32)
         np.testing.assert_allclose(pts_world[:, :3], pts_manual, atol=1e-5)
 
@@ -476,11 +476,11 @@ class TestCoordinateFramesIntegration:
     def test_point_cloud_round_trip(self, nuscenes_loader):
         """sensor → clip_world → sensor recovers original points."""
         sd = next(
-            s for s in nuscenes_loader.sample_data_for_channel("LIDAR_TOP") if s.is_keyframe
+            s for s in nuscenes_loader.sample_data_for_channel("lidar_top") if s.is_keyframe
         )
         pts_sensor = nuscenes_loader.load_point_cloud(sd)
         pts_world = nuscenes_loader.load_point_cloud(sd, frame=CLIP_WORLD)
-        T_back = nuscenes_loader.get_transform(CLIP_WORLD, "LIDAR_TOP", sd=sd)
+        T_back = nuscenes_loader.get_transform(CLIP_WORLD, "lidar_top", sd=sd)
         recovered = T_back.apply(pts_world[:, :3].astype(np.float64)).astype(np.float32)
         np.testing.assert_allclose(recovered, pts_sensor[:, :3], atol=1e-4)