Metadata-Version: 2.4
Name: segcraft
Version: 0.1.5
Summary: Config-driven semantic segmentation framework
Author: oney-erge
License-Expression: MIT
Project-URL: Homepage, https://github.com/oney-erge/SegCraft-Semantic-Segmentation
Project-URL: Repository, https://github.com/oney-erge/SegCraft-Semantic-Segmentation
Project-URL: Issues, https://github.com/oney-erge/SegCraft-Semantic-Segmentation/issues
Project-URL: Changelog, https://github.com/oney-erge/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<13,>=12.3; 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<6,>=5.5; extra == "transformers"
Provides-Extra: video
Requires-Dist: opencv-python<4.12,>=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<13,>=12.3; extra == "web"
Requires-Dist: torch<3,>=2.2; extra == "web"
Requires-Dist: torchvision<1,>=0.17; extra == "web"
Requires-Dist: transformers<6,>=5.5; extra == "web"
Requires-Dist: opencv-python<4.12,>=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<10,>=9.0.3; 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

From a checkout, use the same entry point on every platform. It installs a
pinned `uv`, creates the local environment, starts the web app, waits until it
is ready, and then opens it in your browser.

```powershell
.\run.bat
```

```bash
./run.command  # macOS
./run.sh       # Linux
```

Run `doctor`, intentionally rebuild the environment with `repair`, or use the
Docker path with the same launcher:

```bash
./run.sh doctor
./run.sh repair
./run.sh docker
./run.sh logs
./run.sh stop
```

The PowerShell equivalents are `.\run.ps1 doctor` and `.\run.ps1 docker`.
Docker binds the UI only to `127.0.0.1:8000` and keeps outputs and model caches
in named volumes. An NVIDIA host can opt into GPU access with:

```bash
docker compose -f compose.yaml -f compose.nvidia.yaml up --build
```

For package-only use, install just the extras you need:

```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
pip install "segcraft[web]"                      # FastAPI UI with video + default model backends
```

For development from a checkout:

```bash
uv sync --frozen --extra web --extra 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.

## 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_video`: TorchVision PASCAL/VOC video prediction.
- `cityscapes_video`: SegFormer Cityscapes video prediction.
- `cpu_video_demo`: short Cityscapes CPU demo settings.
- `ade20k_video`: 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.

## 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 `oney-erge`, repository
`SegCraft-Semantic-Segmentation`, workflow `release.yml`, and environment
`pypi`. A `v*` tag publishes the package, container image, distribution files,
and GitHub release. A manual run can publish to TestPyPI without making a
release.
