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:

pip install scmap

Quick Start

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

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:

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()

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:

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

Example using ordering:

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

Example using an explicit rotation matrix:

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.

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.