opentau 0.1.0__py3-none-any.whl

opentau/datasets/standard_data_format_mapping.py

@@ -0,0 +1,278 @@
+# Copyright 2026 Tensor Auto Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Standard data format mapping for dataset feature names and loss types.
+
+This module provides mappings between standard feature names used internally
+by OpenTau and dataset-specific feature names used in various robot learning
+and vision-language datasets. It also maps datasets to their appropriate loss
+types for training.
+
+The standard format uses canonical names like "camera0", "camera1", "state",
+"actions", "prompt", and "response", while different datasets may use
+various naming conventions (e.g., "observation.images.image",
+"observation.state", "action", "task", etc.). These mappings enable the
+codebase to work with multiple datasets without requiring dataset-specific
+code paths.
+
+Key Features:
+    - Feature name standardization: Maps dataset-specific feature names to
+      standard format names for consistent processing across datasets.
+    - Multi-camera support: Handles datasets with varying numbers of camera
+      views, mapping them to standard camera0, camera1, etc. names.
+    - Loss type specification: Maps datasets to appropriate loss functions
+      (MSE for continuous actions, CE for discrete classification tasks).
+
+Constants:
+
+    DATA_FEATURES_NAME_MAPPING
+        Dictionary mapping dataset repository IDs to feature name dictionaries.
+        Each inner dictionary maps standard feature names (keys) to
+        dataset-specific feature names (values). Standard feature names include:
+
+        - "camera0", "camera1", ...: Camera/image observations
+        - "state": Robot state observations
+        - "actions": Action outputs
+        - "prompt": Task descriptions or prompts
+        - "response": Expected responses or labels
+
+    LOSS_TYPE_MAPPING
+        Dictionary mapping dataset repository IDs to loss type strings. Valid
+        values are:
+
+        - "MSE": Mean Squared Error (typically for continuous robotic actions)
+        - "CE": Cross Entropy (typically for discrete classification tasks
+          like VQA)
+
+Example:
+    Access feature name mapping for a dataset:
+        >>> mapping = DATA_FEATURES_NAME_MAPPING["lerobot/aloha_mobile_cabinet"]
+        >>> mapping["camera0"]  # Returns "observation.images.cam_right_wrist"
+        >>> mapping["actions"]  # Returns "action"
+
+    Access loss type for a dataset:
+        >>> loss_type = LOSS_TYPE_MAPPING["lerobot/aloha_mobile_cabinet"]
+        >>> loss_type  # Returns "MSE"
+"""
+
+DATA_FEATURES_NAME_MAPPING = {
+    "ML-GOD/mt-button-press": {
+        "camera0": "observation.image",
+        "state": "observation.robot_state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "ML-GOD/libero_spatial_no_noops_1.0.0_lerobot": {
+        "camera0": "observation.images.image",
+        "camera1": "observation.images.wrist_image",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "ML-GOD/libero": {
+        "camera0": "image",
+        "camera1": "wrist_image",
+        "state": "state",
+        "actions": "actions",
+        "prompt": "task",
+        "response": "response",
+    },
+    "physical-intelligence/libero": {
+        "camera0": "image",
+        "camera1": "wrist_image",
+        "state": "state",
+        "actions": "actions",
+        "prompt": "task",
+        "response": "response",
+    },
+    "danaaubakirova/koch_test": {
+        "camera0": "observation.images.laptop",
+        "camera1": "observation.images.phone",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "lerobot/droid_100": {
+        "camera0": "observation.images.exterior_image_1_left",
+        "camera1": "observation.images.exterior_image_2_left",
+        "camera2": "observation.images.wrist_image_left",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "lerobot/aloha_mobile_cabinet": {
+        "camera0": "observation.images.cam_right_wrist",
+        "camera1": "observation.images.cam_high",
+        "camera2": "observation.images.cam_left_wrist",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "autox/agibot-sample": {
+        "camera0": "observation.images.head_left_fisheye",
+        "camera1": "observation.images.head_right_fisheye",
+        "camera2": "observation.images.top_head",
+        "camera3": "observation.images.hand_left",
+        "camera4": "observation.images.hand_right",
+        "camera5": "observation.images.head_center_fisheye",
+        "camera6": "observation.images.back_left_fisheye",
+        "camera7": "observation.images.back_right_fisheye",
+        "camera8": "observation.images.cam_top_depth",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "bi-so100-block-manipulation": {
+        "camera0": "observation.images.top",
+        "camera1": "observation.images.main",
+        "camera2": "observation.images.cv",
+        "local_camera0": "observation.images.top",
+        "local_camera1": "observation.images.main",
+        "local_camera2": "observation.images.cv",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "cube-on-cylinder": {
+        "camera0": "observation.images.top",
+        "camera1": "observation.images.main",
+        "camera2": "observation.images.cv",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "cylinder-on-cube": {
+        "camera0": "observation.images.top",
+        "camera1": "observation.images.main",
+        "camera2": "observation.images.cv",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "l-shape-on-cross-shape": {
+        "camera0": "observation.images.top",
+        "camera1": "observation.images.main",
+        "camera2": "observation.images.cv",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "lerobot/svla_so101_pickplace": {
+        "camera0": "observation.images.up",
+        "camera1": "observation.images.side",
+        "local_camera0": "observation.images.up",
+        "local_camera1": "observation.images.side",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "lerobot/svla_so100_pickplace": {
+        "camera0": "observation.images.top",
+        "camera1": "observation.images.wrist",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "lerobot/svla_so100_stacking": {
+        "camera0": "observation.images.top",
+        "camera1": "observation.images.wrist",
+        "state": "observation.state",
+        "actions": "action",
+        "prompt": "task",
+        "response": "response",
+    },
+    "pixmo": {
+        "camera0": "image",
+        "state": "state",
+        "actions": "actions",
+        "prompt": "prompt",
+        "response": "postfix",
+    },
+    "dummy": {
+        "camera0": "image",
+        "state": "state",
+        "actions": "actions",
+        "prompt": "prompt",
+        "response": "postfix",
+    },
+    "vsr": {
+        "camera0": "image",
+        "state": "state",
+        "actions": "actions",
+        "prompt": "prompt",
+        "response": "postfix",
+    },
+    "clevr": {
+        "camera0": "image",
+        "state": "state",
+        "actions": "actions",
+        "prompt": "prompt",
+        "response": "postfix",
+    },
+    "cocoqa": {
+        "camera0": "image",
+        "state": "state",
+        "actions": "actions",
+        "prompt": "prompt",
+        "response": "postfix",
+    },
+    "lerobot_dummy": {
+        "camera0": "camera0",
+        "state": "state",
+        "actions": "actions",
+        "prompt": "task",
+        "response": "response",
+    },
+}
+
+"""
+Use "MSE" for mean squared error and "CE" for cross entropy.
+Usually robotic data with actions will have an MSE loss while
+VQA tasks will have a CE loss.
+"""
+LOSS_TYPE_MAPPING = {
+    "ML-GOD/mt-button-press": "MSE",
+    "ML-GOD/libero_spatial_no_noops_1.0.0_lerobot": "MSE",
+    "ML-GOD/libero": "MSE",
+    "physical-intelligence/libero": "MSE",
+    "danaaubakirova/koch_test": "MSE",
+    "lerobot/droid_100": "MSE",
+    "lerobot/aloha_mobile_cabinet": "MSE",
+    "autox/agibot-sample": "MSE",
+    "bi-so100-block-manipulation": "MSE",
+    "cube-on-cylinder": "MSE",
+    "cylinder-on-cube": "MSE",
+    "l-shape-on-cross-shape": "MSE",
+    "lerobot/svla_so101_pickplace": "MSE",
+    "lerobot/svla_so100_pickplace": "MSE",
+    "lerobot/svla_so100_stacking": "MSE",
+    "pixmo": "CE",
+    "dummy": "CE",
+    "vsr": "CE",
+    "clevr": "CE",
+    "cocoqa": "CE",
+    "lerobot_dummy": "MSE",
+}

opentau/datasets/transforms.py

@@ -0,0 +1,330 @@
+#!/usr/bin/env python
+
+# Copyright 2024 The HuggingFace Inc. team. All rights reserved.
+# Copyright 2026 Tensor Auto Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Image transformation utilities for data augmentation.
+
+This module provides configurable image transformation pipelines for data
+augmentation during training. It extends torchvision.transforms.v2 with custom
+transforms and a flexible configuration system that supports weighted random
+sampling of transform subsets.
+
+The module implements a probabilistic augmentation strategy where a random
+subset of available transforms is applied to each image, with configurable
+weights controlling the sampling probability. This approach provides more
+diverse augmentations compared to applying all transforms deterministically.
+
+Key Features:
+    - Random subset sampling: Applies a random subset of N transforms from a
+      larger pool, controlled by configurable weights.
+    - Custom transforms: Includes SharpnessJitter for more diverse sharpness
+      augmentation compared to standard torchvision transforms.
+    - Configurable pipeline: Dataclass-based configuration system for easy
+      customization of transform parameters and weights.
+    - Flexible ordering: Option to apply transforms in random order or
+      deterministic order.
+    - Torchvision v2 integration: Built on top of torchvision.transforms.v2
+      for modern transform API support.
+
+Classes:
+    RandomSubsetApply: Transform container that applies a random subset of
+        transforms with weighted sampling and optional random ordering.
+    SharpnessJitter: Custom transform for randomly jittering image sharpness
+        with uniform distribution sampling.
+    ImageTransformConfig: Dataclass for configuring individual transform
+        parameters (weight, type, kwargs).
+    ImageTransformsConfig: Dataclass for configuring the overall transform
+        pipeline (enable flag, max transforms, random order, transform list).
+    ImageTransforms: Main transform class that composes transforms based on
+        configuration.
+
+Functions:
+    make_transform_from_config: Factory function to create transform instances
+        from ImageTransformConfig.
+
+Example:
+    Create and use image transforms:
+        >>> config = ImageTransformsConfig(
+        ...     enable=True,
+        ...     max_num_transforms=3,
+        ...     random_order=True
+        ... )
+        >>> transforms = ImageTransforms(config)
+        >>> augmented_image = transforms(image_tensor)
+"""
+
+import collections
+from dataclasses import dataclass, field
+from typing import Any, Callable, Sequence
+
+import torch
+from torchvision.transforms import v2
+from torchvision.transforms.v2 import Transform
+from torchvision.transforms.v2 import functional as F  # noqa: N812
+
+
+class RandomSubsetApply(Transform):
+    """Apply a random subset of N transformations from a list of transformations.
+
+    Args:
+        transforms: list of transformations.
+        p: represents the multinomial probabilities (with no replacement) used for sampling the transform.
+            If the sum of the weights is not 1, they will be normalized. If ``None`` (default), all transforms
+            have the same probability.
+        n_subset: number of transformations to apply. If ``None``, all transforms are applied.
+            Must be in [1, len(transforms)].
+        random_order: apply transformations in a random order.
+    """
+
+    def __init__(
+        self,
+        transforms: Sequence[Callable],
+        p: list[float] | None = None,
+        n_subset: int | None = None,
+        random_order: bool = False,
+    ) -> None:
+        super().__init__()
+        if not isinstance(transforms, Sequence):
+            raise TypeError("Argument transforms should be a sequence of callables")
+        if p is None:
+            p = [1] * len(transforms)
+        elif len(p) != len(transforms):
+            raise ValueError(
+                f"Length of p doesn't match the number of transforms: {len(p)} != {len(transforms)}"
+            )
+
+        if n_subset is None:
+            n_subset = len(transforms)
+        elif not isinstance(n_subset, int):
+            raise TypeError("n_subset should be an int or None")
+        elif not (1 <= n_subset <= len(transforms)):
+            raise ValueError(f"n_subset should be in the interval [1, {len(transforms)}]")
+
+        self.transforms = transforms
+        total = sum(p)
+        self.p = [prob / total for prob in p]
+        self.n_subset = n_subset
+        self.random_order = random_order
+
+        self.selected_transforms = None
+
+    def forward(self, *inputs: Any) -> Any:
+        needs_unpacking = len(inputs) > 1
+
+        selected_indices = torch.multinomial(torch.tensor(self.p), self.n_subset)
+        if not self.random_order:
+            selected_indices = selected_indices.sort().values
+
+        self.selected_transforms = [self.transforms[i] for i in selected_indices]
+
+        for transform in self.selected_transforms:
+            outputs = transform(*inputs)
+            inputs = outputs if needs_unpacking else (outputs,)
+
+        return outputs
+
+    def extra_repr(self) -> str:
+        return (
+            f"transforms={self.transforms}, "
+            f"p={self.p}, "
+            f"n_subset={self.n_subset}, "
+            f"random_order={self.random_order}"
+        )
+
+
+class SharpnessJitter(Transform):
+    """Randomly change the sharpness of an image or video.
+
+    Similar to a v2.RandomAdjustSharpness with p=1 and a sharpness_factor sampled randomly.
+    While v2.RandomAdjustSharpness applies — with a given probability — a fixed sharpness_factor to an image,
+    SharpnessJitter applies a random sharpness_factor each time. This is to have a more diverse set of
+    augmentations as a result.
+
+    A sharpness_factor of 0 gives a blurred image, 1 gives the original image while 2 increases the sharpness
+    by a factor of 2.
+
+    If the input is a :class:`torch.Tensor`,
+    it is expected to have [..., 1 or 3, H, W] shape, where ... means an arbitrary number of leading dimensions.
+
+    Args:
+        sharpness: How much to jitter sharpness. sharpness_factor is chosen uniformly from
+            [max(0, 1 - sharpness), 1 + sharpness] or the given
+            [min, max]. Should be non negative numbers.
+    """
+
+    def __init__(self, sharpness: float | Sequence[float]) -> None:
+        super().__init__()
+        self.sharpness = self._check_input(sharpness)
+
+    def _check_input(self, sharpness):
+        if isinstance(sharpness, (int, float)):
+            if sharpness < 0:
+                raise ValueError("If sharpness is a single number, it must be non negative.")
+            sharpness = [1.0 - sharpness, 1.0 + sharpness]
+            sharpness[0] = max(sharpness[0], 0.0)
+        elif isinstance(sharpness, collections.abc.Sequence) and len(sharpness) == 2:
+            sharpness = [float(v) for v in sharpness]
+        else:
+            raise TypeError(f"{sharpness=} should be a single number or a sequence with length 2.")
+
+        if not 0.0 <= sharpness[0] <= sharpness[1]:
+            raise ValueError(f"sharpnesss values should be between (0., inf), but got {sharpness}.")
+
+        return float(sharpness[0]), float(sharpness[1])
+
+    def make_params(self, flat_inputs: list[Any]) -> dict[str, Any]:
+        """Generate random parameters for sharpness jitter.
+
+        Args:
+            flat_inputs: List of input tensors.
+
+        Returns:
+            Dictionary containing 'sharpness_factor' sampled uniformly from
+            the configured sharpness range.
+        """
+        sharpness_factor = torch.empty(1).uniform_(self.sharpness[0], self.sharpness[1]).item()
+        return {"sharpness_factor": sharpness_factor}
+
+    def transform(self, inpt: Any, params: dict[str, Any]) -> Any:
+        """Apply sharpness adjustment to input.
+
+        Args:
+            inpt: Input image or video tensor.
+            params: Dictionary containing 'sharpness_factor' from make_params.
+
+        Returns:
+            Transformed image or video with adjusted sharpness.
+        """
+        sharpness_factor = params["sharpness_factor"]
+        return self._call_kernel(F.adjust_sharpness, inpt, sharpness_factor=sharpness_factor)
+
+
+@dataclass
+class ImageTransformConfig:
+    """
+    For each transform, the following parameters are available:
+      weight: This represents the multinomial probability (with no replacement)
+            used for sampling the transform. If the sum of the weights is not 1,
+            they will be normalized.
+      type: The name of the class used. This is either a class available under torchvision.transforms.v2 or a
+            custom transform defined here.
+      kwargs: Lower & upper bound respectively used for sampling the transform's parameter
+            (following uniform distribution) when it's applied.
+    """
+
+    weight: float = 1.0
+    type: str = "Identity"
+    kwargs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ImageTransformsConfig:
+    """
+    These transforms are all using standard torchvision.transforms.v2
+    You can find out how these transformations affect images here:
+    https://pytorch.org/vision/0.18/auto_examples/transforms/plot_transforms_illustrations.html
+    We use a custom RandomSubsetApply container to sample them.
+    """
+
+    # Set this flag to `true` to enable transforms during training
+    enable: bool = False
+    # This is the maximum number of transforms (sampled from these below) that will be applied to each frame.
+    # It's an integer in the interval [1, number_of_available_transforms].
+    max_num_transforms: int = 3
+    # By default, transforms are applied in Torchvision's suggested order (shown below).
+    # Set this to True to apply them in a random order.
+    random_order: bool = False
+    tfs: dict[str, ImageTransformConfig] = field(
+        default_factory=lambda: {
+            "brightness": ImageTransformConfig(
+                weight=1.0,
+                type="ColorJitter",
+                kwargs={"brightness": (0.8, 1.2)},
+            ),
+            "contrast": ImageTransformConfig(
+                weight=1.0,
+                type="ColorJitter",
+                kwargs={"contrast": (0.8, 1.2)},
+            ),
+            "saturation": ImageTransformConfig(
+                weight=1.0,
+                type="ColorJitter",
+                kwargs={"saturation": (0.5, 1.5)},
+            ),
+            "hue": ImageTransformConfig(
+                weight=1.0,
+                type="ColorJitter",
+                kwargs={"hue": (-0.05, 0.05)},
+            ),
+            "sharpness": ImageTransformConfig(
+                weight=1.0,
+                type="SharpnessJitter",
+                kwargs={"sharpness": (0.5, 1.5)},
+            ),
+        }
+    )
+
+
+def make_transform_from_config(cfg: ImageTransformConfig) -> Transform:
+    """Create a transform instance from an ImageTransformConfig.
+
+    Args:
+        cfg: Configuration object specifying the transform type and parameters.
+
+    Returns:
+        Transform instance (Identity, ColorJitter, or SharpnessJitter).
+
+    Raises:
+        ValueError: If the transform type is not recognized.
+    """
+    if cfg.type == "Identity":
+        return v2.Identity(**cfg.kwargs)
+    elif cfg.type == "ColorJitter":
+        return v2.ColorJitter(**cfg.kwargs)
+    elif cfg.type == "SharpnessJitter":
+        return SharpnessJitter(**cfg.kwargs)
+    else:
+        raise ValueError(f"Transform '{cfg.type}' is not valid.")
+
+
+class ImageTransforms(Transform):
+    """A class to compose image transforms based on configuration."""
+
+    def __init__(self, cfg: ImageTransformsConfig) -> None:
+        super().__init__()
+        self._cfg = cfg
+
+        self.weights = []
+        self.transforms = {}
+        for tf_name, tf_cfg in cfg.tfs.items():
+            if tf_cfg.weight <= 0.0:
+                continue
+
+            self.transforms[tf_name] = make_transform_from_config(tf_cfg)
+            self.weights.append(tf_cfg.weight)
+
+        n_subset = min(len(self.transforms), cfg.max_num_transforms)
+        if n_subset == 0 or not cfg.enable:
+            self.tf = v2.Identity()
+        else:
+            self.tf = RandomSubsetApply(
+                transforms=list(self.transforms.values()),
+                p=self.weights,
+                n_subset=n_subset,
+                random_order=cfg.random_order,
+            )
+
+    def forward(self, *inputs: Any) -> Any:
+        return self.tf(*inputs)