map: Density maps

3D image data from electron microscopy, X-ray crystallography, light microscopy, and medical imaging, and segmentations can be read from dozens of file formats, saved to a few formats (e.g. MRC or HDF5), rendered as transparent 3D image stacks or contour surfaces, filtered (e,g. smoothing), fit with atomic models, annotated with markers, measured, segmented.

Classes

  • Volume - model for drawing 3d images.

  • VolumeSurface - calculates and renders contour surfaces, child model of Volume.

  • VolumeImage - volumetric image rendering, child model of Volume.

  • RenderingOptions - settings for surface and image renderings.

  • GridData - 3d image data, does not render it.

  • ArrayGridData - 3d image data created from a numpy array.

Read, Write, Create

Operations

These operations create new Volume models from existing ones and implement the Chimera volume subcommands (e.g. “volume resample”).

Volume

class Volume(session, data, region=None, rendering_options=None)

Bases: Model

A Volume is a Model that renders a 3-d image of a GridData object. It includes color, display styles including surface, mesh and grayscale, contouring levels, brightness and transparency for grayscale rendering, region bounds for display a subregion including single plane display, subsampled display of every Nth data value along each axis, outline box display.

session

The session that the Volume will belong to.

Type:

Session

data

3D data array

Type:

GridData

region

Initial displayed subregion of 3D array

Type:

(ijk_min, ijk_max, ijk_step)

rendering_options

Appearance settings for surface and image display.

Type:

RenderingOptions

add_surface(level, rgba=(0.7, 0.7, 0.7, 1), display=True)

Supported API . Create and add a new VolumeSurface with specified contour level and color.

property display
property name
new_region(ijk_min=None, ijk_max=None, ijk_step=None, adjust_step=True, adjust_voxel_limit=True)

Experimental API . Set new display region and optionally shows it.

property overall_color
remove_surfaces(surfaces=None)

Supported API . Remove a list of VolumeSurface instances from this Volume. If surfaces is None then all current surfaces are removed.

set_display_style(style)

Experimental API . Set display style to “surface”, “mesh”, or “image”.

set_parameters(surface_levels=None, surface_colors=None, transparency=None, brightness=None, image_levels=None, image_colors=None, transparency_depth=None, image_brightness_factor=None, default_rgba=None, **rendering_options)

Experimental API . Set volume display parameters.

Parameters:

  • surface_levels (list of float) – Threshold levels for contour surfaces.

  • surface_colors (list of (r,g,b) or (r,g,b,a)) – Color for each surface level, color components have 0-1 range.

  • transparency (float) – Surface transparency, 0 = fully opaque, 1 = fully transparent.

  • brightness (float) – Scale surface brightness by this factor.

  • image_levels (list of (float, float)) – Pairs of (threshold, brightness) where threshold is a map value and brighness ranges from 0-1. This defines a piecewise linear brightness curve for image style rendering.

  • image_colors (list of (r,g,b) or (r,g,b,a)) – Color associated with each image level, color components have 0-1 range.

  • transparency_depth (float) – Controls how transparent image style renderings are, range 0-1. Image rendering makes opacity equal to brightness, ie. full brightness (= 1) image levels are fully opaque, and 0 brightness levels are fully transparent. The thickness that produces this transparency is the displayed region size multiplied by the transparency depth, where the region size is the size along the axis (x, y, or z) having fewest grid points.

  • image_brightness_factor (float) – Scale image style rendering by this factor.

  • default_rgba (4 floats) – Initial color (red, green, blue, alpha) to use for surface and image style renderings. Color components in range 0-1.

  • rendering_options (all additional settings) – Any RenderingOption attribute name and value can be specified as a keyword option.

set_transparency(alpha)

Experimental API . Alpha values in range 0-255. Only changes current style (surface/mesh or image).

show(style=None, rendering_options=None, show=True)

Experimental API . Deprecated: Use v.display = True. Display the volume using the current parameters.

show_outline_box(show, rgb, linewidth)

Experimental API . Show an outline box enclosing the displayed subregion of the volume.

surface_bounds()

Experimental API . Surface bounds in volume coordinate system.

property surfaces

Supported API. Return a list of VolumeSurface instances for this Volume.

RenderingOptions

class RenderingOptions

Rendering options for a Volume that specify details of how surface and image style depictions appear. Some options are not implemented but existed in Chimera and may be implemented in the future.

show_outline_box

Whether a outline box is shown for the displayed subregion.

Type:

False

outline_box_rgb

Outline box color (red, green, blue) components, range 0-1.

Type:

(1,1,1)

limit_voxel_count

Whether to auto-adjust step size so at most voxel_limit voxels are shown.

Type:

True

voxel_limit

Choose step size so the region has at most this many Mvoxels.

Type:

16

color_mode

Sets the pixel format for image style rendering color vs grayscale, transparent vs opaque, and bits per color component. (auto|opaque|rgba|rgb|la|l)(4|8|12|16).

Type:

‘auto8’

color_modes

The allowed color modes for image style rendering. Read only.

Type:

(‘auto4’, ‘auto8’, ‘auto12’, ‘auto16’, ‘opaque4’, ‘opaque8’, ‘opaque12’, ‘opaque16’, ‘rgba4’, ‘rgba8’, ‘rgba12’, ‘rgba16’, ‘rgb4’, ‘rgb8’, ‘rgb12’, ‘rgb16’, ‘la4’, ‘la8’, ‘la12’, ‘la16’, ‘l4’, ‘l8’, ‘l12’, ‘l16’)

colormap_on_gpu

Whether colors are computed from map values on the gpu for image style rendering.

Type:

False

colormap_size

If colormap_on_gpu is true, what is the size of the colormap for map values that are not 8 or 16-bit data types.

Type:

2048

colormap_extend_left

Whether the image coloring applies to map values less than the minimum Volume image_level.

Type:

False

colormap_extend_right

Whether the image coloring applies to map values greater than the maximum Volume image_level.

Type:

True

blend_on_gpu

Whether image rendering blends images on gpu instead of cpu.

Type:

False

projection_mode

Determines what slices are used for image rendering.

Type:

‘auto’

projection_modes

Allowed projection modes. Read only.

Type:

(‘auto’, ‘2d-xyz’, ‘2d-x’, ‘2d-y’, ‘2d-z’, ‘3d’)

plane_spacing

Spacing of slices for image style rendering. Values “min”, “max”, “mean” use the grid spacing, or specific distance value can be given.

Type:

‘min’

full_region_on_gpu

For image rendering is the entire map kept on the GPU for fast cropping.

Type:

False

bt_correction

Image rendering axis-dependent brightness and transparency correction. Not implemented.

Type:

False

minimal_texture_memory

Whether to reuse a single texture for image rendering. Not implemented.

Type:

False

maximum_intensity_projection

Whether to use maximum intensity projection image rendering. If False then transparent blending is used.

Type:

False

linear_interpolation

Whether image rendering linearly interpolates pixel colors.

Type:

True

dim_transparency

Whether transparent surface rendering multiplies colors by opacity making more transparent voxels dimmer. True uses (alpha, 1-alpha) blending while False uses (1, 1-alpha) blending.

Type:

True

dim_transparent_voxels

Whether transparent image rendering multiplies colors by opacity making more transparent voxels dimmer. True uses (alpha, 1-alpha) blending while False uses (1, 1-alpha) blending.

Type:

True

line_thickness

The thickness of lines in pixels for mesh display. Not implemented because OpenGL core profile does not support line thickness.

Type:

1

smooth_lines

Whether mesh lines are rendered with anti-aliasing giving a smoother appearance.

Type:

False

mesh_lighting

Whether mesh rendering uses directional lighting.

Type:

True

two_sided_lighting

Whether the interior of surfaces and meshes have directional lighting. Not implemented, always uses two-sided.

Type:

True

flip_normals

Whether negative map values have surface normals flipped. Not implemented. This only has an effect when two sided lighting is false, and that mode is not implemented.

Type:

False

subdivide_surface

Whether to split every triangle into 4 smaller triangles for surfaces and meshes.

Type:

False

subdivision_levels

How many levels of triangle splitting to apply if subdivide surface is True. A value of 1 divides triangles into 4 smaller triangles, 2 divides into 16 smaller triangles, N divides into 4^N smaller triangles.

Type:

1

surface_smoothing

Whether to move surface or mesh vertices to give smoother surface appearance.

Type:

False

smoothing_iterations

How many iterations of smoothing to apply if surface smoothing is enabled.

Type:

2

smoothing_factor

When surface smoothing each vertex is moved a fraction of the ways towards the average position of the connected vertices. This parameter is the fraction.

Type:

.3

square_mesh

Whether mesh display hides diagonal mesh lines. If true than only mesh lines intersecting the xy, yz, and xz grid planes are shown.

Type:

True

cap_faces

Whether surface and mesh display covers the holes on the faces of the volume box where the surface reaches the box boundaries.

Type:

True

orthoplanes_shown

For image style display, show 0 to 3 orthogonal planes perpendicular to x,y,z axes. If any of the 3 values is True then orthoplane mode is enabled.

Type:

(False, False, False)

orthoplane_positions

The center voxel i,j,k grid index for orthoplane image rendering.

Type:

(0,0,0)

tilted_slab_axis

If image_mode is “tilted slab” then this is the axis perpendicular to the displayed slab in volume xyz coordinates.

Type:

(0,0,1)

tilted_slab_offset

Offset of the front face of the slab. The front face plane is defined by dot((x,y,z), tilted_slab_axis) = tilted_slab_offset

Type:

0

tilted_slab_spacing

Spacing of planes shown in tilted slab mode in physical units.

Type:

1

tilted_slab_plane_count

Number of planes shown in tilted slab mode.

Type:

1

image_mode

The mode for image style rendering. Can be ‘full region’, ‘orthoplanes’, ‘box faces’, or ‘tilted slab’.

Type:

‘full region’

backing_color

Color drawn behind transparent image rendering. This blocks the view of objects and the background behind the volume and can give better contrast (e.g. black backing when white background color in use).

Type:

None

VolumeSurface

class VolumeSurface(volume, level, rgba=(1, 1, 1, 1), mesh=False)

Bases: Surface

Model for displaying a contour surface of a Volume model. These models are children of a Volume and should only be created by the Volume.add_surface() method.

property color
property colors
property level

Threshold level for the surface. Settable.

property rgba

Float red,green,blue,alpha values in range 0-1

set_brightness(brightness)

Experimental API . Scale color so maximum of red, green, blue components equals 255*brightness.

set_transparency(alpha)

Experimental API . Set surface transparency, 0-255 range.

VolumeImage

class VolumeImage(volume)

Bases: Image3d

Model for displaying 3d semi-transparent images. These models are children of a Volume model and should only be created by Volume.

property overall_color

Return average color.

GridData

class GridData(size, value_type=<class 'numpy.float32'>, origin=(0, 0, 0), step=(1, 1, 1), cell_angles=(90, 90, 90), rotation=((1, 0, 0), (0, 1, 0), (0, 0, 1)), symmetries=None, name='', path='', file_type='', grid_id='', default_color=None, time=None, channel=None)

3-dimensional array of numeric values usually representing a density map from electron microscopy, x-ray crystallography or optical imaging. The grid points are positioned in space with array index (0,0,0) at the xyz origin, and spacing along the xyz axes given by the step parameter. The rectangular grid can be skewed by specifying angles between each pair of axes as is done to describe crystallographic unit cells. The grid can also be rotated. Values are read from a file for rectangular subregions of the data and cached in memory. The numeric values can be signed or unsigned integer of 8, 16, or 32 bits or real 32-bit or 64-bit values.

size

The number of grid points along x,y,z axes.

Type:

3 integers

value_type

Numeric type of the data values. Default numpy.float32

Type:

numpy.dtype

origin

Position of grid index (0,0,0) in physical coordinates (x,y,z) (usually Angstroms). Default (0,0,0).

Type:

3 floats

step

Grid plane spacing along x,y,z axes. Default (1,1,1)

Type:

3 floats

cell_angles

Cell angles for skewed crystallography maps. Angles (alpha,beta,gamma) between yz, xz, and xy axes in degrees. Default (90,90,90).

Type:

3 floats

rotation

Rotation matrix in physical coordinates. Default ((1,0,0),(0,1,0),(0,0,1))

Type:

3x3 matrix

symmetries

Symmetry transformations that map the to itself in physical coordinates. Default None means no symmetries.

Type:

Places or None

name

Descriptive name of grid data. Default ‘’

Type:

string

path

File path or paths to location of data file. Default ‘’. Data need not come from a file.

Type:

string or list of strings

file_type

File format name when data is read from a file. Default ‘’.

Type:

string

grid_id

Identifier for a specific data set in a file for file formats that allow more than one map in a single file, such as HDF5 format.

Type:

string

default_color

Red, green, blue, alpha color values (range 0-1) indicating preferred color

Type:

4 floats or None

time

Integer time point for time series volume data. Usually 0 based but not required. Default None.

Type:

integer or None

channel

Integer channel number for multi-channel data (e.g. light microscopy). Default None.

Type:

integer or None

ijk_to_xyz(ijk)

Supported API . A matrix i,j,k index corresponds to a point in x,y,z space. This function maps the matrix index to the xyz point. The index can be floating point, non-integral values.

matrix(ijk_origin=(0, 0, 0), ijk_size=None, ijk_step=(1, 1, 1), progress=None, from_cache_only=False)

Supported API . Return a numpy array for a box shaped subregion of the data with specified index origin and size. Every Nth point can be take along an axis by specifying ijk_step. If step size is greater than 1 then the returned array will be smaller than the requested size. The requested ijk_size refers to the region size of the full-resolution array (counting every grid point). The array can be read from a file or be a cached copy in memory. The array should not be modified.

read_matrix(ijk_origin=(0, 0, 0), ijk_size=None, ijk_step=(1, 1, 1), progress=None)

Supported API . Must overide this function in derived class to return a 3 dimensional NumPy matrix. The returned matrix has size ijk_size and element ijk is accessed as m[k,j,i]. It is an error if the requested submatrix does not lie completely within the full data matrix. It is also an error for the size to be <= 0 in any dimension. These invalid inputs might throw an exception or might return garbage. It is the callers responsibility to make sure the arguments are valid.

voxel_count()

Supported API . Return the total number of voxels.

voxel_volume()

Supported API . Volume of one voxel including skewing.

xyz_to_ijk(xyz)

Supported API . A matrix i,j,k index corresponds to a point in x,y,z space. This function maps the xyz point to the matrix index. The returned matrix index is floating point and need not be integers.

ArrayGridData

class ArrayGridData(array, origin=(0, 0, 0), step=(1, 1, 1), cell_angles=(90, 90, 90), rotation=((1, 0, 0), (0, 1, 0), (0, 0, 1)), symmetries=(), name='')

Bases: GridData

Supported API. Create a GridData from a 3-dimensional numpy array.

array

Data array can be any scalar numpy type.

Type:

3D numpy array

origin

Position of grid index (0,0,0) in physical coordinates (x,y,z) (usually Angstroms). Default (0,0,0).

Type:

3 floats

step

Grid plane spacing along x,y,z axes. Default (1,1,1)

Type:

3 floats

cell_angles

Cell angles for skewed crystallography maps. Angles (alpha,beta,gamma) between yz, xz, and xy axes in degrees. Default (90,90,90).

Type:

3 floats

rotation

Rotation matrix in physical coordinates. Default ((1,0,0),(0,1,0),(0,0,1))

Type:

3x3 matrix

symmetries

Symmetry transformations that map the to itself in physical coordinates. Default None means no symmetries.

Type:

Places or None

name

Descriptive name. Default ‘’

Type:

string

Open and Save 3D Image Data

open_map(session, path, name=None, format=None, **kw)

Supported API . Open a density map file having any of the known density map formats. File path can be a string or list of paths.

Parameters:

  • session (Session) – The session that the created Volume will belong to.

  • path (string) – File path on disk.

  • name (string or None) – Name used when creating the Volume model. If None, then the name will be the file name.

  • format (string or None) – Name of the file format. The available formats can be listed with ChimeraX command “open formats”. If None, then the format is derived from the file suffix.

  • channel (int) – The channel number to assign for multi-channel data.

  • vseries (bool) – Whether to treat the open data as a time series.

  • show (bool) – Whether the Volume should be shown or hidden initially.

Returns:

  • models (list of Volume)

  • message (description of the opened data)

save_map(session, path, format_name, models=None, region=None, step=(1, 1, 1), mask_zone=True, subsamples=None, chunk_shapes=None, append=None, compress=None, compress_method=None, compress_level=None, compress_shuffle=None, base_index=1, value_type=None, **kw)

Supported API . Save a density map file having any of the known density map formats.

Parameters:

  • session – Session The session containing the Volume models.

  • path – string File path on disk. For saving multiple volumes to multiple files the path can contain a C-style integer format specifier like “%d” or “%03d” which will have be replaced by integer values starting at parameter base_index for each of the volumes specified in parameter models.

  • format_name – string or None Name of the file format. The available formats can be listed with ChimeraX command “save formats”. If None, then the format is derived from the file suffix.

  • models – list of Volume Volume models to save. Some formats allow saving multiple volumes in one file and some do not. It is an error to specify multiple models if the format only supports saving one volume and the path does not contain a “%d” style integer substitution.

  • region – 6 integers or None Save only the subregion imin,jmin,kmin,imax,jmax,kmax. If None the current volume region is saved.

  • step – 3 integers Save only subsampled data using this step.

  • mask_zone – bool If only a zone is shown near atoms or markers write zeros outside that zone in the saved file if this option is True, otherwise save original data values outside zone. Default True

  • base_index – int When saving multiple files with a C-style integer substitution like “%d” in the path this will be the first integer used. Default 1.

Parameters below only supported by Chimera Map format (*.cmap)

Parameters:

  • subsamples – list of tuples of 3 integers or None For file formats that support saving multiple subsampled copies of the data , this lists the specific subsamples to save. Chimera map format will automatically determine subsamples to save if this is not specified.

  • chunk_shapes – list of ‘xyz’, ‘xzy’, ‘yxz’, ‘yzx’, ‘zxy’, ‘zyx’ Axis order for laying out the data in the file. Can save multiple axis orders for faster performance access of data slices from disk.

  • append – bool Whether to append this volume to an existing file. Default False.

  • compress – bool Whether to compress the data in the file. Default False.

  • compress_method – string Compression method to use. Default zlib. Some HDF5 compression methods are ‘zlib’, ‘lzo’, ‘bzip2’, ‘blosc’, ‘blosc:blosclz’, ‘blosc:lz4’, ‘blosc:lz4hc’, ‘blosc:snappy’, ‘blosc:zlib’, ‘blosc:zstd’.

  • compress_level – integer 1 to 9 Level of compression. Default 5. Higher compression levels take longer. Not all compression methods use level.

  • compress_shuffle – bool Option to blosc compression. Default False.

Parameters below only supported for MRC format (*.mrc)

Parameters:

value_type – string Numeric value type to save in MRC file. Can be int8, int16, uint16, float16, float32. If not specified then the closest type holding the actual map value type is used.

Create a Volume from GridData

volume_from_grid_data(grid_data, session, style='auto', open_model=True, model_id=None, show_dialog=True, allow_reseting_color_sequence=True)

Supported API . Create a new Volume model from a GridData instance and set its initial display style and color and add it to the session open models.

Parameters:

  • grid_data (GridData) – Use this GridData to create the Volume.

  • session (Session) – The session that the Volume will belong to.

  • style ('auto', 'surface', 'mesh' or 'image') – The initial display style.

  • open_model (bool) – Whether to add the Volume to the session open models.

  • model_id (tuple of integers) – Model id for the newly created Volume. It is an error if the specifid id equals the id of an existing model.

  • show_dialog (bool) – Whether to show the Volume Viewer user interface panel.

Returns:

volume

Return type:

the created Volume