Metadata-Version: 2.4
Name: scicomap
Version: 2.0.0
Summary: data visualization on maps with varying levels of granularity
Author-email: Thomas Bury <bury.thomas@gmail.com>
License: MIT License
        
        Copyright (c) [2021] [Thomas Bury]
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: homepage, https://github.com/ThomasBury/scicomap
Project-URL: documentation, https://thomasbury.github.io/scicomap/
Project-URL: repository, https://github.com/ThomasBury/scicomap.git
Project-URL: changelog, https://github.com/ThomasBury/scicomap/releases
Project-URL: Tracker, https://github.com/ThomasBury/scicomap/issues
Keywords: visualization,color,uniform,scientific
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: colorspacious
Requires-Dist: colorcet
Requires-Dist: cmcrameri
Requires-Dist: cmocean
Requires-Dist: cmasher>=1.5.8
Requires-Dist: palettable>=3.3.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: typer>=0.26.0
Requires-Dist: rich>=13.0.0
Provides-Extra: docs
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: marimo; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinxawesome-theme==5.0.0b5; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-tabs; extra == "docs"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Requires-Dist: ty; extra == "lint"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

<img src="pics/logo.png" alt="drawing" width="200"/>

[![Docs](https://img.shields.io/website?url=https%3A%2F%2Fthomasbury.github.io%2Fscicomap%2F&label=docs)](https://thomasbury.github.io/scicomap/)
[![Docs Quality](https://github.com/ThomasBury/scicomap/actions/workflows/docs.yml/badge.svg)](https://github.com/ThomasBury/scicomap/actions/workflows/docs.yml)
[![Marimo](https://img.shields.io/badge/marimo-live-1f7a8c.svg)](https://thomasbury.github.io/scicomap/marimo/index.html)
[![PyPI version](https://img.shields.io/pypi/v/scicomap.svg)](https://pypi.org/project/scicomap/)
[![Python](https://img.shields.io/pypi/pyversions/scicomap.svg)](https://pypi.org/project/scicomap/)
[![GitHub stars](https://img.shields.io/github/stars/ThomasBury/scicomap)](https://github.com/ThomasBury/scicomap/stargazers)

[buy me caffeine](https://ko-fi.com/V7V72SOHX)

# 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)](https://towardsdatascience.com/your-colour-map-is-bad-heres-how-to-fix-it-lessons-learnt-from-the-event-horizon-telescope-b82523f09469)

[Official Documentation](https://thomasbury.github.io/scicomap/)

[Tutorial notebook](./docs/source/notebooks/tutorial.ipynb)

## 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:

```python
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")
```

```shell
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:

```python
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")
```

```shell
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](docs/source/migrating-v2.rst) for breaking changes
and the [user guide](https://thomasbury.github.io/scicomap/user-guide.html)
for scalar data, normalization, and report workflows.

## Documentation map

- [Getting Started](https://thomasbury.github.io/scicomap/getting-started.html): install and first workflow
- [User Guide](https://thomasbury.github.io/scicomap/user-guide.html): choosing, assessing, and correcting colormaps
- [Interactive Marimo Tutorial](https://thomasbury.github.io/scicomap/marimo/index.html): browser-based reactive tutorial
- [API Reference](https://thomasbury.github.io/scicomap/api-reference.html): module and class reference
- [FAQ](https://thomasbury.github.io/scicomap/faq.html) and [Troubleshooting](https://thomasbury.github.io/scicomap/troubleshooting.html): practical answers for common issues
- [LLM Access](https://thomasbury.github.io/scicomap/llm-access.html): `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.

```shell
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](https://github.com/liamedeiros/ehtplot) and
palettes from cmcrameri, cmasher, palettable, colorcet, and cmocean.
See the [introduction](https://thomasbury.github.io/scicomap/Introduction.html)
for color-space concepts and the [gallery](https://thomasbury.github.io/scicomap/gallery.html)
for the six map families.
