Skip to main content

qMRI Colors

A Python package providing the recommended colormaps from Fuderer et al. (2024) for quantitative MRI visualization. This package makes it easy to use the scientifically-optimized lipari and navia colormaps in both matplotlib and vispy, eliminating the need for manual colormap registration in each project.

The colormaps are based on the research presented in "Colormaps for quantitative magnetic resonance imaging" (Magnetic Resonance in Medicine, 2024) and are sourced from the colorResources repository.

WARNING At the moment this package does not comply with the recommendations because it's not adapting to the underlying image, see https://magneticresonanceimaging.github.io/QMRIColors.jl/dev/clip/ for an explanation.

Installation

Install the package using uv (recommended) or pip:

# Using uv
uv add qmricolors

# Using pip
pip install qmricolors

VisPy support is optional:

pip install "qmricolors[vispy]"

For development:

git clone git@github.com:oscarvanderheide/qmricolors.git
cd qmricolors
uv sync

# Install in development mode to use examples
uv pip install -e .

Usage

Simply import the package to automatically register the custom colormaps:

import qmricolors

Matplotlib Usage

import matplotlib.pyplot as plt
import numpy as np
import qmricolors

# Create sample data
data = np.random.rand(100, 100)

# Use the custom colormaps
plt.figure(figsize=(12, 5))

plt.subplot(1, 2, 1)
plt.imshow(data, cmap='lipari')
plt.title('Lipari Colormap')
plt.colorbar()

plt.subplot(1, 2, 2)
plt.imshow(data, cmap='navia')
plt.title('Navia Colormap')
plt.colorbar()

plt.show()

VisPy Usage

from vispy import app, scene
from vispy.color import get_colormap
import numpy as np
import qmricolors

# Create sample data
data = np.random.rand(100, 100)

# Get custom colormap
lipari_cmap = get_colormap('lipari')

# Create visualization
canvas = scene.SceneCanvas(keys='interactive', show=True)
view = canvas.central_widget.add_view()
image = scene.visuals.Image(data, cmap=lipari_cmap, parent=view.scene)
view.camera = scene.PanZoomCamera(aspect=1)
view.camera.set_range()

app.run()

Note: If the VisPy window doesn't appear, this may be due to GUI backend issues. Try:

  1. Installing a GUI backend: pip install PyQt5 or pip install PySide2
  2. On macOS, you may need to run Python from the terminal rather than an IDE
  3. Use the simple test script: python test_vispy_simple.py

Direct API Usage

import qmricolors

# Get colormap for specific backend
lipari_mpl = qmricolors.get_colormap('lipari', backend='matplotlib')
navia_vispy = qmricolors.get_colormap('navia', backend='vispy')

# List available colormaps
print(qmricolors.AVAILABLE_CMAPS)  # ['lipari', 'navia']

# Register colormaps manually (if needed)
qmricolors.register_all_colormaps()

Available Colormaps

  • lipari: A scientifically-optimized colormap for quantitative MRI visualization
  • navia: A scientifically-optimized colormap for quantitative MRI visualization

These colormaps were designed based on perceptual uniformity principles and extensive testing for quantitative medical imaging, as described in Fuderer et al. (2024).

Customizing Colormaps

To use your own colormap data, replace the CSV files in the package:

  1. qmricolors/lipari.csv
  2. qmricolors/navia.csv

The CSV format should contain space-separated RGB values (without headers), with values between 0 and 1:

0.011370 0.073240 0.148284
0.013965 0.079062 0.155370
0.015899 0.084718 0.162521
0.017234 0.090035 0.169728
...

Each line represents one color with three space-separated values for red, green, and blue components.

Examples

The package includes several example scripts to demonstrate usage:

General Example

Test basic colormap functionality:

uv run qmricolors/examples/example.py

Matplotlib Example

See matplotlib-specific plotting examples:

uv run qmricolors/examples/matplotlib_example.py

VisPy Example

Interactive 3D visualization with VisPy (requires GUI):

uv run qmricolors/examples/vispy_example.py

Dependencies

  • matplotlib >= 3.10.3
  • vispy >= 0.15.2
  • numpy >= 1.21.0

References

License

[Add your license information here]

Contributing

[Add contribution guidelines here]

Metadata

Release files for qmricolors 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qmricolors 0.1.3
File Size Uploaded Provenance Actions
qmricolors-0.1.3.tar.gz 40.0 kB With provenance Details for qmricolors-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qmricolors 0.1.3
File Interpreter ABI Platform Actions
qmricolors-0.1.3-py3-none-any.whl Python 3 none any Details for qmricolors-0.1.3-py3-none-any.whl

Total release size: 56.2 kB

Release files / qmricolors-0.1.3.tar.gz

Download URL qmricolors-0.1.3.tar.gz
Size 40.0 kB
Tags Source
SHA-256 checksum
How to use checksums
911ebab9c730f36bc1ab3d06407700eb4ea87fe1c12f42118dedec1370e1deea
BLAKE2b-256 checksum
How to use checksums
1d9f616b6166766180cea9a9241acf0051c49cb0c803dad3aae1e67fc042dbec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / qmricolors-0.1.3-py3-none-any.whl

Download URL qmricolors-0.1.3-py3-none-any.whl
Size 16.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
af30ec20719f47d9a3cea135f172df9657fcfe445faa52695bcd6e91a00cf56f
BLAKE2b-256 checksum
How to use checksums
4f2c42c530c79992bdffec89ad970a2d99795633c63c58340a04f77cfb059249
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for qmricolors 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for qmricolors-0.1.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page