Reference navigation

On this page

CLASS · v0.9.1

DensityMap

An immutable scalar grid with physical coordinates and optional periodic boundaries.

from proteinmotion import DensityMap

Constructor

DensityMap(
    values,
    *,
    spacing=1.0,
    origin=(0, 0, 0),
    basis=None,
    periodic=False,
    max_voxels=32000000,
)

Parameters

Parameter	Default	Description
`values`	Required	Finite three-dimensional array in (x, y, z) order, with at least two samples per axis.
`spacing`keyword only	`1.0`	Positive scalar or (x, y, z) voxel spacing in ångströms for an orthogonal grid.
`origin`keyword only	`(0, 0, 0)`	Physical (x, y, z) origin of the first voxel, in ångströms.
`basis`keyword only	`None`	Optional 3×3 matrix whose columns are voxel step vectors in ångströms; replaces spacing.
`periodic`keyword only	`False`	Wrap sampling and crops at cell boundaries for a full periodic grid.
`max_voxels`keyword only	`32000000`	Maximum number of allocated grid values, default 32 million.

Attributes

Name	Description
`values`	Read-only float32 grid in x, y, z order.
`origin`	Origin in ångströms.
`basis`	Voxel step vectors as matrix columns.
`mean`	Mean of the source grid, preserved in crops.
`std`	Standard deviation of the source grid, preserved in crops.
`periodic`	Whether sampling wraps around the grid.

Example and output

This excerpt runs inside a scene’s construct() method. The full example file includes imports, structure loading, and camera setup. Run it from a repository checkout.

Code Full script

"""1UBQ electron density from PDBe, with a contour and a moving density slice.

Source: https://www.ebi.ac.uk/pdbe/coordinates/files/1ubq.ccp4
Retrieved 2026-09-17. The supplied map covers a complete crystallographic unit
cell. Cropping extends periodic data across the cell boundary when needed.
Sigma contours use the mean and standard deviation of the original map.
"""

from pathlib import Path

from proteinmotion import (
    ColorLegend,
    ColorScale,
    DensityMap,
    FadeIn,
    FadeOut,
    Protein,
    ProteinScene,
    Text,
)

DATA = Path(__file__).parent / "data"


class DensityMaps(ProteinScene):
    def construct(self):
        protein = Protein.from_file(DATA / "1ubq.cif").ball_and_stick().center()
        protein.set_residue_opacity(0.08)
        helix = protein.select(chain="A", residues=(23, 34))
        helix.set_opacity(1)
        density = DensityMap.from_file(DATA / "1ubq.ccp4")
        local = density.crop(helix, padding=2.5)
        shell = local.isosurface(1.5, opacity=0.28, follow=protein)
        scale = ColorScale(-0.5, 2, colors=("#10243d", "#438ca4", "#f5df93"))
        section = local.slice("z", 0.15, scale=scale, follow=protein, resolution=96)
        self.add(protein, shell)
        self.camera.frame(helix, margin=1.55)
        self.camera.orbit(theta=0.22, phi=0.18)
        self.add(Text("Electron density", position=(0.06, 0.07), font_size=42))
        self.add(Text("1UBQ · helix 23–34 · PDBe map", position=(0.06, 0.13), font_size=25))
        self.play(FadeIn(shell), run_time=1)
        self.play(shell.animate.set_level(2.5), self.camera.animate.orbit(theta=0.25), run_time=2)
        self.play(shell.animate.set_level(1.5), run_time=1.5)
        self.play(FadeIn(section), run_time=1)
        self.add(ColorLegend(scale, title="Map value", position=(0.06, 0.81)))
        self.play(section.animate.set_slice(0.85), run_time=3)
        self.play(FadeOut(section), run_time=1)
        self.wait(0.5)

Output Preview · 10.0 s · 60 fps

Electron density and slices

1UBQ PDBe density: animate the contour and move a slice past helix 23–34.

Full source: DensityMaps Download MP4

Methods and properties

Name	Description
from_file()class method	Read MRC/CCP4, optionally gzip-compressed, using Gemmi with map axes and physical coordinates preserved.
boundsproperty	Eight corners in map coordinates, suitable for framing.
sample()method	Trilinear sampling in Å. Periodic grids wrap; other outside points return NaN.
crop()method	Crop a box around a selected region in its protein’s local coordinates, with padding in ångströms.
isosurface()method	Create a shaded marching-cubes contour.
slice()method	Create a trilinearly sampled, colored slice plane.

from_file()

View source

DensityMap.from_file(path, *, origin='auto', max_voxels=32000000)

Read MRC/CCP4, optionally gzip-compressed, using Gemmi with map axes and physical coordinates preserved.

Parameter	Default	Description
`path`	Required	Input or output file path, as specified by the operation.
`origin`keyword only	`'auto'`	auto prefers a nonzero ORIGIN field, otherwise grid starts; header or start forces that convention.
`max_voxels`keyword only	`32000000`	Maximum surface grid cells; increase this limit for large structures or finer grids.

Returns: Protein

Full crystallographic unit-cell grids are periodic. Cropped maps and EM volumes retain their stored extent. No symmetry expansion is performed.

bounds

View source

DensityMap.bounds

Eight corners in map coordinates, suitable for framing.

sample()

View source

DensityMap.sample(points)

Trilinear sampling in Å. Periodic grids wrap; other outside points return NaN.

Parameter	Default	Description
`points`	Required	Coordinates with shape (points, 3), in model ångströms.

crop()

View source

DensityMap.crop(region, *, padding=4.0)

Crop a box around a selected region in its protein’s local coordinates, with padding in ångströms.

Parameter	Default	Description
`region`	Required	Region selection attached to a protein.
`padding`keyword only	`4.0`	Extra highlight size in ångströms. None selects a default for the highlight style.

Periodic maps wrap across cell boundaries. Crops preserve the original mean and standard deviation for sigma contours.

isosurface()

View source

DensityMap.isosurface(
    level=1.0,
    *,
    units='sigma',
    color='#75d5cb',
    opacity=0.3,
    step_size=1,
    follow=None,
)

Create a shaded marching-cubes contour.

Parameter	Default	Description
`level`	`1.0`	Contour value in the units chosen for this surface.
`units`keyword only	`'sigma'`	sigma for mean + level × standard deviation, or absolute for a stored map value.
`color`keyword only	`'#75d5cb'`	Hex color or RGB values. For tint setters, None restores the representation’s base palette.
`opacity`keyword only	`0.3`	Opacity in [0, 1], from transparent to opaque.
`step_size`keyword only	`1`	Positive marching-cubes grid stride. Larger values reduce extraction cost and detail.
`follow`keyword only	`None`	Optional Protein whose translation, rotation, and scale are applied to this map object. Density does not deform with atom coordinates.

slice()

View source

DensityMap.slice(
    axis='z',
    position=0.5,
    *,
    scale=None,
    opacity=1.0,
    resolution=128,
    follow=None,
)

Create a trilinearly sampled, colored slice plane.

Parameter	Default	Description
`axis`	`'z'`	Map grid axis: x, y, or z. In a skew cell these follow the lattice voxel vectors.
`position`	`0.5`	Fractional location along the selected grid axis, from 0 to 1.
`scale`keyword only	`None`	ColorScale shared by the structure, plots, and legend. None derives limits from finite values.
`opacity`keyword only	`1.0`	Opacity in [0, 1], from transparent to opaque.
`resolution`keyword only	`128`	Samples per edge of the slice plane: integer from 2 to 512.
`follow`keyword only	`None`	Optional Protein whose translation, rotation, and scale are applied to this map object. Density does not deform with atom coordinates.