scribble-annotation-generator 0.0.1__tar.gz

scribble_annotation_generator-0.0.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+local/
+.vscode/
+lightning_logs/
+old/

scribble_annotation_generator-0.0.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: scribble-annotation-generator
+Version: 0.0.1
+Summary: Programmatically generate semi-realistic synthetic scribble annotations based on statistics from existing scribble datasets
+Project-URL: Homepage, https://github.com/alexsenden/scribble-annotation-generator
+Project-URL: Repository, https://github.com/alexsenden/scribble-annotation-generator
+Project-URL: Issues, https://github.com/alexsenden/scribble-annotation-generator/issues
+Author: Alex Senden
+License: MIT
+Keywords: annotation,computer-vision,scribble,segmentation,synthetic-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.8
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: scikit-image
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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)`
+
+## License
+
+MIT

scribble_annotation_generator-0.0.1/README.md

@@ -0,0 +1,79 @@
+# 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
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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)`
+
+## License
+
+MIT

scribble_annotation_generator-0.0.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "scribble-annotation-generator"
+description = "Programmatically generate semi-realistic synthetic scribble annotations based on statistics from existing scribble datasets"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Alex Senden" }]
+keywords = [
+    "scribble",
+    "annotation",
+    "segmentation",
+    "computer-vision",
+    "synthetic-data",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = ["numpy", "scipy", "scikit-image", "opencv-python"]
+
+# Version is automatically provided by hatch-vcs
+dynamic = ["version"]
+
+[project.scripts]
+scribble-annotation-generator = "scribble_annotation_generator.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/alexsenden/scribble-annotation-generator"
+Repository = "https://github.com/alexsenden/scribble-annotation-generator"
+Issues = "https://github.com/alexsenden/scribble-annotation-generator/issues"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.sdist]
+include = ["scribble_annotation_generator/**", "README.md"]
+
+[tool.hatch.build.targets.wheel]
+include = ["scribble_annotation_generator/**"]

scribble_annotation_generator-0.0.1/scribble_annotation_generator/cli.py

@@ -0,0 +1,195 @@
+import argparse
+import os
+from typing import Dict, Tuple
+
+from scribble_annotation_generator.crop_field import (
+    NUM_SAMPLES_TO_GENERATE,
+    generate_crop_field_dataset,
+)
+from scribble_annotation_generator.nn import train_and_infer
+
+
+def parse_colour_map(value: str) -> Dict[Tuple[int, int, int], int]:
+    """Parse a colour map from an inline string or a file path."""
+
+    def _validate_rgb(rgb: Tuple[int, int, int]) -> Tuple[int, int, int]:
+        r, g, b = rgb
+        for channel in (r, g, b):
+            if channel < 0 or channel > 255:
+                raise ValueError("RGB values must be between 0 and 255")
+        return rgb
+
+    mapping: Dict[Tuple[int, int, int], int] = {}
+
+    if os.path.isfile(value):
+        with open(value, "r", encoding="utf-8") as handle:
+            for idx, line in enumerate(handle):
+                stripped = line.strip()
+                if not stripped:
+                    continue
+                parts = [part.strip() for part in stripped.split(",") if part.strip()]
+                if len(parts) == 4:
+                    r, g, b, cls = parts
+                elif len(parts) == 3:
+                    r, g, b = parts
+                    cls = idx
+                else:
+                    raise ValueError(
+                        "Each line in the colour map file must have 3 (RGB) or 4 (RGB,class) comma-separated values"
+                    )
+                rgb = _validate_rgb((int(r), int(g), int(b)))
+                mapping[rgb] = int(cls)
+    else:
+        entries = [entry.strip() for entry in value.split(";") if entry.strip()]
+        for entry in entries:
+            if "=" in entry:
+                colour_part, class_part = entry.split("=", 1)
+            elif ":" in entry:
+                colour_part, class_part = entry.split(":", 1)
+            else:
+                raise ValueError(
+                    "Inline colour map entries must separate colour and class with '=' or ':'"
+                )
+            rgb_parts = [part.strip() for part in colour_part.split(",") if part.strip()]
+            if len(rgb_parts) != 3:
+                raise ValueError("Colours must be provided as R,G,B")
+            rgb = _validate_rgb((int(rgb_parts[0]), int(rgb_parts[1]), int(rgb_parts[2])))
+            mapping[rgb] = int(class_part.strip())
+
+    if not mapping:
+        raise ValueError("No colours were parsed for the colour map")
+
+    return mapping
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Scribble Annotation Generator CLI",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    crop_parser = subparsers.add_parser(
+        "crop-field", help="Generate synthetic crop field scribble images."
+    )
+    crop_parser.add_argument(
+        "--output-dir",
+        default="./local/crop_field",
+        help="Directory to write generated crop field images.",
+    )
+    crop_parser.add_argument(
+        "--num-samples",
+        type=int,
+        default=NUM_SAMPLES_TO_GENERATE,
+        help="Number of images to generate.",
+    )
+    crop_parser.add_argument(
+        "--min-rows",
+        type=int,
+        default=4,
+        help="Minimum number of crop rows per sample.",
+    )
+    crop_parser.add_argument(
+        "--max-rows",
+        type=int,
+        default=6,
+        help="Maximum number of crop rows per sample.",
+    )
+    crop_parser.add_argument(
+        "--colour-map",
+        required=True,
+        help=(
+            "Colour map specified inline as 'R,G,B=class;...' or a path to a file "
+            "with one 'R,G,B,class' entry per line."
+        ),
+    )
+
+    train_parser = subparsers.add_parser(
+        "train-nn", help="Train the scribble object generator and run inference."
+    )
+    train_parser.add_argument(
+        "--train-dir",
+        required=True,
+        help="Path to the training dataset directory.",
+    )
+    train_parser.add_argument(
+        "--val-dir",
+        required=True,
+        help="Path to the validation dataset directory.",
+    )
+    train_parser.add_argument(
+        "--checkpoint-dir",
+        default="./local/nn-checkpoints",
+        help="Directory to save model checkpoints.",
+    )
+    train_parser.add_argument(
+        "--inference-dir",
+        default="./local/nn-inference",
+        help="Directory to save inference visualisations.",
+    )
+    train_parser.add_argument(
+        "--batch-size",
+        type=int,
+        default=8,
+        help="Batch size for training.",
+    )
+    train_parser.add_argument(
+        "--num-workers",
+        type=int,
+        default=4,
+        help="Number of worker processes for data loading.",
+    )
+    train_parser.add_argument(
+        "--max-epochs",
+        type=int,
+        default=50,
+        help="Maximum number of training epochs.",
+    )
+    train_parser.add_argument(
+        "--num-classes",
+        type=int,
+        default=None,
+        help="Override the number of classes; defaults to the number of unique class IDs in the colour map.",
+    )
+    train_parser.add_argument(
+        "--colour-map",
+        required=True,
+        help=(
+            "Colour map specified inline as 'R,G,B=class;...' or a path to a file "
+            "with one 'R,G,B,class' entry per line."
+        ),
+    )
+
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    colour_map = parse_colour_map(args.colour_map)
+
+    if args.command == "crop-field":
+        generate_crop_field_dataset(
+            output_dir=args.output_dir,
+            colour_map=colour_map,
+            num_samples=args.num_samples,
+            min_rows=args.min_rows,
+            max_rows=args.max_rows,
+        )
+    elif args.command == "train-nn":
+        train_and_infer(
+            train_dir=args.train_dir,
+            val_dir=args.val_dir,
+            colour_map=colour_map,
+            checkpoint_dir=args.checkpoint_dir,
+            inference_dir=args.inference_dir,
+            batch_size=args.batch_size,
+            num_workers=args.num_workers,
+            max_epochs=args.max_epochs,
+            num_classes=args.num_classes,
+        )
+    else:
+        parser.error("A subcommand is required.")
+
+
+if __name__ == "__main__":
+    main()