scikit-image

scikit-image Best Practices

This document outlines the mandatory guidelines for all scikit-image development within our team. Adhering to these rules ensures consistency, performance, and long-term maintainability of our image processing pipelines.

1. Core Principles

scikit-image is built on NumPy. All functions must accept and return plain ndarray objects.

1.1. Immutability of Input Images

Always treat input images as immutable. Functions must return new arrays, never modify inputs in-place. This prevents unexpected side effects and simplifies debugging.

❌ BAD: In-place modification

import numpy as np
from skimage import exposure

def normalize_image_bad(image: np.ndarray) -> None:
    """❌ BAD: Modifies the input image directly."""
    image[:] = exposure.rescale_intensity(image, out_range=(0, 1))

img = np.array([[0, 100], [50, 200]], dtype=np.uint8)
original_img_id = id(img)
normalize_image_bad(img)
print(f"Image ID changed? {id(img) != original_img_id}") # False, same object modified

✅ GOOD: Return a new array

import numpy as np
from skimage import exposure
from numpy.typing import NDArray, Any

def normalize_image_good(image: NDArray[Any, Any]) -> NDArray[Any, Any]:
    """✅ GOOD: Returns a new, processed image array."""
    return exposure.rescale_intensity(image, out_range=(0, 1))

img = np.array([[0, 100], [50, 200]], dtype=np.uint8)
original_img_id = id(img)
processed_img = normalize_image_good(img)
print(f"Image ID changed? {id(processed_img) != original_img_id}") # True, new object returned

1.2. Public API Usage

Always use the documented public API. Avoid internal or private functions (prefixed with _) to ensure forward compatibility and stability.

2. Code Organization and Structure

2.1. Modular Functions

Break down complex image processing tasks into small, focused, and reusable functions. Each function should do one thing well.

❌ BAD: Monolithic function

import numpy as np
from skimage import io, filters, exposure

def process_image_bad(path: str) -> np.ndarray:
    """❌ BAD: Combines loading, filtering, and normalization."""
    image = io.imread(path, as_gray=True)
    blurred = filters.gaussian(image, sigma=1)
    normalized = exposure.rescale_intensity(blurred, out_range=(0, 1))
    return normalized