Metadata-Version: 2.4
Name: segcraft
Version: 0.1.3
Summary: Config-driven semantic segmentation framework
Author: iodriller
License-Expression: MIT
Project-URL: Homepage, https://github.com/iodriller/SegCraft-Semantic-Segmentation
Project-URL: Repository, https://github.com/iodriller/SegCraft-Semantic-Segmentation
Project-URL: Issues, https://github.com/iodriller/SegCraft-Semantic-Segmentation/issues
Project-URL: Changelog, https://github.com/iodriller/SegCraft-Semantic-Segmentation/blob/master/CHANGELOG.md
Keywords: semantic-segmentation,computer-vision,pytorch,video,segmentation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: PyYAML>=6.0
Provides-Extra: torch
Requires-Dist: numpy<2.0,>=1.26; extra == "torch"
Requires-Dist: pillow<11,>=10.0; extra == "torch"
Requires-Dist: torch<3,>=2.2; extra == "torch"
Requires-Dist: torchvision<1,>=0.17; extra == "torch"
Provides-Extra: smp
Requires-Dist: segmentation-models-pytorch<0.5,>=0.3.3; extra == "smp"
Provides-Extra: transformers
Requires-Dist: transformers<5,>=4.40; extra == "transformers"
Provides-Extra: video
Requires-Dist: opencv-python<5,>=4.8; extra == "video"
Requires-Dist: yt-dlp>=2024.1; extra == "video"
Provides-Extra: app
Requires-Dist: fastapi<1,>=0.115; extra == "app"
Requires-Dist: python-multipart<0.1,>=0.0.9; extra == "app"
Requires-Dist: uvicorn[standard]<1,>=0.30; extra == "app"
Provides-Extra: web
Requires-Dist: numpy<2.0,>=1.26; extra == "web"
Requires-Dist: pillow<11,>=10.0; extra == "web"
Requires-Dist: torch<3,>=2.2; extra == "web"
Requires-Dist: torchvision<1,>=0.17; extra == "web"
Requires-Dist: transformers<5,>=4.40; extra == "web"
Requires-Dist: opencv-python<5,>=4.8; extra == "web"
Requires-Dist: yt-dlp>=2024.1; extra == "web"
Requires-Dist: fastapi<1,>=0.115; extra == "web"
Requires-Dist: python-multipart<0.1,>=0.0.9; extra == "web"
Requires-Dist: uvicorn[standard]<1,>=0.30; extra == "web"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.2; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: twine<7,>=5.0; extra == "dev"
Requires-Dist: packaging<25,>=23.2; extra == "dev"
Requires-Dist: docutils<0.22,>=0.18.1; extra == "dev"
Requires-Dist: rich<14,>=13; extra == "dev"
Dynamic: license-file

# SegCraft

SegCraft is a config-first semantic segmentation toolkit for training,
evaluating, and running image/video prediction from the same YAML setup.

![SegCraft GPU demo: original dashcam video beside semantic segmentation overlay](assets/segcraft-gpu-demo.gif)

## Install

Use an isolated environment. Installing ML/video stacks into a global or Conda
base Python can make pip upgrade unrelated packages and produce dependency
conflicts.

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
```

```bash
pip install segcraft
```

For the browser UI from PyPI:

```bash
pip install "segcraft[web]"
segcraft doctor
segcraft-web
```

Other extras:

```bash
pip install "segcraft[torch]"                    # prediction/training with TorchVision
pip install "segcraft[torch,smp]"                # segmentation-models-pytorch
pip install "segcraft[torch,transformers]"       # Hugging Face segmentation models
pip install "segcraft[torch,transformers,video]" # video files and YouTube helpers
```

From a checkout:

```bash
pip install -e ".[web,dev]"
```

For NVIDIA GPUs, install the CUDA-enabled PyTorch wheel that matches your
system from the PyTorch install page, then run:

```bash
segcraft doctor
```

`segcraft doctor` reports the Python executable, Torch version, CUDA build,
CUDA availability, and visible GPU names. If it reports `CUDA available: False`,
launch SegCraft from the environment where Torch can see CUDA, or keep
`runtime.device: auto` so SegCraft falls back to CPU instead of failing.

## CLI

```bash
segcraft validate
segcraft predict --preset cityscapes_video --local configs/local.yaml
segcraft train --preset fast_dev --local configs/local.yaml
segcraft evaluate --preset quality --local configs/local.yaml
```

`configs/local.yaml` is for machine-specific paths and is ignored by git.
Start from `configs/local.example.yaml`.

## Web App

```bash
segcraft-web
```

Open `http://127.0.0.1:8000`. The UI accepts either a video upload or a
YouTube URL, lets you choose a preset or type a custom preset path/name, shows
job progress, shows the active Torch/CUDA runtime, and exposes downloads for
the generated outputs. YouTube downloads are cached under `outputs/web` by URL
and format, and running jobs can be stopped from the UI.

## Notebooks

- `notebooks/01_quickstart.ipynb`: video prediction demo.
- `notebooks/02_config_and_api.ipynb`: config and API basics.
- `notebooks/03_web_app.ipynb`: launching the optional FastAPI app.

## Presets

SegCraft merges configs in this order:

1. `configs/base.yaml`
2. optional preset
3. optional local config

Preset names work in the CLI, Python API, and web app:

- `fast_dev`: tiny CPU training run.
- `quality`: longer training settings with scheduler and metrics.
- `binary_quickstart`: binary foreground/background setup.
- `pascal_fast_video`: faster TorchVision PASCAL/VOC video prediction.
- `pascal_video`: TorchVision PASCAL/VOC video prediction.
- `pascal_quality_video`: larger TorchVision PASCAL/VOC video prediction.
- `cityscapes_video`: SegFormer Cityscapes video prediction.
- `cityscapes_quality_video`: larger SegFormer Cityscapes video prediction.
- `cpu_video_demo`: short Cityscapes CPU demo settings.
- `ade20k_video`: SegFormer ADE20K video prediction.
- `ade20k_quality_video`: larger SegFormer ADE20K video prediction.
- `smp_unet_resnet34`: SMP Unet training setup.

`task.num_classes` controls trainable model heads. `task.class_names` only
controls display names; if labels are missing or do not match the model,
SegCraft falls back to `class_<id>` names during prediction.

For more pretrained models, use Hugging Face semantic-segmentation model IDs
with `model.backend: transformers`, TorchVision segmentation model names with
`model.backend: torchvision`, or SMP architectures/encoders with
`model.backend: smp`:

- Hugging Face image segmentation models: <https://huggingface.co/models?pipeline_tag=image-segmentation>
- TorchVision semantic segmentation weights: <https://docs.pytorch.org/vision/stable/models.html#semantic-segmentation>
- Segmentation Models PyTorch encoders: <https://smp.readthedocs.io/en/stable/encoders.html>

## Python API

```python
from segcraft import load_config, load_config_object, list_available_presets
from segcraft.prediction import run_prediction

print(list_available_presets())

config = load_config("configs/base.yaml", preset_path="cityscapes_video")
typed = load_config_object("configs/base.yaml", preset_path="cityscapes_video")

events = []
summary = run_prediction(config, progress_callback=events.append)
```

## Outputs

Video prediction writes:

- `original.mp4`
- `overlay.mp4`
- `comparison.mp4`
- `summary.json`

Image-folder prediction writes masks, overlays, an optional overlay video, and
the same summary metadata.

## Development

```bash
pip install -e ".[web,dev]"
pytest
python -m build
twine check dist/*
```

Publishing uses `.github/workflows/release.yml` with GitHub trusted publishing.
Configure the PyPI/TestPyPI publisher for owner `iodriller`, repository
`SegCraft-Semantic-Segmentation`, workflow `release.yml`, and environment
`pypi`, then run the workflow manually for the target repository.
