API Reference

next_color(cs::ColorSpace=SRGB(); gr::GayRNG=gay_rng())

Generate the next deterministic random color. Each call splits the RNG for reproducibility.

next_colors(n::Int, cs::ColorSpace=SRGB(); gr::GayRNG=gay_rng())

Generate n deterministic random colors.

next_palette(n::Int, cs::ColorSpace=SRGB(); 
             min_distance::Float64=30.0, gr::GayRNG=gay_rng())

Generate n deterministic visually distinct colors.

color_at(index::Integer, cs::ColorSpace=SRGB(); seed::Integer=GAY_SEED)

Get the color at a specific invocation index. This allows random access to the deterministic color sequence.

Example

# These will always return the same colors for the same indices
c1 = color_at(1)
c42 = color_at(42)
c1_again = color_at(1)  # Same as c1

colors_at(indices::AbstractVector{<:Integer}, cs::ColorSpace=SRGB(); 
          seed::Integer=GAY_SEED)

Get colors at specific invocation indices.

palette_at(index::Integer, n::Int, cs::ColorSpace=SRGB();
           min_distance::Float64=30.0, seed::Integer=GAY_SEED)

Get a palette at a specific invocation index.

gay_seed!(seed::Integer)

Reset the global Gay RNG with a new seed. All subsequent color generations will be deterministic from this seed.

gay_rng()

Get the global Gay RNG, initializing if needed.

gay_split(gr::GayRNG=gay_rng())

Split the RNG for a new independent stream. Increments invocation counter for tracking.

gay_split(n::Integer, gr::GayRNG=gay_rng())

Get n independent RNG splits as a vector.

GayRNG

A splittable random number generator for deterministic color generation. Each color operation splits the RNG to ensure reproducibility regardless of execution order (Strong Parallelism Invariance).

The RNG state tracks an invocation counter to generate a unique deterministic stream for each call, enabling reproducible sequences even across sessions.

random_color(cs::ColorSpace=SRGB(); rng=Random.GLOBAL_RNG)

Sample a random color uniformly from the given color space's gamut. Returns an RGB color.

random_colors(n::Int, cs::ColorSpace=SRGB(); rng=Random.GLOBAL_RNG)

Generate n random colors from the given color space.

random_palette(n::Int, cs::ColorSpace=SRGB(); 
               min_distance=30.0, rng=Random.GLOBAL_RNG)

Generate n visually distinct random colors using rejection sampling. Colors are separated by at least min_distance in CIEDE2000.

SRGB

sRGB / Rec.709 color space.

DisplayP3

Display P3 (Apple/DCI-P3 with D65) color space.

Rec2020

ITU-R BT.2020 (Rec. 2020) color space - Ultra HD / 4K / 8K.

CustomColorSpace

User-defined color space with arbitrary primaries.

current_colorspace() -> ColorSpace

Get the current preferred color space. Default: DisplayP3.

gay_space(cs::Symbol)

Set the current color space (:srgb, :p3, :rec2020).

rainbow(cs::ColorSpace=SRGB())

Get the Gilbert Baker rainbow flag colors.

transgender(cs::ColorSpace=SRGB())

Get the transgender pride flag colors.

bisexual(cs::ColorSpace=SRGB())

Get the bisexual pride flag colors.

nonbinary(cs::ColorSpace=SRGB())

Get the nonbinary pride flag colors.

pansexual(cs::ColorSpace=SRGB())

Get the pansexual pride flag colors.

asexual(cs::ColorSpace=SRGB())

Get the asexual pride flag colors.

pride_flag(name::Symbol, cs::ColorSpace=SRGB())

Get the colors of a pride flag in the specified color space.

(comrade-ring radius width)

Create a ring primitive with deterministic color from Gay.jl RNG.

(comrade-mring radius α β)

Create an azimuthal ring with Fourier structure.

(comrade-gaussian σx σy)

Create an elliptical Gaussian.

(comrade-disk radius)

Create a uniform disk.

(comrade-crescent r_out r_in shift)

Create a crescent (asymmetric ring).

(sky-add component1 component2 ...)

Combine sky components additively (like Comrade's ring + gaussian).

(sky-stretch model sx sy)

Stretch a model (like Comrade's Stretch modifier).

(sky-rotate model angle)

Rotate a model (like Comrade's Rotate modifier).

(sky-shift model dx dy)

Shift/translate a model (like Comrade's shifted).

sky_show(primitive)

Display a sky primitive as a colored S-expression. The parentheses are colored with the primitive's deterministic color.

sky_render(model; size=30)

Render a sky model as colored ASCII art. Each primitive contributes its color to the visualization.

(comrade-show model)

Display a model as colored S-expression + ASCII render.

comrade_model(; seed=42, style=:m87)

Build a Comrade-style sky model with deterministic colors. Returns the model and its colored S-expression representation.

Styles: :m87, :sgra, :custom

show_colors(colors; width=2)

Display colors as ANSI true-color blocks in the terminal.

show_palette(colors)

Display colors with their hex codes.

color_distance(c1::RGB, c2::RGB) -> Float64

Euclidean distance in RGB space (simple, fast).

Generate a color fingerprint for a set of seeds.

This is the FIRST-CONTACT VERIFICATION primitive: If Alice and Bob compute the same fingerprint from shared seeds, they have proven they're in the same "world" (same SPI implementation).

The fingerprint is computed as: hash([color_at(i; seed=s) for s in seeds for i in 1:12])

Because color_at is PURE, the fingerprint is deterministic.