Package `openpack_toolkit`

OpenPack Dataset Toolkit (optk)

OpenPack Dataset Logo

"OpenPack Dataset" is a new large-scale multi-modal dataset of the manual packing process. OpenPack is an open-access logistics dataset for human activity recognition, which contains human movement and package information from 16 distinct subjects. This repository provides utilities to explore our exciting dataset.

Install

# Pip
pip install openpack-toolkit

# Poetry
poetry add  openpack-toolkit

Note that the supported dataset version is >=1.0.0.

Docs

Work Operation Recognition
OpenPack Challenge 2022

Note: Technical documents of the OpenPack dataset are available at GitHub: openpack-dataset/docs.

OpenPack Dataset

See OpenPack Dataset Homepage or GitHub: openpack-dataset for the details of our dataset. To download our dataset, visit this download instruction page.

Examples

Tutorial

Download and Visualization (Notebook)

Work Activity Recognition (PyTorch)

PyTorch code samples for the work operation prediction task are available. See openpack-torch for more details.

Timestamp

Each data point is associated with a millisecond-precision unix timestamp. The following is a snippet that converts a timestamp (an int value) into a datatime.datetime() object with timezone.

import datetime


def timestamp_to_datetime(ts: int) -> datetime.datetime:
  """Convert unix timestamp (milli-second precision) into datatime object. """
  timezone_jst = datetime.timezone(datetime.timedelta(hours=9))
  dt = datetime.datetime.fromtimestamp(ts / 1000).replace(tzinfo=timezone_jst)
  return dt

def datetime_to_timestamp(dt: datetime.datetime) -> int:
  """Convert a datetime object into a milli-second precision timestamp."""
  return int(dt.timestamp() * 1000)


ts = 1634885786000

dt_out =  timestamp_to_datetime(ts)
ts_out = datetime_to_timestamp(dt_out)
print(f"datetime: {dt_out}")  # datetime: 2021-10-22 15:56:26+09:00
print(f"timestamp: {ts_out}")  # timestamp: 1634885786000
assert ts_out == ts

License

openpack-toolkit has the MIT license, as found in the LICENSE file.

NOTE: OpenPack Dataset itself is available under Creative Commons Attribution Non Commercial Share Alike 4.0 International license. However, OpenPack Dataset (+RGB) License is applied to "OpenPack Dataset (+RGB)" which includes RGB data.

Expand source code

"""
.. include:: ../README.md
"""

__version__ = "1.1.0"
from . import codalab, configs, data, utils
from .activity import ActClass, ActSet
from .configs.datasets.annotations import OPENPACK_OPERATIONS

DATASET_VERSION_LATEST = "v1.0.0"
DATASET_VERSION = DATASET_VERSION_LATEST
SAMPLE_DATASET_VERSION = "v1.0.0"


__all__ = [
    "ActClass",
    "ActSet",
    "codalab",
    "configs",
    "data",
    "utils",
    "DATASET_VERSION",
    "OPENPACK_OPERATIONS",
]

Sub-modules

openpack_toolkit.activity: Activity set definitions for OpenPack dataset.
openpack_toolkit.bin
openpack_toolkit.codalab
openpack_toolkit.configs
openpack_toolkit.data: optk.data module provide easy access to our dataset.
openpack_toolkit.utils
openpack_toolkit.validation

Classes

class ActSet (classes: Tuple[openpack_toolkit.configs._schema.Label, ...])

ActSet binds activity classes and proved methods that can be useful when you apply machine learning approach. Activity class definition of OpenPack dataset will be provided in this format.

Expand source code

@dataclass
class ActSet():
    """ActSet binds activity classes and proved methods that can be useful when you apply machine
    learning approach. Activity class definition of OpenPack dataset will be provided in this
    format.
    """
    classes: Tuple[ActClass, ...]

    def __len__(self) -> int:
        return len(self.classes)

    def __iter__(self):
        self._current = 0
        return self

    def __next__(self):
        if self._current == len(self.classes):
            raise StopIteration
        cls = self.classes[self._current]
        self._current += 1
        return cls

    def __call__(self, cls_idx: int) -> ActClass:
        """Return ActClass object at index=``cls_idx``.

        Args:
            cls_idx (int): ckass index

        Returns:
            ActClass
        """
        return self.classes[cls_idx]

    def to_tuple(
        self, keep_actclass: bool = False,
    ) -> Union[Tuple[Tuple[int, str], ...], Tuple[ActClass, ...]]:
        """Returns a activity classes as a tuple.

        Args:
            keep_actclass (bool, optional): If True, return a tuple of ActClass.
                Otherwise, return a pure tuple, i.e., ``Tuple[Tuple[id:int, name:str], ...]``.
                Defaults to False.

        Returns:
            Union[Tuple[Tuple[int, str], ...], Tuple[ActClass, ...]]
        """
        if keep_actclass:
            return self.classes

        classes = [(cls.id, cls.name) for cls in self.classes]
        return tuple(classes)

    def get_ids(self) -> Tuple[int]:
        """Returns a tuple of class IDs.

        Returns:
            Tuple[int]
        """
        return tuple([act.id for act in self.classes])

    def get_ignore_class_index(self) -> Union[int, Tuple]:
        """Return the index of ignore classes, i.e., ``is_ignore=True``.
        If there are only one ignore class, return the index as int.
        When there is no ignore classe, return None.

        Returns:
            Union[int, Tuple] or None
        """
        index = tuple([i for i, act in enumerate(
            self.classes) if act.is_ignore])
        if len(index) == 0:
            return None
        if len(index) == 1:
            return index[0]
        return index

    def get_ignore_class_id(self) -> Union[int, Tuple]:
        """Return the ID of ignore classes, i.e., ``is_ignore=True``.
        If there are only one ignore class, return the ID as int.
        When there is no ignore classe, return None.

        Returns:
            Union[int, Tuple] or None
        """
        ids = tuple([act.id for act in self.classes if act.is_ignore])
        if len(ids) == 0:
            return None
        if len(ids) == 1:
            return ids[0]
        return ids

    def convert_id_to_index(self, ids: np.ndarray) -> np.ndarray:
        """Translate activity ID into activity index.

        Args:
            ids (np.ndarray): 1d array of activity IDs.

        Returns:
            np.ndarray: 1d array of activity index.
        """
        assert set(ids.ravel()) <= set(self.get_ids()), (
            f"expected ID set is {set(self.get_ids())}, "
            f"but got ID set={set(ids.ravel())}."
        )

        index = np.full(ids.shape, -1)
        for i, cls in enumerate(self.classes):
            index[ids == cls.id] = i
        assert index.min() >= 0

        return index.astype(np.int64)

    def convert_index_to_id(self, index: np.ndarray) -> np.ndarray:
        """Translate activity index into activity ID.

        Args:
            index (np.ndarray): 1d array of activity index.

        Returns:
            np.ndarray: 1d array of activity IDs.
        """
        assert min(self.get_ids()) >= 0
        assert (index.min() >= 0) and (index.max() < len(self.classes)), (
            f"given index have out of range value(s)([0, {len(self.classes)}])."
            f" index.min()={index.min()}, index.max={index.max()}"
        )

        ids = np.full(index.shape, -1)
        for i, cls in enumerate(self.classes):
            ids[index == i] = cls.id
        assert ids.min() >= 0

        return ids.astype(np.int64)

    def id_to_name(self, cls_id: int) -> str:
        """Returns class name of the given class ID.

        Args:
            cls_id (int): class ID.

        Raises:
            ValueError: ``class_id`` does not exists in the activity set.

        Returns:
            str: class name
        """
        for cls in self.classes:
            if cls.id == cls_id:
                return cls.name
        raise ValueError(f"got unexpected class id. cls_id={cls_id}")

    def name_to_id(self, cls_name: str) -> int:
        """Returns class ID of the given class ID.

        Args:
            cls_name (str): class name.

        Raises:
            ValueError: ``class_name`` does not exists in the activity set.

        Returns:
            int: class id
        """
        for cls in self.classes:
            if cls.name == cls_name:
                return cls.id
        raise ValueError(f"got unexpected class name. cls_name={cls_name}")

Class variables

var classes : Tuple[openpack_toolkit.configs._schema.Label, ...]

Methods

def convert_id_to_index(self, ids: numpy.ndarray) ‑> numpy.ndarray

Translate activity ID into activity index.

Args

ids : np.ndarray: 1d array of activity IDs.

Returns

np.ndarray: 1d array of activity index.

Expand source code

def convert_id_to_index(self, ids: np.ndarray) -> np.ndarray:
    """Translate activity ID into activity index.

    Args:
        ids (np.ndarray): 1d array of activity IDs.

    Returns:
        np.ndarray: 1d array of activity index.
    """
    assert set(ids.ravel()) <= set(self.get_ids()), (
        f"expected ID set is {set(self.get_ids())}, "
        f"but got ID set={set(ids.ravel())}."
    )

    index = np.full(ids.shape, -1)
    for i, cls in enumerate(self.classes):
        index[ids == cls.id] = i
    assert index.min() >= 0

    return index.astype(np.int64)

def convert_index_to_id(self, index: numpy.ndarray) ‑> numpy.ndarray

Translate activity index into activity ID.

Args

index : np.ndarray: 1d array of activity index.

Returns

np.ndarray: 1d array of activity IDs.

Expand source code

def convert_index_to_id(self, index: np.ndarray) -> np.ndarray:
    """Translate activity index into activity ID.

    Args:
        index (np.ndarray): 1d array of activity index.

    Returns:
        np.ndarray: 1d array of activity IDs.
    """
    assert min(self.get_ids()) >= 0
    assert (index.min() >= 0) and (index.max() < len(self.classes)), (
        f"given index have out of range value(s)([0, {len(self.classes)}])."
        f" index.min()={index.min()}, index.max={index.max()}"
    )

    ids = np.full(index.shape, -1)
    for i, cls in enumerate(self.classes):
        ids[index == i] = cls.id
    assert ids.min() >= 0

    return ids.astype(np.int64)

def get_ids(self) ‑> Tuple[int]

Returns a tuple of class IDs.

Returns

Tuple[int]

Expand source code

def get_ids(self) -> Tuple[int]:
    """Returns a tuple of class IDs.

    Returns:
        Tuple[int]
    """
    return tuple([act.id for act in self.classes])

def get_ignore_class_id(self) ‑> Union[int, Tuple]

Return the ID of ignore classes, i.e., is_ignore=True. If there are only one ignore class, return the ID as int. When there is no ignore classe, return None.

Returns

Union[int, Tuple] or None

Expand source code

def get_ignore_class_id(self) -> Union[int, Tuple]:
    """Return the ID of ignore classes, i.e., ``is_ignore=True``.
    If there are only one ignore class, return the ID as int.
    When there is no ignore classe, return None.

    Returns:
        Union[int, Tuple] or None
    """
    ids = tuple([act.id for act in self.classes if act.is_ignore])
    if len(ids) == 0:
        return None
    if len(ids) == 1:
        return ids[0]
    return ids

def get_ignore_class_index(self) ‑> Union[int, Tuple]

Return the index of ignore classes, i.e., is_ignore=True. If there are only one ignore class, return the index as int. When there is no ignore classe, return None.

Returns

Union[int, Tuple] or None

Expand source code

def get_ignore_class_index(self) -> Union[int, Tuple]:
    """Return the index of ignore classes, i.e., ``is_ignore=True``.
    If there are only one ignore class, return the index as int.
    When there is no ignore classe, return None.

    Returns:
        Union[int, Tuple] or None
    """
    index = tuple([i for i, act in enumerate(
        self.classes) if act.is_ignore])
    if len(index) == 0:
        return None
    if len(index) == 1:
        return index[0]
    return index

def id_to_name(self, cls_id: int) ‑> str

Returns class name of the given class ID.

Args

cls_id : int: class ID.

Raises

ValueError: class_id does not exists in the activity set.

Returns

str: class name

Expand source code

def id_to_name(self, cls_id: int) -> str:
    """Returns class name of the given class ID.

    Args:
        cls_id (int): class ID.

    Raises:
        ValueError: ``class_id`` does not exists in the activity set.

    Returns:
        str: class name
    """
    for cls in self.classes:
        if cls.id == cls_id:
            return cls.name
    raise ValueError(f"got unexpected class id. cls_id={cls_id}")

def name_to_id(self, cls_name: str) ‑> int

Returns class ID of the given class ID.

Args

cls_name : str: class name.

Raises

ValueError: class_name does not exists in the activity set.

Returns

int: class id

Expand source code

def name_to_id(self, cls_name: str) -> int:
    """Returns class ID of the given class ID.

    Args:
        cls_name (str): class name.

    Raises:
        ValueError: ``class_name`` does not exists in the activity set.

    Returns:
        int: class id
    """
    for cls in self.classes:
        if cls.name == cls_name:
            return cls.id
    raise ValueError(f"got unexpected class name. cls_name={cls_name}")

def to_tuple(self, keep_actclass: bool = False) ‑> Union[Tuple[Tuple[int, str], ...], Tuple[openpack_toolkit.configs._schema.Label, ...]]

Returns a activity classes as a tuple.

Args

keep_actclass : bool, optional: If True, return a tuple of ActClass. Otherwise, return a pure tuple, i.e., Tuple[Tuple[id:int, name:str], ...]. Defaults to False.

Returns

Union[Tuple[Tuple[int, str], …], Tuple[ActClass, …]]

Expand source code

def to_tuple(
    self, keep_actclass: bool = False,
) -> Union[Tuple[Tuple[int, str], ...], Tuple[ActClass, ...]]:
    """Returns a activity classes as a tuple.

    Args:
        keep_actclass (bool, optional): If True, return a tuple of ActClass.
            Otherwise, return a pure tuple, i.e., ``Tuple[Tuple[id:int, name:str], ...]``.
            Defaults to False.

    Returns:
        Union[Tuple[Tuple[int, str], ...], Tuple[ActClass, ...]]
    """
    if keep_actclass:
        return self.classes

    classes = [(cls.id, cls.name) for cls in self.classes]
    return tuple(classes)

class ActClass (id: Union[int, str] = '???', name: str = '???', version: str = '???', is_ignore: bool = False, category: Optional[str] = None, event: Optional[str] = None)

dataclass that represent a single activity class.

Expand source code

@dataclass
class Label():
    """dataclass that represent a single activity class.
    """
    id: Union[int, str] = MISSING
    name: str = MISSING
    version: str = MISSING
    is_ignore: bool = False
    category: Optional[str] = None
    event: Optional[str] = None

Class variables

var category : Optional[str]
var event : Optional[str]
var id : Union[int, str]
var is_ignore : bool
var name : str
var version : str

OpenPack Dataset Toolkit (optk)

Install

Docs

OpenPack Dataset

Examples

Tutorial

Work Activity Recognition (PyTorch)

Timestamp

Links

License

Sub-modules

Classes

Class variables

Methods

Args

Returns

Args

Returns

Returns

Returns

Returns

Args

Raises

Returns

Args

Raises

Returns

Args

Returns

Class variables