Skip to content

Commit 110b32b

Browse files
tnagorratnagorra
authored
Merge pull request #10 from mapswipe/feat/add-csv-to-coco-script
Add example script to generate coco from csv
2 parents 874e3b7 + bf63060 commit 110b32b

2 files changed

Lines changed: 1164 additions & 7 deletions

File tree

‎examples/generate-coco-from-dropbox/README.md‎

Lines changed: 88 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,19 @@ permalink: /examples/generate-coco-from-dropbox/
99

1010
## Background
1111

12-
[Assess Images](../../docs/project_types/assess_images.md) projects are created from a COCO-format JSON file describing the images to be mapped. This page provides a Python script that produces a minimal COCO file (`{ "images": [...] }`) from a folder of images hosted on Dropbox, so they can be referenced by public URL. The script also uploads the resulting JSON back to the same Dropbox folder.
12+
[Assess Images](../../docs/project_types/assess_images.md) projects are created from a COCO-format JSON file describing the images to be mapped. This page provides two Python scripts that generate such a file from a Dropbox folder, exposing image URLs as public Dropbox share links.
1313

14-
> [!CAUTION]
15-
> Ongoing updates to MapSwipe and Dropbox may render this script **out-of-date**.
14+
- **v1** — `generate_coco_from_dropbox.py`: builds a minimal COCO file (`{ "images": [...] }`) from a **flat folder of images**. No annotations, no categories. Useful when you only need to register images for mapping.
15+
- **v2** — `generate_coco_with_annotations_from_dropbox.py`: builds a full COCO file (`images`, `annotations`, `categories`) from an **images folder paired with a CSV metadata file** that describes bounding-box annotations per image. Useful when you already have annotations and want to seed an Assess Images project with them.
1616

17-
Utility script: [`generate_coco_from_dropbox.py`](generate_coco_from_dropbox.py)
17+
> [!CAUTION]
18+
> Ongoing updates to MapSwipe and Dropbox may render these scripts **out-of-date**.
1819
1920
> For the Google Drive equivalent see [Generate COCO File from Google Drive](../generate-coco-from-drive/README.md).
2021
21-
## Prerequisites
22+
## Common Prerequisites
23+
24+
These apply to both scripts.
2225

2326
- A Dropbox account: <https://www.dropbox.com/register>.
2427
- A new Dropbox app: <https://www.dropbox.com/developers/apps>.
@@ -33,9 +36,18 @@ Utility script: [`generate_coco_from_dropbox.py`](generate_coco_from_dropbox.py)
3336
- `sharing.read`
3437
- A generated access token (from the app settings → **Generated access token**).
3538
- [uv](https://docs.astral.sh/uv/getting-started/installation/) installed.
36-
- A Dropbox folder containing the images to be exported.
3739

38-
## Creation Steps
40+
## v1 — From a Flat Image Directory
41+
42+
Utility script: [`generate_coco_from_dropbox.py`](generate_coco_from_dropbox.py)
43+
44+
Produces a minimal COCO file containing only an `images` array. Each image is given a public Dropbox share link as its `coco_url`. The resulting JSON is uploaded back into the same Dropbox folder.
45+
46+
### Additional Prerequisites
47+
48+
- A Dropbox folder containing the images to be exported (`.jpg`, `.jpeg`, `.png`, or `.webp`). The folder is listed **non-recursively** — only files in the top level are picked up.
49+
50+
### Creation Steps
3951

4052
1. Copy the folder path in Dropbox.
4153
2. Copy the generated access token from Dropbox.
@@ -52,3 +64,72 @@ Utility script: [`generate_coco_from_dropbox.py`](generate_coco_from_dropbox.py)
5264
uv run generate_coco_from_dropbox.py sl.yourAccessTokenHere "/COCO TEST" "coco_export.json"
5365
```
5466
4. Download the exported COCO JSON from the link printed in the terminal, or directly from your Dropbox folder.
67+
68+
## v2 — From an Images Directory with a Metadata CSV
69+
70+
Utility script: [`generate_coco_with_annotations_from_dropbox.py`](generate_coco_with_annotations_from_dropbox.py)
71+
72+
Produces a full COCO file (`images`, `annotations`, `categories`) by combining an images sub-folder with a CSV metadata file that describes one bounding-box annotation per row. Image URLs are resolved to public Dropbox share links. The output is written locally; uploading back to Dropbox is opt-in.
73+
74+
### Additional Prerequisites
75+
76+
- A Dropbox folder containing:
77+
- An images sub-folder (default: `images/`) with `.jpg`, `.jpeg`, `.png`, or `.webp` files. The folder is listed **recursively**.
78+
- A CSV metadata file (default: `metadata.csv`) with at least these columns:
79+
- `image_name` — image path relative to the images folder.
80+
- `boxes` — JSON-encoded 4-element list (e.g. `[x1, y1, x2, y2]`).
81+
- `type` — category name for the annotation.
82+
83+
Additional columns are preserved as per-annotation `attributes`. All column names are configurable via flags.
84+
85+
### Creation Steps
86+
87+
1. Copy the folder path in Dropbox (the one containing the images sub-folder and the CSV).
88+
2. Copy the generated access token from Dropbox and export it:
89+
90+
```bash
91+
export DROPBOX_ACCESS_TOKEN="sl.yourAccessTokenHere"
92+
```
93+
3. Run the script:
94+
95+
```bash
96+
# Help
97+
uv run generate_coco_with_annotations_from_dropbox.py --help
98+
99+
# Usage
100+
uv run generate_coco_with_annotations_from_dropbox.py "FOLDER_PATHNAME_IN_DROPBOX" [options]
101+
102+
# Example
103+
uv run generate_coco_with_annotations_from_dropbox.py "/Indonesia"
104+
105+
# Example with custom columns, lenient mode, image-dimension probing, and upload
106+
uv run generate_coco_with_annotations_from_dropbox.py "/Indonesia" \
107+
--output ./indonesia.coco.json \
108+
--images-path images/ \
109+
--metadata-csv-path metadata.csv \
110+
--category-column type \
111+
--image-name-column image_name \
112+
--boxes-column boxes \
113+
--box-format xyxy \
114+
--lenient \
115+
--probe-dimensions \
116+
--upload-to-dropbox
117+
```
118+
4. Download the exported COCO JSON from the local path printed in the terminal (default: `./<base-folder-basename>.coco.json`). If `--upload-to-dropbox` was used, a temporary Dropbox link is also printed.
119+
120+
### Options
121+
122+
| Flag | Default | Purpose |
123+
| --- | --- | --- |
124+
| `--output` | `./<base-folder-basename>.coco.json` | Local path to write the COCO JSON. |
125+
| `--images-path` | `images/` | Images folder, relative to the base folder (absolute Dropbox paths also accepted). |
126+
| `--metadata-csv-path` | `metadata.csv` | CSV file path, relative to the base folder (absolute also accepted). |
127+
| `--category-column` | `type` | CSV column used to derive COCO categories. |
128+
| `--image-name-column` | `image_name` | CSV column with the image path relative to `--images-path`. |
129+
| `--boxes-column` | `boxes` | CSV column with the bounding box (JSON-encoded 4-element list). |
130+
| `--box-format` | `xyxy` | Format of the values in `--boxes-column`. `xyxy` is converted to COCO `xywh` on output. |
131+
| `--annotation-id-column` | _(unset)_ | CSV column to use as annotation id (must be unique). Defaults to sequential 1..N. |
132+
| `--image-id-column` | _(unset)_ | CSV column to use as image id (must be consistent per image). Defaults to sequential 1..N. |
133+
| `--strict` / `--lenient` | `--strict` | Hard-error vs. skip-and-warn on rows referencing missing images or invalid boxes. |
134+
| `--probe-dimensions` | `false` | Download each image and probe `width`/`height` with Pillow. |
135+
| `--upload-to-dropbox` | `false` | Also upload the COCO JSON to `<base_folder>/<output basename>` in Dropbox. |

0 commit comments

Comments
 (0)