Cityscapes Scripts – Quick Overview

What it is – A Python toolbox that helps you work with the Cityscapes dataset, a popular benchmark of street‑level images used for training and evaluating computer‑vision models (semantic segmentation, instance segmentation, panoptic segmentation, 3‑D object detection, etc.).

Why it matters – The dataset is large and has a complex folder layout and many annotation formats (fine/coarse polygons, PNG label maps, 3‑D boxes, etc.). The scripts automate the tedious steps of downloading, visualising, converting, and evaluating those annotations, so researchers can focus on the model itself.

---

Key Features (as described in the README)

Area	What the toolbox provides
Installation	pip install cityscapesscripts (optional GUI extras via cityscapesscripts[gui]).
Data handling	csDownload – command‑line downloader for the official Cityscapes packages.
Visualization	csViewer – image viewer with overlay of any annotation type; csLabelTool – the original labeling UI used by the dataset creators.
Conversion utilities	• csCreateTrainIdLabelImgs – turn polygon JSONs into PNGs with train‑ID labels. • csCreateTrainIdInstanceImgs – same, but with instance IDs. • csCreatePanopticImgs – export to COCO‑style panoptic format.
Evaluation	• Pixel‑level semantic labeling (csEvalPixelLevelSemanticLabeling). • Instance‑level semantic labeling (csEvalInstanceLevelSemanticLabeling). • Panoptic segmentation (csEvalPanopticSemanticLabeling). • 3‑D object detection (csEvalObjectDetection3d).
3‑D visualisation	csPlot3dDetectionResults – plot 3‑D detection outputs stored as JSON.
Helpers	helpers/labels.py and helpers/labels_cityPersons.py define class IDs, colour maps, and mappings used by the conversion/evaluation tools.
Cython acceleration	Optional Cython build (CYTHONIZE_EVAL=1 python setup.py build_ext --inplace) for faster evaluation (tested on Ubuntu).

---

Typical Workflow

1. Set dataset root – Export CITYSCAPES_DATASET=/path/to/cityscapes (many scripts read this env‑var).
2. Download – Run csDownload to fetch the required splits (train/val/test, fine/coarse, etc.).
3. Inspect – Use csViewer to browse images and overlay any annotation type.
4. Prepare – Convert polygon annotations to the PNG label‑maps your model expects with the csCreate* utilities.
5. Train / Infer – Feed the prepared images/labels to your segmentation or detection model.
6. Evaluate – After inference, call the appropriate csEval* script on the validation set to obtain the official Cityscapes metrics (IoU, AP, PQ, etc.).
7. Submit – For the test set, format results as described by the evaluation scripts and upload via the Cityscapes submission portal.

---

Who Might Use This

• Research labs building state‑of‑the‑art street‑scene perception models.
• Students needing a reliable way to convert the dataset into a format compatible with PyTorch/TensorFlow pipelines.
• Competitors in the Cityscapes leaderboard who must follow the exact evaluation protocol.

---

Licensing & Contact

• The scripts are MIT‑licensed (free to modify and redistribute).
• The dataset itself has its own custom license; you must agree to those terms before using the data.
• Maintainers: Marius Cordts, Mohamed Omran – reachable at mail@cityscapes-dataset.net.

---

In short, the Cityscapes Scripts repository is a practical, well‑documented utility package that streamlines the end‑to‑end handling of one of the most widely used autonomous‑driving vision benchmarks.