segment-toolkit 1.0.0__py3-none-any.whl

segment_toolkit/__init__.py

@@ -0,0 +1,60 @@
+"""
+Segment Toolkit: A library and CLI tool for converting binary segmentation masks to YOLO labels and vice versa.
+"""
+
+__version__ = "1.0.0"
+
+import sys
+import subprocess
+
+def _ensure_dependencies():
+    """
+    Checks for required external modules and attempts to install them via pip if missing.
+    """
+    dependencies = {
+        "numpy": "numpy",
+        "cv2": "opencv-python",
+        "PIL": "pillow",
+        "pandas": "pandas",
+        "matplotlib": "matplotlib"
+    }
+    missing = []
+    for module, pip_name in dependencies.items():
+        try:
+            __import__(module)
+        except ImportError:
+            missing.append(pip_name)
+            
+    if missing:
+        print(f"[segment_toolkit] Missing required package(s): {', '.join(missing)}", file=sys.stderr)
+        print("[segment_toolkit] Attempting to auto-install dependencies...", file=sys.stderr)
+        try:
+            subprocess.check_call([sys.executable, "-m", "pip", "install", *missing])
+            print("[segment_toolkit] Dependencies installed successfully.", file=sys.stderr)
+        except Exception as err:
+            print(f"[segment_toolkit] Error: Auto-installation of dependencies failed: {err}", file=sys.stderr)
+            print("[segment_toolkit] Please install them manually using: pip install -r requirements.txt", file=sys.stderr)
+
+# Check and install dependencies before importing other submodules
+_ensure_dependencies()
+
+from .source import MaskToYoloConverter, YoloToMaskConverter
+from .helpers import (
+    safe_read_image,
+    preprocess_image,
+    get_largest_contour,
+    calculate_bbox,
+    normalize_coordinates,
+    denormalize_coordinates,
+)
+
+__all__ = [
+    "MaskToYoloConverter",
+    "YoloToMaskConverter",
+    "safe_read_image",
+    "preprocess_image",
+    "get_largest_contour",
+    "calculate_bbox",
+    "normalize_coordinates",
+    "denormalize_coordinates",
+]

segment_toolkit/cli.py

@@ -0,0 +1,192 @@
+"""
+Command Line Interface (CLI) for segment_toolkit.
+Exposes mask-to-yolo, yolo-to-mask, split, and visualize commands.
+"""
+
+import argparse
+import sys
+import logging
+from typing import List, Optional
+
+from .source import MaskToYoloConverter, YoloToMaskConverter
+
+# Configure basic logging
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+logger = logging.getLogger(__name__)
+
+
+def parse_args(args: List[str]) -> argparse.Namespace:
+    """
+    Parses command-line arguments.
+    """
+    parser = argparse.ArgumentParser(
+        description="Segment Toolkit: Convert segmentation masks to/from YOLO format annotations."
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True, help="Subcommands")
+
+    # subcommand: mask-to-yolo
+    m2y_parser = subparsers.add_parser(
+        "mask-to-yolo", help="Convert binary mask(s) to YOLO format labels."
+    )
+    m2y_parser.add_argument("--image", type=str, help="Path to a single input image.")
+    m2y_parser.add_argument("--mask", type=str, help="Path to a single input binary mask.")
+    m2y_parser.add_argument("--output-txt", type=str, help="Output file path for single YOLO label txt.")
+    
+    m2y_parser.add_argument("--image-dir", type=str, help="Directory containing input images.")
+    m2y_parser.add_argument("--mask-dir", type=str, help="Directory containing input masks.")
+    m2y_parser.add_argument("--output-dir", type=str, help="Directory to save generated YOLO label files.")
+
+    m2y_parser.add_argument("--class-id", type=int, default=0, help="Default Class ID to write (default: 0).")
+    m2y_parser.add_argument(
+        "--ground-truth",
+        type=str,
+        help="Path to GroundTruth.csv mapping images to multi-class columns.",
+    )
+    m2y_parser.add_argument(
+        "--rotated",
+        action="store_true",
+        help="Use rotated minimum area rectangle (minAreaRect) instead of axis-aligned.",
+    )
+    m2y_parser.add_argument(
+        "--resize",
+        type=int,
+        nargs=2,
+        default=[640, 640],
+        metavar=("WIDTH", "HEIGHT"),
+        help="Target dimensions for resizing (default: 640 640).",
+    )
+
+    # subcommand: yolo-to-mask
+    y2m_parser = subparsers.add_parser(
+        "yolo-to-mask", help="Convert YOLO format label(s) to binary mask(s)."
+    )
+    y2m_parser.add_argument("--label", type=str, help="Path to a single input YOLO label txt file.")
+    y2m_parser.add_argument("--output-mask", type=str, help="Output path for single binary mask png.")
+
+    y2m_parser.add_argument("--label-dir", type=str, help="Directory containing YOLO label txt files.")
+    y2m_parser.add_argument("--output-dir", type=str, help="Directory to save generated binary mask png files.")
+
+    y2m_parser.add_argument(
+        "--resize",
+        type=int,
+        nargs=2,
+        default=[640, 640],
+        metavar=("WIDTH", "HEIGHT"),
+        help="Output mask dimensions (default: 640 640).",
+    )
+
+    # subcommand: split
+    split_parser = subparsers.add_parser(
+        "split", help="Randomly split a dataset of images and labels into train/test subfolders."
+    )
+    split_parser.add_argument("--images", type=str, required=True, help="Directory of source images.")
+    split_parser.add_argument("--labels", type=str, required=True, help="Directory of source YOLO label txt files.")
+    split_parser.add_argument("--output", type=str, required=True, help="Root directory for split dataset outputs.")
+    split_parser.add_argument(
+        "--ratio", type=float, default=0.8, help="Split ratio for training partition (default: 0.8)."
+    )
+    split_parser.add_argument("--seed", type=int, default=42, help="Seed value for reproduction (default: 42).")
+
+    # subcommand: visualize
+    vis_parser = subparsers.add_parser(
+        "visualize", help="Draw bounding boxes from a YOLO label file onto the source image."
+    )
+    vis_parser.add_argument("--image", type=str, required=True, help="Path to the source image.")
+    vis_parser.add_argument("--label", type=str, required=True, help="Path to the YOLO label file.")
+    vis_parser.add_argument("--output", type=str, required=True, help="Path to save output visualization image.")
+    vis_parser.add_argument(
+        "--resize",
+        type=int,
+        nargs=2,
+        default=[640, 640],
+        metavar=("WIDTH", "HEIGHT"),
+        help="Resize image for visualization (default: 640 640).",
+    )
+
+    return parser.parse_args(args)
+
+
+def main(args: Optional[List[str]] = None) -> int:
+    """
+    Main entry point for command-line execution.
+    """
+    if args is None:
+        args = sys.argv[1:]
+
+    try:
+        parsed = parse_args(args)
+
+        if parsed.command == "mask-to-yolo":
+            converter = MaskToYoloConverter(
+                target_size=(parsed.resize[0], parsed.resize[1]),
+                bbox_type="rotated" if parsed.rotated else "standard",
+            )
+            # Check if processing single file or folder
+            if parsed.image or parsed.mask or parsed.output_txt:
+                if not (parsed.image and parsed.mask and parsed.output_txt):
+                    logger.error("Error: --image, --mask, and --output-txt must all be specified for single conversion.")
+                    return 1
+                success = converter.convert_single(
+                    parsed.image, parsed.mask, parsed.output_txt, class_id=parsed.class_id
+                )
+                return 0 if success else 1
+            elif parsed.image_dir or parsed.mask_dir or parsed.output_dir:
+                if not (parsed.image_dir and parsed.mask_dir and parsed.output_dir):
+                    logger.error("Error: --image-dir, --mask-dir, and --output-dir must all be specified for folder conversion.")
+                    return 1
+                converter.convert_dataset(
+                    parsed.image_dir,
+                    parsed.mask_dir,
+                    parsed.output_dir,
+                    default_class_id=parsed.class_id,
+                    ground_truth=parsed.ground_truth,
+                )
+                return 0
+            else:
+                logger.error("Error: Must specify either single file arguments (--image, --mask, --output-txt) or directory arguments (--image-dir, --mask-dir, --output-dir).")
+                return 1
+
+        elif parsed.command == "yolo-to-mask":
+            converter = YoloToMaskConverter(target_size=(parsed.resize[0], parsed.resize[1]))
+            if parsed.label or parsed.output_mask:
+                if not (parsed.label and parsed.output_mask):
+                    logger.error("Error: Both --label and --output-mask must be specified for single conversion.")
+                    return 1
+                success = converter.convert_single(parsed.label, parsed.output_mask)
+                return 0 if success else 1
+            elif parsed.label_dir or parsed.output_dir:
+                if not (parsed.label_dir and parsed.output_dir):
+                    logger.error("Error: Both --label-dir and --output-dir must be specified for folder conversion.")
+                    return 1
+                converter.convert_dataset(parsed.label_dir, parsed.output_dir)
+                return 0
+            else:
+                logger.error("Error: Must specify either single file arguments (--label, --output-mask) or directory arguments (--label-dir, --output-dir).")
+                return 1
+
+        elif parsed.command == "split":
+            converter = MaskToYoloConverter()
+            converter.split_dataset(
+                images_dir=parsed.images,
+                labels_dir=parsed.labels,
+                output_dataset_dir=parsed.output,
+                split_ratio=parsed.ratio,
+                seed=parsed.seed,
+            )
+            return 0
+
+        elif parsed.command == "visualize":
+            converter = YoloToMaskConverter(target_size=(parsed.resize[0], parsed.resize[1]))
+            success = converter.visualize_label(parsed.image, parsed.label, parsed.output)
+            return 0 if success else 1
+
+    except Exception as e:
+        logger.error(f"Execution failed: {str(e)}")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

segment_toolkit/helpers.py

@@ -0,0 +1,201 @@
+"""
+Helper utilities for segment_toolkit.
+Provides image preprocessing, contour extraction, bounding box computation,
+coordinate normalization, and visualization helpers.
+"""
+
+import os
+from typing import Tuple, Optional, Union
+import cv2
+import numpy as np
+
+
+def safe_read_image(path: Union[str, os.PathLike]) -> np.ndarray:
+    """
+    Safely reads an image using OpenCV and handles errors.
+
+    Args:
+        path: Path to the image file.
+
+    Returns:
+        np.ndarray: The loaded image array.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the file is not a valid image.
+    """
+    path_str = str(path)
+    if not os.path.exists(path_str):
+        raise FileNotFoundError(f"Image file not found: {path_str}")
+
+    try:
+        image = cv2.imread(path_str)
+        if image is None:
+            raise ValueError(f"Failed to decode image: {path_str}")
+        return image
+    except Exception as e:
+        raise ValueError(f"Error reading image {path_str}: {str(e)}") from e
+
+
+def preprocess_image(image: np.ndarray, target_size: Tuple[int, int], is_mask: bool = False) -> np.ndarray:
+    """
+    Resizes image/mask to target size.
+    Uses linear interpolation for images and nearest-neighbor for masks to keep values binary.
+
+    Args:
+        image: Input image array.
+        target_size: Target (width, height).
+        is_mask: Flag indicating if input is a binary mask.
+
+    Returns:
+        np.ndarray: The preprocessed image/mask.
+    """
+    try:
+        interpolation = cv2.INTER_NEAREST if is_mask else cv2.INTER_LINEAR
+        resized = cv2.resize(image, target_size, interpolation=interpolation)
+        return resized
+    except Exception as e:
+        raise RuntimeError(f"Failed to preprocess/resize image: {str(e)}") from e
+
+
+def get_largest_contour(mask: np.ndarray) -> Optional[np.ndarray]:
+    """
+    Finds the contours of the binary mask and returns the largest one by area.
+
+    Args:
+        mask: Grayscale binary mask array.
+
+    Returns:
+        Optional[np.ndarray]: The largest contour array, or None if no contours are found.
+    """
+    try:
+        # Ensure mask is grayscale / single channel
+        if len(mask.shape) == 3:
+            mask = cv2.cvtColor(mask, cv2.COLOR_BGR2GRAY)
+
+        # Threshold to ensure binary mask
+        _, binary = cv2.threshold(mask, 127, 255, cv2.THRESH_BINARY)
+
+        contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        if not contours:
+            return None
+
+        # Return the contour with maximum area
+        return max(contours, key=cv2.contourArea)
+    except Exception as e:
+        raise RuntimeError(f"Error extracting contour from mask: {str(e)}") from e
+
+
+def calculate_bbox(contour: np.ndarray, bbox_type: str = "standard") -> Tuple[float, float, float, float]:
+    """
+    Calculates center-based bounding box from a contour.
+
+    Args:
+        contour: Contour points array.
+        bbox_type: Type of bounding box, either 'standard' or 'rotated'.
+
+    Returns:
+        Tuple[float, float, float, float]: (x_center, y_center, w, h) in pixel coordinates.
+    """
+    try:
+        if bbox_type == "rotated":
+            # minAreaRect returns ((center_x, center_y), (width, height), angle)
+            rect = cv2.minAreaRect(contour)
+            (x_center, y_center), (w, h), _ = rect
+            return float(x_center), float(y_center), float(w), float(h)
+        else:
+            # boundingRect returns (x_min, y_min, w, h)
+            x_min, y_min, w, h = cv2.boundingRect(contour)
+            x_center = x_min + w / 2.0
+            y_center = y_min + h / 2.0
+            return float(x_center), float(y_center), float(w), float(h)
+    except Exception as e:
+        raise RuntimeError(f"Error calculating bounding box: {str(e)}") from e
+
+
+def normalize_coordinates(
+    x: float, y: float, w: float, h: float, img_width: int, img_height: int
+) -> Tuple[float, float, float, float]:
+    """
+    Normalizes pixel bounding box coordinates to [0, 1] relative to image dimensions.
+
+    Args:
+        x: Center x pixel.
+        y: Center y pixel.
+        w: Width pixel.
+        h: Height pixel.
+        img_width: Image width.
+        img_height: Image height.
+
+    Returns:
+        Tuple[float, float, float, float]: (x_norm, y_norm, w_norm, h_norm).
+    """
+    x_norm = x / img_width
+    y_norm = y / img_height
+    w_norm = w / img_width
+    h_norm = h / img_height
+
+    # Clamp to [0, 1] to stay within image bounds
+    x_norm = max(0.0, min(1.0, x_norm))
+    y_norm = max(0.0, min(1.0, y_norm))
+    w_norm = max(0.0, min(1.0, w_norm))
+    h_norm = max(0.0, min(1.0, h_norm))
+
+    return x_norm, y_norm, w_norm, h_norm
+
+
+def denormalize_coordinates(
+    x_norm: float, y_norm: float, w_norm: float, h_norm: float, img_width: int, img_height: int
+) -> Tuple[int, int, int, int]:
+    """
+    Converts normalized center-based coordinates to pixel-space top-left and bottom-right corners.
+
+    Args:
+        x_norm: Normalized center x.
+        y_norm: Normalized center y.
+        w_norm: Normalized width.
+        h_norm: Normalized height.
+        img_width: Target image width.
+        img_height: Target image height.
+
+    Returns:
+        Tuple[int, int, int, int]: (x1, y1, x2, y2) pixel corners.
+    """
+    x_center = x_norm * img_width
+    y_center = y_norm * img_height
+    w = w_norm * img_width
+    h = h_norm * img_height
+
+    x1 = int(x_center - w / 2)
+    y1 = int(y_center - h / 2)
+    x2 = int(x_center + w / 2)
+    y2 = int(y_center + h / 2)
+
+    # Clamp coordinates to image boundaries
+    x1 = max(0, min(img_width - 1, x1))
+    y1 = max(0, min(img_height - 1, y1))
+    x2 = max(0, min(img_width - 1, x2))
+    y2 = max(0, min(img_height - 1, y2))
+
+    return x1, y1, x2, y2
+
+
+def draw_bbox_on_image(
+    image: np.ndarray, bbox: Tuple[int, int, int, int], color: Tuple[int, int, int] = (0, 255, 255), thickness: int = 2
+) -> np.ndarray:
+    """
+    Draws a bounding box on the image.
+
+    Args:
+        image: Image array.
+        bbox: (x1, y1, x2, y2) pixel coordinates.
+        color: Box color in BGR/RGB (default: yellow).
+        thickness: Box border thickness.
+
+    Returns:
+        np.ndarray: Image with box drawn.
+    """
+    x1, y1, x2, y2 = bbox
+    cv2.rectangle(image, (x1, y1), (x2, y2), color, thickness)
+    return image
+

segment_toolkit/source.py

@@ -0,0 +1,566 @@
+"""
+Core conversion classes for segment_toolkit.
+Includes MaskToYoloConverter and YoloToMaskConverter.
+"""
+
+import os
+import shutil
+import random
+import logging
+from typing import Tuple, Optional, Dict, List, Union
+import numpy as np
+import pandas as pd
+from PIL import Image
+import cv2
+
+from .helpers import (
+    safe_read_image,
+    preprocess_image,
+    get_largest_contour,
+    calculate_bbox,
+    normalize_coordinates,
+    denormalize_coordinates,
+    draw_bbox_on_image,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MaskToYoloConverter:
+    """
+    Converts binary segmentation masks into YOLO bounding box labels.
+    Supports single file conversion, full dataset directory batch conversion,
+    ground truth CSV classification mapping, and train/test dataset splitting.
+    """
+
+    def __init__(self, target_size: Tuple[int, int] = (640, 640), bbox_type: str = "standard"):
+        """
+        Initialize the converter.
+
+        Args:
+            target_size: Dimensions (width, height) to resize images and masks to.
+            bbox_type: Bounding box style, either 'standard' or 'rotated'.
+        """
+        self.target_size = target_size
+        self.bbox_type = bbox_type
+
+    def convert_single(
+        self, image_path: str, mask_path: str, output_txt_path: str, class_id: int = 0
+    ) -> bool:
+        """
+        Convert a single image and mask pair into a YOLO bounding box label file.
+
+        Args:
+            image_path: Path to the input image.
+            mask_path: Path to the input binary mask.
+            output_txt_path: Path to save the output YOLO text file.
+            class_id: The class ID to write to the label file.
+
+        Returns:
+            bool: True if successful, False otherwise.
+        """
+        try:
+            # Read image to obtain original shape
+            image = safe_read_image(image_path)
+            orig_h, orig_w = image.shape[:2]
+
+            # Read and process mask
+            mask = safe_read_image(mask_path)
+            
+            # Preprocess image and mask to the target size
+            resized_image = preprocess_image(image, self.target_size, is_mask=False)
+            resized_mask = preprocess_image(mask, self.target_size, is_mask=True)
+
+            # Get contour from the resized mask
+            contour = get_largest_contour(resized_mask)
+            if contour is None:
+                logger.warning(f"No contour/objects found in mask: {mask_path}")
+                return False
+
+            # Calculate bbox on resized coordinates
+            x_center, y_center, w, h = calculate_bbox(contour, bbox_type=self.bbox_type)
+
+            # Normalize coordinates using the target dimensions
+            x_norm, y_norm, w_norm, h_norm = normalize_coordinates(
+                x_center, y_center, w, h, self.target_size[0], self.target_size[1]
+            )
+
+            # Ensure output directory exists
+            os.makedirs(os.path.dirname(os.path.abspath(output_txt_path)), exist_ok=True)
+
+            # Write to YOLO label format (class_id center_x center_y width height)
+            # Use 'w' to overwrite or write fresh, or 'a+' depending on use case.
+            # Here we write single bounding box per file, so 'w' is appropriate.
+            with open(output_txt_path, "w", encoding="utf-8") as f:
+                f.write(f"{class_id} {x_norm:.6f} {y_norm:.6f} {w_norm:.6f} {h_norm:.6f}\n")
+
+            logger.info(f"Successfully generated label: {output_txt_path}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to convert mask {mask_path} to YOLO label: {str(e)}")
+            return False
+
+    def _load_ground_truth(self, file_path: str) -> Dict[str, int]:
+        """
+        Parses a CSV or JSON file and maps image filename/ID to class ID (int).
+        """
+        import json
+        class_lookup = {}
+        isic_mapping = {
+            "AKIEC": 0,
+            "BCC": 1,
+            "BKL": 2,
+            "DF": 3,
+            "MEL": 4,
+            "NV": 5,
+            "VASC": 6,
+        }
+
+        # Helper to extract class ID from nested indicators
+        def get_class_id_from_indicators(indicators: dict) -> int:
+            for col, val in indicators.items():
+                if val == 1 or val == 1.0 or str(val).strip() == "1":
+                    if col in isic_mapping:
+                        return isic_mapping[col]
+            for key in ["class_id", "class", "label"]:
+                if key in indicators:
+                    v = indicators[key]
+                    if isinstance(v, int):
+                        return v
+                    elif str(v).isdigit():
+                        return int(v)
+                    elif str(v) in isic_mapping:
+                        return isic_mapping[str(v)]
+            return 0
+
+        if file_path.endswith(".json"):
+            logger.info(f"Parsing ground truth metadata JSON: {file_path}")
+            with open(file_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+
+            if isinstance(data, dict):
+                for img_id, val in data.items():
+                    img_id = str(img_id).strip()
+                    if isinstance(val, dict):
+                        class_lookup[img_id] = get_class_id_from_indicators(val)
+                    elif isinstance(val, int):
+                        class_lookup[img_id] = val
+                    elif str(val).isdigit():
+                        class_lookup[img_id] = int(val)
+                    elif str(val) in isic_mapping:
+                        class_lookup[img_id] = isic_mapping[str(val)]
+                    else:
+                        class_lookup[img_id] = 0
+            elif isinstance(data, list):
+                for item in data:
+                    if not isinstance(item, dict):
+                        continue
+                    keys = list(item.keys())
+                    if not keys:
+                        continue
+                    id_key = keys[0]
+                    for k in keys:
+                        if any(x in k.lower() for x in ["image", "file", "name", "id"]):
+                            id_key = k
+                            break
+                    img_id = str(item[id_key]).strip()
+                    remaining = {k: v for k, v in item.items() if k != id_key}
+                    class_lookup[img_id] = get_class_id_from_indicators(remaining)
+        else:
+            logger.info(f"Parsing ground truth metadata CSV: {file_path}")
+            df = pd.read_csv(file_path)
+            id_col = df.columns[0]
+            class_cols = list(df.columns[1:])
+
+            col_to_class = {}
+            for col in class_cols:
+                if col in isic_mapping:
+                    col_to_class[col] = isic_mapping[col]
+                else:
+                    col_to_class[col] = len(col_to_class)
+
+            for _, row in df.iterrows():
+                img_id = str(row[id_col]).strip()
+                for col in class_cols:
+                    if row[col] == 1 or row[col] == 1.0 or str(row[col]).strip() == "1":
+                        class_lookup[img_id] = col_to_class[col]
+                        break
+        return class_lookup
+
+    def convert_dataset(
+        self,
+        images_dir: str,
+        masks_dir: str,
+        output_labels_dir: str,
+        default_class_id: int = 0,
+        ground_truth: Optional[str] = None,
+    ) -> int:
+        """
+        Batch convert a folder of masks into YOLO labels.
+
+        Args:
+            images_dir: Directory containing original images.
+            masks_dir: Directory containing binary masks.
+            output_labels_dir: Directory where YOLO labels will be written.
+            default_class_id: Class ID to use if no ground truth metadata is provided or matches.
+            ground_truth: Optional path to GroundTruth CSV or JSON mapping filenames to classes.
+
+        Returns:
+            int: Number of successfully generated label files.
+        """
+        try:
+            if not os.path.exists(images_dir):
+                raise FileNotFoundError(f"Images directory not found: {images_dir}")
+            if not os.path.exists(masks_dir):
+                raise FileNotFoundError(f"Masks directory not found: {masks_dir}")
+
+            os.makedirs(output_labels_dir, exist_ok=True)
+
+            # Parse Ground Truth CSV or JSON if provided
+            class_lookup = {}
+            if ground_truth:
+                class_lookup = self._load_ground_truth(ground_truth)
+
+            # Process files
+            success_count = 0
+            image_files = [
+                f
+                for f in os.listdir(images_dir)
+                if os.path.isfile(os.path.join(images_dir, f))
+                and f.lower().endswith((".jpg", ".jpeg", ".png", ".bmp"))
+            ]
+
+            logger.info(f"Found {len(image_files)} images to convert.")
+
+            for img_file in image_files:
+                base_name, ext = os.path.splitext(img_file)
+
+                # Attempt to find the mask file with common extension variants
+                mask_file = None
+                for mask_ext in [".png", ".jpg", ".jpeg", "_segmentation.png", "_mask.png"]:
+                    # Try matching base_name directly or with suffixes
+                    candidate1 = os.path.join(masks_dir, f"{base_name}{mask_ext}")
+                    candidate2 = os.path.join(masks_dir, f"{base_name}_segmentation{mask_ext}")
+                    candidate3 = os.path.join(masks_dir, f"{base_name.replace('_segmentation', '')}{mask_ext}")
+                    
+                    if os.path.exists(candidate1):
+                        mask_file = candidate1
+                        break
+                    elif os.path.exists(candidate2):
+                        mask_file = candidate2
+                        break
+                    elif os.path.exists(candidate3):
+                        mask_file = candidate3
+                        break
+
+                # If no direct match, check if image_file base name is related to any mask files
+                if not mask_file:
+                    # Search directory
+                    for m in os.listdir(masks_dir):
+                        if m.startswith(base_name) and m.lower().endswith((".png", ".jpg", ".jpeg")):
+                            mask_file = os.path.join(masks_dir, m)
+                            break
+
+                if not mask_file:
+                    logger.warning(f"No matching mask found for image: {img_file}")
+                    continue
+
+                # Determine Class ID
+                class_id = default_class_id
+                if ground_truth:
+                    # Match exact base name or try parts of the prefix
+                    if base_name in class_lookup:
+                        class_id = class_lookup[base_name]
+                    else:
+                        # Try prefix mapping (e.g. if CSV/JSON has ISIC_0024310 but filename is ISIC_0024310.jpg)
+                        matched = False
+                        for k, v in class_lookup.items():
+                            if base_name.startswith(k) or k.startswith(base_name):
+                                class_id = v
+                                matched = True
+                                break
+                        if not matched:
+                            logger.debug(f"Metadata not found in CSV/JSON for {base_name}. Using default Class ID {default_class_id}")
+
+                output_txt = os.path.join(output_labels_dir, f"{base_name}.txt")
+                if self.convert_single(
+                    os.path.join(images_dir, img_file), mask_file, output_txt, class_id=class_id
+                ):
+                    success_count += 1
+
+            logger.info(f"Dataset conversion completed. Generated {success_count} label files.")
+            return success_count
+
+        except Exception as e:
+            logger.error(f"Error during dataset batch conversion: {str(e)}")
+            raise
+
+    def split_dataset(
+        self,
+        images_dir: str,
+        labels_dir: str,
+        output_dataset_dir: str,
+        split_ratio: float = 0.8,
+        seed: int = 42,
+    ) -> Dict[str, int]:
+        """
+        Splits images and labels into train/test splits under the output directory.
+        Generates standard YOLO data.yaml configuration.
+
+        Args:
+            images_dir: Directory containing images.
+            labels_dir: Directory containing generated text labels.
+            output_dataset_dir: Root output directory for structured dataset.
+            split_ratio: Percentage of data allocated for training (default: 0.8).
+            seed: Random seed for reproducibility.
+
+        Returns:
+            Dict[str, int]: Dictionary with counts of train and test images.
+        """
+        try:
+            random.seed(seed)
+
+            if not os.path.exists(images_dir):
+                raise FileNotFoundError(f"Images directory not found: {images_dir}")
+            if not os.path.exists(labels_dir):
+                raise FileNotFoundError(f"Labels directory not found: {labels_dir}")
+
+            # Collect valid image files that have matching label files
+            valid_pairs = []
+            image_files = os.listdir(images_dir)
+            for img_file in image_files:
+                base_name, _ = os.path.splitext(img_file)
+                label_file = f"{base_name}.txt"
+                if os.path.exists(os.path.join(labels_dir, label_file)):
+                    valid_pairs.append((img_file, label_file))
+                else:
+                    logger.warning(f"Skipping split for {img_file}: label file {label_file} not found.")
+
+            if not valid_pairs:
+                raise ValueError("No matching image and label file pairs found to split.")
+
+            random.shuffle(valid_pairs)
+            split_idx = int(len(valid_pairs) * split_ratio)
+            train_pairs = valid_pairs[:split_idx]
+            test_pairs = valid_pairs[split_idx:]
+
+            # Establish folders
+            for split in ["train", "test"]:
+                os.makedirs(os.path.join(output_dataset_dir, split, "images"), exist_ok=True)
+                os.makedirs(os.path.join(output_dataset_dir, split, "labels"), exist_ok=True)
+
+            def copy_pairs(pairs: List[Tuple[str, str]], split: str):
+                for img, lbl in pairs:
+                    shutil.copy2(os.path.join(images_dir, img), os.path.join(output_dataset_dir, split, "images", img))
+                    shutil.copy2(os.path.join(labels_dir, lbl), os.path.join(output_dataset_dir, split, "labels", lbl))
+
+            copy_pairs(train_pairs, "train")
+            copy_pairs(test_pairs, "test")
+
+            # Collect unique classes to build configuration yaml
+            # In YOLO format, we can read classes to set nc and names automatically
+            unique_classes = set()
+            for _, lbl in valid_pairs:
+                try:
+                    with open(os.path.join(labels_dir, lbl), "r", encoding="utf-8") as f:
+                        for line in f:
+                            parts = line.strip().split()
+                            if parts:
+                                unique_classes.add(int(parts[0]))
+                except Exception:
+                    pass
+
+            num_classes = max(unique_classes) + 1 if unique_classes else 1
+            # Standard class names
+            class_names = [f"class_{i}" for i in range(num_classes)]
+            # If standard ISIC classes, rename them
+            if num_classes == 7:
+                class_names = ["AKIEC", "BCC", "BKL", "DF", "MEL", "NV", "VASC"]
+
+            yaml_path = os.path.join(output_dataset_dir, "data.yaml")
+            with open(yaml_path, "w", encoding="utf-8") as yaml_file:
+                yaml_file.write(f"train: ./train/images\n")
+                yaml_file.write(f"val: ./test/images\n")
+                yaml_file.write(f"test: ./test/images\n\n")
+                yaml_file.write(f"nc: {num_classes}\n")
+                yaml_file.write(f"names: {class_names}\n")
+
+            logger.info(f"Splitting done. Train: {len(train_pairs)}, Test: {len(test_pairs)}.")
+            return {"train": len(train_pairs), "test": len(test_pairs)}
+
+        except Exception as e:
+            logger.error(f"Error splitting dataset: {str(e)}")
+            raise
+
+
+class YoloToMaskConverter:
+    """
+    Converts YOLO format bounding box label files back into binary segmentation masks.
+    Supports single file generation, batch directory conversion, and bbox overlay visualization.
+    """
+
+    def __init__(self, target_size: Tuple[int, int] = (640, 640)):
+        """
+        Initialize the converter.
+
+        Args:
+            target_size: Target mask dimensions (width, height) to generate.
+        """
+        self.target_size = target_size
+
+    def convert_single(self, label_path: str, output_mask_path: str) -> bool:
+        """
+        Create a binary mask image from a YOLO label file.
+
+        Args:
+            label_path: Path to the input YOLO label text file.
+            output_mask_path: Path to save the generated PNG mask.
+
+        Returns:
+            bool: True if successful, False otherwise.
+        """
+        try:
+            if not os.path.exists(label_path):
+                raise FileNotFoundError(f"Label file not found: {label_path}")
+
+            # Create empty black canvas mask
+            mask = np.zeros((self.target_size[1], self.target_size[0]), dtype=np.uint8)
+            img_w, img_h = self.target_size
+
+            has_drawn = False
+            with open(label_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    parts = line.split()
+                    if len(parts) != 5:
+                        logger.warning(f"Malformed label line in {label_path}: '{line}'")
+                        continue
+
+                    # Parse values
+                    class_id = int(parts[0])
+                    x_norm, y_norm, w_norm, h_norm = map(float, parts[1:])
+
+                    # Denormalize coordinates to top-left and bottom-right corners
+                    x1, y1, x2, y2 = denormalize_coordinates(
+                        x_norm, y_norm, w_norm, h_norm, img_w, img_h
+                    )
+
+                    # Draw solid rectangle on mask canvas
+                    if x1 < x2 and y1 < y2:
+                        cv2.rectangle(mask, (x1, y1), (x2, y2), 255, thickness=-1)
+                        has_drawn = True
+                    else:
+                        logger.warning(f"Invalid bounding box in {label_path}: ({x1}, {y1}) to ({x2}, {y2})")
+
+            # Save mask file
+            os.makedirs(os.path.dirname(os.path.abspath(output_mask_path)), exist_ok=True)
+            mask_img = Image.fromarray(mask)
+            mask_img.save(output_mask_path)
+
+            if not has_drawn:
+                logger.warning(f"No bounding boxes were drawn to mask: {output_mask_path}")
+
+            logger.info(f"Successfully generated mask: {output_mask_path}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to convert label {label_path} to mask: {str(e)}")
+            return False
+
+    def convert_dataset(self, labels_dir: str, output_masks_dir: str) -> int:
+        """
+        Batch convert a folder of YOLO label text files into binary mask images.
+
+        Args:
+            labels_dir: Directory containing YOLO text label files.
+            output_masks_dir: Directory where binary masks will be saved.
+
+        Returns:
+            int: Number of masks successfully converted.
+        """
+        try:
+            if not os.path.exists(labels_dir):
+                raise FileNotFoundError(f"Labels directory not found: {labels_dir}")
+
+            os.makedirs(output_masks_dir, exist_ok=True)
+
+            label_files = [f for f in os.listdir(labels_dir) if f.endswith(".txt")]
+            success_count = 0
+
+            for lbl in label_files:
+                base_name = os.path.splitext(lbl)[0]
+                output_mask = os.path.join(output_masks_dir, f"{base_name}.png")
+                if self.convert_single(os.path.join(labels_dir, lbl), output_mask):
+                    success_count += 1
+
+            logger.info(f"Dataset conversion completed. Generated {success_count} masks.")
+            return success_count
+
+        except Exception as e:
+            logger.error(f"Error during label dataset conversion: {str(e)}")
+            raise
+
+    def visualize_label(self, image_path: str, label_path: str, output_image_path: str) -> bool:
+        """
+        Overlays bounding box coordinates from a YOLO label onto the original image.
+
+        Args:
+            image_path: Path to input image.
+            label_path: Path to YOLO label file.
+            output_image_path: Path to save the visualized image output.
+
+        Returns:
+            bool: True if success, False otherwise.
+        """
+        try:
+            image = safe_read_image(image_path)
+            # Standardize image size for visualization matching target size
+            resized_image = preprocess_image(image, self.target_size, is_mask=False)
+            img_w, img_h = self.target_size
+
+            if not os.path.exists(label_path):
+                logger.warning(f"Label file not found for visualization: {label_path}")
+                return False
+
+            with open(label_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    parts = line.split()
+                    if len(parts) != 5:
+                        continue
+
+                    class_id = int(parts[0])
+                    x_norm, y_norm, w_norm, h_norm = map(float, parts[1:])
+
+                    # Convert coordinates
+                    x1, y1, x2, y2 = denormalize_coordinates(
+                        x_norm, y_norm, w_norm, h_norm, img_w, img_h
+                    )
+
+                    # Draw bounding box
+                    cv2.rectangle(resized_image, (x1, y1), (x2, y2), (0, 255, 255), 2)
+                    # Label background
+                    label_text = f"Class {class_id}"
+                    cv2.putText(
+                        resized_image,
+                        label_text,
+                        (x1, max(y1 - 10, 15)),
+                        cv2.FONT_HERSHEY_SIMPLEX,
+                        0.5,
+                        (0, 255, 255),
+                        1,
+                    )
+
+            os.makedirs(os.path.dirname(os.path.abspath(output_image_path)), exist_ok=True)
+            cv2.imwrite(output_image_path, resized_image)
+            logger.info(f"Saved visualization overlay to: {output_image_path}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Error visualizing label {label_path}: {str(e)}")
+            return False

segment_toolkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: segment_toolkit
+Version: 1.0.0
+Summary: A Python toolkit to convert between binary segmentation masks and YOLO labels
+Author: Antigravity
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: pillow
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Segment Toolkit 🛠️
+
+A modern, robust, and premium Python package designed to bridge the gap between pixel-level **binary segmentation masks** and **YOLO bounding box labels**. It provides a bidirectional pipeline with exception handling, extensive logging, a command-line interface (CLI), and a Python API.
+
+---
+
+## 📌 Features
+
+- **Bidirectional Conversion**:
+  - **Forward Pipeline**: Convert binary masks to YOLO format labels (supports standard axis-aligned or advanced minimum area rotated bounding boxes).
+  - **Reverse Pipeline**: Reconstruct binary masks from YOLO labels.
+- **Automatic Dependency Installer**: Missing required packages (`numpy`, `opencv-python`, `pillow`, `pandas`, `matplotlib`) are automatically detected and installed via `pip` upon package import or script execution.
+- **Robust Exception Handling**: Try-catch blocks wrapped around file I/O, contour finding, and resizing to prevent application crashes on corrupted or missing files.
+- **Dynamic Dataset Matching**: Read classification mappings (in **CSV** or **JSON** format) to automatically assign multi-class IDs matching standard dataset schemas (like the ISIC dataset).
+- **YOLO Dataset Splitting**: Automatically shuffles and partitions images & labels into training and testing sets with customizable split ratios, creating standard `data.yaml` configs.
+- **Overlay Visualizer**: Overlay bounding boxes and class indicators directly onto source images for annotation inspection.
+- **Dual Interface**: Use as a command-line application (`segment-toolkit`) or import as a Python library (`import segment_toolkit`).
+
+---
+
+## 📂 Installation
+
+To install the toolkit locally in editable mode (missing dependencies will install automatically):
+
+```bash
+pip install -e .
+```
+
+### Manual Installation
+If you prefer to install dependencies manually before installing the toolkit:
+
+```bash
+pip install -r requirements.txt
+pip install .
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Command Line Interface (CLI)
+
+The package installs a console script called `segment-toolkit`.
+
+#### Convert Masks to YOLO Labels
+- **Single File Conversion**:
+  ```bash
+  segment-toolkit mask-to-yolo \
+    --image images/ISIC_0024310.jpg \
+    --mask mask/ISIC_0024310_segmentation.png \
+    --output-txt labels/ISIC_0024310.txt \
+    --class-id 4
+  ```
+
+- **Batch Directory Conversion**:
+  ```bash
+  segment-toolkit mask-to-yolo \
+    --image-dir images/ \
+    --mask-dir mask/ \
+    --output-dir labels/ \
+    --ground-truth GroundTruth.csv
+  ```
+
+- **Options**:
+  - `--rotated`: Use rotated minimum area rectangles (`cv2.minAreaRect`) instead of standard axis-aligned rectangles.
+  - `--resize WIDTH HEIGHT`: Set target size for image and mask resizing (default: `640 640`).
+
+#### Convert YOLO Labels to Masks
+- **Single File Conversion**:
+  ```bash
+  segment-toolkit yolo-to-mask \
+    --label labels/ISIC_0024310.txt \
+    --output-mask masks_reconstructed/ISIC_0024310_segmentation.png
+  ```
+
+- **Batch Directory Conversion**:
+  ```bash
+  segment-toolkit yolo-to-mask \
+    --label-dir labels/ \
+    --output-dir masks_reconstructed/
+  ```
+
+#### Visualize Bounding Boxes
+Draw YOLO labels on top of the original image:
+```bash
+segment-toolkit visualize \
+  --image images/ISIC_0024310.jpg \
+  --label labels/ISIC_0024310.txt \
+  --output visualization.png
+```
+
+#### Split Dataset
+Organize folders into YOLO-compliant structure (`dataset/train` and `dataset/test` splits) and output `data.yaml`:
+```bash
+segment-toolkit split \
+  --images images/ \
+  --labels labels/ \
+  --output dataset/ \
+  --ratio 0.8 \
+  --seed 42
+```
+
+---
+
+### 2. Ground Truth Formats
+
+The `--ground-truth` parameter in batch conversion supports both CSV and JSON formats.
+
+#### CSV Format
+Assumes the first column contains the image identifier/filename, and the subsequent columns represent binary indicator classes (where `1` indicates class presence).
+Example `GroundTruth.csv`:
+```csv
+image,MEL,NV,BCC,AKIEC,BKL,DF,VASC
+ISIC_0024306,0,1,0,0,0,0,0
+ISIC_0024310,1,0,0,0,0,0,0
+```
+
+#### JSON Format
+Supports three distinct schemas:
+
+1. **Flat Dictionary (Format A)**:
+   Maps image IDs directly to class integers or class name strings.
+   ```json
+   {
+     "ISIC_0024306": 5,
+     "ISIC_0024310": "MEL"
+   }
+   ```
+
+2. **Nested Indicators (Format B)**:
+   Maps image IDs to dictionaries of binary class indicators.
+   ```json
+   {
+     "ISIC_0024306": { "MEL": 0, "NV": 1, "BCC": 0 },
+     "ISIC_0024310": { "MEL": 1, "NV": 0, "BCC": 0 }
+   }
+   ```
+
+3. **List of Records (Format C)**:
+   A list of objects containing image IDs and class descriptors.
+   ```json
+   [
+     { "image": "ISIC_0024306", "class_id": 5 },
+     { "image": "ISIC_0024310", "MEL": 1, "NV": 0 }
+   ]
+   ```
+
+*Note: Class name strings (like `"MEL"`, `"NV"`) are automatically mapped to standard ISIC IDs (`AKIEC=0, BCC=1, BKL=2, DF=3, MEL=4, NV=5, VASC=6`). Custom column names default to index-based IDs.*
+
+---
+
+### 3. Python API
+
+Import classes directly into your code to programmatically build custom pipelines:
+
+```python
+from segment_toolkit import MaskToYoloConverter, YoloToMaskConverter
+
+# 1. Convert mask to YOLO label
+yolo_conv = MaskToYoloConverter(target_size=(640, 640), bbox_type="standard")
+yolo_conv.convert_single(
+    image_path="images/ISIC_0024310.jpg",
+    mask_path="mask/ISIC_0024310_segmentation.png",
+    output_txt_path="labels/ISIC_0024310.txt",
+    class_id=4
+)
+
+# 2. Batch convert a folder of masks with a JSON ground truth
+yolo_conv.convert_dataset(
+    images_dir="images",
+    masks_dir="mask",
+    output_labels_dir="labels",
+    ground_truth="GroundTruth.json"
+)
+```
+
+---
+
+## 🧠 Technical Details
+
+### Coordinate Conversion Math
+
+#### Bounding Box Center Calculation (Pixel Space)
+For standard bounding boxes, the pixel coordinates from `boundingRect` are $(x_{min}, y_{min}, w_{pixel}, h_{pixel})$.
+$$\text{Center } X \quad x_{center} = x_{min} + \frac{w_{pixel}}{2.0}$$
+$$\text{Center } Y \quad y_{center} = y_{min} + \frac{h_{pixel}}{2.0}$$
+
+#### Coordinate Normalization (YOLO Format)
+All coordinates are normalized to the range $[0.0, 1.0]$:
+$$x_{norm} = \frac{x_{center}}{img\_width}, \quad y_{norm} = \frac{y_{center}}{img\_height}$$
+$$w_{norm} = \frac{w_{pixel}}{img\_width}, \quad h_{norm} = \frac{h_{pixel}}{img\_height}$$
+
+---
+
+## 🧑‍💻 Author
+**Zakria Gamal**
+- Computer Vision & AI Engineer
+- 🧠 LinkedIn: [Zakria Gamal](https://www.linkedin.com/in/zkaria-gamal-82b486267/)

segment_toolkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+segment_toolkit/__init__.py,sha256=SAJCWjYekhFC9tUllztl_jqWuTHrEdl40IP5wemlxlQ,1892
+segment_toolkit/cli.py,sha256=25EnYGv8raqu4mibUdhYiVNgmJaaCk5coTj22GG0yO8,8203
+segment_toolkit/helpers.py,sha256=ZlQepDWWwVUn4YQzDCT4n00YGU0wCYl3EF3G1KjuhxQ,6338
+segment_toolkit/source.py,sha256=_CF9iBEQqI9LeeoM173f3Ysqu_3XrMzNGE6clEhfFUY,23023
+segment_toolkit-1.0.0.dist-info/METADATA,sha256=so-tEZInRXj3R4o87WEU02tAO7bkQX-x0k4HjqS5v8U,6925
+segment_toolkit-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+segment_toolkit-1.0.0.dist-info/entry_points.txt,sha256=5FFKlx8pkcqt3R5Xch2w3WRAles919fevfdY9VcbQzk,61
+segment_toolkit-1.0.0.dist-info/top_level.txt,sha256=_TfxcDKObXH5ClqjkITFsxWGjMy0ERiAzCvkDd_CRAE,16
+segment_toolkit-1.0.0.dist-info/RECORD,,

segment_toolkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

segment_toolkit-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+segment-toolkit = segment_toolkit.cli:main

segment_toolkit-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+segment_toolkit