oopsie-data-tools 0.2.0__tar.gz → 0.2.1__tar.gz

oopsie_data_tools-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,67 @@
+name: Publish to PyPI
+
+# Release flow: bump `version` in pyproject.toml, merge to main, then
+#   git tag v0.2.1 && git push origin v0.2.1
+# The tag must sit on a commit that is on main, and its version must match
+# pyproject.toml — both are enforced below before anything is uploaded.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The ancestry check below needs main, which a tag checkout does not fetch.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Tag must be on main
+        run: |
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::${GITHUB_REF_NAME} points at a commit that is not on main."
+            exit 1
+          fi
+
+      # A tag whose version disagrees with pyproject.toml publishes a release under a
+      # name nobody expects, and PyPI uploads cannot be replaced. Fail before building.
+      - name: Tag must match the project version
+        run: |
+          project_version="$(uv version --short)"
+          tag_version="${GITHUB_REF_NAME#v}"
+          if [ "$project_version" != "$tag_version" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} != pyproject.toml version ${project_version}."
+            exit 1
+          fi
+
+      - run: uv build
+      - name: Check metadata renders on PyPI
+        run: uvx twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing: PyPI verifies this workflow's OIDC token instead of an API
+    # token, so there is no long-lived credential in the repo. The environment name
+    # must match the one configured on the PyPI publisher.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/oopsie-data-tools
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

oopsie_data_tools-0.2.1/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: oopsie-data-tools
+Version: 0.2.1
+Summary: Collect, annotate, validate and upload robotic manipulation rollout data.
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: flask>=3.0.0
+Requires-Dist: h5py>=3.7.0
+Requires-Dist: huggingface-hub>=0.36.2
+Requires-Dist: imageio-ffmpeg>=0.5.1
+Requires-Dist: imageio>=2.35.1
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: opencv-python>=4.11.0.86
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: scipy>=1.10.1
+Provides-Extra: droid
+Requires-Dist: pandas>=2.0.0; extra == 'droid'
+Requires-Dist: pillow>=10.0.0; extra == 'droid'
+Requires-Dist: tqdm>=4.66.0; extra == 'droid'
+Requires-Dist: tyro>=0.9.0; extra == 'droid'
+Description-Content-Type: text/markdown
+
+# Oopsie Tools
+
+Tools for collecting, annotating, inspecting, and converting robotic manipulation rollout data.
+
+This repository currently provides around:
+
+- HDF5 episode recording (`EpisodeRecorder`)
+- Web annotation workflows
+- In-the-loop annotation during policy rollout
+
+---
+
+For detailed explanations on how to use our tooling and contribute to the project, please visit [our website](https://oopsie-data.com/).
+
+For an overview of the steps necessary to integrate the tooling into your workflow and to contribute data to the official Oopsie Data repositories, check out [our quickstart guide](https://oopsie-data.com/quickstart).
+You can also use the information in AI_CONTEXT.md to guide a coding agent through the setup.
+
+## Repository structure
+
+The main tooling for data gathering and annotation is located in `oopsie-data-tools`.
+
+We provide example scripts for automatically collecting and annotating evaluation data while running policy inference in examples. Currently we support the evaluation scripts supported by `openpi` and Trossen robotics `act_plus_plus` repository. If you want to run a different evaluation script, check out the detailed instructions on integrating our tools into standard robot evaluation pipelines.
+
+## Issue/PR for support requests
+
+We are very aware that changing eval code and recording data while doing experiments can be a big hassle and cause friction. We are therefore happy to help you integrate the recording tool into your setup. Please let us know what robot platform and policy you are evaluating and where to find a sample of your evaluation & inference code.
+
+## Contributing
+
+You can use our toolset any time you like to record and annotate robot rollouts. To contribute your data to the official Oopsie Dataset, please follow the [sign-up instructions](https://oopsie-data.com/contributing/)!
+
+If you run into any issues, please do not hesitate to contact the team via mail or raise an issue here.

oopsie_data_tools-0.2.1/README.md

@@ -0,0 +1,32 @@
+# Oopsie Tools
+
+Tools for collecting, annotating, inspecting, and converting robotic manipulation rollout data.
+
+This repository currently provides around:
+
+- HDF5 episode recording (`EpisodeRecorder`)
+- Web annotation workflows
+- In-the-loop annotation during policy rollout
+
+---
+
+For detailed explanations on how to use our tooling and contribute to the project, please visit [our website](https://oopsie-data.com/).
+
+For an overview of the steps necessary to integrate the tooling into your workflow and to contribute data to the official Oopsie Data repositories, check out [our quickstart guide](https://oopsie-data.com/quickstart).
+You can also use the information in AI_CONTEXT.md to guide a coding agent through the setup.
+
+## Repository structure
+
+The main tooling for data gathering and annotation is located in `oopsie-data-tools`.
+
+We provide example scripts for automatically collecting and annotating evaluation data while running policy inference in examples. Currently we support the evaluation scripts supported by `openpi` and Trossen robotics `act_plus_plus` repository. If you want to run a different evaluation script, check out the detailed instructions on integrating our tools into standard robot evaluation pipelines.
+
+## Issue/PR for support requests
+
+We are very aware that changing eval code and recording data while doing experiments can be a big hassle and cause friction. We are therefore happy to help you integrate the recording tool into your setup. Please let us know what robot platform and policy you are evaluating and where to find a sample of your evaluation & inference code.
+
+## Contributing
+
+You can use our toolset any time you like to record and annotate robot rollouts. To contribute your data to the official Oopsie Dataset, please follow the [sign-up instructions](https://oopsie-data.com/contributing/)!
+
+If you run into any issues, please do not hesitate to contact the team via mail or raise an issue here.

oopsie_data_tools-0.2.1/examples/conversion_script_examples/_common.py

@@ -0,0 +1,172 @@
+"""Scaffolding shared by the converter examples in this directory.
+
+Everything schema-shaped — root attrs, robot states, actions, video paths, annotations —
+lives in :mod:`oopsie_data_tools.utils.conversion_utils` and is used from there. What is
+left over is the part that is the same in every converter but is not about the format:
+the CLI shape, the output directory layout, and a batch loop that keeps going when one
+episode fails.
+
+A converter in this directory is then three things:
+
+1. ``build_profile(...)`` — the :class:`RobotProfile` describing the source robot;
+2. ``convert_one(item, episode_id, out)`` — read one source episode, write one HDF5;
+3. a ``main`` that discovers items and hands them to :func:`run_batch`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Iterable, Sequence, TypeVar
+
+from tqdm import tqdm
+
+T = TypeVar("T")
+
+
+class Skip(Exception):
+    """Raised by a converter to drop one source episode without counting it as a failure.
+
+    Use it for episodes that are legitimately out of scope — too short for the validator's
+    duration bounds, missing a camera — and let real errors propagate as themselves.
+    """
+
+
+@dataclass(frozen=True)
+class ConversionOutput:
+    """The ``{output_dir}/{episode_id}.h5`` + ``{output_dir}/videos/`` layout.
+
+    Videos are *copied* rather than symlinked: a symlink survives local validation and then
+    uploads as a dangling path.
+    """
+
+    output_dir: Path
+    videos_dir: Path
+
+    @classmethod
+    def create(cls, output_dir: Path | str) -> "ConversionOutput":
+        output_dir = Path(output_dir).resolve()
+        videos_dir = output_dir / "videos"
+        videos_dir.mkdir(parents=True, exist_ok=True)
+        return cls(output_dir=output_dir, videos_dir=videos_dir)
+
+    def episode_h5(self, episode_id: str) -> Path:
+        return self.output_dir / f"{episode_id}.h5"
+
+    def video_path(self, episode_id: str, camera: str) -> Path:
+        """Absolute destination for one camera's MP4.
+
+        Pass it straight to ``write_video_paths``, which relativizes against the .h5 file.
+        """
+        return self.videos_dir / f"{episode_id}_{camera}.mp4"
+
+    def copy_video(self, source: Path, episode_id: str, camera: str) -> Path:
+        if not Path(source).is_file():
+            raise Skip(f"missing source video for camera {camera!r}")
+        destination = self.video_path(episode_id, camera)
+        shutil.copy2(source, destination)
+        return destination
+
+
+def add_common_args(parser: argparse.ArgumentParser, *, source_help: str) -> None:
+    """Add the arguments every converter in this directory takes."""
+    parser.add_argument("--source", "-s", type=Path, required=True, help=source_help)
+    parser.add_argument(
+        "--output-dir",
+        "-o",
+        type=Path,
+        required=True,
+        help="Output directory for the HDF5 files and their videos/ subdirectory.",
+    )
+    parser.add_argument(
+        "--lab-id",
+        required=True,
+        help="Your registered lab id. Written as a root attr; 'your_lab_id' is rejected.",
+    )
+    parser.add_argument(
+        "--operator-name",
+        required=True,
+        help="Who ran the episodes. Written as a root attr.",
+    )
+    parser.add_argument(
+        "--annotator-name",
+        required=True,
+        help="Name of the episode_annotations/<annotator>/ subgroup the labels land in.",
+    )
+    parser.add_argument(
+        "--start-id",
+        type=int,
+        default=0,
+        help="Starting numeric counter for episode IDs (default: 0).",
+    )
+    parser.add_argument(
+        "--max-episodes",
+        type=int,
+        default=None,
+        help="Stop after writing this many episodes.",
+    )
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Rewrite output files that already exist (default: leave them alone).",
+    )
+
+
+def default_episode_id(_item: object, counter: int) -> str:
+    return f"episode_{counter:06d}"
+
+
+def run_batch(
+    items: Sequence[T] | Iterable[T],
+    convert_one: Callable[[T, str, ConversionOutput], None],
+    *,
+    out: ConversionOutput,
+    episode_id_for: Callable[[T, int], str] = default_episode_id,
+    label: Callable[[T], str] = str,
+    start_id: int = 0,
+    desc: str = "Converting",
+    overwrite: bool = False,
+    max_episodes: int | None = None,
+) -> dict[str, int]:
+    """Convert every item, counting outcomes instead of stopping at the first failure.
+
+    ``convert_one`` writes ``out.episode_h5(episode_id)``; raising :class:`Skip` drops the
+    item. The counter behind ``episode_id_for`` advances for every item, skipped ones
+    included, so an id stays tied to its source episode across reruns with different
+    filters.
+    """
+    items = list(items)
+    counts = {"written": 0, "exists": 0, "skipped": 0, "failed": 0}
+
+    with tqdm(items, desc=desc, unit="ep") as progress:
+        for offset, item in enumerate(progress):
+            if max_episodes is not None and counts["written"] >= max_episodes:
+                break
+            episode_id = episode_id_for(item, start_id + offset)
+            progress.set_postfix_str(label(item)[:48])
+
+            if out.episode_h5(episode_id).exists() and not overwrite:
+                counts["exists"] += 1
+                continue
+            try:
+                convert_one(item, episode_id, out)
+            except Skip as skip:
+                tqdm.write(f"  – {episode_id}: {skip}")
+                counts["skipped"] += 1
+            except Exception as exc:  # noqa: BLE001 — one bad episode must not end the run
+                tqdm.write(f"  ✗ {episode_id}: {exc}")
+                counts["failed"] += 1
+            else:
+                counts["written"] += 1
+
+    return counts
+
+
+def report(counts: dict[str, int]) -> None:
+    tqdm.write(
+        f"\nDone: {counts['written']} written, {counts['exists']} already existed, "
+        f"{counts['skipped']} skipped, {counts['failed']} failed.\n"
+        "Next: oopsie-data validate --path <output-dir>"
+    )

oopsie_data_tools-0.2.1/examples/conversion_script_examples/convert_ar_aloha.py

@@ -0,0 +1,275 @@
+"""Convert ACT / ALOHA episode HDF5 files to ``oopsiedata_format_v1`` HDF5.
+
+Source layout (one file per episode, as written by the ACT / ACT++ recording stack):
+
+  /action                                  (T, 14)  target joint positions, both arms
+  /observations/qpos                       (T, 14)  measured joint positions, both arms
+  /observations/qvel, /observations/effort  (T, 14) optional, unused here
+  /success                                 (T,)     per-timestep success flag
+  /compress_len                            (3, T)   JPEG byte lengths, one row per camera
+  /observations/images/camera_high         (T, ...) frames, JPEG-compressed or raw RGB
+  /observations/images/camera_wrist_left   (T, ...)
+  /observations/images/camera_wrist_right  (T, ...)
+
+Both 14-vectors are ``[6 arm joints + gripper]`` per arm. They are written out whole as
+``joint_position``, matching the 14 entries in the profile's joint-name lists, with the two
+gripper columns additionally written as ``gripper_position`` — the layout of the bundled
+``configs/robot_profiles/act_plus_plus_robot_profile.yaml``.
+
+There are no cartesian data in the source and the profile does not claim any: a joint action
+space requires ``joint_position`` state, not ``cartesian_position``. Earlier versions of this
+script wrote zero-filled cartesian arrays, which the validator now rejects as undeclared.
+
+The images are decoded and re-encoded to one MP4 per camera at ``control_freq`` fps, and
+downscaled if a side exceeds the 1280 px the validator allows.
+
+``language_instruction`` is not stored in the source, so it is passed on the command line and
+applies to every episode in the run.
+
+Output — one file per source episode:
+
+  {output_dir}/{episode_id}.h5
+  {output_dir}/videos/{episode_id}_{camera}.mp4
+
+Usage:
+    # A single episode
+    python convert_ar_aloha.py -s /data/aloha/episode_0.hdf5 -o ./converted \\
+        --lab-id my_lab --operator-name alice --annotator-name act_eval \\
+        --language "Pick up the ball"
+
+    # Every episode in a directory
+    python convert_ar_aloha.py -s /data/aloha/rollouts -o ./converted \\
+        --lab-id my_lab --operator-name alice --annotator-name act_eval \\
+        --language "Pick up the ball"
+"""
+
+from __future__ import annotations
+
+import argparse
+from functools import partial
+from pathlib import Path
+
+import cv2
+import h5py
+import numpy as np
+from _common import ConversionOutput, Skip, add_common_args, report, run_batch
+
+from oopsie_data_tools.annotation_tool.episode_recorder import write_mp4
+from oopsie_data_tools.utils.conversion_utils import (
+    resize_frames,
+    write_actions,
+    write_episode_annotations,
+    write_robot_states,
+    write_root_attrs,
+    write_video_paths,
+)
+from oopsie_data_tools.utils.robot_profile.robot_profile import RobotProfile
+
+DEFAULT_CONTROL_FREQ = 50  # Hz — ALOHA's teleop rate, and the video fps
+
+# Column indices within the 14D qpos / action vectors.
+GRIPPER_IDX = [6, 13]
+
+# Source dataset → output camera name. The order is also the row order of /compress_len.
+CAMERA_MAP = {
+    "camera_high": "top",
+    "camera_wrist_left": "left_wrist",
+    "camera_wrist_right": "right_wrist",
+}
+
+JOINT_NAMES = [
+    f"{joint}_{side}"
+    for side in ("left", "right")
+    for joint in (
+        "waist",
+        "shoulder",
+        "elbow",
+        "forearm_roll",
+        "wrist_angle",
+        "wrist_rotate",
+        "gripper",
+    )
+]
+ACTION_SPACE = ["joint_position", "gripper_position"]
+
+
+def build_profile(policy_name: str, control_freq: int) -> RobotProfile:
+    return RobotProfile(
+        policy_name=policy_name,
+        robot_name="viperx_300",
+        gripper_name="viperx_300_gripper",
+        is_biarm=True,
+        uses_mobile_base=False,
+        control_freq=control_freq,
+        camera_names=list(CAMERA_MAP.values()),
+        robot_state_keys=["joint_position", "gripper_position"],
+        robot_state_joint_names=list(JOINT_NAMES),
+        action_space=list(ACTION_SPACE),
+        action_joint_names=list(JOINT_NAMES),
+    )
+
+
+def _decode_frames(raw: np.ndarray, lengths: np.ndarray | None) -> np.ndarray:
+    """Return ``(T, H, W, 3)`` RGB frames from a camera dataset.
+
+    ``lengths`` is the camera's ``/compress_len`` row; without it the dataset is assumed to
+    hold raw RGB frames already, which is how uncompressed ALOHA recordings are stored.
+    """
+    if lengths is None:
+        if raw.ndim != 4 or raw.shape[-1] != 3:
+            raise ValueError(
+                f"Camera dataset has shape {raw.shape} and the file has no /compress_len, "
+                "so it is neither raw RGB nor decodable JPEG."
+            )
+        return np.asarray(raw, dtype=np.uint8)
+
+    frames = []
+    for t in range(raw.shape[0]):
+        buffer = np.frombuffer(raw[t, : int(lengths[t])], dtype=np.uint8)
+        bgr = cv2.imdecode(buffer, cv2.IMREAD_COLOR)
+        if bgr is None:
+            raise ValueError(f"Failed to decode JPEG frame {t}")
+        frames.append(bgr[:, :, ::-1])  # BGR → RGB
+    return np.stack(frames, axis=0)
+
+
+def convert_one(
+    source_h5: Path,
+    episode_id: str,
+    out: ConversionOutput,
+    *,
+    lab_id: str,
+    operator_name: str,
+    annotator_name: str,
+    language_instruction: str,
+    policy_name: str,
+    control_freq: int,
+    success_aggregation: str,
+) -> None:
+    profile = build_profile(policy_name, control_freq)
+
+    with h5py.File(source_h5, "r") as src:
+        action = src["action"][()]
+        qpos = src["observations/qpos"][()]
+
+        success_per_step = src["success"][()]
+        if success_per_step.size == 0:
+            raise Skip("no /success values to aggregate")
+        success = float(
+            success_per_step[-1] if success_aggregation == "last" else success_per_step.max()
+        )
+
+        compress_len = src["compress_len"][()] if "compress_len" in src else None
+        frames = {
+            camera: _decode_frames(
+                src[f"observations/images/{key}"][()],
+                None if compress_len is None else compress_len[row],
+            )
+            for row, (key, camera) in enumerate(CAMERA_MAP.items())
+        }
+
+    video_paths = {}
+    for camera, camera_frames in frames.items():
+        destination = out.video_path(episode_id, camera)
+        write_mp4(destination, resize_frames(camera_frames), float(control_freq))
+        video_paths[camera] = str(destination)
+
+    h5_path = out.episode_h5(episode_id)
+    with h5py.File(h5_path, "w") as f:
+        write_root_attrs(
+            f,
+            episode_id=episode_id,
+            language_instruction=language_instruction,
+            lab_id=lab_id,
+            operator_name=operator_name,
+            robot_profile=profile,
+        )
+        write_video_paths(f, video_paths, h5_path)
+        write_robot_states(
+            f,
+            {
+                "joint_position": qpos,
+                "gripper_position": qpos[:, GRIPPER_IDX],
+            },
+            profile.robot_state_keys,
+        )
+        write_actions(
+            f,
+            {
+                "joint_position": action,
+                "gripper_position": action[:, GRIPPER_IDX],
+            },
+            profile.action_space,
+        )
+        write_episode_annotations(f, annotator_name=annotator_name, success=success)
+
+
+def discover(source: Path) -> list[Path]:
+    if source.is_file():
+        return [source]
+    files = sorted(p for p in source.iterdir() if p.suffix in {".h5", ".hdf5"})
+    if not files:
+        raise SystemExit(f"No .h5 or .hdf5 files found in {source}")
+    return files
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Convert ACT/ALOHA HDF5 episodes to oopsiedata_format_v1 HDF5",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    add_common_args(
+        parser,
+        source_help="A single ACT/ALOHA .hdf5 episode, or a directory of them.",
+    )
+    parser.add_argument(
+        "--language",
+        "-l",
+        required=True,
+        help="Language instruction for every episode (the source files do not store one).",
+    )
+    parser.add_argument(
+        "--policy-name",
+        default="act_plus_plus",
+        help="Value for robot_profile.policy_name (default: act_plus_plus).",
+    )
+    parser.add_argument(
+        "--control-freq",
+        type=int,
+        default=DEFAULT_CONTROL_FREQ,
+        help=f"Control frequency in Hz, also the video fps (default: {DEFAULT_CONTROL_FREQ}).",
+    )
+    parser.add_argument(
+        "--success-aggregation",
+        choices=["max", "last"],
+        default="max",
+        help="How to collapse the per-timestep /success flag to a scalar (default: max).",
+    )
+    args = parser.parse_args()
+
+    out = ConversionOutput.create(args.output_dir)
+    counts = run_batch(
+        discover(args.source.resolve()),
+        partial(
+            convert_one,
+            lab_id=args.lab_id,
+            operator_name=args.operator_name,
+            annotator_name=args.annotator_name,
+            language_instruction=args.language,
+            policy_name=args.policy_name,
+            control_freq=args.control_freq,
+            success_aggregation=args.success_aggregation,
+        ),
+        out=out,
+        label=lambda path: path.name,
+        start_id=args.start_id,
+        desc="ACT/ALOHA",
+        overwrite=args.overwrite,
+        max_episodes=args.max_episodes,
+    )
+    report(counts)
+
+
+if __name__ == "__main__":
+    main()