x4d-devkit 0.1.0__py3-none-any.whl

x4d_devkit/__init__.py

@@ -0,0 +1,42 @@
+"""X-4D dataset format SDK."""
+
+from x4d_devkit.core import (
+    Annotation,
+    CalibratedSensor,
+    ClipLoader,
+    ClipMeta,
+    EgoPose,
+    Instance,
+    Sample,
+    SampleData,
+    Transform,
+    TransformChain,
+    generate_token,
+)
+from x4d_devkit.eval import (
+    DetectionConfig,
+    DetectionEval,
+    DetectionResult,
+    nusc_detection_config,
+)
+from x4d_devkit.validation import validate_clip, ValidationReport
+
+__all__ = [
+    "Annotation",
+    "CalibratedSensor",
+    "ClipLoader",
+    "ClipMeta",
+    "DetectionConfig",
+    "DetectionEval",
+    "DetectionResult",
+    "EgoPose",
+    "Instance",
+    "Sample",
+    "SampleData",
+    "Transform",
+    "TransformChain",
+    "ValidationReport",
+    "generate_token",
+    "nusc_detection_config",
+    "validate_clip",
+]

x4d_devkit/cli.py

@@ -0,0 +1,131 @@
+"""X-4D DevKit CLI."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def cmd_projects_list(args):
+    from x4d_devkit.client import X4DClient
+
+    with X4DClient(base_url=args.base_url) as client:
+        resp = client.projects.list()
+        for p in resp["items"]:
+            print(f"  [{p['id']}] {p['name']} — {p.get('clip_count', '?')} clips")
+
+
+def cmd_clips_list(args):
+    from x4d_devkit.client import X4DClient
+
+    with X4DClient(base_url=args.base_url) as client:
+        resp = client.clips.list(
+            project_id=args.project_id,
+            page_size=args.page_size,
+            lifecycle=args.lifecycle,
+            has_archive=args.has_archive,
+        )
+        print(f"Total: {resp['total']} clips (showing page {resp['page']})")
+        for c in resp["items"]:
+            status = c.get("lifecycle", "?")
+            kf = (
+                c.get("statistics", {}).get("keyframe_count", "?")
+                if c.get("statistics")
+                else "?"
+            )
+            print(f"  {c['clip_id']}  [{status}]  {kf} keyframes")
+
+
+def cmd_clips_download(args):
+    from x4d_devkit.client import X4DClient
+
+    with X4DClient(base_url=args.base_url, timeout=600.0) as client:
+        # Read clip IDs from file or comma-separated
+        if Path(args.clip_ids).exists():
+            clip_ids = Path(args.clip_ids).read_text().strip().splitlines()
+        else:
+            clip_ids = args.clip_ids.split(",")
+        clip_ids = [cid.strip() for cid in clip_ids if cid.strip()]
+
+        print(f"Downloading {len(clip_ids)} clips to {args.output}...")
+
+        def on_progress(clip_id, i, total):
+            print(f"  [{i}/{total}] {clip_id} done")
+
+        paths = client.clips.download_tars(
+            clip_ids=clip_ids,
+            output_dir=args.output,
+            workers=args.workers,
+            on_progress=on_progress,
+        )
+        print(f"Downloaded {len(paths)} clips successfully")
+
+
+def cmd_validate(args):
+    from x4d_devkit.validation import validate_clip
+
+    target = Path(args.path)
+
+    if (target / "meta.json").exists():
+        # Single clip directory
+        report = validate_clip(target)
+        print(report)
+        sys.exit(0 if report.ok else 1)
+    else:
+        # Directory of clips
+        all_ok = True
+        for clip_dir in sorted(target.iterdir()):
+            if clip_dir.is_dir() and (clip_dir / "meta.json").exists():
+                report = validate_clip(clip_dir)
+                print(report)
+                if not report.ok:
+                    all_ok = False
+        sys.exit(0 if all_ok else 1)
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="x4d", description="X-4D DevKit CLI")
+    parser.add_argument(
+        "--base-url", default="http://localhost:8000", help="Platform API URL"
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # projects list
+    p_proj = sub.add_parser("projects", help="Project operations")
+    p_proj_sub = p_proj.add_subparsers(dest="subcommand")
+    p_proj_list = p_proj_sub.add_parser("list", help="List projects")
+    p_proj_list.set_defaults(func=cmd_projects_list)
+
+    # clips list
+    p_clips = sub.add_parser("clips", help="Clip operations")
+    p_clips_sub = p_clips.add_subparsers(dest="subcommand")
+
+    p_clips_list = p_clips_sub.add_parser("list", help="List clips")
+    p_clips_list.add_argument("--project-id", type=int, required=True)
+    p_clips_list.add_argument("--page-size", type=int, default=20)
+    p_clips_list.add_argument("--lifecycle", type=str, default=None)
+    p_clips_list.add_argument("--has-archive", type=bool, default=None)
+    p_clips_list.set_defaults(func=cmd_clips_list)
+
+    p_clips_dl = p_clips_sub.add_parser("download", help="Download clip tar archives")
+    p_clips_dl.add_argument(
+        "--clip-ids", required=True, help="Comma-separated IDs or path to file"
+    )
+    p_clips_dl.add_argument("--output", required=True, help="Output directory")
+    p_clips_dl.add_argument("--workers", type=int, default=4)
+    p_clips_dl.set_defaults(func=cmd_clips_download)
+
+    # validate
+    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)
+
+    args = parser.parse_args()
+    if not hasattr(args, "func"):
+        parser.print_help()
+        sys.exit(1)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

x4d_devkit/client/__init__.py

@@ -0,0 +1,3 @@
+from x4d_devkit.client.client import X4DClient
+
+__all__ = ["X4DClient"]

x4d_devkit/client/client.py

@@ -0,0 +1,56 @@
+"""X-4D platform API client."""
+from __future__ import annotations
+
+import httpx
+
+from x4d_devkit.client.projects import ProjectsAPI
+from x4d_devkit.client.clips import ClipsAPI
+
+
+class X4DClient:
+    """Client for the X-4D platform REST API.
+
+    Args:
+        base_url: Platform API base URL (e.g. "http://localhost:8000")
+        api_key: Optional API key for authentication (future use)
+        timeout: Request timeout in seconds
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        api_key: str | None = None,
+        timeout: float = 30.0,
+    ):
+        self._base_url = base_url.rstrip("/")
+        self._api_prefix = "/api/v1"
+        headers = {}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._http = httpx.Client(
+            base_url=self._base_url, headers=headers, timeout=timeout
+        )
+        self.projects = ProjectsAPI(self)
+        self.clips = ClipsAPI(self)
+
+    def _url(self, path: str) -> str:
+        return f"{self._api_prefix}{path}"
+
+    def get(self, path: str, **kwargs) -> dict:
+        resp = self._http.get(self._url(path), **kwargs)
+        resp.raise_for_status()
+        return resp.json()
+
+    def post(self, path: str, **kwargs) -> dict:
+        resp = self._http.post(self._url(path), **kwargs)
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self):
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

x4d_devkit/client/clips.py

@@ -0,0 +1,135 @@
+"""Clips API wrapper."""
+from __future__ import annotations
+
+import tarfile
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from x4d_devkit.client.client import X4DClient
+
+
+class ClipsAPI:
+    def __init__(self, client: X4DClient):
+        self._client = client
+
+    def list(
+        self,
+        project_id: int,
+        page: int = 1,
+        page_size: int = 100,
+        lifecycle: str | None = None,
+        has_archive: bool | None = None,
+    ) -> dict:
+        """List clips in a project with optional filters."""
+        params: dict = {
+            "project_id": project_id,
+            "page": page,
+            "page_size": page_size,
+        }
+        if lifecycle:
+            params["lifecycle"] = lifecycle
+        if has_archive is not None:
+            params["has_archive"] = str(has_archive).lower()
+        return self._client.get("/clips", params=params)
+
+    def list_all(self, project_id: int, **kwargs) -> list[dict]:
+        """List ALL clips in a project (handles pagination automatically)."""
+        all_items = []
+        page = 1
+        while True:
+            resp = self.list(project_id=project_id, page=page, page_size=100, **kwargs)
+            all_items.extend(resp["items"])
+            if len(all_items) >= resp["total"]:
+                break
+            page += 1
+        return all_items
+
+    def get(self, clip_id: str) -> dict:
+        """Get a single clip by ID."""
+        return self._client.get(f"/clips/{clip_id}")
+
+    def get_archive_status(self, clip_id: str) -> dict:
+        """Get archive/tar status for a clip."""
+        return self._client.get(f"/clips/{clip_id}/archive")
+
+    def get_archive_download_url(self, clip_id: str) -> str:
+        """Get presigned download URL for the clip's tar archive."""
+        resp = self._client.get(f"/clips/{clip_id}/archive/download")
+        return resp["url"]
+
+    def download_tar(
+        self, clip_id: str, output_dir: str | Path, extract: bool = True
+    ) -> Path:
+        """Download and optionally extract a clip's tar archive.
+
+        Args:
+            clip_id: Clip ID to download
+            output_dir: Directory to save/extract to
+            extract: If True, extract tar and remove the tar file
+
+        Returns:
+            Path to extracted clip directory (if extract=True) or tar file
+        """
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        url = self.get_archive_download_url(clip_id)
+        tar_path = output_dir / f"{clip_id}.tar"
+
+        # Stream download
+        with self._client._http.stream("GET", url) as resp:
+            resp.raise_for_status()
+            with open(tar_path, "wb") as f:
+                for chunk in resp.iter_bytes(chunk_size=8 * 1024 * 1024):
+                    f.write(chunk)
+
+        if extract:
+            clip_dir = output_dir / clip_id
+            clip_dir.mkdir(parents=True, exist_ok=True)
+            with tarfile.open(tar_path, "r") as tar:
+                tar.extractall(path=clip_dir)
+            tar_path.unlink()
+            return clip_dir
+
+        return tar_path
+
+    def download_tars(
+        self,
+        clip_ids: list[str],
+        output_dir: str | Path,
+        workers: int = 4,
+        extract: bool = True,
+        on_progress: callable | None = None,
+    ) -> list[Path]:
+        """Batch download multiple clip tar archives in parallel.
+
+        Args:
+            clip_ids: List of clip IDs to download
+            output_dir: Directory to save/extract to
+            workers: Number of parallel download threads
+            extract: If True, extract tars and remove tar files
+            on_progress: Optional callback(clip_id, index, total) called after each download
+
+        Returns:
+            List of paths to extracted clip directories or tar files
+        """
+        results = []
+
+        def _download_one(clip_id: str) -> Path:
+            return self.download_tar(clip_id, output_dir, extract=extract)
+
+        with ThreadPoolExecutor(max_workers=workers) as pool:
+            futures = {pool.submit(_download_one, cid): cid for cid in clip_ids}
+            for i, future in enumerate(as_completed(futures)):
+                clip_id = futures[future]
+                try:
+                    path = future.result()
+                    results.append(path)
+                    if on_progress:
+                        on_progress(clip_id, i + 1, len(clip_ids))
+                except Exception as e:
+                    print(f"Failed to download {clip_id}: {e}")
+
+        return results

x4d_devkit/client/projects.py

@@ -0,0 +1,25 @@
+"""Projects API wrapper."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from x4d_devkit.client.client import X4DClient
+
+
+class ProjectsAPI:
+    def __init__(self, client: X4DClient):
+        self._client = client
+
+    def list(
+        self, page: int = 1, page_size: int = 50, search: str | None = None
+    ) -> dict:
+        """List all projects."""
+        params = {"page": page, "page_size": page_size}
+        if search:
+            params["search"] = search
+        return self._client.get("/projects", params=params)
+
+    def get(self, project_id: int) -> dict:
+        """Get a project by ID."""
+        return self._client.get(f"/projects/{project_id}")

x4d_devkit/converters/__init__.py

@@ -0,0 +1 @@
+"""Dataset format converters."""