### Install Documentation Dependencies

Source: https://github.com/kesai-labs/py123d/blob/main/docs/README.md

Installs the required Python packages for editing and building the documentation. Ensure you are in the project's root directory.

```sh
pip install -e .[docs]
```

--------------------------------

### Install py123d with nuScenes Extras (PyPI)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuscenes.md

Install the py123d library with the optional dependencies for nuScenes using pip.

```bash
pip install py123d[nuscenes]
```

--------------------------------

### Install py123d with AV2 support from Source

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/av2.md

Install py123d from source with AV2 support. This method is useful for development or when working directly with the library's source code.

```bash
pip install -e .[av2]
```

--------------------------------

### Install py123d with nuPlan Support (PyPI)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Installs the py123d library with nuPlan extras and the nuplan-devkit from PyPI. Ensure you use the correct nuplan-devkit version.

```bash
pip install py123d[nuplan]
pip install "nuplan-devkit @ git+https://github.com/motional/nuplan-devkit/@nuplan-devkit-v1.2"
```

--------------------------------

### Install py123d with nuPlan Support (Source)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Installs the py123d library from source with nuPlan extras and the nuplan-devkit. This method is useful for development or when using the latest unreleased versions.

```bash
pip install -e .[nuplan]
pip install "nuplan-devkit @ git+https://github.com/motional/nuplan-devkit/@nuplan-devkit-v1.2"
```

--------------------------------

### Run Documentation Server

Source: https://github.com/kesai-labs/py123d/blob/main/docs/README.md

Starts the documentation server using sphinx-autobuild. This command watches for changes in the 'docs' directory and rebuilds the HTML output in '_build/html'.

```sh
sphinx-autobuild docs docs/_build/html
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/kesai-labs/py123d/blob/main/docs/contributing.md

Set up a development environment using conda and install project dependencies, including development tools and pre-commit hooks.

```sh
conda create -n py123d_dev python=3.12  # Optional
conda activate py123d_dev
pip install -e .[dev]
pre-commit install
```

--------------------------------

### Install py123d with nuScenes Extras (Source)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuscenes.md

Install py123d in editable mode with optional dependencies for nuScenes from source.

```bash
pip install -e .[nuscenes]
```

--------------------------------

### Install Optional Dataset Dependencies

Source: https://github.com/kesai-labs/py123d/blob/main/docs/contributing.md

Install optional dependencies for specific datasets like nuplan or nuscenes by combining them in the pip install command.

```sh
pip install -e .[dev,nuplan,nuscenes]
```

--------------------------------

### Pandaset Directory Structure Example

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/pandaset.md

This example shows the expected directory structure for the Pandaset dataset root directory, including annotations, camera data, lidar data, and metadata. Ensure your downloaded dataset follows this structure for compatibility with 123D conversion.

```text
$PANDASET_DATA_ROOT/
├── 001/
│   ├── annotations/
│   │   ├── cuboids/
│   │   │   ├── 00.pkl.gz
│   │   │   ├── ...
│   │   │   └── 79.pkl.gz
│   │   └── semseg/  (currently not used)
│   │       ├── 00.pkl.gz
│   │       ├── ...
│   │       ├── 79.pkl.gz
│   │       └── classes.json
│   ├── camera/
│   │   ├── back_camera/
│   │   │   ├── 00.jpg
│   │   │   ├── ...
│   │   │   ├── 79.jpg
│   │   │   ├── intrinsics.json
│   │   │   ├── poses.json
│   │   │   └── timestamps.json
│   │   ├── front_camera/
│   │   │   └── ...
│   │   ├── front_left_camera/
│   │   │   └── ...
│   │   ├── front_right_camera/
│   │   │   └── ...
│   │   ├── left_camera/
│   │   │   └── ...
│   │   └── right_camera/
│   │       └── ...
│   ├── LICENSE.txt
│   ├── lidar/
│   │   ├── 00.pkl.gz
│   │   ├── ...
│   │   ├── 79.pkl.gz
│   │   ├── poses.json
│   │   └── timestamps.json
│   └── meta/
│       ├── gps.json
│       └── timestamps.json
├── ...
└── 158/
    └── ...

```

--------------------------------

### Install py123d with NCore support

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/ncore.md

Install the py123d library with the 'ncore' extra to include the NCore reader and Hugging Face downloader. This is a prerequisite for downloading and converting the dataset.

```bash
pip install py123d[ncore]
```

--------------------------------

### Install py123d

Source: https://github.com/kesai-labs/py123d/blob/main/README.md

Install the py123d library using pip. Optional extras for specific datasets can be included.

```bash
pip install py123d
```

--------------------------------

### Install py123d with Waymo Optional Dependencies

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/wod_motion.md

Install py123d including the optional dependencies required for Waymo Open Dataset. This is necessary for dataset conversion and reading TFRecord files.

```bash
pip install py123d[waymo]
```

--------------------------------

### Install py123d with PandaSet extras

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/pandaset.md

Install the py123d library with the necessary dependencies for PandaSet support. This includes the 'pandaset' extras group.

```bash
pip install py123d[pandaset]
```

--------------------------------

### Install py123d from Source with Waymo Optional Dependencies

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/wod_motion.md

Install py123d from source, including the optional Waymo dependencies. This method is useful for development or when working directly with the py123d source code.

```bash
pip install -e .[waymo]
```

--------------------------------

### Install py123d with Argoverse 2 Extra

Source: https://github.com/kesai-labs/py123d/blob/main/README.md

Install py123d with the specific extra for Argoverse 2 dataset support. This is a prerequisite for downloading and converting Argoverse 2 data.

```bash
pip install py123d[av2]
```

--------------------------------

### Compile Waymo Open Dataset Protobufs

Source: https://github.com/kesai-labs/py123d/blob/main/src/py123d/parser/wod/waymo_open_dataset/PROTO_README.md

Use this command to recompile the generated _pb2.py files after editing a .proto file. Ensure you have grpcio-tools installed and are in the correct directory.

```bash
# Prerequisites
pip install grpcio-tools

# Compile
cd src/py123d/conversion/datasets/wod/waymo_open_dataset/protos/
bash compile_protos.sh
```

--------------------------------

### Combine Multiple Scene Filter Options

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/05_scene_filter_tutorial.ipynb

A realistic example combining various filter options for selecting validation scenes with specific modalities, temporal sampling, and post-processing. Requires SceneFilter and get_filtered_scenes.

```python
scene_filter = SceneFilter(
    # Log selection
    split_types=["val"],
    # Metadata requirements
    has_map=True,
    required_scene_modalities=["ego_state_se3", "camera:any"],
    # Temporal sampling
    target_iteration_duration_s=0.5,  # 2 Hz
    future_duration_s=1.0,  # 1-second scenes
    history_duration_s=0.5,  # 1/2-second history
    timestamp_threshold_s=2.0,  # non-overlapping
    # Post-processing
    max_num_scenes=10,
    shuffle=True,
)
scenes = get_filtered_scenes(scene_filter)

print(f"Total scenes: {len(scenes)}\n")
for i, scene in enumerate(scenes):
    meta = scene.scene_metadata
    print(
        f"Scene {i}: split={scene.split}, "
        f"future={meta.num_future_iterations} iters ({meta.future_duration_s:.1f}s), "
        f"history={meta.num_history_iterations} iters ({meta.history_duration_s:.1f}s), "
        f"dt={meta.iteration_duration_s:.2f}s"
    )
```

--------------------------------

### Editable Pip Install for py123d

Source: https://github.com/kesai-labs/py123d/blob/main/docs/installation.md

Install py123d as an editable package from a cloned repository. This is useful for development.

```bash
mkdir -p $HOME/py123d_workspace; cd $HOME/py123d_workspace # Optional
git clone git@github.com:kesai-labs/py123d.git
cd py123d
pip install -e .
```

--------------------------------

### Preview NuPlan Download (Dry Run)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Use this command to preview the NuPlan dataset download without actually fetching any files. This is useful for checking configurations and understanding what would be downloaded.

```bash
py123d-download dataset=nuplan dataset.downloader.dry_run=true
```

--------------------------------

### Preview download plan without downloading

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/av2.md

Use this command to see what would be downloaded without actually transferring any data. This is useful for planning or verifying download configurations.

```bash
py123d-download dataset=av2-sensor \
    dataset.downloader.num_logs=3 \
    dataset.downloader.dry_run=true
```

--------------------------------

### Launching Viser Viewer for 3D Scene Visualization

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/03_visualizations_tutorial.ipynb

Initializes and displays the Viser viewer for a given set of scenes. This provides an interactive 3D visualization of the scene data.

```python
from py123d.visualization.viser.viser_viewer import ViserViewer

ViserViewer(scenes)
```

--------------------------------

### Download First Training Shard of WOD Motion

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/wod_motion.md

Use this command to download the initial training shard of the Waymo Open Motion Dataset. Ensure the WOD_MOTION_DATA_ROOT environment variable is set.

```bash
py123d-download dataset=wod-motion \
    'dataset.downloader.splits=[wod-motion_train]' \
    dataset.downloader.num_shards=1
```

--------------------------------

### Preview WOD-Motion Shards for Download

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/wod_motion.md

Preview which shards would be downloaded for the Waymo Open Dataset - Motion without actually downloading them. This command is useful for planning downloads or verifying configurations.

```bash
py123d-download dataset=wod-motion \
    'dataset.downloader.splits=[wod-motion_train]' \
    dataset.downloader.num_shards=3 \
    dataset.downloader.dry_run=true
```

--------------------------------

### Scene Filtering with Default and Windowed Durations

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/05_scene_filter_tutorial.ipynb

Demonstrates scene generation with no duration set (full log) versus using future and history durations to create sliding windows. Useful for analyzing data over specific time intervals.

```python
# No duration: one scene per log (entire recording)
scenes_full = get_filtered_scenes(SceneFilter())
print(f"No duration set:          {len(scenes_full)} scene(s)")
if len(scenes_full) > 0:
    meta = scenes_full[0].scene_metadata
    print(f"  Duration: {meta.future_duration_s:.1f}s, Iterations: {meta.num_future_iterations}")

# 2-second windows with 1-second history
scenes_windowed = get_filtered_scenes(SceneFilter(future_duration_s=2.0, history_duration_s=1.0))
print(f"\n2s future + 1s history:   {len(scenes_windowed)} scene(s)")
if len(scenes_windowed) > 0:
    meta = scenes_windowed[0].scene_metadata
    print(f"  Future duration: {meta.future_duration_s:.1f}s, Future iterations: {meta.num_future_iterations}")
    print(f"  History duration: {meta.history_duration_s:.1f}s, History iterations: {meta.num_history_iterations}")
```

--------------------------------

### Create and Inspect a 2D Bounding Box

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/04_geometry_tutorial.ipynb

Demonstrates creating a 2D bounding box with a specified center pose (including rotation) and dimensions. Shows how to access its properties and corners.

```python
center = PoseSE2(x=5.0, y=3.0, yaw=np.pi / 6)  # 30-degree rotation
bbox_2d = BoundingBoxSE2(center_se2=center, length=4.0, width=2.0)

print("BoundingBoxSE2:\t", bbox_2d)
print("Center:\t\t", bbox_2d.center_se2)
print("Length:\t\t", bbox_2d.length)
print("Width:\t\t", bbox_2d.width)
print("Area:\t\t", bbox_2d.shapely_polygon.area)

# Get corners
corners = bbox_2d.corners_array
print("\nCorners (4x2):")
print(corners.round(4))

# Named corner access
corners_dict = bbox_2d.corners_dict
for name, corner in corners_dict.items():
    print(f"  {name.name}:\t{corner}")
```

--------------------------------

### Helper Function to Plot Polyline

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/02_map_tutorial.ipynb

Plots a given polyline. Can optionally mark the start and end points.

```python
def add_polyline(ax: plt.Axes, polyline: Polyline2D, add_start_end: bool = False, **plot_kwargs) -> None:
    """Helper to plot a polyline."""
    polyline_array = polyline.array
    ax.plot(polyline_array[:, 0], polyline_array[:, 1], **plot_kwargs)
    if add_start_end:
        ax.plot(polyline.array[0, 0], polyline.array[0, 1], "o", label="Start", color="black")
        ax.plot(polyline.array[-1, 0], polyline.array[-1, 1], "x", label="End", color="black")
```

--------------------------------

### Download NuPlan with Camera and Lidar Shards

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

This command downloads the nuPlan dataset and additionally includes the 8-camera shards and merged-point-cloud shards, which can significantly increase the download size (hundreds of GB per split).

```bash
py123d-download dataset=nuplan \
    dataset.downloader.include_cameras=true \
    dataset.downloader.include_lidar=true
```

--------------------------------

### Get Timestamp at Iteration

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/01_scene_tutorial.ipynb

Retrieves the Timestamp object for a given iteration index. Requires the Timestamp datatype.

```python
from py123d.datatypes.time import Timestamp

iteration = 0
timestamp: Timestamp = scene.get_timestamp_at_iteration(iteration=iteration)
print(f"Time at iteration {iteration}:", timestamp)
```

--------------------------------

### Get MapAPI and MapMetadata from a scene

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/02_map_tutorial.ipynb

Selects a random scene and retrieves its MapAPI and MapMetadata. Asserts that the MapAPI is available.

```python
scene: SceneAPI = np.random.choice(scenes)  # type: ignore
map_api: Optional[MapAPI] = scene.get_map_api()
assert map_api is not None, "Map API is required for this tutorial, but not available for the selected scene."

map_metadata = scene.get_map_metadata()
map_metadata
```

--------------------------------

### Create and Use PoseSE3

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/04_geometry_tutorial.ipynb

Shows how to create a 3D pose, extract its components (point, quaternion, Euler angles), and construct poses from rotation and translation. Requires py123d.geometry.PoseSE3, EulerAngles, Point3D, and numpy.

```python
from py123d.geometry import PoseSE3, EulerAngles, Point3D
import numpy as np

# Create a 3D pose with identity rotation
pose_3d = PoseSE3(x=10.0, y=20.0, z=1.0, qw=1.0, qx=0.0, qy=0.0, qz=0.0)
print("PoseSE3:\t", pose_3d)
print("Point3D:\t", pose_3d.point_3d)
print("Point2D:\t", pose_3d.point_2d)
print("Quaternion:\t", pose_3d.quaternion)
print("Euler angles:\t", pose_3d.euler_angles)

# Create from rotation + translation
euler = EulerAngles(roll=0.0, pitch=0.0, yaw=np.pi / 2)
translation = Point3D(5.0, 10.0, 0.0)
pose_from_R_t = PoseSE3.from_R_t(rotation=euler, translation=translation)
print("\nFrom R, t:\t", pose_from_R_t)
print("Yaw (deg):\t", np.degrees(pose_from_R_t.yaw))

# SE3 -> SE2 projection
print("\nSE3 -> SE2:\t", pose_from_R_t.pose_se2)
```

--------------------------------

### Set NUSCENES_DATA_ROOT Environment Variable

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuscenes.md

Set the NUSCENES_DATA_ROOT environment variable in your ~/.bashrc file to point to your nuScenes data installation path.

```bash
export NUSCENES_DATA_ROOT=/path/to/nuplan/data/root
```

--------------------------------

### Download NuPlan Sensor Data (Bash)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Manually download sensor data archives (camera and lidar) for different splits of the NuPlan dataset using wget. These are large downloads and should be opted into explicitly.

```bash
# 1. nuplan_train
for split in {0..42}; do
    wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/sensor_blobs/train_set/nuplan-v1.1_train_camera_${split}.zip
    wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/sensor_blobs/train_set/nuplan-v1.1_train_lidar_${split}.zip
done

# 2. nuplan_val
for split in {0..11}; do
    wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/sensor_blobs/val_set/nuplan-v1.1_val_camera_${split}.zip
    wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/sensor_blobs/val_set/nuplan-v1.1_val_lidar_${split}.zip
done

# 3. nuplan_test
for split in {0..11}; do
    wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/sensor_blobs/test_set/nuplan-v1.1_test_camera_${split}.zip
    wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/sensor_blobs/test_set/nuplan-v1.1_test_lidar_${split}.zip
done
```

--------------------------------

### Download NuPlan License (Bash)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Manually download the LICENSE file for the NuPlan dataset using wget. Always check the LICENSE file before downloading the dataset.

```bash
# NOTE: Please check the LICENSE file when downloading the nuPlan dataset
wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/LICENSE
```

--------------------------------

### Check Optional Package Dependencies

Source: https://github.com/kesai-labs/py123d/blob/main/docs/contributing.md

Use the check_dependencies function to verify if required optional packages are installed for a specific dataset. This function raises an error if dependencies are missing.

```python
from py123d.common.utils.dependencies import check_dependencies

check_dependencies(["optional_package_a", "optional_package_b"], "optional_dataset")
import optional_package_a
import optional_package_b

def load_camera_from_outdated_dataset(...) -> ...:
    optional_package_a.module(...)
    optional_package_b.module(...)
    pass
```

--------------------------------

### Download NuPlan Logs (Bash)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Manually download log files (.db files) for various NuPlan splits using wget. Logs are always fetched for requested splits.

```bash
# 1. nuplan_train, nuplan_val (both derived from splits/trainval/)
wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/nuplan-v1.1_train_boston.zip
wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/nuplan-v1.1_train_pittsburgh.zip
wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/nuplan-v1.1_train_singapore.zip
for split in {1..6};
    wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/nuplan-v1.1_train_vegas_${split}.zip
done

# 2. nuplan_test (→ splits/test/)
wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/nuplan-v1.1_test.zip

# 3. nuplan-mini_train, nuplan-mini_val, nuplan-mini_test (→ splits/mini/)
wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/nuplan-v1.1_mini.zip
```

--------------------------------

### Create and Use PoseSE2

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/04_geometry_tutorial.ipynb

Demonstrates creating a 2D pose (x, y, yaw), accessing its components, and converting it to rotation and transformation matrices. Requires py123d.geometry.PoseSE2 and numpy.

```python
from py123d.geometry import PoseSE2
import numpy as np

# Create a 2D pose
pose_2d = PoseSE2(x=5.0, y=3.0, yaw=np.pi / 4)  # 45-degree rotation
print("PoseSE2:\t", pose_2d)
print("Point:\t\t", pose_2d.point_2d)
print("Yaw (deg):\t", np.degrees(pose_2d.yaw))

# 2x2 rotation matrix
print("\nRotation matrix:")
print(pose_2d.rotation_matrix.round(4))

# 3x3 transformation matrix
print("\nTransformation matrix:")
print(pose_2d.transformation_matrix.round(4))

# Identity pose
print("\nIdentity:\t", PoseSE2.identity())
```

--------------------------------

### Stream PandaSet data (first run)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/pandaset.md

Initiate streaming conversion for PandaSet data. On the first run, this command downloads the ~44.5 GB pandaset.zip file into the system temporary directory and then streams 3 logs.

```bash
py123d-conversion dataset=pandaset-stream \
    dataset.parser.downloader.num_logs=3
```

--------------------------------

### Create and Inspect a 3D Bounding Box

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/04_geometry_tutorial.ipynb

Shows how to create a 3D bounding box using a SE3 pose and dimensions. It details accessing its properties, corners, and its SE2 projection.

```python
# Create a 3D bounding box
center_3d = PoseSE3(x=10.0, y=5.0, z=1.0, qw=1.0, qx=0.0, qy=0.0, qz=0.0)
bbox_3d = BoundingBoxSE3(center_se3=center_3d, length=4.5, width=2.0, height=1.8)

print("BoundingBoxSE3:\t", bbox_3d)
print("Length:\t\t", bbox_3d.length)
print("Width:\t\t", bbox_3d.width)
print("Height:\t\t", bbox_3d.height)

# 8 corners of the 3D box
corners_3d = bbox_3d.corners_array
print("\nCorners (8x3):")
print(corners_3d.round(4))

# Named corner access
corners_3d_dict = bbox_3d.corners_dict
for name, corner in corners_3d_dict.items():
    print(f"  {name.name}:\t{corner}")

# SE3 -> SE2 projection
print("\nSE2 projection:\t", bbox_3d.bounding_box_se2)
```

--------------------------------

### Create and Use Euler Angles

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/04_geometry_tutorial.ipynb

Demonstrates creating Euler angles, accessing their components, and converting them to rotation matrices and quaternions. Ensure numpy is imported as np.

```python
from py123d.geometry import EulerAngles
import numpy as np

# Create Euler angles: 90-degree yaw rotation (turn left)
euler = EulerAngles(roll=0.0, pitch=0.0, yaw=np.pi / 2)
print("EulerAngles:\t", euler)
print("roll:\t\t", euler.roll)
print("pitch:\t\t", euler.pitch)
print("yaw:\t\t", euler.yaw)

# Convert to rotation matrix
print("\nRotation matrix:")
print(euler.rotation_matrix.round(4))

# Convert to quaternion
print("\nQuaternion:\t", euler.quaternion)
```

--------------------------------

### Download NuPlan Maps (Bash)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Manually download the nuplan-maps-v1.1.zip archive using wget. This is required for using the 'nuplan' and 'nuplan-mini' datasets and for HD-map conversion.

```bash
wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/nuplan-maps-v1.1.zip
```

--------------------------------

### Download nuPlan Mini Dataset

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Downloads the nuplan_mini_train, nuplan_mini_val, and nuplan_mini_test datasets using wget. This command iterates through splits 0 to 8 to download camera and lidar sensor blobs.

```bash
for split in {0..8}; do
    wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/sensor_blobs/mini_set/nuplan-v1.1_mini_camera_${split}.zip
    wget https://motional-nuplan.s3-ap-northeast-1.amazonaws.com/public/nuplan-v1.1/sensor_blobs/mini_set/nuplan-v1.1_mini_lidar_${split}.zip
done
```

--------------------------------

### Download NuPlan Mini Dataset

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Use this command to download the mini set of nuPlan logs and maps, which is smaller (~11 GB) and suitable for quicker testing or development. Specify the desired splits for the mini dataset.

```bash
py123d-download dataset=nuplan \
    'dataset.downloader.splits=[nuplan-mini_train, nuplan-mini_val, nuplan-mini_test]'
```

--------------------------------

### Convert WOD-Motion Dataset (Streaming Mode - First Shard)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/wod_motion.md

Convert the Waymo Open Dataset - Motion using streaming mode, fetching only the first shard for each default split. Data is downloaded to a temporary directory.

```bash
py123d-conversion dataset=wod-motion-stream \
    dataset.parser.downloader.num_shards=1
```

--------------------------------

### Download NuPlan Regular Dataset

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Use this command to download the regular set of nuPlan logs and maps for training, validation, and testing. This includes approximately 135 GB of data.

```bash
py123d-download dataset=nuplan
```

--------------------------------

### Create and Interpolate PolylineSE2

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/04_geometry_tutorial.ipynb

Creates a PolylineSE2 from SE2 states (x, y, yaw) and demonstrates interpolation, which returns a PoseSE2 object including heading. Requires numpy.

```python
# Create from SE2 array (x, y, yaw)
# Create a smooth, curvy path using a sine wave
num_points = 30
x = np.linspace(0, 4 * np.pi, num_points)
y = 2 * np.sin(x / 2)

# Calculate yaw as the angle of the path's tangent
yaw = np.arctan2(np.gradient(y), np.gradient(x))

# Create the SE2 states array (x, y, yaw)
se2_states = np.stack([x, y, yaw], axis=-1)

polyline_se2 = PolylineSE2.from_array(se2_states)

# or from 2d points:
polyline_se2 = PolylineSE2.from_array(se2_states[..., PoseSE3Index.XY])


print("Length:\t\t", round(polyline_se2.length, 4))

# Interpolation returns PoseSE2 (with heading)
interp_pose = polyline_se2.interpolate(polyline_se2.length / 2)
print("Midpoint pose:\t", interp_pose)
print("Midpoint yaw:\t", round(np.degrees(interp_pose.yaw), 2), "degrees")
```

--------------------------------

### Convert WOD-Motion Dataset (Local Mode)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/wod_motion.md

Convert the Waymo Open Dataset - Motion when the data is already downloaded and accessible via the WOD_MOTION_DATA_ROOT environment variable. This is the local conversion mode.

```bash
py123d-conversion dataset=wod-motion
```

--------------------------------

### Create and Inspect Point2D and Point3D

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/04_geometry_tutorial.ipynb

Demonstrates the creation of Point2D and Point3D objects directly or from NumPy arrays, and shows how to access their coordinates and underlying array representation.

```python
# Create points directly
p2d = Point2D(1.0, 2.0)
print("Point2D:\t", p2d)
print("x, y:\t\t", p2d.x, p2d.y)
print("Array:\t\t", p2d.array)

p3d = Point3D(1.0, 2.0, 3.0)
print("\nPoint3D:\t", p3d)
print("x, y, z:\t", p3d.x, p3d.y, p3d.z)

# Create from arrays
p2d_from_array = Point2D.from_array(np.array([5.0, 6.0]))
print("\nFrom array:\t", p2d_from_array)

# 3D to 2D projection
print("3D -> 2D:\t", p3d.point_2d)
```

--------------------------------

### Download NuScenes Dataset (Full)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuscenes.md

Downloads the entire NuScenes dataset, including all archives. Requires NUSCENES_EMAIL and NUSCENES_PASSWORD environment variables to be set.

```bash
export NUSCENES_EMAIL=...
export NUSCENES_PASSWORD=...

# Full dataset (~700 GB): every archive in the catalog
py123d-download dataset=nuscenes downloader.preset=full
```

--------------------------------

### Convert Waymo Perception Dataset (Local Mode)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/wod_perception.md

Initiate the conversion process for the Waymo Open Dataset for Perception when the data is already downloaded and accessible locally. This command assumes the dataset root is correctly configured.

```bash
py123d-conversion dataset=wod-perception
```

--------------------------------

### Download NuScenes Dataset (Custom Archives)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuscenes.md

Downloads a custom selection of NuScenes dataset archives. Requires NUSCENES_EMAIL and NUSCENES_PASSWORD environment variables to be set.

```bash
export NUSCENES_EMAIL=...
export NUSCENES_PASSWORD=...

# Or a custom archive list:
py123d-download dataset=nuscenes \
    'downloader.archives=[v1.0-trainval_meta.tgz, v1.0-trainval03_blobs.tgz, nuScenes-map-expansion-v1.3.zip, can_bus.zip]'
```

--------------------------------

### Download NuScenes Dataset (Smallest Useful)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuscenes.md

Downloads the smallest useful trainval slice of the NuScenes dataset, including trainval metadata, the first blob, maps, and CAN bus data. Requires NUSCENES_EMAIL and NUSCENES_PASSWORD environment variables to be set.

```bash
export NUSCENES_EMAIL=...
export NUSCENES_PASSWORD=...

# Smallest useful trainval slice (~75 GB): trainval metadata + first blob + maps + CAN bus
py123d-download dataset=nuscenes downloader.preset=trainval_one
```

--------------------------------

### Convert WOD-Motion Dataset (Streaming Mode - Persist Downloads)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/wod_motion.md

Convert the Waymo Open Dataset - Motion using streaming mode, persisting downloaded shards to a specified output directory instead of a temporary location. This allows for reuse of downloaded data.

```bash
py123d-conversion dataset=wod-motion-stream \
    dataset.parser.downloader.num_shards=1 \
    dataset.parser.downloader.output_dir=/mnt/scratch/wod_motion_cache
```

--------------------------------

### Convert nuScenes Dataset (Local Mode)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuscenes.md

Initiate the conversion process for the nuScenes dataset when data is already extracted to NUSCENES_DATA_ROOT.

```bash
py123d-conversion datasets=["nuscenes"]
```

```bash
py123d-conversion datasets=["nuscenes-mini"]
```

--------------------------------

### Create and Use Quaternions

Source: https://github.com/kesai-labs/py123d/blob/main/tutorials/04_geometry_tutorial.ipynb

Shows how to create identity quaternions, convert rotation matrices to quaternions, and extract Euler angles from quaternions. Requires numpy and py123d.geometry.Quaternion.

```python
from py123d.geometry import Quaternion
import numpy as np

# Identity quaternion (no rotation)
q_identity = Quaternion(qw=1.0, qx=0.0, qy=0.0, qz=0.0)
print("Identity quaternion:\t", q_identity)
print("Rotation matrix:")
print(q_identity.rotation_matrix)

# Create from rotation matrix
R_90 = np.array([[0, -1, 0], [1, 0, 0], [0, 0, 1]], dtype=np.float64)  # 90-degree yaw
q_from_R = Quaternion.from_rotation_matrix(R_90)
print("\nFrom rotation matrix:", q_from_R)
print("Euler angles:\t\t", q_from_R.euler_angles)
```

--------------------------------

### Download NuScenes Dataset (Minimal)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuscenes.md

Downloads the minimal smoketest version of the NuScenes dataset, including mini split, HD maps, and CAN bus data. Requires NUSCENES_EMAIL and NUSCENES_PASSWORD environment variables to be set.

```bash
export NUSCENES_EMAIL=...
export NUSCENES_PASSWORD=...

# Minimal smoketest (~600 MB): mini split + HD maps + CAN bus
py123d-download dataset=nuscenes downloader.preset=mini
```

--------------------------------

### Set Streaming Download Credentials

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuscenes.md

Set the NUSCENES_EMAIL and NUSCENES_PASSWORD environment variables for streaming downloads.

```bash
export NUSCENES_EMAIL=...
```

```bash
export NUSCENES_PASSWORD=...
```

--------------------------------

### Convert nuPlan Dataset with Sensor Data (Streaming Mode)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Enables the inclusion of camera and lidar sensor data during streaming conversion. Be aware that this significantly increases download size.

```bash
py123d-conversion dataset=nuplan-mini-stream \
    dataset.parser.downloader.include_cameras=true \
    dataset.parser.downloader.include_lidar=true
```

--------------------------------

### Convert nuPlan Dataset (Local Mode)

Source: https://github.com/kesai-labs/py123d/blob/main/docs/datasets/nuplan.md

Initiates the nuPlan dataset conversion using py123d-conversion in local mode. Assumes data is already extracted under the configured NUPLAN_DATA_ROOT.

```bash
py123d-conversion datasets=["nuplan"]
# or
py123d-conversion datasets=["nuplan-mini"]
```

--------------------------------

### Launch Viser Viewer for Converted Scenes

Source: https://github.com/kesai-labs/py123d/blob/main/README.md

Launch the Viser interactive 3D viewer for the converted Argoverse 2 scenes. This command filters scenes to display, allowing for interactive exploration of the dataset.

```bash
py123d-viser scene_filter=av2-sensor
```