segimage 0.0.3

Image segmentation and processing library with CLI support

segimage

A Python library for image segmentation and processing with comprehensive command-line interface support.

Overview

SegImage is designed to handle various image formats, including MATLAB .mat files, and provides multiple processing algorithms for image analysis and graph generation. It features an extensible plugin architecture for easy addition of new algorithms.

Project Details

• Name: segimage
• Version: 0.0.2
• Author: Lucas Lopes Felipe
• Python Version: ≥3.12
• License: Custom (see LICENSE file)

🖼️ Core Features

• MATLAB .mat file support: Read and process MATLAB data files with automatic data extraction
• Multiple input formats: .mat, .npy, .tif, .tiff, .png, .jpg, .jpeg
• Multiple output formats: PNG, JPG, TIFF, NumPy arrays, and various graph formats
• Command-line interface: Easy-to-use CLI for batch processing
• Extensible architecture: Easy to add new processing methods
• Configurable graph edge filters: Build pixel adjacency graphs with optional LBP/gray/RGB similarity-based edge filtering
• Pixel vs Superpixel node mode: All graph builders (grid, affinity, prob4, contrast4) can build graphs whose nodes are either pixels or SLICO superpixels, selectable via CLI
• Graph view renderer: Visualize graphs with adjustable node size, edge thickness, and weight-based edge opacity

Installation

From PyPI (when published)

pip install segimage

From source

git clone https://github.com/yourusername/segimage.git
cd segimage
# With uv (recommended for devs)
uv pip install -e '.[dev]'
# or using pip
pip install -e '.[dev]'

Quick Start

Command Line Usage

The library provides a command-line interface that can be used directly:

# Convert a MATLAB .mat file to PNG format (default)
segimage process input.mat output_directory --process-type mat_to_image

# Convert to JPG format
segimage process input.mat output_directory -t mat_to_image -f jpg

# With verbose output
segimage process input.mat output_directory -t mat_to_image -f png -v

# Color clustering (top-K frequent colors)
segimage process input.png output_directory -t color_cluster -K 4 --palette rainbow

# LBP visualization (8-neighbor local binary pattern)
segimage process input.png output_directory -t lbp --palette bw

# SLICO superpixels
segimage process input.png output_directory -t slico --n-segments 300 --compactness 10

# Create a pixel adjacency graph (8-connected) and save as GraphML
segimage process input.png output_directory -t graph -f graphml

# Graph with edge filtering:
# - Keep edges only if neighboring pixels have similar gray levels (exact match)
segimage process input.png output_directory -t graph -f graphml --edge-filter gray --edge-similarity 1.0
# - Keep edges for similar RGB colors (allow moderate difference)
segimage process input.png output_directory -t graph -f graphml --edge-filter rgb --edge-similarity 0.6
# - Keep edges for similar LBP codes (continuous threshold)
segimage process input.png output_directory -t graph -f graphml --edge-filter lbp --edge-similarity 0.8
# - Exact LBP code equality (legacy behavior)
segimage process input.png output_directory -t graph -f graphml --edge-filter lbp_eq

# Show supported formats
segimage formats

# Show library information
segimage info

# Graph → View (pixels as nodes)
segimage process input.png output_directory -t graph_view --graph-method grid --node-mode pixel --node-radius 2

# Graph → View (superpixels as nodes)
segimage process input.png output_directory -t graph_view --graph-method grid --node-mode superpixel \
  --n-segments 300 --compactness 10 --sigma 1.0 --start-label 0 --node-radius 12 --edge-width-max 8

Python API Usage

from pathlib import Path
from segimage import ImageProcessor

# Initialize the processor
processor = ImageProcessor()

success = processor.process_image(
    Path("input.png"),
    Path("out/input_clustered.png"),
    "color_cluster",
    K=4,
    palette="rainbow",
)

if success:
    print("Conversion successful!")
else:
    print("Conversion failed!")

Supported Formats

Input Formats

• .mat - MATLAB data files
• .npy - NumPy array files
• .tif, .tiff - TIFF images
• .png, .jpg, .jpeg - Common image formats

Output Formats

• .png - PNG images (default, lossless)
• .jpg, .jpeg - JPEG images (compressed)
• .tif, .tiff - TIFF images
• .npy - NumPy array files
• Graphs: .graphml, .gml, .lg/.lgl, .edgelist/.edges/.txt, .pickle/.pkl
  • Note: Companion .meta files are only written for image outputs

🔧 Processing Types

Currently supported processing types:

• mat_to_image (default): Convert MATLAB .mat files to standard image formats
• color_cluster: Group pixels by most frequent exact colors into up to K clusters
• lbp: Visualize 8-neighbor Local Binary Pattern values per pixel (palettes: bw, rainbow)
• slico: SLICO superpixels using scikit-image's SLIC with slic_zero=True
• graph: Build an 8-connected pixel adjacency graph and save to graph formats (GraphML, GML, etc.).
  • Optional edge filters: --edge-filter {none, lbp_eq, lbp, gray, rgb}
  • Similarity control: --edge-similarity [0..1] where 1.0 requires exact match, 0.0 allows any difference (no filtering). Applies to lbp, gray, rgb and is ignored for lbp_eq.

SLICO usage examples

# Run SLICO with defaults
segimage process input.png output_dir -t slico

# Customize superpixel parameters
segimage process input.png output_dir -t slico --n-segments 500 --compactness 10 --sigma 1 --start-label 1

Python API:

from pathlib import Path
from segimage import ImageProcessor

processor = ImageProcessor()
processor.process_image(
    Path("input.png"),
    Path("out/input_slico.png"),
    "slico",
    n_segments=280,
    compactness=2.0,
    sigma=1.0,
    start_label=1,
)

LBP usage examples

# Black-and-white palette
segimage process input.png output_dir -t lbp --palette bw

# Rainbow palette (rank-normalized)
segimage process input.png output_dir -t lbp --palette rainbow

Color clustering examples

# Cluster by top-3 most frequent colors (two top colors + remaining)
segimage process input.png output_dir -t color_cluster -K 3 --palette bw

# Rainbow palette for clusters
segimage process input.png output_dir -t color_cluster -K 5 --palette rainbow

Graph creation examples

# Create 8-neighbor pixel graph and save as GraphML
segimage process input.png output_dir -t graph -f graphml

# Save as GML instead
segimage process input.png output_dir -t graph -f gml

# Gray-level similarity filtering (exact match)
segimage process input.png output_dir -t graph -f graphml --edge-filter gray --edge-similarity 1.0

# RGB similarity filtering (looser threshold)
segimage process input.png output_dir -t graph -f graphml --edge-filter rgb --edge-similarity 0.5

# LBP similarity filtering
segimage process input.png output_dir -t graph -f graphml --edge-filter lbp --edge-similarity 0.8

# LBP exact code equality
segimage process input.png output_dir -t graph -f graphml --edge-filter lbp_eq

# Graph view (render graph overlay)
segimage process input.png output_dir -t graph_view --graph-method grid --node-mode pixel --node-radius 2
segimage process input.png output_dir -t graph_view --graph-method affinity --node-mode superpixel \
  --n-segments 250 --compactness 8 --sigma 1.0 --start-label 1 --edge-width-max 12 --edge-min 0.0

🌐 Graph Generation & Export

• Graph formats: GraphML, GML, LGL, EdgeList, Pickle
• Edge filtering options:
  • gray: Filter by gray-level similarity
  • rgb: Filter by RGB color similarity
  • lbp: Filter by LBP code similarity
  • lbp_eq: Exact LBP code equality
  • none: No filtering (all edges included)

🎨 Visualization Options

• Color palettes: bw (black/white), rainbow (rank-normalized)
• Configurable parameters:
  • Node mode: --node-mode {pixel, superpixel}
  • SLICO params for superpixels: --n-segments, --compactness, --sigma, --start-label
  • Edge filtering: --edge-filter {none, lbp_eq, lbp, gray, rgb} + --edge-similarity [0..1]
  • Graph view sizing: --node-radius (pixel radius), --edge-width-max (max thickness)
  • Graph view filtering: --edge-min (minimum weight to draw)

Examples

Basic MATLAB to PNG conversion

segimage process data/2018.mat output/ --process-type mat_to_image

Convert to JPG format

segimage process input.mat output/ -t mat_to_image -f jpg

Convert to TIFF format

segimage process input.mat output/ -t mat_to_image -f tif

Verbose processing

segimage process input.mat output/ -t mat_to_image -f png -v

How It Works

The library automatically:

1. Reads MATLAB .mat files and extracts numeric data
2. Handles complex data structures including object arrays and structured arrays
3. Normalizes data to appropriate ranges for image formats
4. Converts to PIL Image objects for proper image processing
5. Saves in standard formats that macOS and other systems recognize as images
6. Preserves metadata in companion .meta files

🏗️ Architecture

Core Components

src/segimage/
├── processor.py          # Main processing logic and router
├── utils.py             # Utility functions and helpers
├── cli/                 # Command-line interface
│   ├── main.py         # Click group and shared options
│   └── commands/       # Subcommands implementation
│       ├── process.py  # Main processing command
│       ├── formats.py  # Supported formats listing
│       ├── info.py     # Library information
│       └── inspect.py  # File inspection
└── processors/          # Pluggable processing algorithms
    ├── color_cluster.py # Color clustering implementation
    ├── lbp.py          # Local Binary Pattern processor
    ├── slico.py        # SLICO superpixels
    └── graph.py        # Graph generation and export

Design Patterns

• Plugin Architecture: Extensible processor system for easy addition of new algorithms
• Command Pattern: CLI commands are modular and self-contained
• Strategy Pattern: Different processing strategies can be swapped easily

📦 Dependencies

Core Dependencies

• scipy≥1.7.0: Scientific computing and MATLAB file support
• click≥8.0.0: Command-line interface framework
• Pillow≥8.0.0: Image processing and manipulation
• scikit-image≥0.20.0: Advanced image processing algorithms
• hedonic≥0.0.7: Additional utilities

Development Dependencies

• pytest≥6.0.0: Testing framework
• black≥21.0.0: Code formatting
• flake8≥3.8.0: Linting and style checking

🚀 Development

Setup development environment

# Recommended: uv (fast installer and runner)
uv pip install -e '.[dev]'

# Or using pip
pip install -e '.[dev]'

Run tests

uv run -m pytest -q
# or
pytest -q

Code formatting

uv run black src/
# or
black src/

Lint code

uv run flake8 src/
# or
flake8 src/

CLI Development

# Run CLI commands
uv run segimage --help
uv run segimage process --help

🎯 Use Cases

Academic Research

• MATLAB data analysis and visualization
• Image segmentation algorithm development
• Graph-based image analysis
• Texture analysis with LBP

Data Science

• Batch image processing
• Image format conversion
• Superpixel generation for ML preprocessing
• Graph representation of images

Image Analysis

• Color-based segmentation
• Texture analysis
• Boundary detection
• Region-based analysis

Project Structure

segimage/
├── src/
│   └── segimage/
│       ├── __init__.py      # Main package exports
│       ├── processor.py     # Core image processing logic and router
│       ├── cli/             # CLI entrypoint and commands
│       │   ├── main.py      # Click group and shared options
│       │   └── commands/    # Subcommands: process, formats, inspect, info
│       └── processors/      # Pluggable processors (color_cluster, lbp, slico, graph)
├── pyproject.toml          # Project configuration
└── README.md              # This file

Project Status

• Current Version: 0.0.2
• Development Stage: Active development
• Python Support: Modern Python (3.12+)
• Package Manager: uv (recommended), pip supported

Future Enhancements

• Additional segmentation algorithms
• More graph export formats
• Performance optimizations
• Extended CLI options
• Additional visualization palettes

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the terms specified in the LICENSE file.

Support

For issues and questions, please use the GitHub issue tracker.