# harunaacar/cvat-nuscenes-roundtrip architecture

> Architecture diagram of the GitHub repository harunaacar/cvat-nuscenes-roundtrip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harunaacar/cvat-nuscenes-roundtrip
- Repository: https://github.com/harunaacar/cvat-nuscenes-roundtrip

## Overview

This is a two-script nuScenes↔CVAT 3D annotation converter. The forward script prepares sensor media, Datumaro annotations, labels, and mapping metadata for CVAT; after editing and exporting in CVAT, the round-trip script uses that export, mapping, and original dataset to rebuild nuScenes annotations and instances while preserving other dataset content. CVAT editing is an external human/tool stage. The excerpts show the major conversion responsibilities, but not every helper or exact call sequence, so edges are limited to documented or visible relationships.

Main entry points: [`scripts/cvat_to_nuscenes_roundtrip_v2 .py`](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py) (Round-trip converter), [`scripts/nuscenes_to_cvat_v5.py`](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/nuscenes_to_cvat_v5.py) (Forward converter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_forward["nuScenes to CVAT"]
  node_forward_converter["Forward converter"]
  node_sensor_media["Sensor media"]
  node_datumaro_annotations["Datumaro annotations"]
  node_mapping_labels["Mapping and labels"]
end

subgraph group_roundtrip["CVAT to nuScenes"]
  node_roundtrip_converter["Round-trip converter"]
  node_coordinate_transform["Coordinate transform"]
  node_annotation_instance_rebuild["Annotation and instance rebuild"]
  node_dataset_output[("Updated nuScenes dataset")]
  node_roundtrip_report["Round-trip report"]
end

node_nuscenes[("nuScenes dataset")]
node_cvat(("CVAT task and edits"))
node_cvat_export["Datumaro export"]

node_nuscenes -->|"reads dataset"| node_forward_converter
node_forward_converter -->|"writes media"| node_sensor_media
node_forward_converter -->|"writes annotations"| node_datumaro_annotations
node_forward_converter -->|"writes metadata"| node_mapping_labels
node_sensor_media -->|"upload media"| node_cvat
node_datumaro_annotations -->|"import annotations"| node_cvat
node_cvat -->|"exports edits"| node_cvat_export
node_cvat_export -->|"provides export"| node_roundtrip_converter
node_mapping_labels -->|"provides mapping"| node_roundtrip_converter
node_nuscenes -->|"provides source data"| node_roundtrip_converter
node_roundtrip_converter -->|"converts cuboids"| node_coordinate_transform
node_roundtrip_converter -->|"rebuilds records"| node_annotation_instance_rebuild
node_roundtrip_converter -->|"writes dataset"| node_dataset_output
node_roundtrip_converter -->|"writes report"| node_roundtrip_report
node_dataset_output -->|"re-import for verification"| node_forward_converter

click node_forward_converter "https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/nuscenes_to_cvat_v5.py"
click node_sensor_media "https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/nuscenes_to_cvat_v5.py"
click node_datumaro_annotations "https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/nuscenes_to_cvat_v5.py"
click node_mapping_labels "https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/nuscenes_to_cvat_v5.py"
click node_roundtrip_converter "https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py"
click node_coordinate_transform "https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py"
click node_annotation_instance_rebuild "https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py"
click node_dataset_output "https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py"
click node_roundtrip_report "https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_forward_converter,node_sensor_media,node_datumaro_annotations,node_mapping_labels toneBlue
class node_roundtrip_converter,node_coordinate_transform,node_annotation_instance_rebuild,node_dataset_output,node_roundtrip_report,node_nuscenes toneAmber
class node_cvat toneRose
class node_cvat_export toneIndigo
```

## Components

### nuScenes to CVAT

- [Forward converter](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/nuscenes_to_cvat_v5.py): `scripts/nuscenes_to_cvat_v5.py`
- [Sensor media](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/nuscenes_to_cvat_v5.py): `scripts/nuscenes_to_cvat_v5.py`
- [Datumaro annotations](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/nuscenes_to_cvat_v5.py): `scripts/nuscenes_to_cvat_v5.py`
- [Mapping and labels](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/nuscenes_to_cvat_v5.py): `scripts/nuscenes_to_cvat_v5.py`

### CVAT to nuScenes

- [Round-trip converter](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py): `scripts/cvat_to_nuscenes_roundtrip_v2 .py`
- [Coordinate transform](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py): `scripts/cvat_to_nuscenes_roundtrip_v2 .py`
- [Annotation and instance rebuild](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py): `scripts/cvat_to_nuscenes_roundtrip_v2 .py`
- [Updated nuScenes dataset](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py): `scripts/cvat_to_nuscenes_roundtrip_v2 .py`
- [Round-trip report](https://github.com/harunaacar/cvat-nuscenes-roundtrip/blob/master/scripts/cvat_to_nuscenes_roundtrip_v2%20.py): `scripts/cvat_to_nuscenes_roundtrip_v2 .py`

### Other components

- **nuScenes dataset**
- **CVAT task and edits**
- **Datumaro export**

## Connections

- nuScenes dataset → Forward converter: reads dataset (evidence: `scripts/nuscenes_to_cvat_v5.py`)
- Forward converter → Sensor media: writes media (evidence: `scripts/nuscenes_to_cvat_v5.py`)
- Forward converter → Datumaro annotations: writes annotations (evidence: `scripts/nuscenes_to_cvat_v5.py`)
- Forward converter → Mapping and labels: writes metadata (evidence: `scripts/nuscenes_to_cvat_v5.py`)
- Sensor media → CVAT task and edits: upload media (evidence: `README.md`)
- Datumaro annotations → CVAT task and edits: import annotations (evidence: `README.md`)
- CVAT task and edits → Datumaro export: exports edits (evidence: `README.md`)
- Datumaro export → Round-trip converter: provides export (evidence: `README.md`)
- Mapping and labels → Round-trip converter: provides mapping (evidence: `README.md`)
- nuScenes dataset → Round-trip converter: provides source data (evidence: `README.md`)
- Round-trip converter → Coordinate transform: converts cuboids (evidence: `scripts/cvat_to_nuscenes_roundtrip_v2 .py`)
- Round-trip converter → Annotation and instance rebuild: rebuilds records (evidence: `scripts/cvat_to_nuscenes_roundtrip_v2 .py`)
- Round-trip converter → Updated nuScenes dataset: writes dataset (evidence: `scripts/cvat_to_nuscenes_roundtrip_v2 .py`)
- Round-trip converter → Round-trip report: writes report (evidence: `README.md`)
- Updated nuScenes dataset → Forward converter: re-import for verification (evidence: `README.md`)
