Reference navigation
On this page
CLASS · v0.9.1
DensitySlice
A trilinearly sampled map plane with a fixed color scale and animated position.
from proteinmotion import DensitySliceConstructor
DensitySlice(
density,
axis='z',
position=0.5,
*,
scale=None,
opacity=1.0,
resolution=128,
follow=None,
)Parameters
| Parameter | Default | Description |
|---|---|---|
density | Required | DensityMap 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. |
position | 0.5 | Fractional location along the selected grid axis, from 0 to 1. |
scalekeyword only | None | ColorScale shared by the structure, plots, and legend. None derives limits from finite values. |
opacitykeyword only | 1.0 | Opacity in [0, 1], from transparent to opaque. |
resolutionkeyword only | 128 | Samples per edge of the slice plane: integer from 2 to 512. |
followkeyword only | None | Optional 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.
"""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)1UBQ PDBe density: animate the contour and move a slice past helix 23–34.
Methods and properties
| Name | Description |
|---|---|
| positionsproperty | Eight map corners in local coordinates, for camera framing. |
| set_slice()method | Set a slice’s fractional grid position. |
| mesh_data()method | Evaluate or reuse the cached local-space vertices, faces, colors, and normals. |
| set_opacity()method · inherited from MeshObject | Set or animate opacity in [0, 1]. |
| shift()method · inherited from MeshObject | Translate the object by an offset. |
| rotate()method · inherited from MeshObject | Rotate around the molecular centroid. |
| scale()method · inherited from MeshObject | Scale around the molecular centroid. |
| model_matrixproperty · inherited from MeshObject | Map object transform, including its followed protein transform if present. |
| snapshot()method · inherited from MeshObject | Capture the current state for deterministic timeline evaluation. |
| restore()method · inherited from MeshObject | Restore a state produced by snapshot(). |
| animateproperty · inherited from MeshObject | Animate opacity and transforms, or use set_level() on a surface and set_slice() on a slice. |
DensitySlice.positionsEight map corners in local coordinates, for camera framing.
Returns: Array with shape (selected atoms, 3), in ångströms.
DensitySlice.set_slice(position)Set a slice’s fractional grid position.
| Parameter | Default | Description |
|---|---|---|
position | Required | Fractional location along the selected grid axis, from 0 to 1. |
DensitySlice.mesh_data()Evaluate or reuse the cached local-space vertices, faces, colors, and normals.
Inherited from mesh.MeshObject.
DensitySlice.set_opacity(opacity)Set or animate opacity in [0, 1].
| Parameter | Default | Description |
|---|---|---|
opacity | Required | Opacity in [0, 1], from transparent to opaque. |
Returns: The object or animation builder.
Inherited from mesh.MeshObject.
DensitySlice.shift(vector)Translate the object by an offset.
| Parameter | Default | Description |
|---|---|---|
vector | Required | Finite 3D translation vector in ångströms. |
Returns: The object or animation builder.
Inherited from mesh.MeshObject.
DensitySlice.rotate(angle, axis=(0, 1, 0))Rotate around the molecular centroid.
| Parameter | Default | Description |
|---|---|---|
angle | Required | Rotation 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.
DensitySlice.scale(factor)Scale around the molecular centroid.
| Parameter | Default | Description |
|---|---|---|
factor | Required | Positive scale or zoom factor. |
Returns: The protein or animation builder.
Inherited from mesh.MeshObject.
DensitySlice.model_matrixMap object transform, including its followed protein transform if present.
Inherited from mesh.MeshObject.
DensitySlice.snapshot()Capture the current state for deterministic timeline evaluation.
Returns: State dictionary.
Inherited from mesh.MeshObject.
DensitySlice.restore(state)Restore a state produced by snapshot().
| Parameter | Default | Description |
|---|---|---|
state | Required | State returned by snapshot(). |
Returns: None
Inherited from mesh.MeshObject.
DensitySlice.animateAnimate opacity and transforms, or use set_level() on a surface and set_slice() on a slice.