Metadata-Version: 2.4
Name: scmap
Version: 0.1.1
Summary: Assigns rgb colors to orientations.
Home-page: https://github.com/vedranaa/sphere-colormap
Author: Vedrana Andersen Dahl
Author-email: vand@dtu.dk
License: lgpl-2.1
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: summary

# scmap

Assign RGB colors to 3D orientations (points on a sphere).

`scmap` maps each 3D direction vector to an RGB color. This is useful for
visualizing orientation fields, directional measurements, or vector data in 3D.

## Installation

Install from PyPI:

```bash
pip install scmap
```

## Quick Start

Generate random unit vectors and color them with the default all-purpose map
`Ico`:

```python
import numpy as np
import scmap

# 1000 random 3D vectors
vectors = np.random.standard_normal((1000, 3))
vectors /= np.linalg.norm(vectors, axis=1, keepdims=True)

coloring = scmap.Ico()
colors = coloring(vectors)  # shape: (1000, 3), RGB values in [0, 1]
```

Plot the result with Matplotlib:

```python
import matplotlib.pyplot as plt

fig = plt.figure()
ax = fig.add_subplot(projection="3d")
ax.scatter(vectors[:, 0], vectors[:, 1], vectors[:, 2], c=colors)
ax.set_xlim(-1, 1)
ax.set_ylim(-1, 1)
ax.set_zlim(-1, 1)
plt.show()
```

![](https://github.com/vedranaa/colorsphere/raw/main/Figure1.png)

## Orienting the Colormap

All colormap classes support these orientation options:

- `z_direction`: define which direction should be treated as the colormap z-axis.
- `rotation`: pass a custom 3x3 rotation matrix.
- `ordering`: permute input axes, for example `[2, 0, 1]`.

Example using `z_direction`:

```python
coloring = scmap.Duo(z_direction=[0.3, 0.4, 0.5])
colors = coloring(vectors)
```

Example using `ordering`:

```python
coloring = scmap.Uno(ordering=[2, 0, 1])
colors = coloring(vectors)
```

Example using an explicit rotation matrix:

```python
R = scmap.get_rotation([0.0, 1.0, 0.0])
coloring = scmap.Ico(rotation=R)
colors = coloring(vectors)
```

## Available Colormaps

The package includes six colormaps:

- `Uno`: best when vectors are mostly aligned with one dominant direction.
- `Duo`: best when vectors are mostly distributed in a plane.
- `Tre`: emphasizes alignment with x/y/z axes.
- `Ico`: balanced, general-purpose spherical colormap.
- `Inc`: colors by inclination.
- `Azy`: colors by azimuth.

![](https://github.com/vedranaa/colorsphere/raw/main/Figure2.png)

## Notes

- Input vectors should be provided as an array with shape `(..., 3)`, where the last dimension is always 3 (x, y, z). Works with any number of leading dimensions, e.g., `(n, 3)`, `(h, w, 3)`, `(d, h, w, 3)`, etc.
- Vectors are normalized internally before color mapping and must be non-zero.
- Output colors are RGB arrays with shape `(..., 3)`, matching the input shape.
