LSV / LabOS Spatial Code Toolkit

This toolkit converts the LabOS segmentation dataset into spatial code.

The main input should be labos1/segmentation, because it already provides instance segmentation annotations for lab equipment in COCO JSON and YOLO polygon formats.

1. Install

conda create -n lsv_spatial python=3.10 -y
conda activate lsv_spatial
pip install -r requirements.txt

2. Run with automatic Hugging Face download

python convert_segmentation_to_spatial_code.py \
  --repo-id labos1/segmentation \
  --output-dir outputs/segmentation_spatial_code \
  --annotation-name annotations.json \
  --polygon-mode summary \
  --make-viz \
  --viz-count 8

3. Run after manual download

If you manually downloaded the dataset and have a local folder such as:

dataset-2/
├── images/
├── labels/
├── annotations.json
├── annotations_train.json
├── annotations_val.json
└── dataset.yaml

then run:

python convert_segmentation_to_spatial_code.py \
  --dataset-root /path/to/dataset-2 \
  --output-dir outputs/segmentation_spatial_code \
  --annotation-name annotations.json \
  --polygon-mode summary \
  --make-viz \
  --viz-count 8

4. Outputs

The script writes:

spatial_code.jsonl             # one JSON object per image
spatial_code_pretty.json       # readable first N image-level codes
spatial_code_objects.csv       # one row per object instance
spatial_code_relations.csv     # one row per pairwise relation
summary.json                   # dataset-level summary
examples/*.png                 # optional bbox visualization examples