# vicomtech/dmd-driver-monitoring-dataset architecture
> Architecture diagram of the GitHub repository vicomtech/dmd-driver-monitoring-dataset, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/vicomtech/dmd-driver-monitoring-dataset
- Repository: https://github.com/vicomtech/dmd-driver-monitoring-dataset
## Overview
1. **What this repo is**
- This repository is not a model-training codebase; it is the **tooling layer around the Driver Monitoring Dataset (DMD)**.
- It contains two standalone Python utilities: one for **creating/editing temporal annotations** and one for **exploring annotated material and exporting subsets**.
2. **Primary data boundary**
- The central artifact is **video plus annotation metadata** in the **VCD/OpenLABEL ecosystem**.
- Per the README, the current usable corpus is **RGB real-car footage only**; older simulator, IR, and depth streams are deprecated.
- The tools therefore operate on local dataset folders containing video files and matching annotation files, not on a remote service.
3. **Annotation tool subsystem: `annotation-tool/`**
- `TaTo.py` is the main entry point for the **Temporal Annotation Tool**.
- This tool is responsible for **authoring and updating temporal labels** such as distraction, drowsiness, gaze, hands, and static states.
- It is configured by scenario-specific JSON files:
- `config_distraction.json`
- `config_drowsiness.json`
- `config_gaze.json`
- `config_hands.json`
- `config_statics.json`
- Those configs define the annotation vocabulary and behavior for each labeling task, making the tool **schema-driven** rather than hardcoded.
4. **Annotation tool support files**
- `vcd4parser.py` is the annotation-format adapter for reading/writing the dataset’s **VCD 4+/OpenLABEL-style structure**.
- `setUp.py` is the environment/bootstrap script used to prepare the tool’s runtime dependencies and local setup.
- The annotation tool is therefore a **desktop/local workflow**: load video + existing annotation file, edit labels, then persist back to the VCD-based format.
5. **Exploration/export subsystem: `exploreMaterial-tool/`**
- `DExTool.py` is the main entry point for the **Dataset Explorer**.
- This subsystem is used to **inspect annotations, summarize dataset contents, and export customized training subsets**.
- It is driven by `config_DEx.json`, which indicates the explorer is also **configuration-based** and likely controls input paths, filters, and output structure.
6. **Dataset reading and annotation access**
- `vcd4reader.py` is the reader counterpart to the annotation parser: it loads VCD annotations for analysis and browsing.
- `accessDMDAnn.py` appears to provide a higher-level access layer around DMD annotations, likely abstracting away raw file structure.
- This creates a clean boundary: the explorer does not need to understand low-level annotation serialization details directly.
7. **Export, grouping, and analytics in the explorer**
- `group_split_material.py` suggests dataset partitioning logic, likely for grouping samples by subject/session/material and producing splits.
- `statistics.py` indicates reporting/summary generation over the annotations or exported subsets.
- Together these scripts make the explorer more than a viewer: it is a **dataset curation and preparation tool**.
8. **Shared architectural dependency: annotation format**
- Both toolchains depend on the same underlying annotation model, so the repo has a **shared format boundary** centered on VCD/OpenLABEL.
- That means the annotation tool writes, and the explorer reads, the same class of files, enabling a round-trip workflow:
- label or revise data in `annotation-tool`
- inspect, split, and export in `exploreMaterial-tool`
9. **Documentation and deployment boundary**
- `docs/setup_linux.md` and `docs/setup_windows.md` show the tools are meant to run on **local desktop environments** across OSes.
- `annotation-tool/README.md` and `exploreMaterial-tool/README.md` likely document tool-specific usage, while the top-level README describes the dataset and policy changes.
- This repo is therefore a **tool + documentation bundle**, not a hosted application.
10. **Operational flow an architecture diagram should show**
- Start with the **DMD dataset directory** containing RGB videos and VCD annotations.
- Feed that into either:
- **TaTo** for annotation creation/editing, or
- **DEx** for browsing, analysis, and export.
- Both tools use their own **JSON config layer** and their own **VCD read/write adapters**.
- Outputs are updated annotation files, statistics, and curated/exported dataset subsets.
11. **Important project constraint**
- The 2026 revision changes the dataset boundary significantly: only a subset of subjects is unrestricted, and only RGB real-car material remains available.
- Any downstream architecture or workflow diagram should reflect that the tools operate on a **restricted, current dataset version**, not the historical full multimodal release.
Main entry points: [`exploreMaterial-tool/DExTool.py`](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/DExTool.py) (DExTool), [`annotation-tool/TaTo.py`](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/TaTo.py) (TaTo), [`exploreMaterial-tool/vcd4reader.py`](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/vcd4reader.py) (VCD reader), [`docs/setup_linux.md`](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/docs/setup_linux.md) (Linux setup)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_dataset["DMD data"]
node_dmd_dataset[("Dataset files
video+ann dataset")]
end
subgraph group_annotation_tool["Annotation tool"]
node_tato["TaTo
annotation app
[TaTo.py]"]
node_tato_config["Label configs
task schema"]
node_tato_adapter["VCD parser
format adapter
[vcd4parser.py]"]
node_tato_setup["Setup script
bootstrap
[setUp.py]"]
end
subgraph group_explorer_tool["Explorer/export tool"]
node_dex["DExTool
explorer app
[DExTool.py]"]
node_dex_config["Explorer config
runtime config
[config_DEx.json]"]
node_vcd_reader["VCD reader
analysis adapter
[vcd4reader.py]"]
node_ann_access["Ann access
access layer
[accessDMDAnn.py]"]
node_material_split["Split logic
partitioning"]
node_stats["Statistics
reporting
[statistics.py]"]
end
subgraph group_docs["Docs"]
node_linux_setup["Linux setup
docs
[setup_linux.md]"]
node_windows_setup["Windows setup
docs
[setup_windows.md]"]
node_ann_readme["Annot. readme
docs
[README.md]"]
node_dex_readme["Explorer readme
docs
[README.md]"]
node_top_readme["Top README
docs
[README.md]"]
end
node_dmd_dataset -->|"load/edit"| node_tato
node_tato -->|"driven by"| node_tato_config
node_tato -->|"reads/writes"| node_tato_adapter
node_tato -->|"writes back"| node_dmd_dataset
node_tato -.->|"bootstrapped by"| node_tato_setup
node_dmd_dataset -->|"browse/analyze"| node_dex
node_dex -->|"driven by"| node_dex_config
node_dex -->|"loads"| node_vcd_reader
node_dex -->|"abstracts"| node_ann_access
node_dex -->|"exports subsets"| node_material_split
node_dex -->|"summarizes"| node_stats
node_vcd_reader -->|"reads"| node_dmd_dataset
node_ann_access -->|"wraps"| node_vcd_reader
node_material_split -->|"derives subsets"| node_dmd_dataset
node_stats -->|"reports on"| node_dmd_dataset
node_linux_setup -.->|"installs"| node_tato
node_windows_setup -.->|"installs"| node_tato
node_linux_setup -.->|"installs"| node_dex
node_windows_setup -.->|"installs"| node_dex
node_ann_readme -.->|"documents"| node_tato
node_dex_readme -.->|"documents"| node_dex
node_top_readme -.->|"defines boundary"| node_dmd_dataset
click node_tato "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/TaTo.py"
click node_tato_config "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/config_distraction.json"
click node_tato_adapter "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/vcd4parser.py"
click node_tato_setup "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/setUp.py"
click node_dex "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/DExTool.py"
click node_dex_config "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/config_DEx.json"
click node_vcd_reader "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/vcd4reader.py"
click node_ann_access "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/accessDMDAnn.py"
click node_material_split "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/group_split_material.py"
click node_stats "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/statistics.py"
click node_linux_setup "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/docs/setup_linux.md"
click node_windows_setup "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/docs/setup_windows.md"
click node_ann_readme "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/README.md"
click node_dex_readme "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/README.md"
click node_top_readme "https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/README.md"
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_dmd_dataset toneBlue
class node_tato,node_tato_config,node_tato_adapter,node_tato_setup toneAmber
class node_dex,node_dex_config,node_vcd_reader,node_ann_access,node_material_split,node_stats toneMint
class node_linux_setup,node_windows_setup,node_ann_readme,node_dex_readme,node_top_readme toneRose
```
## Components
### DMD data
Local dataset folders containing RGB real-car videos and matching VCD/OpenLABEL-style annotations.
- **Dataset files**: video+ann dataset · Local RGB video material with matching annotation metadata in the current restricted DMD release.
### Annotation tool
Temporal labeling workflow for creating and updating DMD annotations.
- [TaTo](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/TaTo.py): annotation app · Main entry point for temporal annotation creation and editing. · `annotation-tool/TaTo.py`
- [Label configs](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/config_distraction.json): task schema · Scenario-specific annotation definitions for distraction, drowsiness, gaze, hands, and statics. · `annotation-tool/config_distraction.json`
- [VCD parser](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/vcd4parser.py): format adapter · Reads and writes VCD 4+/OpenLABEL-style annotation structures for the annotation tool. · `annotation-tool/vcd4parser.py`
- [Setup script](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/setUp.py): bootstrap · Local environment preparation for the annotation tool runtime. · `annotation-tool/setUp.py`
### Explorer/export tool
Dataset browsing, analysis, grouping, and export workflow.
- [DExTool](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/DExTool.py): explorer app · Main entry point for dataset exploration, summarization, and subset export. · `exploreMaterial-tool/DExTool.py`
- [Explorer config](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/config_DEx.json): runtime config · Configuration layer for explorer inputs, filters, and export behavior. · `exploreMaterial-tool/config_DEx.json`
- [VCD reader](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/vcd4reader.py): analysis adapter · Loads VCD annotations for browsing and analysis in the explorer. · `exploreMaterial-tool/vcd4reader.py`
- [Ann access](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/accessDMDAnn.py): access layer · Higher-level access wrapper around DMD annotation data. · `exploreMaterial-tool/accessDMDAnn.py`
- [Split logic](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/group_split_material.py): partitioning · Groups material and prepares curated dataset subsets. · `exploreMaterial-tool/group_split_material.py`
- [Statistics](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/statistics.py): reporting · Produces annotation and dataset summaries for exploration and export. · `exploreMaterial-tool/statistics.py`
### Docs
Setup and usage documentation for local desktop installation.
- [Linux setup](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/docs/setup_linux.md): docs · Local installation and setup guide for Linux environments. · `docs/setup_linux.md`
- [Windows setup](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/docs/setup_windows.md): docs · Local installation and setup guide for Windows environments. · `docs/setup_windows.md`
- [Annot. readme](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/annotation-tool/README.md): docs · Tool-specific documentation for the annotation workflow. · `annotation-tool/README.md`
- [Explorer readme](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/exploreMaterial-tool/README.md): docs · Tool-specific documentation for the dataset explorer workflow. · `exploreMaterial-tool/README.md`
- [Top README](https://github.com/vicomtech/dmd-driver-monitoring-dataset/blob/master/README.md): docs · Repository overview and dataset boundary notes for the current DMD release. · `README.md`
## Connections
- Dataset files → TaTo: load/edit · TaTo opens local videos and existing annotations for temporal labeling.
- TaTo → Label configs: driven by · Task-specific annotation vocabularies and behavior are defined in JSON.
- TaTo → VCD parser: reads/writes · Annotation editing persists through the VCD/OpenLABEL adapter.
- TaTo → Dataset files: writes back · Updated annotations are saved alongside the dataset files.
- TaTo → Setup script: bootstrapped by · Local setup prepares the annotation tool environment.
- Dataset files → DExTool: browse/analyze · DExTool reads the local dataset for inspection and curation.
- DExTool → Explorer config: driven by · Explorer behavior is controlled by configuration.
- DExTool → VCD reader: loads · Dataset exploration uses the VCD reader for annotation access.
- DExTool → Ann access: abstracts · Higher-level annotation access hides raw file structure from explorer logic.
- DExTool → Split logic: exports subsets · Grouping and split logic produces curated dataset subsets.
- DExTool → Statistics: summarizes · Statistics module generates dataset and annotation summaries.
- VCD reader → Dataset files: reads · Explorer reads the same annotation files produced by the authoring tool.
- Ann access → VCD reader: wraps · Access layer builds on top of the lower-level VCD reader.
- Split logic → Dataset files: derives subsets · Split logic creates curated partitions from the local corpus.
- Statistics → Dataset files: reports on · Statistics are computed over the current dataset release.
- Linux setup → TaTo: installs · One of the documented local setup paths for the annotation tool.
- Windows setup → TaTo: installs · One of the documented local setup paths for the annotation tool.
- Linux setup → DExTool: installs · One of the documented local setup paths for the explorer tool.
- Windows setup → DExTool: installs · One of the documented local setup paths for the explorer tool.
- Annot. readme → TaTo: documents · Tool usage and workflow notes for annotation editing.
- Explorer readme → DExTool: documents · Tool usage and workflow notes for dataset exploration and export.
- Top README → Dataset files: defines boundary · Repository-level documentation describes the current restricted dataset scope.