prismatica

The universal compile-time scientific colormap library for Rust

[!IMPORTANT] Pre-1.0.0 — the API may change between minor versions. The API will be considered stable at 1.0.0.

Status

Highlights

• 308 scientific colormaps from 10 established collections
• 70 discrete palettes for categorical data (ColorBrewer, CartoColors, d3)
• Compile-time constants -- zero runtime file I/O, zero parsing
• #![no_std] -- core functionality works without allocation
• Continuous sampling -- linear interpolation between 256-step LUT entries for any t in [0, 1]
• Rich metadata -- every colormap carries its kind, perceptual uniformity flag, CVD safety, and citation
• Feature-gated collections -- include only the maps you need; ~1 KB per colormap
• Framework integrations -- bidirectional conversion for 19 crates including plotters, egui, image, bevy, ratatui, iced, palette, and more
• Sibling project -- chromata provides editor color themes with the same Color type and integration pattern

For Everyone

What are scientific colormaps?

A colormap is a function that converts a scalar value (like temperature, elevation, or density) into a color. When you see a weather map where blue means cold and red means hot, that is a colormap at work.

Perceptual uniformity means that equal steps in data produce equal steps in perceived color difference. Without it, your visualization can create false features -- bright bands or phantom boundaries that exist in the colormap but not in the data. The classic "rainbow" and "jet" colormaps are notorious for this.

Prismatica provides every established scientific colormap collection as compile-time Rust data. A researcher writes BATLOW.eval(0.5) and gets a perceptually uniform, colorblind-safe color. No files to load, no dependencies to install.

Quick start

Add prismatica to your project:

[dependencies]
prismatica = "0.3.0"

Use a colormap:

use prismatica::crameri::BATLOW;

let color = BATLOW.eval(0.5);
println!("RGB: ({}, {}, {})", color.r, color.g, color.b);

Supported collections

Choosing the right colormap

What prismatica is not

• Not a color manipulation library (use palette for that)
• Not a gradient builder (use colorgrad for custom gradients)
• Not a rendering engine
• Not a data visualization framework

Prismatica is the data layer. It answers one question: given a colormap name and a scalar t in [0, 1], what RGB color should I use?

For Researchers

The Color type

pub struct Color {
    pub r: u8,
    pub g: u8,
    pub b: u8,
}

Methods: new(r, g, b), from_hex(0xFF8800), to_css_hex(), to_f32(), lerp(other, t), luminance(), contrast_ratio(other).

Colormap sampling

use prismatica::crameri::BATLOW;

// Continuous: sample at any float in [0, 1]
let color = BATLOW.eval(0.5);

// Rational: the 30th of 100 evenly-spaced samples
let color = BATLOW.eval_rational(30, 100);

// Reversed direction (zero allocation)
let rev = BATLOW.reversed();
let color = rev.eval(0.2); // equivalent to BATLOW.eval(0.8)

// Extract N discrete colors
let legend_colors = BATLOW.colors(10);

Values outside [0, 1] are clamped. Interpolation is linear in sRGB space, matching matplotlib, ParaView, and most scientific tools.

Colormap discovery

use prismatica::{ColormapKind, all_colormaps, find_by_name, filter_by_collection};

// Find all perceptually uniform diverging colormaps
let diverging: Vec<_> = all_colormaps()
    .iter()
    .filter(|cm| {
        cm.meta.kind == ColormapKind::Diverging
            && cm.meta.perceptually_uniform
    })
    .collect();

// Look up by name
let viridis = find_by_name("viridis").unwrap();

// Filter by collection
let crameri_maps = filter_by_collection("crameri");

Discrete palettes

ColorBrewer, CartoColors, and d3 provide discrete palettes alongside continuous colormaps:

use prismatica::colorbrewer::SET2_PALETTE;

for i in 0..SET2_PALETTE.len() {
    let c = SET2_PALETTE.get(i);
    println!("Category {}: #{:02x}{:02x}{:02x}", i, c.r, c.g, c.b);
}

// Also available via the registry
let palette = prismatica::find_palette_by_name("Blues").unwrap();

Feature flags

Framework integrations

All integrations provide bidirectional conversion via From/Into. Enum-based types use TryFrom for the reverse direction. Enable all-integrations to get everything.

Binary size

Each colormap is a 256x3 = 768-byte LUT plus ~200 bytes of metadata. Approximately 1 KB per colormap.

Even with all 308 colormaps enabled, the total is smaller than a single PNG image.

Metadata

Every colormap carries structured metadata for programmatic filtering:

pub struct ColormapMeta {
    pub name: &'static str,              // "batlow"
    pub collection: &'static str,        // "crameri"
    pub author: &'static str,            // "Fabio Crameri"
    pub kind: ColormapKind,              // Sequential, Diverging, Cyclic, ...
    pub perceptually_uniform: bool,      // true
    pub cvd_friendly: bool,              // true (colorblind safe)
    pub grayscale_safe: bool,            // true
    pub lut_size: usize,                 // 256
    pub citation: &'static str,          // DOI / reference string
}

Citation

If you use prismatica in academic work, please cite the upstream colormap authors. Each colormap's meta.citation field contains the appropriate reference. Key citations:

• Crameri: Crameri, F. (2018). Scientific colour maps. Zenodo. doi:10.5281/zenodo.1243862
• CET: Kovesi, P. (2015). Good Colour Maps: How to Design Them. arXiv:1509.03700
• CMOcean: Thyng, K. M. et al. (2016). True colors of oceanography. Oceanography, 29(3), 10.
• CMasher: van der Velden, E. (2020). CMasher: Scientific colormaps for making accessible, informative and 'cmashing' plots. JOSS, 5(46), 2004.

For Developers

Architecture

Prismatica's core data model is simple:

1. A lookup table (LUT) of 256 evenly-spaced RGB values, stored as static [[u8; 3]; 256]
2. A metadata struct describing the colormap's properties
3. A sampling function that interpolates between LUT entries for any input t in [0, 1]

All colormap data is compiled into the binary as const/static arrays. There is no runtime I/O, no parsing, and no allocation for basic operations.

Module structure

src/
├── lib.rs              # Crate-level docs, re-exports, feature gates
├── types.rs            # Color, Colormap, ColormapMeta, ColormapKind, DiscretePalette
├── traits.rs           # Framework conversion traits (feature-gated)
├── registry.rs         # all_colormaps(), find_by_name(), filter functions, palette functions
├── prelude.rs          # Convenience re-exports
├── integration/        # Feature-gated framework conversions (19 crates)
│
├── matplotlib/         # Feature: "matplotlib" — 8 maps
├── crameri/            # Feature: "crameri" — 40 maps
├── cet/                # Feature: "cet" — 59 maps
├── cmocean/            # Feature: "cmocean" — 22 maps
├── colorbrewer/        # Feature: "colorbrewer" — 35 maps + 35 palettes
├── cmasher/            # Feature: "cmasher" — 53 maps
├── ncar/               # Feature: "ncar" — 44 maps
├── cartocolors/        # Feature: "cartocolors" — 34 maps + 34 palettes
├── moreland/           # Feature: "moreland" — 6 maps
└── d3/                 # Feature: "d3" — 7 maps + 1 palette

Code generation pipeline

Colormaps are not written by hand. A two-stage pipeline generates all colormap source code:

1. Fetch (cargo xtask fetch [collection]): Downloads upstream data and normalizes to data/{collection}/{name}.csv (256 rows of R,G,B as uint8) plus data/{collection}/{name}.json (metadata).

2. Generate (cargo xtask generate [collection]): Reads normalized CSV + JSON and emits Rust source files with const colormap definitions and static LUT arrays.

Upstream data -> cargo xtask fetch -> data/*.csv + data/*.json -> cargo xtask generate -> src/{collection}/*.rs

Data sources

Adding new colormaps

To add a new collection:

1. Add a fetch module in xtask/src/fetch/{collection}.rs
2. Register it in xtask/src/fetch/mod.rs
3. Run cargo xtask fetch {collection} to populate data/{collection}/
4. Add generate module (or use the generic path) in xtask/src/generate/
5. Run cargo xtask generate {collection} to emit src/{collection}/*.rs
6. Add a feature flag in Cargo.toml and add to the all feature
7. Add #[cfg(feature = "...")] module declaration in lib.rs
8. Add the collection to for_each_colormap() in registry.rs

Testing

cargo test                                         # All tests (unit + integration)
cargo test --all-features                          # With all collections enabled
cargo check --no-default-features --features core  # Verify no_std compatibility
cargo clippy -- -W clippy::all                     # Lint
cargo test --test property --features all          # Property-based tests (proptest)
cargo test --test snapshots --features all         # Snapshot tests (insta)

Snapshot tests use insta to detect codegen changes. After modifying the code generation pipeline, run cargo insta review to inspect and accept updated snapshots.

Code quality

#![no_std]
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used)]

Competitive positioning

Minimum supported Rust version

Rust edition 2024, targeting stable Rust 1.85+.

Support

If prismatica is useful to your projects, consider supporting development via thanks.dev.

License

This project is licensed under the GNU General Public License v3.0.

Prismatica bundles colormap data from multiple upstream sources, each with its own license. All upstream licenses are permissive (MIT, Apache-2.0, CC-BY, CC0, BSD-3, public domain) and compatible with GPL-3.0. See individual collection module docs for source URLs and license details.