diff --git a/README.md b/README.md index 8a37364e..0cdd233c 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,37 @@ -# tier4_perception_dataset +# TIER IV Perception Dataset Conversion Tools -This is the data conversion tools around T4 dataset. +This repository provides tools for converting ROS2 bag files and TIER IV (T4) dataset files, as well as the design specifications for the T4 dataset format. +These tools facilitate the preparation and transformation of perception data for autonomous driving applications. -## Tools Overview +## Table of Contents + +1. [Dataset Overview](#dataset-overview) +2. [Usage of T4 dataset](#usage-of-t4-format-dataset) +3. [Usage of Conversion Tools](#usage-of-conversion-tools) + - [Conversion Tools Overview](#conversion-tools-overview) + - [Setup](#setup) + - [Test](#test) + - [Pre Commit](#pre-commit) + +## Dataset Overview + +The T4 dataset is designed to support autonomous driving research and development. +It can include various types of perception data such as images and lidar point clouds, radar point clouds, along with annotations for tasks like object detection, segmentation, and tracking. + +For detailed information about the T4 dataset format, please refer to the [T4 Dataset Format Documentation](docs/t4_format_3d_detailed.md). + +## Usage of T4 format dataset + +t4-devkit is a development kit for working with the T4 dataset, providing additional utilities and tools. +Please see [t4-devkit](t4-devkit/README.md) about details. + +## Usage of Conversion Tools + +### Conversion Tools Overview See [tools_overview](docs/tools_overview.md) about the converters. -## Setup +### Setup ```bash git clone git@github.com:tier4/tier4_perception_dataset.git perception_dataset @@ -34,9 +59,9 @@ pip3 install poetry poetry install ``` -## Test +### Test -### Download test data +#### Download test data - [GitHub CLI](https://github.com/cli/cli#installation) @@ -47,7 +72,7 @@ unzip 'tests/data/*.zip' -d tests/data/ or manually download zipped data from [the release page](https://github.com/tier4/tier4_perception_dataset/releases/tag/test-data) to a `test/data` directory -### Run tests +#### Run tests ```bash source /opt/ros/${ROS_DISTRO}/setup.sh @@ -55,7 +80,7 @@ source ./install/setup.bash poetry run pytest ``` -## Pre commit +### Pre commit ```bash # to install hooks of formatter and linter files diff --git a/docs/t4_format_3d_detailed.md b/docs/t4_format_3d_detailed.md index 9fc22f93..775d81d7 100644 --- a/docs/t4_format_3d_detailed.md +++ b/docs/t4_format_3d_detailed.md @@ -9,11 +9,13 @@ - (2021.11.30) T4 format ver1.1: Updated format to make it available in ADP - (2022.06.03) T4 format ver1.2: Update topics contained in input_bag. Add status.json. Remove occlusion_state in attribute, write to visibility.json - (2022.07.26) T4 format ver1.2: Add a topic contained in input_bag. +- (2024.07.24) T4 Format ver1.3: Added optional values for the T4 format, which are used in the Co-MLOps dataset format. ## Dataset Sample -You can download one sample dataset manually from [here](https://drive.google.com/file/d/1UjMWZj5Yc55O7BZiGHa0ikZGhwmcfPiS/view). -For this sample, the directory named "sample_dataset" corresponds to the "T4 dataset ID" described in the following section. +You can download one sample T4 format dataset manually from [here](https://drive.google.com/file/d/1UjMWZj5Yc55O7BZiGHa0ikZGhwmcfPiS/view). +For this sample, the directory named "sample_dataset" corresponds to the "T4 dataset ID" described in the following section. +Note: This sample dataset contains only lidar point cloud sensor data and includes annotations. ## Directory Structure @@ -36,6 +38,7 @@ For this sample, the directory named "sample_dataset" corresponds to the "T4 dat - scene.json - sensor.json - visibility.json + - vehicle_state.json (Optional; Necessary for Co-MLOps dataset) - object_ann.json (If 2D annotation exists) - surface_ann.json (If 2D annotation exists) - data/ @@ -303,8 +306,6 @@ its calibration is not done. So, if cameras used in collecting the data have any - "token": [str] -- Unique record identifier. - "sensor_token": [str] -- Foreign key pointing to the sensor type. - "translation": [float] [3] -- Coordinate system origin in meters: (x, y, z). - - "velocity": [Optional[float]] [3] -- Coordinates system origin in m/s: (vx, vy, vz). **(Added)** - - "acceleration": [Optional[float]] [3] -- Coordinates system origin in m/s^2: (ax, ay, az). **(Added)** - "rotation": [float] [4] -- Coordinate system orientation as - quaternion: (w, x, y, z). - "camera_intrinsic": [float] [3, 3] -- Intrinsic camera calibration. Empty list `[]` for sensors other than cameras. - "camera_distortion": [float] [5] -- Distortion parameters (k1, k2, p1, p2, k3) Empty list '[]' for sensors other than cameras. **(Added)** @@ -359,18 +360,9 @@ For t4 format, "name" should be one of the following: - "translation": [float] [3] -- Coordinate system origin in meters: x, y, z. ~~Note that z is always 0~~. **(changed)** - "rotation": [float] [4] -- Coordinate system orientation as - quaternion: w, x, y, z. - "timestamp": [int] -- Unix time stamp (μ sec). - -#### Future extension - -- We plan to extend the twist data - - make when rosbag to Tier4 dataset -- ego_pose - - "token": [str] -- Unique record identifier. - - "translation": [float] [3] -- Coordinate system origin in meters: x, y, z. ~~Note that z is always 0.~~ - - "rotation": [float] [4] -- Coordinate system orientation as - quaternion: w, x, y, z. - - "twist": [float] [6] -- Coordinate system origin in m/s and deg/s : vel_x, vel_y, vel_z, yaw_rate, pitch_rate, roll_rate. - - "accel": [float] [2] -- Coordinate system origin in m/s^2 : long_accel, lat_accel. - - "timestamp": [int] -- Unix time stamp (μ sec). + - "twist": [Optional[float]] [6] -- Coordinates system origin in m/s: (vel_x, vel_y, vel_z, yaw_rate, pitch_rate, roll_rate). **(Added)** + - "acceleration": [Optional[float]] [3] -- Coordinates system origin in m/s^2: (ax, ay, az). **(Added)** + - "geocoordinate": [Optional[float]] [3] -- Coordinates system origin in the WGS 84 reference ellipsoid: (latitude, longitude, altitude). **(Added)** ### instance.json @@ -579,6 +571,33 @@ For T4 annotated dataset, visibility is classified into 4 bins below: - "level": [str] -- Visibility level. - "description": [str] -- Description of visibility level. +### vehicle_state.json + +A description of vehicle status. + +#### Description + +The vehicle_state.json file is an optional component of the T4 dataset format, necessary for the Co-MLOps dataset. +This file provides comprehensive information about the vehicle's state at a given timestamp, including the status of doors, indicators, steering data, and other relevant information. + +#### Items + +- vehicle_state + - "token": [str] -- Unique record identifier. + - "timestamp": [int] -- Unix time stamp (μ sec). + - "accel_pedal": [Optional[float]] -- Accel pedal position [%] + - "brake_pedal": [Optional[float]] -- Brake pedal position [%] + - "steer_pedal": [Optional[float]] -- Steering wheel position [%] + - "steering_tire_angle": [Optional[float]] -- Steering tire angle [rad] + - "steering_wheel_angle": [Optional[float]] -- steering wheel angle [rad] + - "shift_state": [Optional[str]] {PARK, REVERSE, NEUTRAL, HIGH, FORWARD, LOW, NONE} -- Shift state. + - "indicators": [Optional[str]] [3] + - "left": [Optional[str]] -- State of the left indicator ("on" or "off"). + - "right": [Optional[str]] -- State of the right indicator ("on" or "off"). + - "hazard": [Optional[str]] -- State of the hazard lights ("on" or "off"). + - "additional_info": + - "speed": [Optional[float]] -- Speed of the vehicle in km/h. + ### Reference - nuScenes: