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¶
open_map()
- read 3d image data from a file
save_map()
- write 3d image data to a file
volume_from_grid_data()
- create aVolume
from image data.
Operations¶
These operations create new Volume
models from existing ones and
implement the Chimera volume subcommands (e.g. “volume resample”).
volume_add()
- add two or more volumes
volume_bin()
- reduce map size by averaging over bins
volume_boxes()
- extract subvolumes centered on markers
volume_copy()
- copy a volume
volume_cover()
- use symmetry to extend a volume
volume_erase()
- erase volume inside or outside a sphere
volume_falloff()
- smooth the falloff of a masked map at its boundary
volume_flatten()
- scale values to flatten map baseline
volume_flip()
- reverse data planes along a specified axis
volume_fourier()
- Fourier transform
volume_gaussian()
- Gaussian smoothing or sharpening
volume_laplacian()
- Laplacian filtering
volume_local_correlation()
- calculate map-map correlation over a sliding box
mask()
- mask a map to a surface; see alsoones_mask()
volume_maximum()
- take the maximum values pointwise from two or more maps
volume_median()
- set each value to the median of values in a surrounding box
volume_minimum()
- take the minimum values pointwise from two or more maps
volume_morph()
- morph (interpolate) between two or more maps
volume_multiply()
- multiply values in two or more maps
volume_new()
- create empty (zero-valued) map; see also volume onesmask
volume_octant()
- erase all but the positive octant
ones_mask()
- create map with values of 1 bounded by a surface
volume_permute_axes()
- permute axes
volume_resample()
- resample a map on a different grid
volume_ridges()
- skeletonize; emphasize ridges or filaments in the density
volume_scale()
- scale, shift, normalize, and/or cast to a different data value type
split_volume_by_color_zone()
- split map by zones previously colored with color zone
volume_subtract()
- subtract another map from the first
volume_threshold()
- reassign values that are below a specified minimum and/or above a specified maximum
volume_tile()
- make a single-plane volume from tiled slices of another volume
volume_unbend()
- unbend a map near a path formed by markers/links or atoms/bonds
volume_unroll()
- unroll a cylindrical slab into a flat slab
volume_unzone()
- show the full extent of a map previously limited to a zone with volume zone
volume_zone()
- limit the display to a zone around specified atoms, or make a new map with values of zero at grid points within or beyond the zone
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.- 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:
- 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’)
- ray_step¶
Distance between samples when raycasting. Smaller values mean more samples.
- 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 theVolume.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¶
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:
- 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 aGridData
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