flashseg 1.0.0__tar.gz

flashseg-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FlashVision
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flashseg-1.0.0/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: flashseg
+Version: 1.0.0
+Summary: Ultra-lightweight real-time image segmentation with LoRA fine-tuning & Knowledge Distillation
+Author-email: FlashVision <flashvision@github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/FlashVision/FlashSeg
+Project-URL: Repository, https://github.com/FlashVision/FlashSeg
+Project-URL: Documentation, https://github.com/FlashVision/FlashSeg#readme
+Project-URL: Issues, https://github.com/FlashVision/FlashSeg/issues
+Keywords: segmentation,semantic-segmentation,instance-segmentation,deep-learning,edge-ai,real-time,lightweight
+Classifier: Development Status :: 4 - Beta
+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 Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: torchvision>=0.15
+Requires-Dist: numpy>=1.21
+Requires-Dist: opencv-python>=4.5
+Requires-Dist: Pillow>=9.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.60
+Provides-Extra: export
+Requires-Dist: onnx>=1.12; extra == "export"
+Requires-Dist: onnxruntime>=1.13; extra == "export"
+Requires-Dist: onnxsim>=0.4; extra == "export"
+Provides-Extra: analytics
+Requires-Dist: matplotlib>=3.5; extra == "analytics"
+Requires-Dist: seaborn>=0.12; extra == "analytics"
+Requires-Dist: pandas>=1.4; extra == "analytics"
+Provides-Extra: solutions
+Requires-Dist: shapely>=2.0; extra == "solutions"
+Provides-Extra: all
+Requires-Dist: flashseg[analytics,export,solutions]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.png" width="200" alt="FlashSeg Logo">
+</p>
+
+<h1 align="center">FlashSeg</h1>
+
+<p align="center">
+  <a href="https://github.com/FlashVision/FlashSeg/actions"><img src="https://img.shields.io/github/actions/workflow/status/FlashVision/FlashSeg/ci.yml?logo=github" alt="CI"></a>
+  <img src="https://img.shields.io/badge/PyTorch-2.0+-ee4c2c?logo=pytorch&logoColor=white" alt="PyTorch">
+  <img src="https://img.shields.io/badge/Python-3.8+-3776ab?logo=python&logoColor=white" alt="Python">
+  <img src="https://img.shields.io/badge/ONNX-Export-005CED?logo=onnx&logoColor=white" alt="ONNX">
+  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
+</p>
+
+<p align="center">
+  <b>Ultra-lightweight real-time semantic segmentation with LoRA fine-tuning & knowledge distillation</b>
+</p>
+
+<p align="center">
+  <a href="#installation">Install</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#models">Models</a> •
+  <a href="#solutions">Solutions</a> •
+  <a href="#training">Training</a> •
+  <a href="#examples">Examples</a>
+</p>
+
+---
+
+## What is FlashSeg?
+
+FlashSeg is an ultra-lightweight semantic segmentation framework built for **speed and edge deployment**. Using a ShuffleNetV2 backbone with FPN neck, it delivers real-time pixel-level predictions with models as small as 0.3M parameters.
+
+```bash
+pip install -e .
+flashseg train --model-size m --num-classes 21 --train-images data/images --train-masks data/masks --val-images data/val_img --val-masks data/val_mask
+flashseg predict --model best.pth --source images/
+```
+
+---
+
+## Installation
+
+```bash
+# From source
+git clone https://github.com/FlashVision/FlashSeg.git
+cd FlashSeg
+pip install -e ".[all]"
+```
+
+### Optional extras
+
+```bash
+pip install -e ".[export]"      # ONNX export
+pip install -e ".[analytics]"   # Benchmarking, plots
+pip install -e ".[solutions]"   # Background removal, lane detection
+pip install -e ".[all]"         # Everything
+```
+
+### Verify
+
+```bash
+flashseg check
+flashseg settings
+flashseg version
+```
+
+---
+
+## Usage
+
+### Python API
+
+```python
+from flashseg import Trainer, Predictor, Exporter
+
+# Train
+trainer = Trainer(
+    model_size="m",
+    train_images="data/images",
+    train_masks="data/masks",
+    val_images="data/val_images",
+    val_masks="data/val_masks",
+    num_classes=21,
+    epochs=100,
+    device="cuda",
+)
+trainer.train()
+
+# Predict
+predictor = Predictor(model_path="workspace/best.pth", num_classes=21, device="cuda")
+mask = predictor.predict("photo.jpg")
+
+# Export
+exporter = Exporter(model_path="workspace/best.pth", num_classes=21)
+exporter.export(output="model.onnx", simplify=True)
+```
+
+### CLI
+
+```bash
+flashseg train --model-size m --epochs 100 --device cuda \
+  --train-images data/images --train-masks data/masks \
+  --val-images data/val_img --val-masks data/val_mask --num-classes 21
+
+flashseg predict --model best.pth --source images/ --save-dir output/
+
+flashseg val --model best.pth --val-images data/val --val-masks data/val_mask
+
+flashseg export --model best.pth --output model.onnx --simplify
+```
+
+---
+
+## Models
+
+| Model | Params | FP16 Size | Input | mIoU (VOC) |
+|-------|--------|-----------|-------|-------------|
+| **FlashSeg-n** | 0.3M | ~0.7 MB | 256 | — |
+| **FlashSeg-s** | 0.8M | ~1.6 MB | 256 | — |
+| **FlashSeg-m** | 1.5M | ~3.0 MB | 512 | — |
+| **FlashSeg-l** | 3.2M | ~6.4 MB | 512 | — |
+
+### Config-driven Training
+
+```bash
+flashseg train --config configs/flashseg_m_512_voc.yaml
+flashseg train --config configs/flashseg_s_256_cityscapes.yaml
+flashseg train --config configs/flashseg_m_512_lora.yaml
+```
+
+---
+
+## Solutions
+
+Built-in high-level applications:
+
+```python
+from flashseg import Predictor
+from flashseg.solutions import BackgroundRemover, LaneDetector, SceneParser, AreaCalculator
+
+predictor = Predictor(model_path="best.pth", num_classes=21)
+
+# Remove background
+remover = BackgroundRemover(predictor, foreground_classes=[15])
+result = remover.remove(image)
+
+# Detect lanes
+lanes = LaneDetector(predictor, lane_class_id=1)
+
+# Parse scenes
+parser = SceneParser(predictor, class_names=["bg", "road", "building", ...])
+stats = parser.parse(image)  # {"road": 35.2, "building": 12.1, ...}
+
+# Calculate areas
+calc = AreaCalculator(predictor, pixels_per_meter=10.0)
+areas = calc.calculate(image)  # {class_id: area_m2, ...}
+```
+
+| Solution | Description |
+|----------|-------------|
+| **BackgroundRemover** | Remove/replace backgrounds, generate alpha mattes |
+| **LaneDetector** | Detect road lanes from segmentation |
+| **SceneParser** | Break scene into labeled regions with area stats |
+| **AreaCalculator** | Measure real-world areas from masks |
+
+---
+
+## Training
+
+### Standard
+
+```bash
+flashseg train --model-size m --epochs 100 --num-classes 21 --device cuda
+```
+
+### LoRA Fine-Tuning
+
+```bash
+flashseg train --model-size m --lora --config configs/flashseg_m_512_lora.yaml
+```
+
+### Mixed Precision
+
+```bash
+flashseg train --model-size m --amp --device cuda
+```
+
+---
+
+## Examples
+
+| Script | What it does |
+|--------|--------------|
+| `train_voc.py` | Train on Pascal VOC |
+| `predict_image.py` | Segment a single image |
+| `background_removal.py` | Remove image background |
+| `export_onnx.py` | Export to ONNX |
+| `benchmark_model.py` | Measure FPS and latency |
+
+---
+
+## Project Structure
+
+```
+FlashSeg/
+├── flashseg/                  # Main package
+│   ├── cfg/                   # Configuration + YAML loading
+│   ├── data/                  # Datasets, transforms
+│   ├── engine/                # Trainer, Predictor, Exporter, Validator
+│   ├── models/                # ShuffleNetV2, FPN, SegHead
+│   ├── losses/                # CE, Dice, Focal, Combined
+│   ├── nn/                    # ConvBnRelu, ASPP, DepthwiseSeparable
+│   ├── utils/                 # Metrics, visualization
+│   ├── solutions/             # Background removal, lanes, scene parsing
+│   └── analytics/             # Benchmark, profiler
+├── configs/                   # YAML configs (pick & train)
+├── examples/                  # Ready-to-run scripts
+├── tests/                     # Unit tests
+├── docker/                    # Dockerfile + compose
+├── pyproject.toml             # Package config
+└── LICENSE                    # MIT
+```
+
+---
+
+## Docker
+
+```bash
+docker build -t flashseg -f docker/Dockerfile .
+docker run --gpus all -v $(pwd)/data:/app/data flashseg predict --model best.pth --source data/
+```
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/FlashVision/FlashSeg.git
+cd FlashSeg
+pip install -e ".[dev,all]"
+ruff check flashseg/
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<p align="center">
+  <a href="https://github.com/FlashVision"><b>FlashVision</b></a> — Open-source lightweight AI
+</p>

flashseg-1.0.0/README.md

@@ -0,0 +1,256 @@
+<p align="center">
+  <img src="assets/logo.png" width="200" alt="FlashSeg Logo">
+</p>
+
+<h1 align="center">FlashSeg</h1>
+
+<p align="center">
+  <a href="https://github.com/FlashVision/FlashSeg/actions"><img src="https://img.shields.io/github/actions/workflow/status/FlashVision/FlashSeg/ci.yml?logo=github" alt="CI"></a>
+  <img src="https://img.shields.io/badge/PyTorch-2.0+-ee4c2c?logo=pytorch&logoColor=white" alt="PyTorch">
+  <img src="https://img.shields.io/badge/Python-3.8+-3776ab?logo=python&logoColor=white" alt="Python">
+  <img src="https://img.shields.io/badge/ONNX-Export-005CED?logo=onnx&logoColor=white" alt="ONNX">
+  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
+</p>
+
+<p align="center">
+  <b>Ultra-lightweight real-time semantic segmentation with LoRA fine-tuning & knowledge distillation</b>
+</p>
+
+<p align="center">
+  <a href="#installation">Install</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#models">Models</a> •
+  <a href="#solutions">Solutions</a> •
+  <a href="#training">Training</a> •
+  <a href="#examples">Examples</a>
+</p>
+
+---
+
+## What is FlashSeg?
+
+FlashSeg is an ultra-lightweight semantic segmentation framework built for **speed and edge deployment**. Using a ShuffleNetV2 backbone with FPN neck, it delivers real-time pixel-level predictions with models as small as 0.3M parameters.
+
+```bash
+pip install -e .
+flashseg train --model-size m --num-classes 21 --train-images data/images --train-masks data/masks --val-images data/val_img --val-masks data/val_mask
+flashseg predict --model best.pth --source images/
+```
+
+---
+
+## Installation
+
+```bash
+# From source
+git clone https://github.com/FlashVision/FlashSeg.git
+cd FlashSeg
+pip install -e ".[all]"
+```
+
+### Optional extras
+
+```bash
+pip install -e ".[export]"      # ONNX export
+pip install -e ".[analytics]"   # Benchmarking, plots
+pip install -e ".[solutions]"   # Background removal, lane detection
+pip install -e ".[all]"         # Everything
+```
+
+### Verify
+
+```bash
+flashseg check
+flashseg settings
+flashseg version
+```
+
+---
+
+## Usage
+
+### Python API
+
+```python
+from flashseg import Trainer, Predictor, Exporter
+
+# Train
+trainer = Trainer(
+    model_size="m",
+    train_images="data/images",
+    train_masks="data/masks",
+    val_images="data/val_images",
+    val_masks="data/val_masks",
+    num_classes=21,
+    epochs=100,
+    device="cuda",
+)
+trainer.train()
+
+# Predict
+predictor = Predictor(model_path="workspace/best.pth", num_classes=21, device="cuda")
+mask = predictor.predict("photo.jpg")
+
+# Export
+exporter = Exporter(model_path="workspace/best.pth", num_classes=21)
+exporter.export(output="model.onnx", simplify=True)
+```
+
+### CLI
+
+```bash
+flashseg train --model-size m --epochs 100 --device cuda \
+  --train-images data/images --train-masks data/masks \
+  --val-images data/val_img --val-masks data/val_mask --num-classes 21
+
+flashseg predict --model best.pth --source images/ --save-dir output/
+
+flashseg val --model best.pth --val-images data/val --val-masks data/val_mask
+
+flashseg export --model best.pth --output model.onnx --simplify
+```
+
+---
+
+## Models
+
+| Model | Params | FP16 Size | Input | mIoU (VOC) |
+|-------|--------|-----------|-------|-------------|
+| **FlashSeg-n** | 0.3M | ~0.7 MB | 256 | — |
+| **FlashSeg-s** | 0.8M | ~1.6 MB | 256 | — |
+| **FlashSeg-m** | 1.5M | ~3.0 MB | 512 | — |
+| **FlashSeg-l** | 3.2M | ~6.4 MB | 512 | — |
+
+### Config-driven Training
+
+```bash
+flashseg train --config configs/flashseg_m_512_voc.yaml
+flashseg train --config configs/flashseg_s_256_cityscapes.yaml
+flashseg train --config configs/flashseg_m_512_lora.yaml
+```
+
+---
+
+## Solutions
+
+Built-in high-level applications:
+
+```python
+from flashseg import Predictor
+from flashseg.solutions import BackgroundRemover, LaneDetector, SceneParser, AreaCalculator
+
+predictor = Predictor(model_path="best.pth", num_classes=21)
+
+# Remove background
+remover = BackgroundRemover(predictor, foreground_classes=[15])
+result = remover.remove(image)
+
+# Detect lanes
+lanes = LaneDetector(predictor, lane_class_id=1)
+
+# Parse scenes
+parser = SceneParser(predictor, class_names=["bg", "road", "building", ...])
+stats = parser.parse(image)  # {"road": 35.2, "building": 12.1, ...}
+
+# Calculate areas
+calc = AreaCalculator(predictor, pixels_per_meter=10.0)
+areas = calc.calculate(image)  # {class_id: area_m2, ...}
+```
+
+| Solution | Description |
+|----------|-------------|
+| **BackgroundRemover** | Remove/replace backgrounds, generate alpha mattes |
+| **LaneDetector** | Detect road lanes from segmentation |
+| **SceneParser** | Break scene into labeled regions with area stats |
+| **AreaCalculator** | Measure real-world areas from masks |
+
+---
+
+## Training
+
+### Standard
+
+```bash
+flashseg train --model-size m --epochs 100 --num-classes 21 --device cuda
+```
+
+### LoRA Fine-Tuning
+
+```bash
+flashseg train --model-size m --lora --config configs/flashseg_m_512_lora.yaml
+```
+
+### Mixed Precision
+
+```bash
+flashseg train --model-size m --amp --device cuda
+```
+
+---
+
+## Examples
+
+| Script | What it does |
+|--------|--------------|
+| `train_voc.py` | Train on Pascal VOC |
+| `predict_image.py` | Segment a single image |
+| `background_removal.py` | Remove image background |
+| `export_onnx.py` | Export to ONNX |
+| `benchmark_model.py` | Measure FPS and latency |
+
+---
+
+## Project Structure
+
+```
+FlashSeg/
+├── flashseg/                  # Main package
+│   ├── cfg/                   # Configuration + YAML loading
+│   ├── data/                  # Datasets, transforms
+│   ├── engine/                # Trainer, Predictor, Exporter, Validator
+│   ├── models/                # ShuffleNetV2, FPN, SegHead
+│   ├── losses/                # CE, Dice, Focal, Combined
+│   ├── nn/                    # ConvBnRelu, ASPP, DepthwiseSeparable
+│   ├── utils/                 # Metrics, visualization
+│   ├── solutions/             # Background removal, lanes, scene parsing
+│   └── analytics/             # Benchmark, profiler
+├── configs/                   # YAML configs (pick & train)
+├── examples/                  # Ready-to-run scripts
+├── tests/                     # Unit tests
+├── docker/                    # Dockerfile + compose
+├── pyproject.toml             # Package config
+└── LICENSE                    # MIT
+```
+
+---
+
+## Docker
+
+```bash
+docker build -t flashseg -f docker/Dockerfile .
+docker run --gpus all -v $(pwd)/data:/app/data flashseg predict --model best.pth --source data/
+```
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/FlashVision/FlashSeg.git
+cd FlashSeg
+pip install -e ".[dev,all]"
+ruff check flashseg/
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<p align="center">
+  <a href="https://github.com/FlashVision"><b>FlashVision</b></a> — Open-source lightweight AI
+</p>

flashseg-1.0.0/flashseg/__init__.py

@@ -0,0 +1,20 @@
+"""FlashSeg - Ultra-lightweight real-time image segmentation."""
+
+__version__ = "1.0.0"
+
+from flashseg.cfg.config import get_config
+from flashseg.engine.trainer import Trainer
+from flashseg.engine.predictor import Predictor
+from flashseg.engine.exporter import Exporter
+from flashseg.engine.validator import Validator
+from flashseg.models.build import build_model
+
+__all__ = [
+    "__version__",
+    "get_config",
+    "build_model",
+    "Trainer",
+    "Predictor",
+    "Exporter",
+    "Validator",
+]

flashseg-1.0.0/flashseg/analytics/__init__.py

@@ -0,0 +1,6 @@
+"""Analytics and benchmarking tools."""
+
+from flashseg.analytics.benchmark import Benchmark
+from flashseg.analytics.profiler import Profiler
+
+__all__ = ["Benchmark", "Profiler"]

flashseg-1.0.0/flashseg/analytics/benchmark.py

@@ -0,0 +1,65 @@
+"""Model benchmarking for segmentation."""
+
+import time
+import logging
+
+import torch
+
+from flashseg.cfg.config import get_config
+from flashseg.models.build import build_model
+
+logger = logging.getLogger(__name__)
+
+
+class Benchmark:
+    """Benchmark FlashSeg model speed and efficiency."""
+
+    def __init__(self, model_path: str = None, model_size: str = "m", input_size: int = 512, num_classes: int = 21, device: str = "cuda"):
+        self.device = torch.device(device if torch.cuda.is_available() or device == "cpu" else "cpu")
+        config = get_config(model_size=model_size, input_size=input_size, num_classes=num_classes)
+        self.model = build_model(config).to(self.device)
+
+        if model_path:
+            self.model.load_state_dict(torch.load(model_path, map_location=self.device))
+
+        self.model.eval()
+        self.input_size = input_size
+
+    def run(self, warmup: int = 10, iterations: int = 100) -> dict:
+        """Run benchmark and return timing results."""
+        dummy = torch.randn(1, 3, self.input_size, self.input_size).to(self.device)
+
+        # Warmup
+        with torch.no_grad():
+            for _ in range(warmup):
+                self.model(dummy)
+
+        if self.device.type == "cuda":
+            torch.cuda.synchronize()
+
+        # Benchmark
+        times = []
+        with torch.no_grad():
+            for _ in range(iterations):
+                start = time.perf_counter()
+                self.model(dummy)
+                if self.device.type == "cuda":
+                    torch.cuda.synchronize()
+                times.append(time.perf_counter() - start)
+
+        avg_ms = sum(times) / len(times) * 1000
+        fps = 1000.0 / avg_ms
+        params = sum(p.numel() for p in self.model.parameters())
+
+        results = {
+            "latency_ms": round(avg_ms, 2),
+            "fps": round(fps, 1),
+            "params": params,
+            "params_m": round(params / 1e6, 2),
+            "size_mb": round(params * 4 / 1024 / 1024, 2),
+            "device": str(self.device),
+            "input_size": self.input_size,
+        }
+
+        logger.info(f"Benchmark: {fps:.1f} FPS, {avg_ms:.2f}ms, {params / 1e6:.2f}M params")
+        return results