Metadata-Version: 2.4
Name: twoD-cmaps
Version: 0.1.3
Summary: Two-dimensional colormaps for Matplotlib-friendly Python workflows
Author: Marcos Wappner
License-Expression: MIT
Project-URL: Homepage, https://github.com/mwappner/cmap2d
Project-URL: Repository, https://github.com/mwappner/cmap2d
Project-URL: Issues, https://github.com/mwappner/cmap2d/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: colorspacious>=1.1
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# cmap2d

`cmap2d` is a small Matplotlib-friendly Python package for building, transforming, inspecting, and applying **two-dimensional colormaps**.

A normal colormap maps one scalar value to color. A `cmap2d` colormap maps two scalar values, usually called `U` and `V`, to RGB/RGBA colors:

```python
colors = cmap(U, V)
```

This is useful when each point, pixel, polygon, cell, or region has two quantities that should be visualized together.

![Colormap in use](https://raw.githubusercontent.com/mwappner/cmap2d/main/examples/output/cmap_on_countries.png)

## Installation

Once published on PyPI:

```bash
pip install twoD-cmaps
```

For local development from a cloned repository:

```bash
pip install -e ".[dev]"
```

## Basic usage

The core workflow is:

1. prepare or load two scalar arrays, `U` and `V`;
2. choose a 2D colormap;
3. call the colormap to obtain RGB/RGBA colors;
4. use those colors in Matplotlib.

```python
import matplotlib.pyplot as plt
import cmap2d as c2d

# Replace this with your own data loading.
# U and V should be broadcast-compatible arrays with the quantities to encode.
U, V = load_my_two_scalar_fields()

# Get a 2D colormap from the registry.
cmap = c2d.get_2d_cmap("RG")

# Map the two scalar fields to colors.
extent = c2d.extent_from_data(U, V, pad_u="5%", pad_v="5%")
colors = cmap(U, V,
    umin=extent[0], umax=extent[1],
    vmin=extent[2], vmax=extent[3],
)

# Use the colors in a normal Matplotlib plot.
fig, ax = plt.subplots()
ax.imshow(colors)

# Add a 2D colorbar showing how U and V map to color.
c2d.add_2d_colorbar(ax, cmap, extent=extent,
                    xlabel="U", ylabel="V" )
```

For a fully runnable version with synthetic data, see [`examples/basic_usage.py`](examples/basic_usage.py).

![Basic usage output](https://raw.githubusercontent.com/mwappner/cmap2d/main/examples/output/basic_usage.png)

## Inspecting colormaps

Use `show_2d_cmap` to display one colormap, or `show_2d_cmaps` to display several:

```python
import cmap2d as c2d

c2d.show_2d_cmap("RG")
c2d.show_2d_cmaps(["RG", "CM", "teuling_fig2"])
```

You can also inspect the registry:

```python
c2d.list_2d_cmaps()
c2d.list_2d_cmap_categories()
c2d.list_2d_cmaps(category="RGB")
c2d.list_2d_cmaps(kind="sampled")

info = c2d.cmap_info("teuling_fig2")
print(info.display_name)
print(info.source)
print(info.reference)
```

## Available colormap families

`cmap2d` includes analytic colormaps, custom constructors, and a curated set of image-based colormaps.

| Category | What it contains | Example |
|---|---|---|
| `RGB` | Analytic maps made from pairs of RGB channels. | `c2d.cm.RG` |
| `CMY` | Analytic maps made from pairs of cyan, magenta, and yellow channels. | `c2d.cm.CM` |
| `RGB-CMY` | Analytic maps combining one RGB channel with one CMY channel. | `c2d.cm.RY` |
| `ColorMap Explorer` | Curated sampled 2D colormaps derived from the ColorMap Explorer project. | `c2d.cm.teuling_fig2` |

All registered maps can be accessed either by name:

```python
cmap = c2d.get_2d_cmap("RG")
```

or through the lazy `cm` namespace:

```python
cmap = c2d.cm.RG
```

## Custom colormaps

### Two-color constructor

Use `make_two_colors_cmap` to build a map from two perceptual color vectors, one for the `U` axis and one for the `V` axis:

```python
cmap = c2d.make_two_colors_cmap(
    color_u="tab:blue",
    color_v="tab:orange",
    background="black",
)
```

### Four-corner constructor

Use `make_four_corners_cmap` to specify the colors at the four corners of the `U/V` plane. Colors are interpolated in CIELab space.

```python
cmap = c2d.make_four_corners_cmap(
    c00="black",      # U=0, V=0
    c10="tab:red",    # U=1, V=0
    c01="tab:blue",   # U=0, V=1
    c11="white",      # U=1, V=1
)
```

### Image-based colormaps

A 2D colormap can also be backed by an image:

```python
cmap = c2d.make_cmap_from_image("my_2d_colormap.png", origin="upper")
```

This is also how curated image-based colormaps are loaded internally.

## Transforming colormaps

Colormap objects are immutable. Transformations return new colormap objects and can be chained:

```python
cmap = c2d.cm.RG

swapped = cmap.swapped()
reversed_u = cmap.reversed_u()
reversed_v = cmap.reversed_v()

lighter = cmap.lightened(0.4)
darker = cmap.darkened(0.4)
desaturated = cmap.desaturated(0.7)

custom = cmap.reversed_v().lightened(0.25).desaturated(0.2)
```

You can export any colormap, including transformed or custom maps, to an image:

```python
c2d.save_cmap_image(custom, "my_cmap.png", n=512)
```

This is useful for sharing colormaps, using them in figure workflows, or inspecting them in external tools.
## Showing colormaps in use

For quick demonstrations, `show_cmap_in_use` applies a colormap to lightweight example datasets:

```python
fig, ax, cbar_ax = c2d.show_cmap_in_use("RG", kind="voronoi")
```

Supported demo kinds include scatter-like data, random ellipses, Voronoi-like polygons, and a map-like polygon example. See [`examples/show_cmap_in_use.py`](examples/show_cmap_in_use.py).

![Colormaps in use](https://raw.githubusercontent.com/mwappner/cmap2d/main/examples/output/show_cmap_in_use.png)


## ColorMap Explorer colormaps and credits

`cmap2d` includes a small curated set of sampled 2D colormaps generated from [ColorMap Explorer](https://github.com/fraunhofer-igd-iva/colormap-explorer), a Fraunhofer IGD / IVA project for exploring, comparing, and evaluating 2D colormaps.

ColorMap Explorer is licensed under Apache-2.0. It collects and implements 2D colormaps from the visualization literature. The image-based maps included in `cmap2d` are loaded through the same registry as the analytic maps, and their source, license, and reference metadata can be inspected with `cmap_info`.

Colormaps created with `cmap2d` can be exported with `save_cmap_image(...)` and then analyzed with ColorMap Explorer or other image/LUT-based colormap tools.

## Examples

Runnable examples live in [`examples/`](examples/):

| Example | What it shows |
|---|---|
| [`basic_usage.py`](examples/basic_usage.py) | Applying a registered 2D colormap to synthetic data. |
| [`show_all_cmaps.py`](examples/show_all_cmaps.py) | Displaying registered colormaps grouped by category. |
| [`show_cmap_in_use.py`](examples/show_cmap_in_use.py) | Applying maps to demo datasets. |
| [`two_color_construction.py`](examples/two_color_construction.py) | Building a custom two-color map. |
| [`four_corners_construction.py`](examples/four_corners_construction.py) | Building a custom four-corner map. |
| [`mutators.py`](examples/mutators.py) | Lightening, darkening, desaturating, and reversing maps. |
| [`sampled_cmap.py`](examples/sampled_cmap.py) | Loading and using an image-backed colormap. |

Most examples save figures to [`examples/output/`](examples/output/).

## License

`cmap2d` is distributed under the license included in [`LICENSE`](LICENSE).

Selected image-based colormaps derived from ColorMap Explorer retain their own attribution and source metadata. Use `cmap_info(name)` for source, license, and reference details for a specific colormap.
