Colormaps

How a complex value becomes a colour. Reading a phase portrait covers choosing between these, including measured colour-vision-deficiency behaviour.

The base contract

complexplorer.Colormap

Colormap(out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: ABC

Abstract base class for complex-to-color mappings.

A colormap defines how complex values are mapped to colors. Subclasses must implement the hsv_tuple method.

Parameters:

Name	Type	Description	Default
out_of_domain_hsv	tuple[float, float, float]	HSV color for points outside the domain.	OUT_OF_DOMAIN_COLOR_HSV

Initialize colormap with out-of-domain color.

hsv_tuple abstractmethod

hsv_tuple(z: ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Convert complex values to HSV components.

Parameters:

Name	Type	Description	Default
z	ndarray	Complex values.	required

Returns:

Type	Description
H, S, V : tuple of np.ndarray	Hue, saturation, and value arrays (each in [0, 1]).

hsv

hsv(z: ndarray, outmask: ndarray | None = None) -> np.ndarray

Convert complex values to HSV array.

Parameters:

Name	Type	Description	Default
z	ndarray	Complex values.	required
outmask	ndarray	Boolean mask (True for out-of-domain points).	None

Returns:

Type	Description
ndarray	HSV values with shape (*z.shape, 3).

rgb

rgb(z: ndarray, outmask: ndarray | None = None) -> np.ndarray

Convert complex values to RGB array.

Parameters:

Name	Type	Description	Default
z	ndarray	Complex values.	required
outmask	ndarray	Boolean mask (True for out-of-domain points).	None

Returns:

Type	Description
ndarray	RGB values with shape (*z.shape, 3).

Phase portraits

complexplorer.Phase

Phase(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, v_base: float = 0.5, auto_scale_r: bool = False, scale_radius: float = 1.0, emphasize_unit_circle: bool = False, unit_circle_strength: float = 0.3, unit_circle_color: tuple[float, float, float] | None = None, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Phase colormap with optional enhancement.

Maps complex phase to hue. Can create enhanced phase portraits by modulating saturation/value based on phase sectors and/or modulus contours.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhancement.	None
r_linear_step	float	Linear modulus step for contours.	None
r_log_base	float	Logarithmic base for modulus contours.	None
v_base	float	Base value (brightness), in [0, 1).	0.5
auto_scale_r	bool	Auto-calculate r_linear_step for square cells.	False
scale_radius	float	Reference radius for auto-scaling.	1.0
emphasize_unit_circle	bool	If True, emphasize the unit circle |z|=1.	False
unit_circle_strength	float	Strength of unit circle emphasis (0 to 1).	0.3
unit_circle_color	tuple	Optional HSV color to blend at unit circle. If None, just brightens.	None
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize phase colormap.

Perceptual families

complexplorer.OklabPhase

OklabPhase(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, auto_scale_r: bool = False, scale_radius: float = 1.0, enhanced: bool = False, L: float = 0.7, C: float = 0.35, v_base: float = 0.5, emphasize_unit_circle: bool = False, unit_circle_strength: float = 0.3, phase_offset: float = 0.8936868 * np.pi, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Pure OKLAB phase colormap with optional enhancement.

Implements a perceptually uniform phase portrait using the OKLAB color space. Maps complex phase directly to OKLAB hue angle while maintaining consistent lightness and chroma. Supports enhanced phase/modulus visualization through sawtooth modulation.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhancement.	None
r_linear_step	float	Linear modulus step for contours.	None
r_log_base	float	Logarithmic base for modulus contours.	None
auto_scale_r	bool	Auto-calculate r_linear_step for square cells.	False
scale_radius	float	Reference radius for auto-scaling.	1.0
enhanced	bool	If True, use sawtooth modulation for better structure visibility. If False (default), use smooth OKLAB colors similar to cplot.	False
L	float	Base lightness in OKLAB space (0 to 1). Default is 0.7.	0.7
C	float	Chroma (saturation) in OKLAB space (typically 0 to 0.4). Default is 0.35.	0.35
v_base	float	Base value for enhanced mode, in [0, 1). Default is 0.5.	0.5
emphasize_unit_circle	bool	If True, emphasize the unit circle |z|=1.	False
unit_circle_strength	float	Strength of unit circle emphasis (0 to 1).	0.3
phase_offset	float	Phase rotation offset in radians. Default is 0.8936868*π to match cplot's color mapping (green for arg=0, blue for arg=π/2, orange for arg=-π/2, pink for arg=π).	0.8936868 * pi
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Notes

The OKLAB color space provides perceptually uniform color gradients, meaning equal steps in the color values correspond to equal perceptual differences. This is particularly useful for accurate interpretation of complex function behavior.

When enhanced=True, the colormap uses sawtooth functions to create discontinuous edges at phase and modulus boundaries, dramatically improving the visibility of mathematical structures.

Initialize OKLAB phase colormap.

complexplorer.PerceptualPastel

PerceptualPastel(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, L_center: float = 0.55, L_range: float = 0.3, C: float = 0.1, v_base: float = 0.5, auto_scale_r: bool = False, scale_radius: float = 1.0, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Perceptually uniform pastel colormap using OkLCh color space.

Creates elegant, non-fluorescent colors with uniform perceived lightness as hue cycles. Phase determines hue, modulus creates lightness bands.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhanced phase portrait.	None
r_linear_step	float	Linear modulus step for contours.	None
r_log_base	float	Logarithmic base for modulus contours.	None
L_center	float	Center lightness value in [0, 1]. Default is 0.55.	0.55
L_range	float	Lightness variation range. Default is 0.3.	0.3
C	float	Chroma (saturation) in [0, 0.4]. Default is 0.10 for pastels.	0.1
v_base	float	Base value (brightness) for phase sectors, in [0, 1). Default is 0.5.	0.5
auto_scale_r	bool	Auto-calculate r_linear_step for square cells.	False
scale_radius	float	Reference radius for auto-scaling.	1.0
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize perceptual pastel colormap.

complexplorer.AnalogousWedge

AnalogousWedge(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, H_center: float = 0.55, H_wedge: float = 0.2, S: float = 0.35, V_base: float = 0.55, V_range: float = 0.35, auto_scale_r: bool = False, scale_radius: float = 1.0, use_sigmoid: bool = True, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Analogous color scheme with compressed hue range.

Maps phase to a wedge of the color wheel (20-50% range) for harmonious color schemes while preserving phase winding information.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhanced phase portrait.	None
r_linear_step	float	Linear modulus step for contours.	None
r_log_base	float	Logarithmic base for modulus contours.	None
H_center	float	Center hue in [0, 1]. Default is 0.55 (cyan-ish).	0.55
H_wedge	float	Hue range as fraction of color wheel in [0.2, 0.5]. Default is 0.2.	0.2
S	float	Saturation in [0, 1]. Default is 0.35 (muted).	0.35
V_base	float	Base value (brightness) in [0, 1]. Default is 0.55.	0.55
V_range	float	Value modulation range. Default is 0.35.	0.35
auto_scale_r	bool	Auto-calculate r_linear_step for square cells.	False
scale_radius	float	Reference radius for auto-scaling.	1.0
use_sigmoid	bool	Use sigmoid for smooth modulus mapping. Default is True.	True
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize analogous wedge colormap.

complexplorer.DivergingWarmCool

DivergingWarmCool(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, auto_scale_r: bool = False, scale_radius: float = 1.0, H_warm: float = 30, H_cool: float = 220, L_center: float = 0.5, L_range: float = 0.3, C_min: float = 0.04, C_max: float = 0.14, v_base: float = 0.5, use_oklch: bool = True, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Diverging warm-cool colormap based on phase sign.

Positive phases lean toward warm colors, negative toward cool. Creates refined, cartographic appearance with natural emphasis on real/imaginary axes.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhanced phase portrait.	None
r_linear_step	float	Period for linear modulus rings. Default is None (no rings).	None
r_log_base	float	Base for logarithmic modulus rings. Default is None (no rings).	None
auto_scale_r	bool	Auto-calculate r_linear_step from phase_sectors. Default is False.	False
scale_radius	float	Scale factor for auto-calculated r_linear_step. Default is 1.0.	1.0
H_warm	float	Warm anchor hue in degrees. Default is 30 (amber).	30
H_cool	float	Cool anchor hue in degrees. Default is 220 (indigo).	220
L_center	float	Center lightness in [0, 1]. Default is 0.5.	0.5
L_range	float	Lightness modulation range. Default is 0.3.	0.3
C_min	float	Minimum chroma. Default is 0.04.	0.04
C_max	float	Maximum chroma. Default is 0.14.	0.14
v_base	float	Base value for phase sectors, in [0, 1). Default is 0.5.	0.5
use_oklch	bool	Use OkLCh color space for perceptual uniformity. Default is True.	True
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize diverging warm-cool colormap.

complexplorer.Isoluminant

Isoluminant(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, auto_scale_r: bool = False, scale_radius: float = 1.0, L: float = 0.6, C_min: float = 0.12, C_max: float = 0.18, v_base: float = 0.5, show_contours: bool = True, contour_period: float = 1.0, contour_width: float = 0.05, use_oklch: bool = True, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Isoluminant colormap with optional contour lines.

Maintains constant lightness with hue encoding phase only. Optionally overlays thin contour lines to show modulus information.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhanced phase portrait.	None
r_linear_step	float	Period for linear modulus rings. Default is None (no rings).	None
r_log_base	float	Base for logarithmic modulus rings. Default is None (no rings).	None
auto_scale_r	bool	Auto-calculate r_linear_step from phase_sectors. Default is False.	False
scale_radius	float	Scale factor for auto-calculated r_linear_step. Default is 1.0.	1.0
L	float	Constant lightness in [0, 1]. Default is 0.6.	0.6
C_min	float	Minimum chroma. Default is 0.12.	0.12
C_max	float	Maximum chroma. Default is 0.18.	0.18
v_base	float	Base value for phase sectors, in [0, 1). Default is 0.5.	0.5
show_contours	bool	Show modulus contour lines. Default is True.	True
contour_period	float	Period for contour lines. Default is 1.0.	1.0
contour_width	float	Width parameter for contours. Default is 0.05.	0.05
use_oklch	bool	Use OkLCh for perceptual uniformity. Default is True.	True
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize isoluminant colormap.

complexplorer.CubehelixPhase

CubehelixPhase(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, auto_scale_r: bool = False, scale_radius: float = 1.0, start: float = 0.5, rotations: float = -1.5, saturation: float = 0.8, L_min: float = 0.15, L_max: float = 0.85, v_base: float = 0.5, gamma: float = 1.0, modulate_with_r: bool = True, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Cubehelix colormap driven by complex phase.

Uses Dave Green's cubehelix color scheme which maintains monotonic perceived brightness and prints well in grayscale.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhanced phase portrait.	None
r_linear_step	float	Period for linear modulus rings. Default is None (no rings).	None
r_log_base	float	Base for logarithmic modulus rings. Default is None (no rings).	None
auto_scale_r	bool	Auto-calculate r_linear_step from phase_sectors. Default is False.	False
scale_radius	float	Scale factor for auto-calculated r_linear_step. Default is 1.0.	1.0
start	float	Starting color (1=red, 2=green, 3=blue). Default is 0.5.	0.5
rotations	float	Number of rotations through color space. Default is -1.5.	-1.5
saturation	float	Color saturation in [0, 1]. Default is 0.8.	0.8
L_min	float	Minimum lightness. Default is 0.15.	0.15
L_max	float	Maximum lightness. Default is 0.85.	0.85
v_base	float	Base value for phase sectors, in [0, 1). Default is 0.5.	0.5
gamma	float	Gamma correction factor. Default is 1.0.	1.0
modulate_with_r	bool	Modulate lightness with modulus. Default is True.	True
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize cubehelix phase colormap.

complexplorer.InkPaper

InkPaper(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, auto_scale_r: bool = False, scale_radius: float = 1.0, L_min: float = 0.35, L_max: float = 0.85, C_min: float = 0.02, C_max: float = 0.06, v_base: float = 0.5, add_phase_stripes: bool = False, stripe_count: int = 8, stripe_amplitude: float = 0.03, use_oklch: bool = True, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Nearly monochrome colormap with subtle phase tints.

Creates a classy, etching-like appearance that's almost grayscale with just enough color to read phase information.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhanced phase portrait.	None
r_linear_step	float	Period for linear modulus rings. Default is None (no rings).	None
r_log_base	float	Base for logarithmic modulus rings. Default is None (no rings).	None
auto_scale_r	bool	Auto-calculate r_linear_step from phase_sectors. Default is False.	False
scale_radius	float	Scale factor for auto-calculated r_linear_step. Default is 1.0.	1.0
L_min	float	Minimum lightness. Default is 0.35.	0.35
L_max	float	Maximum lightness. Default is 0.85.	0.85
C_min	float	Minimum chroma (very low for near-monochrome). Default is 0.02.	0.02
C_max	float	Maximum chroma. Default is 0.06.	0.06
v_base	float	Base value for phase sectors, in [0, 1). Default is 0.5.	0.5
add_phase_stripes	bool	Add subtle phase stripes. Default is False.	False
stripe_count	int	Number of phase stripes if enabled. Default is 8.	8
stripe_amplitude	float	Amplitude of phase stripes. Default is 0.03.	0.03
use_oklch	bool	Use OkLCh color space. Default is True.	True
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize ink & paper colormap.

complexplorer.EarthTopographic

EarthTopographic(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, auto_scale_r: bool = False, scale_radius: float = 1.0, L_min: float = 0.4, L_max: float = 0.8, H_water: float = 200, H_land: float = 30, C_min: float = 0.05, C_max: float = 0.12, add_hillshade: bool = True, hillshade_amplitude: float = 0.07, v_base: float = 0.5, use_oklch: bool = True, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Earth-tone topographic colormap.

Creates a terrain-inspired aesthetic where modulus appears as elevation with phase providing subtle earth-tone tints.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhanced phase portrait.	None
r_linear_step	float	Period for linear modulus rings. Default is None (no rings).	None
r_log_base	float	Base for logarithmic modulus rings. Default is None (no rings).	None
auto_scale_r	bool	Auto-calculate r_linear_step from phase_sectors. Default is False.	False
scale_radius	float	Scale factor for auto-calculated r_linear_step. Default is 1.0.	1.0
L_min	float	Minimum lightness. Default is 0.4.	0.4
L_max	float	Maximum lightness. Default is 0.8.	0.8
H_water	float	Water hue in degrees (bluish). Default is 200.	200
H_land	float	Land hue in degrees (brownish). Default is 30.	30
C_min	float	Minimum chroma. Default is 0.05.	0.05
C_max	float	Maximum chroma. Default is 0.12.	0.12
add_hillshade	bool	Add hillshade effect to modulus. Default is True.	True
hillshade_amplitude	float	Amplitude of hillshade effect. Default is 0.07.	0.07
v_base	float	Base value for phase sectors, in [0, 1). Default is 0.5.	0.5
use_oklch	bool	Use OkLCh color space. Default is True.	True
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize earth topographic colormap.

complexplorer.FourQuadrant

FourQuadrant(phase_sectors: int | None = None, r_linear_step: float | None = None, r_log_base: float | None = None, auto_scale_r: bool = False, scale_radius: float = 1.0, H_anchors: tuple[float, float, float, float] = (10, 120, 210, 300), C: float = 0.1, L_min: float = 0.4, L_max: float = 0.8, use_oklch: bool = True, smooth_interpolation: bool = True, v_base: float = 0.5, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: BasePhasePortrait

Four-quadrant colormap with smooth circular interpolation.

Maps the four principal phase angles to four color anchors and smoothly interpolates between them on the circle.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors for enhanced phase portrait.	None
r_linear_step	float	Period for linear modulus rings. Default is None (no rings).	None
r_log_base	float	Base for logarithmic modulus rings. Default is None (no rings).	None
auto_scale_r	bool	Auto-calculate r_linear_step from phase_sectors. Default is False.	False
scale_radius	float	Scale factor for auto-calculated r_linear_step. Default is 1.0.	1.0
H_anchors	tuple	Four hue anchors in degrees for 0°, 90°, 180°, 270°. Default is (10, 120, 210, 300) for red, green, cyan, magenta.	(10, 120, 210, 300)
C	float	Chroma (saturation) in [0, 0.4]. Default is 0.10.	0.1
L_min	float	Minimum lightness. Default is 0.4.	0.4
L_max	float	Maximum lightness. Default is 0.8.	0.8
use_oklch	bool	Use OkLCh for perceptual uniformity. Default is True.	True
smooth_interpolation	bool	Use smooth spline interpolation. Default is True.	True
v_base	float	Base value for phase sectors, in [0, 1). Default is 0.5.	0.5
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize four-quadrant colormap.

Pattern maps

These show the mapping rather than the phase.

complexplorer.Chessboard

Chessboard(spacing: float = 1.0, center: complex = 0 + 0j, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: Colormap

Cartesian chessboard pattern.

Creates a black and white chessboard pattern aligned with real and imaginary axes.

Parameters:

Name	Type	Description	Default
spacing	float	Size of each square.	1.0
center	complex	Center of the pattern.	0 + 0j
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize chessboard colormap.

hsv_tuple

hsv_tuple(z: ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Convert complex values to HSV components.

complexplorer.PolarChessboard

PolarChessboard(phase_sectors: int = 6, spacing: float = 1.0, r_log: float | None = None, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: Colormap

Polar chessboard pattern.

Creates a black and white pattern in polar coordinates, with sectors in phase and rings in modulus.

Parameters:

Name	Type	Description	Default
phase_sectors	int	Number of phase sectors.	6
spacing	float	Radial spacing between rings.	1.0
r_log	float	Logarithmic base for radial spacing.	None
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize polar chessboard.

hsv_tuple

hsv_tuple(z: ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Convert complex values to HSV components.

complexplorer.LogRings

LogRings(log_spacing: float = 0.2, out_of_domain_hsv: tuple[float, float, float] = OUT_OF_DOMAIN_COLOR_HSV)

Bases: Colormap

Logarithmic black and white rings.

Creates concentric rings with logarithmic spacing.

Parameters:

Name	Type	Description	Default
log_spacing	float	Logarithmic spacing parameter.	0.2
out_of_domain_hsv	tuple	Color for out-of-domain points.	OUT_OF_DOMAIN_COLOR_HSV

Initialize logarithmic rings.

hsv_tuple

hsv_tuple(z: ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Convert complex values to HSV components.