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:
- Installing a GUI backend:
pip install PyQt5orpip install PySide2 - On macOS, you may need to run Python from the terminal rather than an IDE
- 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:
qmricolors/lipari.csvqmricolors/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
- Fuderer, M., et al. (2024). Colormaps for quantitative magnetic resonance imaging. Magnetic Resonance in Medicine. https://pubmed.ncbi.nlm.nih.gov/39415361/
- Original colormap resources: https://github.com/mfuderer/colorResources
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.