tessl/pypi-cmasher

Scientific colormaps for making accessible, informative and 'cmashing' plots

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

CLI Tools

Name: tessl/pypi-cmasher
Author: tessl

Command-line interface tools for colormap management, visualization, and color extraction. The cmr command provides convenient access to CMasher functionality from the terminal.

Installation and Access

The CLI is automatically available after installing CMasher:

pip install cmasher

Access via the cmr command:

cmr --help

Capabilities

Basic Information Commands

Get CMasher Version

cmr --version
# Output: CMasher v1.9.2

Print BibTeX Citation

cmr bibtex

Prints the complete BibTeX entry for citing CMasher in scientific publications.

List Available Colormaps

cmr cmlist [--type TYPE]

# Options:
# --type: Filter by colormap type
#   all (default), s/seq/sequential, d/div/diverging, c/cyc/cyclic

Usage Examples

# List all colormaps
cmr cmlist

# List only sequential colormaps
cmr cmlist --type sequential
cmr cmlist --type seq
cmr cmlist --type s

# List diverging colormaps
cmr cmlist --type diverging
cmr cmlist --type div
cmr cmlist --type d

# List cyclic colormaps
cmr cmlist --type cyclic
cmr cmlist --type cyc
cmr cmlist --type c

Colormap Analysis Commands

Get Colormap Type

cmr cmtype CMAP

# Parameters:
# CMAP: Colormap name or object path (e.g., 'cmr.rainforest' or 'a.b:c.d')

Usage Examples

# Check CMasher colormap types
cmr cmtype cmr.rainforest    # Output: sequential
cmr cmtype cmr.iceburn       # Output: diverging
cmr cmtype cmr.seasons       # Output: cyclic

# Check matplotlib colormap types
cmr cmtype viridis           # Output: sequential
cmr cmtype coolwarm          # Output: diverging

Color Extraction Commands

Extract Specific Number of Colors

cmr cmcolors CMAP N [OPTIONS]

# Parameters:
# CMAP: Colormap name
# N: Number of colors to extract

# Options:
# --range LOWER UPPER: Normalized range to extract from (default: 0 1)
# --fmt FORMAT: Output format (default: float)
#   float/norm, int/8bit, str/hex

Usage Examples

# Extract 5 colors as normalized RGB
cmr cmcolors cmr.rainforest 5
# Output:
# 0.00000000 0.00000000 0.00000000
# 0.22612359 0.12458403 0.56299728
# 0.05482105 0.51583525 0.45667819
# 0.70961598 0.72286398 0.08347276
# 1.00000000 1.00000000 1.00000000

# Extract colors as hex strings
cmr cmcolors cmr.ocean 3 --fmt hex
# Output:
# #000000
# #0E8474
# #FFFFFF

# Extract colors as 8-bit RGB
cmr cmcolors cmr.iceburn 4 --fmt int
# Output:
# 0 0 0
# 58 32 144
# 181 184 21
# 255 255 255

# Extract from specific range
cmr cmcolors cmr.wildfire 5 --range 0.2 0.8 --fmt hex
# Output: colors from 20% to 80% of the colormap

# Extract with different range and format
cmr cmcolors cmr.tropical 10 --range 0.1 0.9 --fmt int

Get Full RGB Table

cmr rgbtable CMAP [OPTIONS]

# Parameters:
# CMAP: Colormap name

# Options:
# --range LOWER UPPER: Normalized range (default: 0 1)
# --fmt FORMAT: Output format (default: float)
#   float/norm, int/8bit, str/hex

Usage Examples

# Get complete RGB table
cmr rgbtable cmr.rainforest

# Get RGB table as hex values
cmr rgbtable cmr.ocean --fmt hex

# Get subset of colormap as 8-bit RGB
cmr rgbtable cmr.iceburn --range 0.3 0.7 --fmt int

# Get full RGB table with all colors as integers
cmr rgbtable cmr.wildfire --fmt int

# Extract specific range for analysis
cmr rgbtable cmr.seasons --range 0.25 0.75 --fmt float

Visualization Commands

View Single Colormap

cmr cmview CMAP [OPTIONS]

# Parameters:
# CMAP: Colormap name

# Options:
# --save [PATH]: Save plot to file (PNG if no path given)
# --test: Show colormap test pattern instead of gradient
# --gs/--grayscale: Show grayscale version alongside

Usage Examples

# Basic colormap view
cmr cmview cmr.rainforest

# View with grayscale comparison
cmr cmview cmr.iceburn --grayscale

# View with test pattern
cmr cmview cmr.ocean --test

# Save visualization
cmr cmview cmr.wildfire --save
cmr cmview cmr.seasons --save colormap_seasons.png

# Combined options
cmr cmview cmr.tropical --test --grayscale --save tropical_analysis.png

Module Generation Commands

Create Standalone Modules

cmr mkcmod CMAP [CMAP ...] [OPTIONS]

# Parameters:
# CMAP: One or more CMasher colormap names

# Options:
# -d/--dir DIR: Output directory (default: current directory)

Usage Examples

# Create module for single colormap
cmr mkcmod rainforest

# Create modules for multiple colormaps
cmr mkcmod iceburn wildfire ocean

# Create modules in specific directory
mkdir colormap_modules
cmr mkcmod rainforest iceburn --dir colormap_modules

# Create modules for all sequential colormaps
cmr mkcmod amber amethyst apple arctic bubblegum chroma cosmic --dir sequential_modules

Application Integration Commands

Tableau Integration

cmr app_usage tableau [OPTIONS]

# Options:
# -d/--dir DIR: Directory for Tableau preferences file (default: current)

Usage Examples

# Update Tableau preferences in current directory
cmr app_usage tableau

# Update in specific directory
cmr app_usage tableau --dir ~/Documents/My\ Tableau\ Repository/Preferences

# Update in Tableau's default location (adjust path for your system)
cmr app_usage tableau --dir "/c/Users/username/Documents/My Tableau Repository/Preferences"

Language Usage Information

cmr lang_usage r

Displays URL to documentation for using CMasher colormaps in R.

Advanced Usage Patterns

Batch Operations

# Create visualization for all diverging colormaps
for cmap in $(cmr cmlist --type diverging); do
    cmr cmview cmr.$cmap --save ${cmap}_view.png
done

# Extract color palettes for web design
mkdir web_colors
for cmap in rainforest ocean ember iceburn; do
    cmr cmcolors cmr.$cmap 8 --fmt hex > web_colors/${cmap}_palette.txt
done

# Generate standalone modules for distribution
mkdir cmasher_modules
cmr cmlist --type sequential | head -5 | xargs cmr mkcmod --dir cmasher_modules

Pipeline Integration

# Use in data processing pipeline
COLORMAP_TYPE=$(cmr cmtype cmr.rainforest)
echo "Using $COLORMAP_TYPE colormap for data visualization"

# Extract colors for external plotting tool
cmr cmcolors cmr.ocean 256 --fmt hex > ocean_colormap.hex

# Integrate with other tools
cmr rgbtable cmr.iceburn --fmt int | python process_colors.py

Configuration and Environment

# Set environment variable for additional colormap packages
export CMR_CMAP_PKGS="colorcet:cmocean"

# Use with custom colormap packages
cmr cmtype colorcet.fire  # If colorcet is installed

# Object path syntax for custom colormaps
cmr cmtype mypackage.colormaps:custom_cmap

Output Redirection and Processing

# Save colormap list to file
cmr cmlist > available_colormaps.txt

# Create color lookup table
cmr cmcolors cmr.rainforest 100 --fmt hex > rainforest_lut.txt

# Extract specific color ranges
cmr cmcolors cmr.iceburn 20 --range 0.0 0.5 --fmt int > iceburn_cool.rgb
cmr cmcolors cmr.iceburn 20 --range 0.5 1.0 --fmt int > iceburn_warm.rgb

# Process multiple colormaps
echo "rainforest ocean ember" | xargs -n1 -I{} cmr cmcolors cmr.{} 5 --fmt hex

Help and Documentation

# Get general help
cmr --help

# Get help for specific commands
cmr cmcolors --help
cmr cmview --help
cmr app_usage --help

# Get help for subcommands
cmr app_usage tableau --help
cmr lang_usage --help

Error Handling

The CLI provides informative error messages:

# Invalid colormap name
cmr cmtype invalid_colormap
# Output: Requested 'CMAP' ('invalid_colormap') cannot be found!

# Invalid command
cmr invalidcommand
# Shows help with available commands

# Missing required arguments
cmr cmcolors
# Shows usage information for cmcolors command

Integration with Scripts

#!/usr/bin/env python3
import subprocess
import json

def get_cmasher_info(cmap_name):
    """Get colormap information using CLI."""
    
    # Get colormap type
    result = subprocess.run(['cmr', 'cmtype', f'cmr.{cmap_name}'], 
                          capture_output=True, text=True)
    cmap_type = result.stdout.strip()
    
    # Get color palette
    result = subprocess.run(['cmr', 'cmcolors', f'cmr.{cmap_name}', '10', '--fmt', 'hex'],
                          capture_output=True, text=True)
    colors = result.stdout.strip().split('\n')
    
    return {
        'name': cmap_name,
        'type': cmap_type,
        'palette': colors
    }

# Example usage
info = get_cmasher_info('rainforest')
print(json.dumps(info, indent=2))

Install with Tessl CLI