Metadata-Version: 2.4
Name: color-operations
Version: 0.4.0
Summary: Apply basic color-oriented image operations.
Project-URL: Homepage, https://github.com/vincentsarago/color-operations
Project-URL: Source, https://github.com/vincentsarago/color-operations
Project-URL: Issues, https://github.com/vincentsarago/color-operations/issues
Author-email: Charlie Loyd <charlie@mapbox.com>
Maintainer-email: Vincent Sarago <vincent@developmentseed.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Requires-Dist: numpy
Description-Content-Type: text/markdown

# color-operations (fork of [**rio-color**](https://github.com/mapbox/rio-color) )

<p align="center">
  <p align="center">Apply basic color-oriented image operations.</p>
</p>

<p align="center">
  <a href="https://github.com/vincentsarago/color-operations/actions?query=workflow%3ACI" target="_blank">
      <img src="https://github.com/vincentsarago/color-operations/workflows/CI/badge.svg" alt="Test">
  </a>
  <a href="https://codecov.io/gh/vincentsarago/color-operations" target="_blank">
      <img src="https://codecov.io/gh/vincentsarago/color-operations/branch/main/graph/badge.svg" alt="Coverage">
  </a>
  <a href="https://pypi.org/project/color-operations" target="_blank">
      <img src="https://img.shields.io/pypi/v/color-operations?color=%2334D058&label=pypi%20package" alt="Package version">
  </a>
  <a href="https://github.com/vincentsarago/color-operations/blob/main/LICENSE" target="_blank">
      <img src="https://img.shields.io/github/license/vincentsarago/color-operations.svg" alt="license">
  </a>
</p>

Modified version of Mapbox's [**rio-color**](https://github.com/mapbox/rio-color), removing rasterio dependency and with python>=3.10 compatibility.

## Install

You can install color-operations using pip

```
python -m pip install -U pip
python -m pip install color-operations
```

or build from source

We recommand using [`uv`](https://docs.astral.sh/uv) as project manager for development.

See https://docs.astral.sh/uv/getting-started/installation/ for installation 

```
git checkout https://github.com/vincentsarago/color-operations.git
cd color-operations
uv sync
```

## Operations

**Gamma** adjustment adjusts RGB values according to a power law, effectively brightening or darkening the midtones. It can be very effective in satellite imagery for reducing atmospheric haze in the blue and green bands.

**Sigmoidal** contrast adjustment can alter the contrast and brightness of an image in a way that
matches human's non-linear visual perception. It works well to increase contrast without blowing out the very dark shadows or already-bright parts of the image.

**Saturation** can be thought of as the "colorfulness" of a pixel. Highly saturated colors are intense and almost cartoon-like, low saturation is more muted, closer to black and white. You can adjust saturation independently of brightness and hue but the data must be transformed into a different color space.

Ref https://github.com/mapbox/rio-color/blob/master/README.md

## Examples

#### Sigmoidal

Contrast

![sigmoidal_contrast](img/sigmoidal_contrast.jpg)

Bias

![sigmoidal_bias](img/sigmoidal_bias.jpg)

#### Gamma

Red

![gamma_red](img/gamma_red.jpg)

Green

![gamma_green](img/gamma_green.jpg)

Blue

![gamma_blue](img/gamma_blue.jpg)

#### Saturation

![saturation](img/saturation.jpg)

#### Combinations of operations

![combos](img/combos.jpg)

Ref https://github.com/mapbox/rio-color/blob/master/README.md

## Python API

#### `color_operations.operations`

The following functions accept and return numpy `ndarrays`. The arrays are assumed to be scaled 0 to 1. In some cases, the input array is assumed to be in the RGB colorspace.

All arrays use rasterio ordering with the shape as (bands, columns, rows). Be aware that other image processing software may use the (columns, rows, bands) axis order.

* `sigmoidal(arr, contrast, bias)`
* `gamma(arr, g)`
* `saturation(rgb, proportion)`
* `simple_atmo(rgb, haze, contrast, bias)`

The `color_operations.operations.parse_operations` function takes an *operations string* and
returns a list of python functions which can be applied to an array.

```python
from color_operations import parse_operations

ops = "gamma b 1.85, gamma rg 1.95, sigmoidal rgb 35 0.13, saturation 1.15"

assert arr.shape[0] == 3
assert arr.min() >= 0
assert arr.max() <= 1

for func in parse_operations(ops):
    arr = func(arr)
```

This provides a tiny domain specific language (DSL) to allow you
to compose ordered chains of image manipulations using the above operations.
For more information on operation strings, see the `rio color` command line help.

#### `color_operations.colorspace`

The `colorspace` module provides functions for converting scalars and numpy arrays between different colorspaces.

```python
from color_operations.colorspace import ColorSpace as cs  # enum defining available color spaces
from color_operations.colorspace import convert, convert_arr

convert_arr(array, src=cs.rgb, dst=cs.lch) # for arrays
...

convert(r, g, b, src=cs.rgb, dst=cs.lch)  # for scalars
...

dict(cs.__members__)  # can convert to/from any of these color spaces
{
    'rgb': <ColorSpace.rgb: 0>,
    'xyz': <ColorSpace.xyz: 1>,
    'lab': <ColorSpace.lab: 2>,
    'lch': <ColorSpace.lch: 3>,
    'luv': <ColorSpace.luv: 4>
}
```
