Color Operations

Common errors

• ValueError: operands could not be broadcast together with shapes (H,W,C) (C,H,W)

  cause The input NumPy array has an incorrect dimension order. `color-operations` expects `(bands, rows, columns)`, but you might be providing `(rows, columns, bands)`.
  fix Reshape your NumPy array. If your array is `(rows, columns, bands)`, use `your_array.transpose(2, 0, 1)` before passing it to `color-operations` functions.

• Output image appears completely washed out, over-saturated, or incorrect.

  cause Input pixel values are not scaled between 0.0 and 1.0 (e.g., still 0-255), or the output 0-1.0 values are being misinterpreted by a display tool expecting 0-255.
  fix Verify that your input NumPy array's pixel values are floating-point numbers between 0.0 and 1.0. If starting from an 8-bit image (0-255), convert it with `image_255.astype(np.float32) / 255.0`. Remember to convert output back to 0-255 for display/saving if necessary (e.g., `(output_array * 255).astype(np.uint8)`).

• ModuleNotFoundError: No module named 'rasterio'

  cause You are attempting to use `color-operations` in a manner that expects `rasterio` integration. This library is a fork specifically designed to *remove* `rasterio` as a dependency.
  fix This library does not support `rasterio` directly. Extract the raw `numpy.ndarray` from your `rasterio` dataset to use with `color-operations`. If deep `rasterio` integration is required, use the original `rio-color` library.

Warnings

• breaking Python 3.8 is no longer supported; the library now requires Python >= 3.9 for installation and use.
  Fix: Upgrade your Python environment to version 3.9 or higher.
• breaking This library is an explicit fork of `rio-color` that *removes* the `rasterio` dependency. Code expecting `rasterio` objects or direct `rasterio` integration will not work.
  Fix: Ensure all image data is provided as raw `numpy.ndarray` objects. If `rasterio` integration is critical, consider using `rio-color` instead.
• gotcha Input and output NumPy arrays for all operations are expected to be in `(bands, columns, rows)` order (similar to `rasterio`'s internal representation) and have pixel values scaled from 0.0 to 1.0. Many other image processing libraries use `(rows, columns, bands)` or 0-255 scaling.
  Fix: Before passing data to `color-operations`, ensure your arrays are reshaped (e.g., `image.transpose(2, 0, 1)` for (H,W,C) to (C,H,W)) and rescaled (e.g., `image_255 / 255.0` for 0-255 to 0-1). Convert back if needed for display or other libraries.

Install

• pip install color-operations Install stable release

Imports

• operations

  from color_operations import operations

  Contains core image manipulation functions like `sigmoidal`, `gamma`, and `saturation`.

Quickstart

This quickstart demonstrates basic color operations (sigmoidal contrast, gamma correction, saturation adjustment) on a simulated NumPy image array. The library expects input arrays to be in `(bands, rows, columns)` order with pixel values scaled between 0.0 and 1.0.

import numpy as np
from color_operations import operations

# Simulate a 3-band RGB image (e.g., 100x100 pixels)
# Input arrays are expected to be (bands, rows, columns) and scaled 0-1.
image_array = np.random.rand(3, 100, 100).astype(np.float32)

# Apply a sigmoidal contrast adjustment
# contrast: adjusts the slope of the sigmoid function (higher values mean higher contrast)
# bias: shifts the sigmoid function (affects brightness)
sigmoidal_adjusted = operations.sigmoidal(image_array, contrast=5, bias=0.5)

# Apply gamma correction to brighten midtones (e.g., gamma > 1.0 darkens, < 1.0 brightens)
gamma_corrected = operations.gamma(image_array, g=0.8)

# Adjust saturation (proportion > 1.0 increases saturation, < 1.0 decreases)
saturated_image = operations.saturation(image_array, proportion=1.5)

print(f"Original image array shape: {image_array.shape}")
print(f"Sigmoidal adjusted image shape: {sigmoidal_adjusted.shape}")
print(f"Gamma corrected image shape: {gamma_corrected.shape}")
print(f"Saturated image shape: {saturated_image.shape}")