scribble-annotation-generator 0.3.1

Programmatically generate semi-realistic synthetic scribble annotations based on statistics from existing scribble datasets

Scribble Annotation Generator

Programmatically generate semi-realistic scribble annotations for segmentation-style tasks. The project exposes a single CLI entrypoint for two workflows: synthetic crop-field generation and training/inference of the neural scribble generator.

Installation

pip install -e .
# or
pip install scribble-annotation-generator

After installation, the CLI command scribble-annotation-generator becomes available.

Colour Map Specification

Many commands require a colour map that links RGB tuples to class IDs. Provide it in either form:

• Inline string: R,G,B=class;R,G,B=class (also accepts R,G,B:class)
  • Example: 0,0,0=0;0,128,255=1;124,255,121=2
• File path: a text file with one entry per line. Each line is R,G,B,class. If the class column is omitted, class IDs are assigned by line order starting at 0.

CLI

1) Crop-field synthesis

Generate synthetic crop-field scribble images using a procedural model.

scribble-annotation-generator crop-field \
  --colour-map "0,0,0=0;0,128,255=1;124,255,121=2" \
  --output-dir ./path/to/output \
  --num-samples 50 \
  --min-rows 4 \
  --max-rows 6

Key flags:

• --colour-map (required): inline or file as described above
• --output-dir: where PNGs are written (default ./local/crop_field)
• --num-samples: number of images to create (default 200)
• --min-rows, --max-rows: range for rows per sample

2) Train and run neural generator

Train the transformer-based object generator on a dataset of scribble annotations, then render model predictions on the validation set.

scribble-annotation-generator train-nn \
  --train-dir ./local/soybean1/train \
  --val-dir ./local/soybean1/val \
  --colour-map ./colour_map.csv \
  --checkpoint-dir ./local/nn-checkpoints \
  --inference-dir ./local/nn-inference \
  --batch-size 8 \
  --num-workers 4 \
  --max-epochs 50

Key flags:

• --train-dir, --val-dir (required): directories containing training and validation data
• --colour-map (required): inline or file form
• --checkpoint-dir: where PyTorch Lightning checkpoints are stored (default ./local/nn-checkpoints)
• --inference-dir: where rendered scribbles from validation samples are saved (default ./local/nn-inference)
• --batch-size, --num-workers, --max-epochs: training configuration
• --num-classes: override number of classes; by default derived from the colour map

Python API

Instead of calling the CLI, you can call the main functions directly:

• scribble_annotation_generator.crop_field.generate_crop_field_dataset(output_dir, colour_map, num_samples=..., min_rows=..., max_rows=...)
• scribble_annotation_generator.nn.train_and_infer(train_dir, val_dir, colour_map, checkpoint_dir=..., inference_dir=..., batch_size=..., num_workers=..., max_epochs=..., num_classes=None)
• scribble_annotation_generator.bbox_random_generator.BBoxRandomGenerator(num_classes, num_components=..., class_names=..., colour_map=...).fit(dataset)

The bbox generator learns per-class object size distributions from existing annotation masks, then samples a class uniformly at inference time and places one fully contained bounding box at a random location.

License

MIT