ProteinMotion
Reference navigation
On this page

CLASS · v0.9.1

DensitySlice

A trilinearly sampled map plane with a fixed color scale and animated position.

python
from proteinmotion import DensitySlice

Constructor

python
DensitySlice(
    density,
    axis='z',
    position=0.5,
    *,
    scale=None,
    opacity=1.0,
    resolution=128,
    follow=None,
)

Parameters

ParameterDefaultDescription
densityRequiredDensityMap supplying scalar values and map coordinates.
axis'z'Map grid axis: x, y, or z. In a skew cell these follow the lattice voxel vectors.
position0.5Fractional location along the selected grid axis, from 0 to 1.
scalekeyword onlyNoneColorScale shared by the structure, plots, and legend. None derives limits from finite values.
opacitykeyword only1.0Opacity in [0, 1], from transparent to opaque.
resolutionkeyword only128Samples per edge of the slice plane: integer from 2 to 512.
followkeyword onlyNoneOptional Protein whose translation, rotation, and scale are applied to this map object. Density does not deform with atom coordinates.

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
python
"""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.

Methods and properties

NameDescription
positionspropertyEight map corners in local coordinates, for camera framing.
set_slice()methodSet a slice’s fractional grid position.
mesh_data()methodEvaluate or reuse the cached local-space vertices, faces, colors, and normals.
set_opacity()method · inherited from MeshObjectSet or animate opacity in [0, 1].
shift()method · inherited from MeshObjectTranslate the object by an offset.
rotate()method · inherited from MeshObjectRotate around the molecular centroid.
scale()method · inherited from MeshObjectScale around the molecular centroid.
model_matrixproperty · inherited from MeshObjectMap object transform, including its followed protein transform if present.
snapshot()method · inherited from MeshObjectCapture the current state for deterministic timeline evaluation.
restore()method · inherited from MeshObjectRestore a state produced by snapshot().
animateproperty · inherited from MeshObjectAnimate opacity and transforms, or use set_level() on a surface and set_slice() on a slice.
python
DensitySlice.positions

Eight map corners in local coordinates, for camera framing.

Returns: Array with shape (selected atoms, 3), in ångströms.

python
DensitySlice.set_slice(position)

Set a slice’s fractional grid position.

ParameterDefaultDescription
positionRequiredFractional location along the selected grid axis, from 0 to 1.
python
DensitySlice.mesh_data()

Evaluate or reuse the cached local-space vertices, faces, colors, and normals.

Inherited from mesh.MeshObject.

python
DensitySlice.set_opacity(opacity)

Set or animate opacity in [0, 1].

ParameterDefaultDescription
opacityRequiredOpacity in [0, 1], from transparent to opaque.

Returns: The object or animation builder.

Inherited from mesh.MeshObject.

python
DensitySlice.shift(vector)

Translate the object by an offset.

ParameterDefaultDescription
vectorRequiredFinite 3D translation vector in ångströms.

Returns: The object or animation builder.

Inherited from mesh.MeshObject.

python
DensitySlice.rotate(angle, axis=(0, 1, 0))

Rotate around the molecular centroid.

ParameterDefaultDescription
angleRequiredRotation angle in radians.
axis(0, 1, 0)Nonzero 3D rotation axis; it is normalized internally.

Returns: The protein or animation builder.

Inherited from mesh.MeshObject.

python
DensitySlice.scale(factor)

Scale around the molecular centroid.

ParameterDefaultDescription
factorRequiredPositive scale or zoom factor.

Returns: The protein or animation builder.

Inherited from mesh.MeshObject.

python
DensitySlice.model_matrix

Map object transform, including its followed protein transform if present.

Inherited from mesh.MeshObject.

python
DensitySlice.snapshot()

Capture the current state for deterministic timeline evaluation.

Returns: State dictionary.

Inherited from mesh.MeshObject.

python
DensitySlice.restore(state)

Restore a state produced by snapshot().

ParameterDefaultDescription
stateRequiredState returned by snapshot().

Returns: None

Inherited from mesh.MeshObject.

python
DensitySlice.animate

Animate opacity and transforms, or use set_level() on a surface and set_slice() on a slice.