Functions for User Commands

The chimerax.core.commands module contains Python functions for the core commands available from the ChimeraX command-line. Tools define additional commands noted with a (*) and their code location is described with the function descriptions.

2dlabels * - Show text labels with graphics
alias - Define aliases for commands
align - Align one set of atoms to another
bumps * - Mark cell protrusions in 3D light microscopy
cage * - Place models on polygonal cages
camera - Change camera settings
cartoon * - Display atomic structure ribbons or pipes/planks
cd - Change working directory
clip - Clip models
close - Close models
cofr - Set center of rotation method
color - Color atoms, ribbons and surfaces
coordset - Play through structure coordinate sets
crossfade - Fade between scenes for movie making
crosslinks * - Move atomic structures to minimize crosslinks
delete - Delete models
device * - Enable devices such virtual reality headsets and space navigator
echo - Write message to log
exit - Quit
fitmap - fit atomic structures in density maps
help - Show documentation
hide - Hide atoms, ribbons, models
info * - Report model info
interfaces * - Make a buried area contact graph
ks * - Enable keyboard shortcuts
label * - Show text labels on atoms
lighting - Change lighting parameters
log * - Clear or save the log
material - Change surface material light reflection properties
measure - Calculate properties of models
mlp * - Color surfaces by molecular lipophilicity
molmap - Calculate a density map from atoms
morph * - Morph between atomic models
mousemode - Set mouse modes
move - Move camera
movie * - Record videos
mseries * - Display a series of models
open - Open data files
pdbimages - Render PDB assembly images
perframe - Run a command for every rendered frame
pwd - Print working directory
rainbow - Color residues and chains
rename - Rename models
resfit * - Show density around residues
roll - Rotate models
run - Run a user command string
rungs - Display nucleotides as cylinders
save - Save sessions, images, density maps…
scolor - Color surfaces
select - Select objects
set - Set rendering effects (background color, silhouettes)
show - Show atoms, ribbons, models
style - Set rendering style for atoms, ribbons, models
size - Change atom, bond, pseudobond sizes
smoothlines * - Smooth paths in line drawings
split - Split atomic structures into pieces
stop - Stop motion
struts * - Add struts between atoms for 3d printing
style - Change atom display style and sizes
surface - Compute a molecular surface
sym - Show molecular assemblies involving symmetry
time - Time a command
toolshed * - Control the Tool Shed user interface
transparency - Set transparency of atoms, ribbons and surfaces
turn - Rotate models
view - Move camera to view specified objects
volume - Change density map settings and filter maps
vseries - Play density map time series
wait - Wait before executing next command
windowsize - Set or report graphics window size
zoom - Zoom in or out


Function found in chimerax.label.label2d

label_create(session, name, text='', color=None, size=24, font='Arial', xpos=0.5, ypos=0.5, visibility=True)

Create a label at a fixed position in the graphics window.


name : string

Identifier for the label used to change or delete label.

text : string

Displayed text of the label.

color : Color

Color of the label text. If no color is specified black is used on light backgrounds and white is used on dark backgrounds.

size : int

Font size in pixels.

font : string

Font name. This must be a true type font installed on Mac in /Library/Fonts and is the name of the font file without the “.ttf” suffix.

xpos : float

Placement of left edge of text. Range 0 - 1 covers full width of graphics window.

ypos : float

Placement of bottom edge of text. Range 0 - 1 covers full height of graphics window.

visibility : bool

Whether or not to display the label.

label_change(session, name, text=None, color=None, size=None, font=None, xpos=None, ypos=None, visibility=None)

Change label parameters.

label_delete(session, name)

Delete label.


alias(session, name, text='')

Create command alias

  • name – name of the alias
  • text – optional text of the alias

If the alias name is not given, then a text list of all the aliases is shown. If alias text is not given, the text of the named alias is shown. If both arguments are given, then a new alias is made.


align(session, atoms, to_atoms=None, move=None, each=None, match_chain_ids=False, match_numbering=False, match_atom_names=False, sequence=None, cutoff_distance=None, report_matrix=False)

Move atoms to minimize RMSD with to_atoms. Returns matched atoms and matched to_atoms, matched atom rmsd, paired atom rmsd, and transform. The matched atoms can be fewer than the paired atoms if cutoff distance is specified. If “each” is not None then nothing is returned.

If ‘move’ is ‘structures’, superimpose the models by changing the model positions. If it is ‘atoms’, ‘residues’, ‘chains’ or ‘structure atoms’, then atoms promoted extended to this level are moved. If move is False move nothing or True move structures. If move is an Atoms collection then move only the specified atoms.

If ‘each’ is “structure” then each structure of atoms is separately aligned to the to_atoms. If ‘each’ is “chain” then each chain is aligned separately. If ‘each’ is “coordset” then each coordinate set of the first set of atoms (which must belong to a single structure) is aligned. Default is that all atoms are aligned as one group.

If ‘match_chain_ids’ is true then only atoms with matching chain identifiers are paired. Unpaired atoms or to_atoms are not used for alignment.

If ‘match_numbering’ is true then only atoms with matching residue numbers are paired. It is assumed the atoms are in residue number order. Unpaired atoms or to_atoms are not used.

If ‘match_atom_names’ is true then only atoms with matching names are paired. Unpaired atoms or to_atoms are not used for alignment.

If ‘sequence’ names a reference sequence then the previously calculated alignment of atoms and to_atoms to that reference sequence is used to pair the atoms.

If ‘report_matrix’ is True, report the transformation matrix to the Reply Log.


bumps(session, volume, center=None, range=None, base_area=10.0, height=1.0, marker_radius=1.0, marker_color=(100, 200, 100, 255), color_surface=True, name='bumps', all_extrema=False)

Find protrusions on T-cells in 3d light microscopy.

Algorithm finds points on contour surface whose distance from a center point is locally maximal then extends to neighbor grid points inside the surface as long as the border area (ie protrusion base area) is less than a specified value. Protrusions of sufficient height are marked. A marker closer to the center and within another protrusion is not marked.


volume : Volume

Map to find protrusions on. Highest surface contour level used.

center : Center

Point which is the cell center for finding radial protrusions.

range : float or None

How far out from center to look for protrusions.

base_area : float

Area of base of protrusion. Protrusion is extended inward until this area is attained and that defines the protrusion height.

height : float

Minimum height of a protrusion to be marked.

marker_radius : float

Size of marker spheres to place at protrusion tips.

marker_color : uint8 4-tuple

Color of markers. Default light green.

color_surface : bool

Whether to color the protrusion surface near the protrusion grid points. Each protrusion is assigned a random color. Default true.

name : string

Name of created marker model. Default “bumps”.

all_extrema : bool

Whether to mark all radial extrema even if the don’t meet the protrusion height minimum. Markers within another protrusion are colored yellow, ones that never attain the specified protrusion base_area (often smal disconnected density blobs) are colored pink, markers on protrusions that are too short are colored blue.


cage(session, cage, place_model=None, polygon_sides=6, surface_only=False, resolution=None)

Build polygonal cages and place molecules on faces.


cage : Structure

Cage model.

place_model : Model

Place copies of model on each n-sided polygon of cage.

polygon_sides : int

Place on polygons with this number of sides.

surface_only : bool

Instead of showing instances of the molecule, show instances of surfaces of each chain. The chain surfaces are computed if they do not already exist.

resolution : float

Resolution for computing surfaces when surface_only is true.


camera(session, type=None, field_of_view=None, eye_separation=None, pixel_eye_separation=None)

Change camera parameters.


type : string

Controls type of projection, currently “mono”, “360”, “360tb” (stereoscopic top-bottom layout), “360sbs” (stereoscopic side-by-side layout), “stereo”, “sbs” (side by side stereo), “tb” (top bottom stereo)

field_of_view : float

Horizontal field of view in degrees.

eye_separation : float

Distance between left/right eye cameras for stereo camera modes in scene distance units.

pixel_eye_separation : float

Physical distance between viewer eyes for stereo camera modes in screen pixels. This is needed for shutter glasses stereo so that an object very far away appears has left/right eye images separated by the viewer’s physical eye spacing. Usually this need not be set and will be figured out from the pixels/inch reported by the display. But for projectors the size of the displayed image is unknown and it is necessary to set this option to get comfortable stereoscopic viewing.


cartoon(session, atoms=None, smooth=None, suppress_backbone_display=None, spine=False)

Display cartoon for specified residues.


atoms : atom specifier

Show ribbons for the specified residues. If no atom specifier is given then ribbons are shown for all residues. Residues that are already shown as ribbons remain shown as ribbons.

smooth : floating point number

Adjustment factor for strand and helix smoothing. A factor of zero means the cartoon will pass through the atom position. A factor of one means the cartoon will pass through the “ideal” position, e.g., center of the cylinder that best fits a helix. A factor of “default” means to return to default (0.7 for strands and 0 for everything else).

suppress_backbone_display : boolean

Set whether displaying a ribbon hides the sphere/ball/stick representation of backbone atoms.

spine : boolean

Display ribbon “spine” (horizontal lines across center of ribbon). This parameter applies at the atomic structure level, so setting it for any residue sets it for the entire structure.

uncartoon(session, atoms=None)

Undisplay ribbons for specified residues.


atoms : atom specifier

Hide ribbons for the specified residues. If no atom specifier is given then all ribbons are hidden.


cd(session, directory=None)

Change working directory.


clip(session, near=None, far=None, front=None, back=None, slab=None, position=None, axis=None, coordinate_system=None, cap=None)

Enable or disable clip planes.


near, far, front, back : float or “off”

Distance to move near, far, front or back clip planes. Near and far clip planes remain perpendicular to the view direction. Front and back planes rotate with models. If a plane is not currently enabled then the offset value is from the center of rotation. Positive distances are further away, negative are closer.

position : Center

Plane offsets are relative to this point. If not give then offsets are relative to current plane positions. If plane is not enabled then offset is relative to center of bounding box of displayed models.

axis : Axis

Normal to clip plane for planes front and back. Not used for near and far planes.

coordinate_system : Place

Coordinate system for axis and position, if none then screen coordinates are used.


close(session, models=None)

Close models.


models : list of models

These models and any submodels are closed. If models is none all models are closed.


cofr(session, method=None, objects=None, pivot=None, coordinate_system=None, show_pivot=None)

Set center of rotation method to “front center” or “fixed”. For fixed can specify the pivot point as the center of specified displayed objects, or as a 3-tuple of numbers and optionally a model whose coordinate system is used for 3-tuples.


method : string

“front center” or “fixed” specifies how the center of rotation point is defined.

objects : Objects

Set the method to “fixed” and use the center of the bounding box of these objects as the pivot point.

pivot : 3 floats

Set the method to “fixed” and used the specified point as center of rotation.

coordinate_system : Model

The pivot argument is given in the coordinate system of this model. If this option is not specified then the pivot is in scene coordinates.

show_pivot : bool or 2 floats

Whether to draw the center of rotation point in the scene as 3 colored axes. If two floats are given, they are axes length and radius of the pivot point indicator and the pivot is shown.


color(session, objects, color=None, what=None, target=None, transparency=None, sequential=None, palette=None, halfbond=None, map=None, range=None, offset=0, zone=None, distance=2, undo_name='color')

Color atoms, ribbons, surfaces, ….


objects : Objects

Which objects to color.

color : Color

Color can be a standard color name or “byatom”, “byelement”, “byhetero”, “bychain”, “bypolymer”, “bynucleotide”, “bymodel”.

what : ‘atoms’, ‘cartoons’, ‘ribbons’, ‘surfaces’, ‘bonds’, ‘pseudobonds’ or None

What to color. Everything is colored if option is not specified.

target : string

Alternative to the “what” option for specifying what to color. Characters indicating what to color, a = atoms, c = cartoon, r = cartoon, s = surfaces, l = labels, b = bonds, p = pseudobonds, d = distances. Everything is colored if no target is specified.

transparency : float

Percent transparency to use. If not specified current transparency is preserved.

sequential : “residues”, “chains”, “polymers”, “structures”

Assigns each object a color from a color map.

palette : Colormap

Color map to use with sequential coloring.

halfbond : bool

Whether to color each half of a bond to match the connected atoms. If halfbond is false the bond is given the single color assigned to the bond.

map : Volume

Color specified surfaces by sampling from this density map using palette, range, and offset options.

range : 2 comma-separated floats or “full”

Specifies the range of map values used for sampling from a palette.

offset : float

Displacement distance along surface normals for sampling map when using map option. Default 0.

zone : Atoms

Color surfaces to match closest atom within specified zone distance.

distance : float

Zone distance used with zone option.


coordset(session, structures, index_range, hold_steady=None, pause_frames=1, loop=1, bounce=False, compute_ss=False)

Change which coordinate set is shown for a structure. Can play through a range of coordinate sets.


structures : list of Structure

List of structures to show as assemblies.

index_range : 3-tuple with integer or None elements, or just None

Starting, ending and step coordinate set ids. If starting id is None start with the currently shown coordinate set. If ending id is None treat it as the last coordset. If step id is None use step 1 if start < end else step -1. Otherwise coordinate set is changed from start to end incrementing by step with one step taken per graphics frame. Negative start / end ids are relative to the (one past) the last coordinate set, so -1 refers to the last coordinate set. If index_range is just None, then treated as 1,None,None.

hold_steady : Atoms

Collection of atoms to hold steady while changing coordinate set. The atomic structure is repositioned to minimize change in RMSD of these atoms.

pause_frames : integer

Stay at each coordset for this number of graphics frames. This is to slow down playback. Default 1.

loop : integer

How many times to repeat playing through the coordinates in the specified range.

bounce : bool

Whether to reverse direction instead of jumping to beginning when looping. Default false.

compute_ss : bool

Whether to recompute secondary structure using dssp for every new frame. Default false.


crossfade(session, frames=30)

Fade from the current view to the next drawn view. Used in movie recording.


frames : integer

Linear interpolate between the current and next image over this number of frames.


delete(session, atoms)

Delete atoms.


atoms : Atoms collection

Delete these atoms. If all atoms of a model are closed then the model is closed.


device_snav(session, enable=None, fly=None, speed=None)

Enable or disable moving models with Space Navigator input device.


enable : bool

Enable (true) or disable (false) use of the Space Navigator device.

fly : bool

Enable flying mode where the Space Navigator motions control the camera, for example pushing forward flies the camera forward. If fly is false, then the device controls the models, pushing forward would push the models away from the camera. In both cases it is actually the camera that moves.

speed : float

Controls device sensitive, how fast the models move for a given device motion. Default 1.0.

vr(session, enable=None, room_position=None, mirror=True, icons=False, show_controllers=True, multishadow_allowed=False)

Enable stereo viewing and head motion tracking with virtual reality headsets using SteamVR.


enable : bool

Enable or disable use of an HTC Vive headset or Oculus Rift headset using SteamVR. The device must be connected and powered on to enable it. Graphics will not be updated in the main ChimeraX window because the different rendering rates of the headset and a conventional display will cause stuttering of the headset graphics. Also the Side View panel in the main ChimeraX window should be closed to avoid stuttering.

room_position : Place or “report”

Maps physical room coordinates to molecular scene coordinates. Room coordinates have origin at center of room and units are meters.

mirror : bool

Whether to update the ChimeraX graphics window. This also turns off waiting for display vertical sync on the computer monitor so that the 60 Hz refresh rate does not slow down the 90 Hz rendering to the VR headset.

icons : bool

Whether to show a panel of icons when controller trackpad is touched. For demonstrations the icons can be too complex and it is better not to have icons. Default false.

show_controllers : bool

Whether to show the hand controllers in the scene. Default true.

multishadow_allowed : bool

If this option is false and multi-shadow lighting is enabled (ambient occlusion) when vr is enabled, then lighting is switched to simple lighting. If the option is true then no changes to lighting mode are made. Often rendering is not fast enough to support multishadow lighting so this option makes sure it is off so that stuttering does not occur. Default False.


Equivalent to the “log text” command.



Quit the program.


fitmap(session, atoms_or_map, in_map=None, subtract_maps=None, metric=None, envelope=True, resolution=None, shift=True, rotate=True, symmetric=False, move_whole_molecules=True, search=0, placement='sr', radius=None, cluster_angle=6, cluster_shift=3, asymmetric_unit=True, level_inside=0.1, sequence=0, max_steps=2000, grid_step_min=0.01, grid_step_max=0.5, list_fits=None, each_model=False)

Fit an atomic model or a map in a map using a rigid rotation and translation by locally optimizing correlation. There are four modes: 1) fit all models into map as a single rigid group, 2) fit each model into the map separately, 3) fit each model separately while subtracting others (sequence mode), or 4) use random starting positions when fitting (search mode).



Atoms or map that will be moved.

in_map : Volume

Target density map to fit into.

subtract_maps : Objects

Subtract these maps or maps for these atoms from the target map before fitting.




each_model : bool

Whether to fit each model independently or all as one rigid group.

sequence : integer

Fit each model in sequence subtracting other models first for this number of specified fits.

search : integer

Fit using N randomized initial placements and cluster similar results.


Fitting settings


metric : ‘overlap’, ‘correlation’, or ‘cam’

Optimization function to use. Overlap is pointwise sum. Cam is correlation about mean (ie. mean value is subtracted from maps before computing correlation).

envelope : bool

Whether to consider fit only within lowest displayed contour level if moving map.

resolution : float

Resolution for making simulated maps from atomic models. Required when correlation or cam metric is used and atomic models are being fit.

shift : bool

Allow translation when fitting.

rotate : bool

Allow rotation when fitting.

symmetric : bool

Whether to use symmetry of the target map to take account of clashes between copies of the fit models.

max_steps: integer

Maximum number of gradient ascent steps to take

grid_step_max : float

Maximum motion during a fitting step in grid index units.

grid_step_min : float

The fit is considered converged when Motion less than this value (grid index units).


Search options


placement : ‘sr’, ‘s’, or ‘r’

Whether random placements should include shift and rotation

radius : float

Limits the random placements to within this distance of the starting position.

cluster_angle : float

Rotational difference for a fit to form a new cluster.

cluster_shift : float

Shift difference for a fit to form a new cluster.

asymmetric_unit : bool

List only one symmetrically equivalent fit position if the target map has symmetry.

level_inside : float

Fraction of fit atoms or map that must be inside the target map contour level in order to keep the fit.


Output options


move_whole_molecules : bool

Move entire molecules, or only the atoms that were specified.

list_fits : bool

Show the fits in a dialog.


help(session, topic=None, *, option=None, is_query=False)

Display help


topic : string

Show documentation for the specified topic. If no topic is specified then the overview is shown. Topics that are command names can be abbreviated.

is_query : bool

Instead of showing the documetation, return if it exists.


hide(session, objects=None, what=None, target=None)

Hide specified atoms, bonds or models.


objects : Objects or None

Atoms, bonds or models to hide. If None then all are hidden.

what : ‘atoms’, ‘bonds’, ‘pseudobonds’, ‘pbonds’, ‘cartoons’, ‘ribbons’, ‘models’ or None

What to hide. If None then ‘atoms’ if any atoms specified otherwise ‘models’.

target : set of “what” values, or None

Alternative to the “what” option for specifying what to hide.


info(session, models=None)

Report state of models, such as whether they are displayed, color, number of children, number of instances…

Parameters:models : list of models
info_bounds(session, models=None)

Report bounds of displayed parts of models in scene coordinates. If not models are given the bounds for the entire scene is reported.

Parameters:models : list of models


Function found in chimerax.interfaces.cmd

contacts(session, atoms=None, probe_radius=1.4, area_cutoff=300, interface_residue_area_cutoff=15)

Compute buried solvent accessible surface areas between chains and show a 2-dimensional network graph depicting the contacts.


atoms : Atoms

probe_radius : float


ks(session, shortcut=None)

Enable keyboard shortcuts. Keys typed in the graphics window will be interpreted as shortcuts.


shortcut : string

Keyboard shortcut to execute. If no shortcut is specified switch to shortcut input mode.


Function found in chimerax.label.label3d

label(session, objects=None, object_type=None, text=None, offset=None, orient=None, color=None, size=None, height=None, font=None, on_top=None)

Create atom labels. The belong to a child model named “labels” of the structure.


objects : Objects or None

Create labels on specified atoms, residues, pseudobonds, or bonds. If None then adjust settings of all existing labels.

object_type : ‘atoms’, ‘residues’, ‘pseudobonds’, ‘bonds’

What type of object to label.

text : string or “default”

Displayed text of the label.

offset : float 3-tuple or “default”

Offset of label from atom center in screen coordinates in physical units (Angstroms)

orient : float

Reorient the labels to face the view direction only when the view direction changes changes by the specified number of degrees. Default 0 makes the labels always face the view direction. This option is primarily of interest with virtual reality viewing.

color : Color or “default”

Color of the label text. If no color is specified black is used on light backgrounds and white is used on dark backgrounds.

size : int or “default”

Font size in pixels. Default 24.

height : float or “fixed”

Text height in scene units. Or if “fixed” use fixed pixel height on screen.

font : string or “default”

Font name. This must be a true type font installed on Mac in /Library/Fonts and is the name of the font file without the “.ttf” suffix. Default “Arial”.

on_top : bool

Whether labels always appear on top of other graphics (cannot be occluded). This is a per-structure attribute. Default True.

label_delete(session, objects=None, object_type=None)

Delete object labels.


objects : Objects or None

Delete labels for specified atoms, residues, pseudobonds or bonds. If None delete all labels.

object_type : ‘atoms’, ‘residues’, ‘pseudobonds’, ‘bonds’

What type of object label to delete.


lighting(session, preset=None, direction=None, intensity=None, color=None, fill_direction=None, fill_intensity=None, fill_color=None, ambient_intensity=None, ambient_color=None, depth_cue=None, depth_cue_start=None, depth_cue_end=None, depth_cue_color=None, move_with_camera=None, shadows=None, quality_of_shadows=None, depth_bias=None, multi_shadow=None, ms_map_size=None, ms_depth_bias=None)

Set lighting parameters. There are 2 directional lights, a key light and a fill light, in addition to ambient lighting. The key light can cast a shadow, and shadows cast from multiple uniformly distributed directions can produce ambient shadowing (aka “ambient occlusion”). Parameters that are not specified retain their current value. If no options are specified then the current settings are printed to the log.


preset : string

Names a standard set of lighting parameters. Allowed values are “default”, “simple”, “full”, “soft” and “flat”. Simple is the same as default and has no shadows. Full includes direct and ambient shadows. Soft includes ambient shadows from 64 directions and no direct lighting. Flat has only anbient lighting and no shadows with silhouettes enabled. Specifying a preset only specifies some of the lighting parameters. Specifying other options overrides the preset values.

direction : 3 floats

Key light direction as vector. Does not have to have unit length. Points in the direction the light shines. The viewing direction is along -z. Initially is pointing down to the right (1,-1,-1).

intensity : float

Key light intensity. This is a brightness scale factor. Initial value 1.

color : Color

Key light color, initial value RGB = (1,1,1).

fill_direction : 3 floats

Fill light direction. Initially is pointing from lower left (-0.2,-0.2,-0.959).

fill_intensity : float

Fill light intensity. Initial value 0.5.

fill_color : Color

Fill light color, initial value RGB = (1,1,1).

ambient_intensity : float

Ambient light intensity. Initial value 0.4.

ambient_color : Color

Ambient color, initial value RGB = (1,1,1).

depth_cue : bool

Whether to dim scene with depth.

depth_cue_start : float

Fraction of distance from near to far clip plane where dimming starts. Initial value 0.5

depth_cue_end : float

Fraction of distance from near to far clip plane where dimming ends. Initial value 1.

depth_cue_color : Color

Color to fade towards, initial value RGB = (0,0,0).

move_with_camera : bool

Whether light directions move with the camera or are fixed in scene coordinates. Initial value true.

shadows : bool

Whether to show shadows. Initial value false.

quality_of_shadows : string or int

Shadows are rendered with a 2 dimensional texture. Pixelated shadow edges result from using small texture sizes. Value can be “coarse” (1024), “normal” (2048), “fine” (4096), “finer” (8192), or an integer value can be specified.

depth_bias : float

To avoid a surface shadowing itself due to numerical rounding errors an bias distance is used. This is a fraction of the scene diameter. Initial value 0.005.

multi_shadow : int

How many directions to use for casting ambient shadows. Value 0 means no ambient shadows. The soft preset uses 64 directions. Initial value 0.

ms_map_size : int

Size of one 2-dimensional texture holding all the ambient shadow maps. Small values give coarser shadows that give a smoother appearance when many shadows ar rendered. Initial value 1024.

ms_depth_bias : float

Depth bias to avoid surface self shadowing for ambient shadows as a fraction of the scene diameter. Because small shadow map sizes are typically used a larger bias is needed than for directional shadows. Initial value 0.01.


Function found in chimerax.log.cmd

log(session, save_path=None, thumbnail=False, text=None, html=None, width=100, height=100, warning_dialog=None, error_dialog=None)

Operations on the Log window.


save_path : string

Save log contents as html to a file.

thumbnail : bool

Place a thumbnail image of the current graphics in the log.

height : int

Height in pixels of thumbnail image.

width : int

Width in pixels of thumbnail image.

warning_dialog : bool

If true, warnings popup a separate dialog, if false no warning dialog is shown. In either case the warning appears in the log text.

error_dialog : bool

If true, errors popup a separate dialog, if false no error dialog is shown. In either case the errors appears in the log text.


material(session, preset=None, reflectivity=None, specular_reflectivity=None, exponent=None, ambient_reflectivity=None, transparent_cast_shadows=None)

Change surface material properties controlling the reflection of light. Currently all models use the same material properties.


preset : string

Can be “default”, “shiny” or “dull”. Default sets all material properties to there default values. Shiny sets specular reflectivity to 1. Dull sets specular reflectivity to 0.

reflectivity : float

Fraction of directional light reflected diffusely (reflected equally in all directions). Initial value 0.8.

specular_reflectivity : float

Fraction of key light reflected specularly (mirror reflection with some spread given by exponent. Initial value 0.8.

exponent : float

Controls specularly reflected light scaling intensity by a factor of cosine(x) raised to the exponent power, where x is the between the mirror reflection direction and the view direction. Larger values produce smaller specular highlight spots on surfaces. Initial value 30.

ambient_reflectivity : float

Fraction of ambient light reflected. Initial value 0.8.

transparent_cast_shadows : bool

Whether transparent objects cast shadows. If set to true then transparent objects cast a shadows as if the objects are opaque making everything inside appear black. Raytracing would be required to render a partial shadow, and we don’t support that. Initial value is false.


measure_buriedarea(session, atoms1, with_atoms2=None, probe_radius=1.4, list_residues=False, cutoff_area=1, color=None, select=False)

Compute buried solvent accessible surface (SAS) area between two sets of atoms. This is the sum of the SAS area of each set of atoms minus the SAS area of the combined sets of atoms, that difference divided by two since each set of atoms has surface at the interface, so the interface area is defined as half the buried area. Atoms not specified in either atom set are ignored when considering where the probe sphere can reach.


atoms1 : Atoms

First set of atoms.

with_atoms2 : Atoms

Second set of atoms – must be disjoint from first set.

probe_radius : float

Radius of the probe sphere.

list_residues : bool

Whether to report a list of contacting residues for each set of atoms.

cutoff_area : float

Per-residue minimum area for listing residues.

color : Color or None

Color contacting residues.

select : bool

Whether to select contacting residues.

measure_convexity(session, surfaces, palette=None, range=None, smoothing_iterations=5)

Compute the convexity at each surface vertex defined as 2*pi minus the cone-angle spanned by the triangles incident at the vertex. The surface vertices are colored based on convexity value.

This definition of convexity is not standard and gives mottled coloring because the values depend strongly on the triangulation. Vertices surrounded by large triangles on a smooth surface will have sharper cone angles then vertices surrounded by small triangles. (Normalizing by vertex triangle areas does not help because the patch about a vertex is often irregular in shape.) To ameliorate this the “smoothing_iterations” option is useful.


surface : Model list

palette : Colormap

Default color palette is cyan-gray-maroon.

range : 2-tuple of float or “full”

Minimum and maximum convexity values corresponding to ends of color palette.

smoothing_iterations : int

Convexity values are averaged with neighbor vertices connected by an edge. This value specifies how many rounds of smoothing to perform. Default 5.

measure_length(session, bonds)

Compute sum of length of bonds.

measure_sasa(session, atoms=None, probe_radius=1.4, sum=None, set_attribute=True)

Compute solvent accessible surface area.


atoms : Atoms

A probe sphere is rolled over these atoms ignoring collisions with any other atoms.

probe_radius : float

Radius of the probe sphere.

sum : Atoms

Sum the accessible areas per atom only over these atoms.

set_attribute : bool

Whether to set atom.area and residue.area values.


Function found in chimerax.mlp.mlp

mlp(session, atoms=None, method='fauchere', spacing=1.0, max_distance=5.0, nexp=3.0, color=True, palette=None, range=None, map=False)

Display Molecular Lipophilic Potential for a single model.


atoms : Atoms

Color surfaces for these atoms using MLP map.

method : ‘dubost’,’fauchere’,’brasseur’,’buckingham’,’type5’

Distance dependent function to use for calculation

spacing : float

Grid spacing, default 1 Angstrom.

max_distance : float

Maximum distance from atom to sum lipophilicity. Default 5 Angstroms.

nexp : float

The buckingham method uses this numerical exponent.

color : bool

Whether to color molecular surfaces. They are created if they don’t yet exist.

palette : Colormap

Color palette for coloring surfaces. Default is lipophilicity colormap (orange lipophilic, blue lipophobic).

range : 2-tuple of float

Range of lipophilicity values defining ends of color map. Default is -20,20

map : bool

Whether to open a volume model of lipophilicity values


molmap(session, atoms, resolution, grid_spacing=None, edge_padding=None, on_grid=None, cutoff_range=5, sigma_factor=0.22507907903927651, balls=False, symmetry=None, center=None, axis=None, coordinate_system=None, display_threshold=0.95, model_id=None, replace=True, show_dialog=True)

Create a density map by placing Gaussians centered on atoms.


atoms : Atoms

resolution : float

grid_spacing : float

Default is 1/3 resolution.

edge_padding : float

Default is 3 times resolution.

cutoff_range : float

In standard deviations.

sigma_factor : float

Scale factor equal to standard deviation / resolution, default 1/(pi*sqrt(2)).

balls : bool

Use balls instead of Gaussians

symmetry : Symmetry object or None.

Apply symmetry operations to atoms

center : Center object or None

Center of symmetry.

axis : Axis object or None

Axis of symmetry.

coordinate_system : Place

Coordinate system of symmetry.

display_threshold : float

Initial contour level as fraction of total density, default 0.95.

model_id : list of integers

replace : bool

Default true

show_dialog : bool, not supported


Function defined in chimerax.morph.morph

morph(session, structures, frames=20, rate='linear', method='corkscrew', cartesian=False, same=False, core_fraction=0.5, min_hinge_spacing=6, hide_models=True, play=True, slider=True, color_segments=False, color_core=None)

Morph between atomic models using Yale Morph Server algorithm.


structures : list of Structure

Configurations to morph

frames : int

Number of frames for each morph segment. One less than this value is new configurations are inserted between every pair of structures given.

rate : ‘linear’, ‘ramp down’, ‘ramp up’ or ‘sinusoidal’

The rate of morphing from one state to the next.

method : ‘corkscrew’, ‘independent’, ‘linear’

How hinged groups of atoms are morphed.

cartesian : bool

Whether to interpolate x,y,z atom coordinates or use internal coordinates which preserve bond lengths.

same : bool

Whether to match atoms with same chain id, same residue number and same atom name. Default false.

core_fraction : float

Fraction of residues of each chain that align best used to define core and non-core residues which are then split into contiguous residues stretches where the chain crosses between the two residue sets. Default 0.5.

min_hinge_spacing : int

Minimum number of consecutive residues when splitting chains into rigidly moving segments at boundaries between core and non-core residues. Default 6.

hide_models : bool

Whether to hide the input models after morph model is created. Default true.

play : bool

Whether to play the morph. Default true.

slider : bool

Whether to show a slider to play through the morph. Default true.

color_segments : bool

Whether to color the residues for each rigid segment with a unique color. This is to see how the morph algorithm divided the structure into segments. For morphing a sequence of 3 or more structures only the residues segments for the morph between the first two in the sequence is shown. Segments are recomputed for each consecutive pair in the sequence. Default false.

color_core : Color or None

Color the core residues the specified color. This is to understand what residues the algorithm calculates to be the core.


mousemode(session, left_mode=None, middle_mode=None, right_mode=None, wheel_mode=None, pause_mode=None, alt=None, command=None, control=None, shift=None)

Set or list mouse modes. If no options given lists mouse modes.


left_mode : mode

Bind the left mouse button to mouse mode.

middle_mode : mode

Bind the middle mouse button to mouse mode.

right_mode : mode

Bind the right mouse button to mouse mode.

wheel_mode : mode

Bind the mouse wheel to mouse mode.

pause_mode : mode

Bind mouse hover to mouse mode.


move(session, axis, distance=None, frames=None, coordinate_system=None, models=None, atoms=None)

Shift the scene. Actually the camera is shifted and the models stay fixed unless the models option is specified in which case the model coordinate systems are moved, or if atoms is specifed the atom coordinates are moved.


axis : Axis

Defines the axis in scene coordinates to shift along.

distance : float

Distance to shift in scene units.

frames : integer

Repeat the shift for N frames.

coordinate_system : Place

The coordinate system for the axis. If no coordinate system is specified then scene coordinates are used.

models : list of Models

Move the coordinate systems of these models. Camera is not moved.

atoms : Atoms

Change the coordinates of these atoms. Camera is not moved.


Functions defined in

movie_record(session, directory=None, pattern=None, format=None, size=None, supersample=1, limit=90000)

Start recording a movie.


directory : string

A temporary directory for saving image files before the movie is encoded. If a directory is specified, it must already exist – it will not be created. If no directory is specified a temporary system directory is created.

pattern : string

File name including a “*” character that is substituted with the frame number when saving images.

format : string

Image file format (default ppm) for saving frames. Possible values ppm, png, jpeg. ppm is fastest but takes the most disk space because it is not compressed.

size : 2 int

Width and height in pixels of movie.

supersample : int

Amount of supersampling when saving individual image frames.

limit : int

Maximum number of frames to save. This is a safe guard so that the entire computer disk storage is not filled with images if a movie recording is never stopped.

movie_encode(session, output=None, format=None, quality=None, qscale=None, bitrate=None, framerate=25, round_trip=False, reset_mode='clear', wait=False, verbose=False)

Enode images captured with movie record command creating a movie file. This uses the standalone video encoding program ffmpeg which is included with ChimeraX.


output : list of strings

Filenames of movie output files. By specifying multiple files, different video encoding formats can be made.

format : string

Format of video file to write. If not specified, the file suffix determines the format. Use of a .mp4 file suffix and h264 format is by far the best choice. Allowed formats (file suffix) are: h264 (.mp4), mov (.mov), avi (.avi), wmv (.wmv).

quality : string

Quality of video, higher quality results in larger file size. Qualities are “highest”, “higher”, “high”, “good”, “medium”, “fair”, “low”. Default “good”. This overrides the qscale and bitrate options.

qscale : int

Quality scale parameter used by some video codecs. This overrides the bitrate option.

bitrate : int

Target bit rate for video encoding in Kbits/second.

framerate : int

Frames per second that video should playback at in a video player.

round_trip : bool

If true, the images are played forward and than backward so movie ends where it began. This is used for making movies that loop without a jump between the last frame and first frame.

reset_mode : string

Whether to keep or delete the image files that were captured after the video files is made. Values are “clear”, “keep” or “none”. Default “clear” means the image files are deleted.

wait : bool

Whether to wait until movie encoding is finished before the command returns. Default false means the command can return before the video encoding is complete.

movie_crossfade(session, frames=25)

Linear interpolate between the current graphics image and the next image over a specified number of frames.

movie_duplicate(session, frames=25)

Repeat the current image frame a specified number of frames so that the video does not change during playback.


Stop recording video frames. Using the movie encode command also stops recording.


Stop movie recording and delete any recorded frames.

movie_reset(session, reset_mode='clear')

Clear images saved with movie record.

movie_ignore(session, ignore=True)

Ignore subsequent movie commands except for the movie ignore command. This can be used to run a movie recording script without recording the movie.


Report recording status such as number of frames saved to the log.


Report the available video formats to the log.


mseries(session, models, pause_frames=10, loop=1, step=1)

Display series of models one after another.


models : list of Model

Sequence of models to show.

pause_frames : int

Number of frames to show each model. Default 10.

loop : integer

How many times to repeat playing through the models. Default 1.

step : integer

Show every Nth model with N given by step, default 1.

mseries_slider(session, models, pause_frames=10, step=1, movie_framerate=25)

Show slider to play through (i.e. display) a series of models.


models : list of Model

Sequence of models to show.

pause_frames : int

Number of frames to show each model. Default 10.

step : integer

Show every Nth model with N given by step, default 1.

movie_framerate : float

Frames per second used when playing back a movie recorded with the record button.


open(session, filename, format=None, name=None, from_database=None, ignore_cache=False, **kw)

Open a file. Specific formats have additional keyword arguments using commands.add_keyword_arguments(). These are listed with command “usage open”.


filename : string

A path to a file (relative to the current directory), or a database id code to fetch prefixed by the database name, for example, pdb:1a0m, mmcif:1jj2, emdb:1080. A 4-letter id that is not a local file is interpreted as an mmCIF fetch.

format : string

Read the file using this format, instead of using the file suffix to infer the format.

name : string

Name to use for data set. If none specified then filename is used.

from_database : string

Database to fetch from. The filename is treated as a database identifier.

ignore_cache : bool

Whether to fetch files from cache. Fetched files are always written to cache.


pdbimages(session, directory='.', subdirectories=True, width=400, height=400, supersample=2, image_suffix='.png', exclude=['1m4x.cif'], log_file=None)

Assembly images command for batch rendering mmCIF assembly images. This is for the Protein DataBank to render images.


directory : string

Find all files with suffix .cif in this directory and recursively in subdirectories.

subdirectories : bool

Whether to recursively search subdirectories for .cif files.

width : integer

Width in pixels of saved image.

height : integer

Height in pixels of saved image.

supersample : integer

Supersampling makes image N-fold larger than averages down to smooth object images.

image_suffix : string

File suffix for images, used to determine image format (e.g. .png, .jpg, .tif)

exclude : list of strings

File names to exclude from rendering (some large files cause graphics crashes).

log_file : string

Path to file to write log messages as each mmCIF file is rendered.


perframe(session, command, frames=None, interval=1, format=None, zero_pad_width=None, ranges=None, show_commands=False)

Execute specified command each frame, typically used during movie recording.


command : string

The command to be run each frame, optionally containing “$1” which will be replaced by the frame number starting at 0.

frames : int

Number of frames to execute the specified command.

interval : int

Run the command only every Kth frame.

format : string

Printf style format (e.g. %d, %.3f) for substituting value in for $1.

zero_pad_width : int

Field width in characters used when substituting $1 left padded with zeros.

ranges : list of tuples of 2 or 3 int

start,end[,step] integer or float range of values to substitute for $1 instead of frame number.

show_commands : bool

Whether to echo commands to log.



Report the current directory to the log.


rainbow(session, objects, level='residues', target=None, transparency=None, palette=None, halfbond=None)

Color residues or chains by sequence using a color map. Arguments are the same as for the color command.


rename(session, models, name=None, id=None)

Rename a model. Might extend this command in the future to rename chains, residues, atoms…


models : list of models

name : string

id : tuple of integers


resfit(session, atoms, map=None, residue_range=(-2, 1), motion_frames=50, pause_frames=50, movie_framerate=25)

Display fit of each residue in a density map.


atoms : Atoms

Atoms from one chain or part of a chain.

map : Volume

Density map to show near each residue.


roll(session, axis=<chimerax.core.commands.cli.Axis object>, angle=1, frames=-1, rock=None, center=None, coordinate_system=None, models=None, atoms=None)

Rotate the scene. Same as the turn command with infinite frames argument and angle step 1 degree.


axis : Axis

Defines the axis to rotate about.

angle : float

Rotation angle in degrees.

frames : integer

Repeat the rotation for N frames, typically used in recording movies.

rock : integer

Repeat the rotation reversing the direction every N/2 frames. The first reversal occurs at N/4 frames so that the rocking motion is centered at the current orientation.

center : Center

Specifies the center of rotation. If not specified, then the current center of rotation is used.

coordinate_system : Place

The coordinate system for the axis and optional center point. If no coordinate system is specified then scene coordinates are used.

models : list of Models

Move the coordinate systems of these models. Camera is not moved.

atoms : Atoms

Change the coordinates of these atoms. Camera is not moved.


run(session, text, *, log=True, downgrade_errors=False)

execute a textual command


text : string

The text of the command to execute.

log : bool

Print the command text to the reply log.

downgrade_errors : bool

True if errors in the command should be logged as informational.


rungs(session, atoms=None, color=None, radius=None, halfbond=None, hide_atoms=True, show_ribbon=True, hide_hbonds=True)

Make a cylinder for each base for nucleic acid residues. The cylinders are pseudobonds between C3’ and N1 (A,G) or N3 (C,T).


atoms : Atoms or None

Make rungs for these atoms or all atoms of None specified.

color : Color

Color of cylinders.

radius : float

Radius of cylinders.

halfbond : bool

Whether to color bond to match end atom colors.

hide : bool

Hide already shown rungs.

hide_atoms : bool

Whether to hide atoms of residues shown as cylinders.

show_ribbon : bool

Whether to show ribbon for residues shown as cylinders.

hide_hbonds : bool

Whether to hide hydrogen bonds read from mmCIF file.


save(session, filename, models=None, format=None, **kw)

Save data, sessions, images. Specific formats have additional keyword arguments using commands.add_keyword_arguments(). These are listed with command “usage save”.


filename : string

File to save. File suffix determines what type of file is saved unless the format option is given. For sessions the suffix is .cxs. Image files can be saved with .png, .jpg, .tif, .ppm, .gif suffixes.

models : list of Model or None

Models to save

format : string

Recognized formats are session, or for saving images png, jpeg, tiff, gif, ppm, bmp. If not specified, then the filename suffix is used to identify the format.


scolor(session, atoms=None, color=None, opacity=None, byatom=False, per_atom_colors=None, map=None, palette=None, range=None, offset=0)

Color surfaces using a variety of methods, for example, to match nearby atom colors, or use a single color, or color by electrostatic potential, or color radially. TODO: Only a few options are currently supported.


select(session, objects=None, polymer=None, residues=False)

Select specified objects.


objects : Objects

Replace the current selection with the specified objects (typically atoms). If no objects are specified then everything is selected.

residues : bool

Extend atoms that are selected to containing residues if true (default false).

polymer : Atoms

Reduce the selection to include only atoms belonging to chains having a sequence that is the same as one of the sequences specified by the polymer option.


set(session, bg_color=None, silhouettes=None, silhouette_width=None, silhouette_color=None, silhouette_depth_jump=None, subdivision=None, max_frame_rate=None)

Set global parameters. With no options reports the current settings.


bg_color : Color

Set the graphics window background color.

silhouettes : bool

Enable or disable silhouette edges (black lines drawn at boundaries of objects where the depth of the scene jumps.

silhouette_width : float

Width in pixels of silhouette edges. Minimum width is 1 pixel.

silhouette_color : color

Color of silhouette edges.

silhouette_depth_jump : float

Fraction of scene depth giving minimum depth change to draw a silhouette edge. Default 0.03.

subdivision : float

Controls the rendering quality of spheres and cylinders for drawing atoms and bonds. Default value is 1, higher values give smoother spheres and cylinders.

max_frame_rate : float

Maximum frames per second to render graphics. The default frame rate is 60 frames per second. A slower rate is sometimes useful when making movies to preview at the slower movie playback rate.


show(session, objects=None, what=None, target=None, only=False)

Show specified atoms, bonds or models.


objects : Objects or None

Atoms, bonds or models to show. If None then all are shown. Objects that are already shown remain shown.

what : ‘atoms’, ‘bonds’, ‘pseudobonds’, ‘pbonds’, ‘cartoons’, ‘ribbons’, ‘surfaces’, ‘models’ or None

What to show. If None then ‘atoms’ if any atoms specified otherwise ‘models’.

target : set of “what” values, or None

Alternative to the “what” option for specifying what to show.

only : bool

Show only the specified atoms/bonds/residues in each specified molecule. If what is models then hide models that are not specified.


size(session, objects=None, atom_radius=None, stick_radius=None, pseudobond_radius=None, ball_scale=None)

Set the sizes of atom and bonds.


objects : Objects

Change the size of these atoms, bonds and pseudobonds. If not specified then all are changed.

atom_radius : float or “default”

New radius value for atoms.

stick_radius : float

New radius value for bonds shown in stick style.

pseudobond_radius : float

New radius value for pseudobonds.

ball_scale : float

Multiplier times atom radius for determining atom size in ball style (default 0.3).


smoothlines(session, models, step_factor=0.1, iterations=10, replace=False)

Smooth models consisting of lines. Each vertex is moved the fraction step_factor towards the average position of it and its connected neighbors. This is repeated for the specified number of iterations. A new model is created unless the replace option is given in which case the current model is changed.


models : list Model

The models must consist of line segments.

step_factor : float

Fraction of distance to move each vertex toward average of itself and connected neighbors. Default 0.1

iterations : integer

Number of times to repeat smoothing. Default 10.

replace : bool

Whether to replace the lines in the existing model, or make a new model.


split(session, structures=None, chains=None, ligands=False, connected=False, atoms=None)

Partition atoms into separate structures. If only the first argument is given then those structures are split into a separate structure for each chain. If chains, ligands, connected, or atoms keywords are given then additional partitioning into smaller subsets is performed.


Structures : Structures or None

Structures to split. If no structures specified then all are used.

chains : bool

Split each chain into into a separate atomic structure.

ligands : bool

Split each connected ligand into a separate atomic structure.

connected : bool

Split each connected subset of atoms into a separate atomic structure.

atoms : list of Atoms

Split specified atoms into separate atomic structures. This option can be specified multiple times.



Stop a motion initiated with turn, roll or move with the frames argument.


struts(session, atoms, length=7.0, loop=30.0, radius=0.6, color=None, fatten_ribbon=True, replace=True, name=None, model_id=None)

Create fake bonds between atoms of a structure in order to strengthen it for 3d printing.


atoms : Atoms

Set of atoms to use as strut end-points.

length : float

The maximum length of a strut. Default 7.0.

loop : float

Add struts between atoms when their through-bond distance from each other is greater than this loop distance. Default 30.

radius : float

Radius for drawing the strut cylinders. Default 0.6.

color : Color

Make the struts this color. Default gray.

fatten_ribbon : bool

Increase ribbon thickness to make it stronger for printing. Default true.

replace : bool

Whether to replace or keep previously calculated struts.

name : string

Name for the strut model.

model_id : tuple of integers

Model id number for strut model.

struts_delete(session, atoms=None)

Delete struts between the specified atoms.


style(session, objects=None, atom_style=None, dashes=None)

Set the atom and bond display styles.


objects : Objects

Change the style of these atoms, bonds and pseudobonds. If not specified then all atoms are changed.

atom_style : “sphere”, “ball” or “stick”

Controls how atoms and bonds are depicted.

dashes : int

Number of dashes shown for pseudobonds.


surface(session, atoms=None, enclose=None, include=None, probe_radius=None, grid_spacing=None, resolution=None, level=None, color=None, transparency=None, visible_patches=None, sharp_boundaries=None, nthread=None, replace=True)

Compute and display solvent excluded molecular surfaces.


atoms : Atoms

Atoms controlling which surface patch is shown. Surfaces are computed for each chain these atoms belong to and patches of these surfaces near the specifed atoms are shown. Solvent, ligands and ions are excluded from each chain surface.

enclose : Atoms

Make a surface enclosing exactly these specified atoms excluding solvent, ligands and ions

include : Atoms

Solvent, ligands or ions to include in the surface.

probe_radius : float

Radius of probe sphere rolled over atoms to produce surface. Only used for solvent excluded surfaces. Default is 1.4 Angstroms.

grid_spacing : float

Surface is computed on 3-dimensional grid with this spacing between grid points along each axis.

resolution : float

Specifying a resolution value (Angstroms) causes the surface calculation to use a contour surface of a 3-d grid of a sum of Gaussians one centered at each atom instead of a solvent excluded surface. See the molmap command for details. A resolution of 0 computes an SES surface.

level : float

Contour level for Gaussian surface in atomic number units. Each Gaussian has height scaled by the atom atomic number.

color : Color

Colors surfaces using this color.

transparency : float

Percentage transparency for surfaces.

visible_patches : int

Maximum number of connected surface pieces per chain to show.

sharp_boundaries : bool

Make the surface triangulation have edges exactly between atoms so per-atom surface colors and surface patches have smoother edges.

nthread : int

Number of CPU threads to use in computing surfaces.

replace : bool

Whether to replace an existing surface for the same atoms or make a copy.

surface_close(session, objects=None)

Close molecular surfaces.


objects : Objects

Close specified molecular surfaces and surfaces for specified atoms.

surface_dust(session, surfaces, metric='size', size=None, update=False)

Hide connected surface patchs smaller than a specified size.


surfaces : Models list

Surface models to act on.

metric : One of ‘size’, ‘area’, ‘volume’, ‘size rank’, ‘area rank’, ‘volume rank’

Use this size metric. Rank metrics hide patches smaller than the N largest.

size : float

Hide patches smaller than this size.

update : bool

Whether to update dust hiding when surface shape changes. Not implemented.

surface_hide(session, objects=None)

Hide patches of existing surfaces for specified atoms.


objects : Objects

Hide atom patches for specified molecular surfaces or for specified atoms.

surface_show(session, objects=None)

Show surface patches for atoms of existing surfaces.


objects : Objects

Show atom patches for existing specified molecular surfaces or for specified atoms.

surface_zone(session, surfaces, near_atoms=None, range=2, max_components=None, bond_point_spacing=None, update=False)

Hide parts of a surface beyond a given distance from specified atoms.


surfaces : Model list

Surface models to act on.

near_atoms : Atoms

Display only surface triangles that have all vertices in range of at least one of these atoms.

range : float

Maximum distance from atoms.

max_components : integer

Show at most this number of connected surface patches, hiding the smaller ones. The limit applies for each surface model.

bond_point_spacing : float

Include distances from points along bonds between the given atoms at this spacing. Not implemented.

update : bool

Whether to recompute the zone when the surface geometry changes. Not implemented.


sym(session, structures, symmetry=None, center=None, axis=None, coordinate_system=None, assembly=None, copies=False, new_model=None, surface_only=False, resolution=None, grid_spacing=None)

Show molecular assemblies of molecular models defined in mmCIF files. These can be subassemblies or symmetrical copies with individual chains placed according to matrices specified in the mmCIF file.


structures : list of AtomicStructure

List of structures to show as assemblies.

symmetry : cli.Symmetry

Desired symmetry to display

center : cli.Center

Center of symmetry. Default 0,0,0.

axis : Axis

Axis of symmetry. Default z.

coordinate_system : Place

Transform mapping coordinates for center and axis arguments to scene coordinates.

assembly : string

The name of assembly in the mmCIF file. If this parameter is None then the names of available assemblies are printed in log.

copies : bool

Whether to make copies of the molecule chains. If copies are not made then graphical instances of the original molecule are used. Copies are needed to give different colors or styles to each copy. When copies are made a new model with submodels for each copy are created.

new_model : bool

Copy the structure to create the assembly. Default is True if an assembly is specified and false if the symmetry option is given. If the copies option is true then new_model is automatically true. If copies is false and new_model is true then one copy of the structure for each set of position matrices is used, and additional copies use graphical instances. If copies is false and new_model is false then instances of the original structure is used. If there is more than one set of position matrices, then copies are required and an error message is given.

surface_only : bool

Instead of showing instances of the molecule, show instances of surfaces of each chain. The chain surfaces are computed if they do not already exist. It is an error to request surfaces only and to request copies.

resolution : float

Resolution for computing surfaces when surface_only is true.

grid_spacing : float

Grid spacing for computing surfaces when surface_only is true.


time(session, command)

Time a command.


toolshed_list(session, bundle_type='installed', outdated=False, newest=True)

List installed bundles in the log.


bundle_type : string

Types are “installed”, “available”, or “all”

toolshed_reload(session, reload_type='installed')

Rebuild the bundle metadata cache using information from currently installed bundle.

toolshed_install(session, bundle_name, user_only=True, reinstall=None, version=None)

Install a bundle.


bundle_name : string

user_only : bool

Install for this user only, or install for all users.

version : string

toolshed_uninstall(session, bundle_name, force_remove=False)

Uninstall an installed bundle.


bundle_name : string

force_remove : boolean

toolshed_url(session, url=None, wait=False)

Show or set toolshed URL

Parameters:url : string
toolshed_show(session, tool_name, _show=True)

Show a tool, or start one if none is running.

Parameters:tool_name : string
toolshed_hide(session, tool_name)

Hide tool.

Parameters:tool_name : string


transparency(session, objects, percent, what=None, target=None)

Set transparency of atoms, ribbons, surfaces, ….


objects : Objects or None

Which objects to set transparency.

percent : float

Percent transparent from 0 completely opaque, to 100 completely transparent.

target : string

Characters indicating what to make transparent: a = atoms, b = bonds, p = pseudobonds, c = cartoon, r = cartoon, s = surfaces, A = all


turn(session, axis=<chimerax.core.commands.cli.Axis object>, angle=90, frames=None, rock=None, center=None, coordinate_system=None, models=None, atoms=None)

Rotate the scene. Actually the camera is rotated about the scene center of rotation unless the models argument is specified in which case the model coordinate systems are moved, or if atoms is specifed the atom coordinates are moved.


axis : Axis

Defines the axis to rotate about.

angle : float

Rotation angle in degrees.

frames : integer

Repeat the rotation for N frames, typically used in recording movies.

rock : integer

Rotate +/- angle degrees repeating, one cycle every specified number of frames. The rocking steps are small at the ends of the rock, using sine modulation. If the frames option is not given the rocking continues indefinitely.

center : Center

Specifies the center of rotation. If not specified, then the current center of rotation is used.

coordinate_system : Place

The coordinate system for the axis and optional center point. If no coordinate system is specified then scene coordinates are used.

models : list of Models

Move the coordinate systems of these models. Camera is not moved.

atoms : Atoms

Change the coordinates of these atoms. Camera is not moved.


view(session, objects=None, frames=None, clip=True, cofr=True, orient=False, pad=0.05)

Move camera so the displayed models fill the graphics window. Also camera and model positions can be saved and restored. Adjust camera to view all models if objects is None.


objects : Objects

Move camera so the bounding box of specified objects fills the window.

frames : int

Interpolate to the desired view over the specified number of frames.

clip : bool

Turn on clip planes in front and behind objects.

cofr : bool

Set center of rotation to center of objects.

orient : bool

Specifying the orient keyword moves the camera view point to look down the scene z axis with the x-axis horizontal and y-axis vertical.

pad : float

When making objects fit in window use a window size reduced by this fraction. Default value is 0.05. Pad is ignored when restoring named views.

view_delete(session, name)

Delete named saved view.


name : string

Name of the view. “all” deletes all named views.

view_initial(session, models=None)

Set models to initial positions.


models : Models

Set model positions to no rotation, no shift.


Print the named camera views in the log.

The names are links and clicking them show the corresponding view.

view_matrix(session, camera=None, models=None, coordinate_system=None)

Set model and camera positions. With no options positions are reported for the camera and all models. Positions are specified as 12-numbers, the rows of a 3-row, 4-column matrix where the first 3 columns are a rotation matrix and the last column is a translation applied after the rotation.


camera : Place

Set the camera position.

models : list of (Model, Place)

Set model positions.

coordinate_system : Place

Treat camera and model positions relative to this coordinate system. If none, then positions are in scene coordinates.

view_name(session, name)

Save current view as given name.


name : string

Name the current camera view and model positions so they can be shown later with the “show” option.


volume(session, volumes=None, style=None, show=None, hide=None, toggle=None, level=None, rms_level=None, sd_level=None, enclose_volume=None, fast_enclose_volume=None, color=None, brightness=None, transparency=None, step=None, region=None, name_region=None, expand_single_plane=None, origin=None, origin_index=None, voxel_size=None, planes=None, dump_header=None, pickable=None, symmetry=None, center=None, center_index=None, axis=None, coordinate_system=None, data_cache_size=None, show_on_open=None, voxel_limit_for_open=None, show_plane=None, voxel_limit_for_plane=None, show_outline_box=None, outline_box_rgb=None, outline_box_linewidth=None, limit_voxel_count=None, voxel_limit=None, color_mode=None, projection_mode=None, bt_correction=None, minimal_texture_memory=None, maximum_intensity_projection=None, linear_interpolation=None, dim_transparency=None, dim_transparent_voxels=None, line_thickness=None, smooth_lines=None, mesh_lighting=None, two_sided_lighting=None, flip_normals=None, subdivide_surface=None, subdivision_levels=None, surface_smoothing=None, smoothing_iterations=None, smoothing_factor=None, square_mesh=None, cap_faces=None, box_faces=None, orthoplanes=None, position_planes=None)

Control the display of density maps.


volumes : list of maps

style : “surface”, “mesh”, or “solid”

show : bool

hide : bool

toggle : bool

level : sequence of 1 or 2 floats

In solid style 2 floats are used the first being a density level and second 0-1 brightness value.

enclose_volume : float

fast_enclose_volume : float

color : Color

brightness : float

transparency : float

step : sequence of 3 integers

region : sequence of 6 integers

3 minimum grid indices and 3 maximum grid indices for x,y,z axes.

name_region : string

expand_single_plane : bool

origin : sequence of 3 floats

origin_index : sequence of 3 floats

voxel_size : sequence of 3 floats

planes : tuple of (axis, start, end, increment, depth), last 3 are optional


Symmetry assignment options


symmetry : string

center : string

Parsed as 3 comma-separated floats, or an atom specifier

center_index : sequence of 3 floats

axis : sequence of 3 floats

coordinate_system : Place

Coordinate system for axis and center symmetry options


Global options


data_cache_size : float

In Mbytes

show_on_open : bool

voxel_limit_for_open : float

show_plane : bool

voxel_limit_for_plane : float


Rendering options


show_outline_box : bool

outline_box_rgb : Color

outline_box_linewidth : float

limit_voxel_count : bool

Auto-adjust step size.

voxel_limit : float (Mvoxels)

color_mode : string

Solid rendering pixel formats: ‘auto4’, ‘auto8’, ‘auto12’, ‘auto16’, ‘opaque4’, ‘opaque8’, ‘opaque12’, ‘opaque16’, ‘rgba4’, ‘rgba8’, ‘rgba12’, ‘rgba16’, ‘rgb4’, ‘rgb8’, ‘rgb12’, ‘rgb16’, ‘la4’, ‘la8’, ‘la12’, ‘la16’, ‘l4’, ‘l8’, ‘l12’, ‘l16’

projection_mode : string

One of ‘auto’, ‘2d-xyz’, ‘2d-x’, ‘2d-y’, ‘2d-z’, ‘3d’

bt_correction : bool

Brightness and transparency view angle correction for solid mode.

minimal_texture_memory : bool

Reduce graphics memory use for solid rendering at the expense of rendering speed.

maximum_intensity_projection : bool

linear_interpolation : bool

Interpolate gray levels in solid style rendering.

dim_transparency : bool

Makes transparent surfaces dimmer

dim_transparent_voxels : bool

For solid rendering.

line_thickness : float

smooth_lines : bool

mesh_lighting : bool

two_sided_lighting : bool

flip_normals : bool

subdivide_surface : bool

subdivision_levels : integer

surface_smoothing : bool

smoothing_iterations : integer

smoothing_factor : float

square_mesh : bool

cap_faces : bool

box_faces : bool

orthoplanes : One of ‘xyz’, ‘xy’, ‘xz’, ‘yz’, ‘off’

position_planes : sequence of 3 integers

Intersection grid point of orthoplanes display

volume_add(session, volumes, on_grid=None, bounding_grid=None, subregion='all', step=1, grid_subregion='all', grid_step=1, value_type=None, in_place=False, scale_factors=None, model_id=None)

Add maps.

volume_bin(session, volumes, subregion='all', step=1, bin_size=(2, 2, 2), model_id=None)

Reduce map by averaging over rectangular bins.

volume_boxes(session, volumes, centers, size=0, isize=None, use_marker_size=False, subregion='all', step=1, model_id=None)

Extract boxes centered at marker positions.

volume_cover(session, volumes, atom_box=None, pad=5.0, box=None, x=None, y=None, z=None, f_box=None, fx=None, fy=None, fz=None, i_box=None, ix=None, iy=None, iz=None, use_symmetry=True, cell_size=None, step=(1, 1, 1), model_id=None)

Extend a map using symmetry to cover a specified region.

volume_falloff(session, volumes, iterations=10, in_place=False, subregion='all', step=1, model_id=None)

Smooth edges of a masked map.

volume_flatten(session, volumes, method='multiplyLinear', fitregion=None, subregion='all', step=1, model_id=None)

Make map background flat.

volume_flip(session, volumes, axis='z', subregion='all', step=1, in_place=False, model_id=None)

Flip a map axis reversing the hand.

volume_fourier(session, volumes, subregion='all', step=1, model_id=None, phase=False)

Fourier transform a map

volume_gaussian(session, volumes, s_dev=(1.0, 1.0, 1.0), subregion='all', step=1, value_type=None, invert=False, model_id=None)

Smooth maps by Gaussian convolution.

volume_laplacian(session, volumes, subregion='all', step=1, model_id=None)

Detect map edges with Laplacian filter.

volume_local_correlation(session, volumes, window_size=5, subtract_mean=False, model_id=None)

Compute correlation between two maps over a sliding window.

volume_maximum(session, volumes, on_grid=None, bounding_grid=None, subregion='all', step=1, grid_subregion='all', grid_step=1, value_type=None, in_place=False, scale_factors=None, model_id=None)

Pointwise maximum of maps.

volume_median(session, volumes, bin_size=(3, 3, 3), iterations=1, subregion='all', step=1, model_id=None)

Replace map values with median of neighboring values.

volume_minimum(session, volumes, on_grid=None, bounding_grid=None, subregion='all', step=1, grid_subregion='all', grid_step=1, value_type=None, in_place=False, scale_factors=None, model_id=None)

Pointwise minimum of maps.

volume_morph(session, volumes, frames=25, start=0, play_step=0.04, play_direction=1, play_range=None, add_mode=False, constant_volume=False, scale_factors=None, hide_original_maps=True, interpolate_colors=True, subregion='all', step=1, model_id=None)

Linearly interpolate pointwise between maps.

volume_multiply(session, volumes, on_grid=None, bounding_grid=None, subregion='all', step=1, grid_subregion='all', grid_step=1, value_type=None, in_place=False, scale_factors=None, model_id=None)

Pointwise multiply maps.

volume_octant(session, volumes, center=None, i_center=None, subregion='all', step=1, in_place=False, fill_value=0, model_id=None)

Extract an octant from a map.

volume_permute_axes(session, volumes, axis_order='xyz', subregion='all', step=1, model_id=None)

Permute map axes.

volume_resample(session, volumes, on_grid=None, bounding_grid=False, subregion='all', step=1, grid_subregion='all', grid_step=1, value_type=None, model_id=None)

Interoplate a map on a new grid.

volume_ridges(session, volumes, level=None, subregion='all', step=1, model_id=None)

Find ridges in a map.

volume_scale(session, volumes, shift=0, factor=1, sd=None, rms=None, value_type=None, subregion='all', step=1, model_id=None)

Scale, shift and convert number type of map values.

volume_subtract(session, volumes, on_grid=None, bounding_grid=False, subregion='all', step=1, grid_subregion='all', grid_step=1, value_type=None, in_place=False, scale_factors=None, min_rms=False, model_id=None)

Subtract two maps.

volume_threshold(session, volumes, minimum=None, set=None, maximum=None, set_maximum=None, subregion='all', step=1, model_id=None)

Set map values below or above a threshold to a constant.

volume_tile(session, volumes, axis='z', pstep=1, trim=0, columns=None, rows=None, fill_order='ulh', subregion='shown', step=1, model_id=None)

Concatenate maps along an axis.

volume_unbend(session, volumes, path, yaxis=None, xsize=None, ysize=None, grid_spacing=None, subregion='all', step=1, model_id=None)

Unbend a map near a smooth splined path.

volume_unroll(session, volumes, inner_radius=None, outer_radius=None, length=None, grid_spacing=None, axis=None, center=None, coordinate_system=None, subregion='all', step=(1, 1, 1), model_id=None)

Flatten a cylindrical shell within a map.

volume_zone(session, volumes, near_atoms=None, range=None, bond_point_spacing=None, minimal_bounds=False, invert=False, subregion='all', step=1, model_id=None)

Mask a map keeping only parts close to specified atoms.


vseries_align(session, series, enclose_volume=None, fast_enclose_volume=None)

Align each frame of a map series to the preceeding frame.

vseries_measure(session, series, output=None, centroids=True, color=(0.7, 0.7, 0.7, 1), radius=None)

Report centroid motion of a map series.

vseries_play(session, series, direction='forward', loop=False, max_frame_rate=None, pause_frames=0, jump_to=None, range=None, start_time=None, normalize=False, markers=None, preceding_marker_frames=0, following_marker_frames=0, color_range=None, cache_frames=1)

Show a sequence of maps from a volume series.

vseries_save(session, series, path, subregion=None, step=None, value_type=None, threshold=None, zero_mean=False, scale_factor=None, match_scale=None, enclose_volume=None, fast_enclose_volume=None, normalize_level=None, align=False, on_grid=None, mask=None, final_value_type=None, compress=False)

Process the frames of a map series and save the result to a a file. Processing can normalize, align, mask and change the numeric value type of maps.

vseries_slider(session, series)

Display a graphical user interface slider to play through frames of a map series.

vseries_stop(session, series)

Stop playing a map series.


wait(session, frames=None)

Wait before proceeding to the next command. Used in movie recording scripts.


frames : integer

Wait until this many frames have been rendered before executing the next command in a command script.


window_size(session, width=None, height=None)

Report or set graphics window size in pixels.


zoom(session, factor=None, frames=None, pixel_size=None)

Move the camera toward or away from the center of rotation to make the objects appear bigger by a specified factor.


factor : float

Factor by which to change apparent object size.

frames : integer

Perform the specified zoom over N frames.

pixel_size : float or None

Zoom so that the pixel size in physical units (Angstroms) is this value. For perspective camera modes the pixel size is set at the center of rotation depth. If factor is also given then it multiplies pixel size.