vicomtech/dmd-driver-monitoring-dataset

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.