buy me caffeine

Scientific color maps

Scicomap helps you choose, assess, and improve scientific colormaps so your figures remain readable and faithful to the underlying data.

Blog post

Scicomap Medium blog post (free)

Official Documentation

Tutorial notebook

Install v2

Python 3.10 or newer is required. This checkout is the 2.0.0 release candidate; install it locally with pip install .. After publication, use pip install 'scicomap>=2,<3'.

Inspect the original map

Python and CLI use the same diagnostics and selected map:

import scicomap as sc

chart = sc.ScicoSequential("hawaii")
print(sc.diagnose_cmap(chart.cmap, chart.ctype)["status"])
chart.assess_cmap(figsize=(14, 6)).savefig("hawaii-original.png")

scicomap check hawaii --type sequential
scicomap preview hawaii --type sequential --out hawaii-original.png

Correct and reuse

Correction is explicit. Save the exact corrected colors for later use:

corrected = chart.unif_sym_cmap(lightness_rounding=0, bitonic=False)
chart.assess_cmap(figsize=(14, 6)).savefig("hawaii-corrected.png")
chart.export_cmap("hawaii.json")

scicomap fix hawaii --lightness-rounding 0 --no-bitonic --out hawaii-corrected.png --export hawaii.json
scicomap apply hawaii.json --image input.png --out mapped.png --json

Python plots return Figures; call plt.show() to display them. Only wizard prompts. Every CLI command accepts --json, which never prompts or opens a window; rendering requires --out. JSON responses use ok, command, inputs, data, warnings, and errors. Artifacts include their kind, absolute path, and selected map. Exit codes: 0 success, 2 invalid input, 1 operational failure.

Diagnostics are family-specific heuristics. CVD previews simulate selected color-vision conditions and do not certify accessibility. Review the actual figure, labels, contrast, and alternate encodings.

See the v2 migration guide for breaking changes and the user guide for scalar data, normalization, and report workflows.

Documentation map

• Getting Started: install and first workflow
• User Guide: choosing, assessing, and correcting colormaps
• Interactive Marimo Tutorial: browser-based reactive tutorial
• API Reference: module and class reference
• FAQ and Troubleshooting: practical answers for common issues
• LLM Access: llms.txt and markdown mirror policy

Development

Use just recipes with uv's project .venv. Routine commands use the committed lockfile without updating it. Run uv lock when changing dependencies.

just sync          # lint and test extras only
just check         # ordinary tests, Ruff on src/tests/scripts, and ty on src/scicomap
just sync-docs     # add documentation tools; Pandoc binary required separately
just docs          # build web docs and LLM assets
just check-docs    # strict generated examples and browser bootstrap tests

Run a focused test with uv run --locked python -m pytest tests/core/test_cmath.py. Tests marked docs need the docs extra and run separately through just check-docs.

Read the Docs is kept as a temporary fallback during the Pages rollout.

Contribution guidelines are available in CONTRIBUTING.md. Release notes are tracked in CHANGELOG.md and GitHub releases.

Background

Scicomap uses CAM02-UCS lightness J', chroma C', and hue to assess and transform colormaps. It builds on ehtplot and palettes from cmcrameri, cmasher, palettable, colorcet, and cmocean. See the introduction for color-space concepts and the gallery for the six map families.