Segment Toolkit
A modern, robust, and premium Python package designed to bridge the gap between pixel-level binary/colored segmentation masks and YOLO labels. It provides a bidirectional pipeline for both standard Bounding Boxes (YOLO object detection) and Polygon Coordinates (YOLO instance segmentation format).
Equipped with a flexible image-mask transform pipeline, exception handling, extensive logging, a CLI, and a clean Python API.
Features
- Bidirectional Conversions:
- Bounding Boxes: Convert binary masks to YOLO format labels (supports standard axis-aligned or advanced minimum area rotated bounding boxes) and vice versa.
- Polygon Segmentation: Convert binary or multi-class color-coded masks to YOLO instance segmentation polygon coordinates and vice versa.
- Transform Pipeline (
Compose,Resize,Normalize): Jointly apply spatial and pixel transforms (like resizing and normalizations) on both images and masks. - Robust Exception Handling: Prevents crashes on corrupted, missing, or empty files.
- Dynamic Dataset Matching: Parse Ground Truth CSV or JSON files (supports multiple indicator formats) to automatically map filenames to diagnostic class IDs (e.g. standard ISIC classes).
- YOLO Dataset Splitting: Automatically partitions images and label files into standard
trainandteststructures and generates thedata.yamlconfiguration file. - Visualization Overlays:
- Overlay bounding boxes onto source images.
- Blend masks onto source images.
- Render colored segmentation polygons with class tags onto source images.
- Dual Interface: Use as a command-line application (
segment-toolkit) or import as a Python library (import segment_toolkit).
Installation
1. Standard Installation (via PyPI)
pip install segment-toolkit
2. Local Development Installation
# Clone the repository
git clone https://github.com/zkzkGamal/mask-to-yolo-toolkit.git
cd mask-to-yolo-toolkit
# Install in editable mode
pip install -e .
Command Line Interface (CLI)
The package installs a console script called segment-toolkit.
1. Bounding Box Conversions
Convert Masks to YOLO Bounding Boxes
# Single File
segment-toolkit mask-to-yolo \
--image images/sample.jpg \
--mask masks/sample.png \
--output-txt labels/sample.txt \
--class-id 4
# Batch Directory
segment-toolkit mask-to-yolo \
--image-dir images/ \
--mask-dir masks/ \
--output-dir labels/ \
--ground-truth GroundTruth.csv
Options:
--rotated: Use rotated minimum area rectangles (cv2.minAreaRect) instead of standard axis-aligned boxes.--resize WIDTH HEIGHT: Set target size for resizing (default: 640 640).
Convert YOLO Bounding Boxes to Masks
# Single File
segment-toolkit yolo-to-mask \
--label labels/sample.txt \
--output-mask reconstructed/sample.png
# Batch Directory
segment-toolkit yolo-to-mask \
--label-dir labels/ \
--output-dir reconstructed/
Visualize Bounding Boxes
segment-toolkit visualize \
--image images/sample.jpg \
--label labels/sample.txt \
--output visualization.png
2. Polygon Segmentation Conversions
Convert Masks to YOLO Polygon Labels
Supports standard black-and-white masks or multi-class colored masks (requires passing a --classes JSON config mapping colors to class names).
# Single binary mask
segment-toolkit mask-to-polygon \
--image images/sample.jpg \
--mask masks/sample.png \
--output-txt labels/sample.txt \
--class-id 1
# Batch directory of multi-class colored masks
segment-toolkit mask-to-polygon \
--image-dir images/ \
--mask-dir masks/ \
--output-dir labels/ \
--classes classes.json
Convert YOLO Polygons back to Masks
# Single file (creates color mask if classes.json is provided)
segment-toolkit polygon-to-mask \
--label labels/sample.txt \
--output-mask reconstructed/sample.png \
--classes classes.json
# Batch directory
segment-toolkit polygon-to-mask \
--label-dir labels/ \
--output-dir reconstructed/
Visualize Polygon Segmentation
segment-toolkit visualize-polygon \
--image images/sample.jpg \
--label labels/sample.txt \
--output polygon_overlay.png \
--classes classes.json
3. Dataset Utilities
Split Dataset
Partitions image-label pairs into YOLO-compliant subfolders (train/, test/) and generates data.yaml:
segment-toolkit split \
--images images/ \
--labels labels/ \
--output dataset/ \
--ratio 0.8
Validation Overlays
To verify the pipeline, check out the visualization overlays generated by running the test suite under the scripts/ folder:
Bounding Box Overlay (ISIC Skin Lesion)
Bounding Box Overlay (Plant Disease)
Polygon Segmentation Overlay (ISIC Skin Lesion)
Reconstructed Mask Overlay (Multi-class Color Mask)
Python API
Programmatically build custom preprocessing and conversion pipelines:
from segment_toolkit import MaskToYoloConverter, YoloToMaskConverter
from segment_toolkit import MaskToPolygonConverter, PolygonToMaskConverter
from segment_toolkit.transforms import Compose, Resize, Normalize
# 1. Image & Mask Joint Transforms Pipeline
transform_pipeline = Compose([
Resize((640, 640)),
Normalize()
])
# 2. Bounding Box Converter
bbox_converter = MaskToYoloConverter(target_size=(640, 640), bbox_type="rotated")
bbox_converter.convert_single(
image_path="images/sample.jpg",
mask_path="masks/sample.png",
output_txt_path="labels/sample.txt",
class_id=0
)
# 3. Multi-class Colored Mask to Polygon Converter
classes = [
((255, 0, 0), "lesion_red"),
((0, 255, 0), "lesion_green")
]
poly_converter = MaskToPolygonConverter(target_size=(640, 640))
poly_converter.convert_single(
image_path="images/sample.jpg",
mask_path="masks/sample_colored.png",
output_txt_path="labels/sample_poly.txt",
classes=classes
)
Ground Truth JSON Format Example
To feed multi-class configurations to CLI commands using --classes, prepare a JSON file listing color lists and class names:
[
[[255, 0, 0], "lesion_red"],
[[0, 255, 0], "lesion_green"]
]
License
This project is licensed under the MIT License - see the LICENSE file for details.
Author
Zakria Gamal
- Computer Vision and AI Engineer
- LinkedIn: Zakria Gamal
Metadata
Release files for segment-toolkit 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| segment_toolkit-1.2.0.tar.gz | 22.6 kB | Without provenance | Details for segment_toolkit-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| segment_toolkit-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for segment_toolkit-1.2.0-py3-none-any.whl |
Total release size: 50.7 kB
Release files / segment_toolkit-1.2.0.tar.gz
| Download URL | segment_toolkit-1.2.0.tar.gz |
|---|---|
| Size | 22.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4687637f7905ebaccfce33ffd299240ff954e6d1a8d4118798aa9e6421afacd5
|
|
BLAKE2b-256 checksum How to use checksums |
b0d19b73dff4be64592605aaceb54031d652c1eadd9fc2821603b18c01d3b2a2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.12
|
Release files / segment_toolkit-1.2.0-py3-none-any.whl
| Download URL | segment_toolkit-1.2.0-py3-none-any.whl |
|---|---|
| Size | 28.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a5919ca1f4131f9757bc659ea9cc207c030c095133217f67f6e7be7e9cd8f72e
|
|
BLAKE2b-256 checksum How to use checksums |
2a4b0055fe8513dc10e51b9ea6cfcdc3805a359d75c5b9650f90b5d6bd4e33e1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.12
|
Security for segment-toolkit 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.