Cleopatra

Cleopatra is a matplotlib utility package for visualizing 2D/3D numpy arrays, unstructured meshes, and statistical histograms. It targets scientific and research users working with geospatial and raster data, providing a high-level API over matplotlib with sensible defaults and rich customization.

Package Layout

graph TD
    cleopatra["cleopatra"]

    cleopatra --> glyph["glyph<br/>Glyph (base class)"]
    cleopatra --> array_glyph["array_glyph<br/>ArrayGlyph, FacetGrid"]
    cleopatra --> mesh_glyph["mesh_glyph<br/>MeshGlyph"]
    cleopatra --> statistical_glyph["statistical_glyph<br/>StatisticalGlyph"]
    cleopatra --> tiles["tiles<br/>add_tiles + helpers (optional 'tiles' extra)"]
    cleopatra --> colors["colors<br/>Colors"]
    cleopatra --> styles["styles<br/>Styles, Scale, ColorScale, MidpointNormalize"]
    cleopatra --> config["config<br/>Config (matplotlib backend helper)"]

    array_glyph -. extends .-> glyph
    mesh_glyph -. extends .-> glyph

Loading

• glyph provides the shared Glyph base class (figure/axes lifecycle, colorbars, color norms, ticks, animation).
• array_glyph (ArrayGlyph, FacetGrid), mesh_glyph (MeshGlyph), and statistical_glyph (StatisticalGlyph) are the user-facing visualizers; ArrayGlyph and MeshGlyph subclass Glyph, StatisticalGlyph stands alone.
• tiles adds the optional web-tile basemap helper (cleopatra.tiles.add_tiles), behind the cleopatra[tiles] extra.
• colors, styles, and config are supporting utilities (colour conversions, predefined styles / MidpointNormalize / ColorScale, and the matplotlib-backend helper).

Main Features

ArrayGlyph -- Raster / Array Visualization

• Plot 2D numpy arrays with automatic colorbar and customizable color scales (linear, power, symmetric log-norm, boundary-norm, midpoint).
• Display cell values and overlay point markers on the plot.
• Animate 3D arrays over time and export to GIF, MP4, MOV, or AVI (via ffmpeg).

MeshGlyph -- Unstructured Mesh Visualization

• Visualize UGRID-style unstructured mesh data using triangulation (tripcolor, tricontourf).
• Render wireframe outlines via LineCollection.
• Accepts raw numpy arrays of node coordinates and face-node connectivity.
• Animate time-varying mesh data.

StatisticalGlyph -- Histogram Plots

• Create histograms for 1D and 2D datasets with customizable bins, colors, and transparency.

Colors -- Color Utilities

• Convert between hex, RGB (0-255), and normalized RGB (0-1) formats.
• Extract color ramps from images and create custom matplotlib colormaps.

Installation

pip

pip install cleopatra

# with the optional web-tile basemap support (cleopatra.tiles.add_tiles)
pip install "cleopatra[tiles]"

conda

conda install -c conda-forge cleopatra

# with the optional web-tile basemap support
conda install -c conda-forge cleopatra-tiles

The conda packages are built from the cleopatra-feedstock (the cleopatra-tiles output bundles mercantile, pillow, pyproj, and xyzservices).

From source (latest development version)

pip install git+https://github.com/serapeum-org/cleopatra

Quick Start

Plot a 2D array

import numpy as np
from cleopatra.array_glyph import ArrayGlyph

arr = np.random.rand(10, 10)
glyph = ArrayGlyph(arr)
fig, ax = glyph.plot(title="Random Array")

Create a histogram

import numpy as np
from cleopatra.statistical_glyph import StatisticalGlyph

data = np.random.normal(0, 1, 1000)
stat = StatisticalGlyph(data)
fig, ax = stat.histogram(bins=30)

Plot an unstructured mesh

import numpy as np
from cleopatra.mesh_glyph import MeshGlyph

node_x = np.array([0.0, 1.0, 0.5, 1.5])
node_y = np.array([0.0, 0.0, 1.0, 1.0])
face_nodes = np.array([[0, 1, 2], [1, 3, 2]])
face_data = np.array([10.0, 20.0])

mg = MeshGlyph(node_x, node_y, face_nodes)
fig, ax = mg.plot(face_data, location="face", title="Mesh Data")

Requirements

• Python >= 3.11
• numpy >= 2.0.0
• matplotlib >= 3.8.4

Documentation

Full documentation is available at serapeum-org.github.io/cleopatra.

License

Cleopatra is licensed under the GNU General Public License v3.