Command: save

Usage:
save  filename [ format  format-name ] [ models  model-spec ]  other-options

Usage:
save formats

The save command saves an image, ChimeraX session, map (volume data), atomic coordinates, sequences, or other data to filename, which can be a pathname including the directory location. The pathname can be absolute or relative to the current working directory as reported by pwd. The working directory can be changed with cd. Giving the word browse instead of a filename opens a file browser window for choosing it interactively. Files can also be saved with menu File... Save or Toolbar icon . See also: open, log, ChimeraX positions format, writing mmCIF files in ChimeraX

The file type is specified with either the filename suffix or the format option. If the format is specified separately, the appropriate suffix will be added to filename.

Sessions, images, and scenes (most formats) include all contents, but atomic coordinate, map, GLTF, and VRML saving can be limited to specific models with the models option. The models keyword can be omitted if model-spec is given immediately after filename, for example:

save mutated.pdb #3

There may be additional required arguments or options, depending on the file type:

• Image
• Session
• Map
• Atomic Coordinates:  PDB   mmCIF   Mol2 
• Attribute Values
• Sequence Data
• GLTF
• VRML
• MTZ (Options from Clipper)

[back to top: save]

Output Formats

The command save formats lists the possible output formats in the Log.

[back to top: save]

Save Image

Usage: save  filename [ format  format-name ] [[ width  w ][ height  h ] | pixelSize  p ] [ supersample N ] [ quality M ] [ transparentBackground  true | false ]

Images generally have the same contents as the graphics window, but are rendered offscreen. See also: snapshot, windowsize, view, making images, making movies,

[ width  w ][ height  h ] | pixelSize  p
Image pixel dimensions can be specified directly with width and height, or relative to the physical dimensions of the view in the window with pixelSize. If none of these are given, the image will have the same pixel dimensions as the graphics display. The display dimensions are usually the same as the graphics window reported by windowsize, except twice as large on high-DPI displays such as Apple Retina. If only width or height is specified, the other will be set according to the window aspect ratio; if both are specified but the image aspect ratio is not the same as the window aspect ratio, the image contents will differ from what is shown in the window. With the pixelSize option, the image contents will be the same as what is shown in the window, but image pixel dimensions will be chosen to give pixels of size p in Å. With perspective, the pixel size varies with depth, but pixelSize sets the value at half-depth (the midpoint along the line of sight). For example, if at half-depth the graphics window encloses a 400-Å by 300-Å rectangle, pixelSize 0.4 specifies image pixel dimensions of 1000 by 750.

supersample N
Supersampling refers to initially generating an image at a higher resolution than requested and then sampling it down to the final size. This gives a smoother (less pixelated) appearance of lines and boundaries in the final image. The degree of supersampling N defaults to 3, meaning that the initial image will be 3 times larger in each dimension, with 9 times as many pixels, as the final result. A value of 1 corresponds to no supersampling. See also: graphics quality

quality M
The quality M applies to JPEG format only, with values in the range 0–100 (default 95).

transparentBackground  true | false
Whether to include opacity values (alpha) in an output PNG or TIFF file. With background transparency, the background will be completely invisible in the saved images. This facilitates combining the image with different backgrounds in image-editing applications. (Note: TIFF images with background transparency may not be interpreted correctly by Adobe Photoshop.)

[back to top: save]

Save Session

Usage: save  filename [ format  format-name ] [ includeMaps  true | false ] [ compress  gzip | lz4 | none ]

A ChimeraX session file encodes most aspects of a modeling session in ChimeraX:

• atomic and other models
• active torsions and active angles
• sequences and sequence alignments
• axis, plane, and centroid objects
• lighting, display styles, coloring, labels (2D and 3D)
• selections, selection highlighting color and width
• defined targets (e.g., named selections)
• named views
• aliases
• attributes
• custom colors
• custom button panels
• surface zones
• segmentation results
• virtual reality status including model positions in the room and hand-controller button assignments
• Log contents
• slider interfaces for playback of trajectories and model series

Sessions are saved in a ChimeraX-specific format not read by other programs. Maps generated on the fly (rather than read from a file) are always included if present, but the includeMaps option indicates whether maps read from pre-existing files should also be included. The default is false, as maps can be very large. If the maps are not included, the session file will still include the locations of the corresponding map files and open them automatically upon session restore, or if they are not found, prompt the user for their current locations. The session file will include the map file location as a relative path if the map file is in the same directory as the session file, or in a subdirectory of that directory. If the map file is in neither the same directory as the session file nor a subdirectory of that directory, its location will be stored as an absolute path.

The compress option defaults to lz4, which gives a file approximately 4x smaller (depending on the data being saved) than the uncompressed version obtained with none; using gzip gives a file approximately 7x smaller than uncompressed, but takes about twice as long as the other choices. Compressed and uncompressed session files have the same .cxs filename suffix, but compression is recognized automatically when the file is read.

[back to top: save]

Save Map

Usage: save  filename [ baseIndex M ] [ format  format-name ] [ models  model-spec ] [ step  N | Nx,Ny,Nz ] [ region  all | i1,j1,k1,i2,j2,k2 ] [ maskZone  true | false ] [ valueType  value-type ]  chimera-map-options

Various formats are available for saving maps (volume data). MRC files written by ChimeraX are in the MRC 2000 format. Older MRC-reading programs or programs expecting CCP4 format will read such files successfully but may not align the data correctly with other data sets. See also: segger exportmask, saving maps after fitting

If the map is cropped, the current display region will be written unless different extents are specified with region.

Only the Chimera map (cmap) format can accommodate multiple data sets in a single file, and will include symmetry if previously assigned, such as with volume symmetry or measure symmetry. Several options (compression, etc.) apply only to Chimera map format.

Multiple data sets can be written to multiple files by including a %d integer format specification in filename:

save data%d.mrc models #2,3,7
save data%03d.mrc models #2,3,7

The first example would generate the files data1.mrc, data2.mrc, and data3.mrc, while the second would instead use names like data001.mrc. Successive integers starting with baseIndex M (default 1) will be used in the new names regardless of the volume model numbers. If the format specification is incorrect, filename will be interpreted as the name of a single file.

For the imagejtiff format, the default is to save the stack as a single file, but Z-planes can be saved to multiple individual files by including “{z}” in the filename, for example:

save mymap_{z}.tif format imagejtiff

Further options (all map formats):

models  model-spec
Volume model(s) to save; can be omitted if only one volume model is open. The models keyword can be omitted if model-spec is given immediately after filename.

step  N | Nx,Ny,Nz
Whether to use the full resolution of the data (step size 1, default) or a specified subsample (step size > 1). Step sizes must be integers. A step size of 1 indicates all data points, 2 indicates every other data point, 3 every third point, etc. If a single number is supplied, it is used along all three axes; if three numbers are supplied (separated by commas but not spaces), they are used along the X, Y, and Z axes, respectively.

region  all | i1,j1,k1,i2,j2,k2
Whether to write the full extents of the data (all, default) or a specified subregion. A subregion can be specified by grid indices i1–i2 along the X axis, j1–j2 along the Y axis, and k1–k2 along the Z axis. Grid indices must be integers separated by commas but not spaces. If the region option is not supplied, the currently displayed subregion will be written. In this context, a zone is not considered a subregion.

maskZone  true | false
If zoning is in effect (see surface zone), whether to write out data for a region enclosing the zone, with values outside the zone set to zero. See also: volume zone

valueType  value-type
The value-type of an output MRC map can be specified as 8- or 16-bit signed integer (int8 or int16), 16-bit unsigned integer (uint16), or 16- or 32-bit floating-point (float16 or float32). If the actual map values are outside the range of the requested type, the resulting saved values will be undefined rather than clamped to the minimum and maximum values of the requested type. If the value type is not specified, it defaults to the same type as the input map if among the possibilities listed above, otherwise to an available type that can accommodate the range of map values. For example, a map read as 8-bit unsigned integer would be saved as 16-bit integer.

append  true | false
For Chimera map (cmap) format only, whether to append the data to an existing file instead of overwriting the file.

chunkShapes  order
For Chimera map (cmap) format only, how to lay out the data within the file. The layout affects the efficiency of later reading the data, primarily a concern for very large data sets (hundreds of Mb). The order can be one or more of the following, separated by commas but not spaces:

• zyx (default)
• zxy
• yxz
• yzx
• xzy
• xyz

Data are written in blocks of up to 64 Kb. The blocks are shaped according to the specified order: smallest along the first axis and largest along the third. Data planes are read from a file with different efficiencies depending on their orientations and the layout. For example, from data written in the default order (zyx), XY planes will be read the most efficiently and YZ planes the least efficiently. When multiple orders are specified, multiple copies of the data are written to the same file. When the file is read, the most efficient copy available will be used. Saving a file with an order ending in “z” can be very slow because one Z-plane is written at a time.

compress  true | false
For Chimera map (cmap) format only, whether to compress the data (default false). If compress is true, the compress_method, compress_level, and compress_shuffle options apply. Compression is most useful for volume masks (values 0/1), as other data sets tend to be noisy and less compressible.

compress_method  method
The method of compression can be:

• zlib
• lzo
• bzip2
• blosc
• blosc:blosclz
• blosc:lz4 (default; fast)
• blosc:lz4hc
• blosc:snappy
• blosc:zlib
• blosc:zstd

compress_level  level
The level of compression can be an integer in the range 1-9 (default 5).

compress_shuffle  true | false
Whether to shuffle the data prior to compression (default true), which sometimes produces a smaller file.

← Saving Maps after Fitting

Simply saving a map to a file after fitting will not save its new position, because the map file formats do not include rotation information. One way to save the new position is to save a ChimeraX session file, which preserves the translations and orientations of all models. However, if data files are needed for use in another program:

• When a map has been fit to an atomic structure, save the PDB file relative to the map rather than vice versa.
• When a map has been fit to another map, a new map can be created in the new orientation by resampling the map that was fit, on the grid of the map to which it was fit. The new, resampled map can be saved as described above. (Even if the map was not fit to another map, however, a separate zero-valued map to serve as a grid for resampling can be created with volume new.)

[back to top: save]

Save PDB

Usage: save  filename [ format  pdb ] [ models  model-spec ] [ relModel  model-spec ] [ selectedOnly  true | false ] [ displayedOnly  true | false ] [ allCoordsets  true | false ] [ pqr  true | false ] [ serialNumbering  amber | h36 ]

Atomic coordinates can be saved in PDB format. The filename can include [NAME] and/or [ID] to indicate substitution with model name and/or model number, respectively, as needed to save multiple atomic models to multiple files with a single command. See also: getcrd, view, adding full sequence information

models  model-spec
Write only the specified models, otherwise all atomic models. The models keyword can be omitted if model-spec is given immediately after filename.

relModel  model-spec
Write coordinates relative to the original coordinates of the specified model. Otherwise, coordinates will be written relative to the scene (same as the original coordinates of each model unless it was moved separately). Saving a model relative to another is useful for preserving their spatial relationship without having to save copies of both models. For example, if model 2 has been matched or docked to model 1 (such as with matchmaker, align, or fitmap), saving model 2 relative to model 1 results in them being matched or docked in the same way when the original model 1 file and the new model 2 file (saved relative to 1) are opened.

selectedOnly  true | false
Whether to include only the selected atoms when saving a PDB file, or only the selected pseudobonds when saving a pseudobond file (in addition to any restriction by models). To simply list the selection contents (e.g., atom identifiers) in the Log or to save that list to a file, see info selection instead.

displayedOnly  true | false
Whether to include only the displayed atoms. Note that cartoon display does not imply atomic display, and conversely, backbone atoms may be displayed but suppressed by cartoon.

allCoordsets  true | false
Whether to save all frames (coordinate sets) of a trajectory or just the frame that is currently displayed (default). Saving all frames produces a multi-model PDB or mmCIF file.

pqr  true | false
Whether to generate PQR format instead of standard PDB. In PQR format, atomic partial charge (Q) and radius (R) fields follow the X,Y,Z atomic coordinates.

serialNumbering  amber | h36
How to accommodate structures so large that the numbering fields in standard PDB format would overflow (output for smaller structures is not affected):

• amber handles atomic models with > 99,999 atoms by “stealing” a column to the left of the atom numbering field in standard PDB format
• h36 (default) handles atomic models with > 99,999 atoms (up to 87,440,031) and/or > 9999 residues in a chain (up to 2,436,111) by incorporating alphabetical characters (details...)

[back to top: save]

Save mmCIF

Usage: save  filename [ format  mmcif ] [ models  model-spec ] [ relModel  model-spec ] [ selectedOnly  true | false ] [ displayedOnly  true | false ] [ allCoordsets  true | false ] [ fixedWidth  true | false ] [ bestGuess  true | false ] [ computedSheets  true | false ]

Atomic coordinates and associated information can be saved in mmCIF format. A subset of the mmCIF data types are written (details...). The options are as described for saving PDB, except for the following:

• fixedWidth (default true) – whether to write fixed-width columns, as in mmCIF files from the RCSB Protein Data Bank; fixed-width columns make reading the file faster in ChimeraX
• bestGuess (default false) – whether to try to write polymer sequence information when it was missing from the input file, or the structure was built or modified by the user.

  The bestGuess option will only include residues with atomic coordinates. However, a different approach can be used to add the full sequence information (including any residues without atomic coordinates) prior to saving a file:

  1. open the full sequence in the Sequence Viewer, e.g., by reading it from a sequence file or by fetching it from UniProt
  2. make sure that the sequence is associated with the structure chain (should occur automatically in most cases)
  3. use Structure... Update Chain Sequence in the Sequence Viewer context menu (or use the sequence update command)
  
  
• computedSheets (default false) – although ChimeraX retains protein helix and strand assignments from input, it currently loses track of which strands are in the same sheets as each other. This option specifies whether to run dssp to recalculate strands and their sheet membership and to include that information in the output mmCIF. It does not affect secondary structure assignments in the currently open structure, but the strand assignments in the file may be different from those in the open structure. Further, if the existing structure did not already have helix assignments, the helix assignments from running dssp will also be saved in the output mmCIF.

[back to top: save]

Save Mol2

Usage: save  filename [ format  mol2 ] [ models  model-spec ] [ relModel  model-spec ] [ combineModels  true | false ] [ atoms  atom-spec ] [ skipAtoms  atom-spec ] [ anchor  atom-spec ] [ sybylHydNaming  true | false ] [ resNum  true | false ] [ gaffType  true | false ]

Atomic coordinates can be saved in Sybyl Mol2 format, with options:

models  model-spec
Write only the specified models, otherwise all atomic models (except as restricted with atoms and/or skipAtoms). The models keyword can be omitted if model-spec is given immediately after filename.

relModel  model-spec
Write coordinates relative to the original coordinates of the specified model (as described above for PDB).

combineModels  true | false
Whether to write multiple models into one combined @MOLECULE section. If false (default), separate @MOLECULE sections will be used for different models.

atoms  atom-spec
Write only the specified atoms.

skipAtoms  atom-spec
Skip (omit) the specified atoms.

anchor  atom-spec
Write the specified atoms into the @SET section of the file.

sybylHydNaming  true | false
If true (default), hydrogen names will be of the form HG21 instead of 1HG2.

resNum  true | false
Whether to append residue number to reside name, giving substructure names of the form ALA85 instead of ALA (default false).

gaffType  true | false
Whether to write GAFF atom types instead of Sybyl atom types. GAFF types are not yet computed, so this should be kept false.

[back to top: save]

Save Attribute Values

Usage: save  filename  attrName  [a:][r:][m:]attribute-name  [ format  defattr ] [ matchMode  any | non-zero | 1-to-1 ] [ modelIds  true | false ] [ models  model-spec ] [ selectedOnly  true | false ]

The attributes of atoms, residues, and atomic models (or equivalently, markers and their models) can be saved in the simple, human-readable attribute assignment format that can be read with the open command. The attrName keyword and attribute name are required. An a:, r:, or m: immediately preceding the attribute name can be used to indicate the attribute level as atom, residue, or (atomic) model, but this is only needed when the name exists at multiple levels. See also: info

Options:

matchMode  any | non-zero | 1-to-1
What to write as the match mode in the file; this only matters if the file will be used to assign values with open.

modelIds  true | false
Whether the atom specification strings in the file should include model numbers, where true means yes, false means no, and omitting the option (default) means to include model numbers only when multiple atomic models are open.

models  model-spec
Write only attributes of the specified models, otherwise all atomic models. The models keyword can be omitted if model-spec is given immediately after filename.

selectedOnly  true | false
Whether to limit the scope of what is written to the current selection (in addition to any restriction by models).

[back to top: save]

Save Sequence Data

Usage: save  filename [ format  aln | fasta | pir ] [ alignment  alignment-id ]

An individual sequence or multiple sequence alignment open in the Sequence Viewer can be saved to a file. Only the contents of a single Sequence Viewer window can be saved at a time. When more than sequence window is present, which one to save is indicated with the alignment option, using the alignment-id shown in the window's title bar. Example:

save example.pir alignment 1.A

[back to top: save]

3D Objects Not Clipped

Note that clipping only hides part of the scene but does not remove it. Files saved in 3D object formats (gltf, stl, obj, x3d, vrml, vtk) will include the entire models regardless of which parts (if any) are hidden by clipping.

[back to top: save]

Save GLTF

Usage: save  filename [ format  gltf ] [ models  model-spec ] [ center  x,y,z | true | false ] [ centerEachNode  true | false ] [ size  s ] [ shortVertexIndices  true | false ] [ floatColors  true | false ] [ pruneVertexColors  true | false ] [ textureColors  true | false ] [ preserveTransparency  true | false ] [ instancing  true | false ] [ backfaceCulling  true | false ] [ flatLighting  true | false ] [ metallicFactor  f_m ] [ roughnessFactor  f_r ]

Several options apply only to saving GL Transmission Format (.glb). The models are not clipped. See also: Exporting atomic models with colors to GLTF or OBJ, Embedding a 3D scene in a web page

center  true | false | x,y,z
The center option applies to GLTF and VRML formats. It allows placing the center of the scene bounding box at a specific position in the output file coordinates:

• center true (default) – at 0,0,0 (same as center 0,0,0)
• center false – unchanged from the current scene
• center x,y,z (allowed for GLTF only) – at x,y,z

centerEachNode  true | false
The centerEachNode option indicates whether to adjust the transform of each node to place its geometric center (average of vertex positions) at (0,0,0) in its local coordinate system (default true). This does not affect the positions of the objects in the scene, only how their coordinates are expressed. Centering objects in their local coordinate systems makes them easier to edit in other applications such as Blender.

size  s
Bounding size for the exported objects. The coordinates are scaled so that the longest edge of the bounding box becomes the specified size.

shortVertexIndices  true | false
Whether vertex indices in the exported file must fit within 16 bits (0-65535).

floatColors  true | false
Whether to use floating-point color values.

pruneVertexColors  true | false
Whether to omit vertex colors from the file if an object is all in one color. Specifically, if true (default): if all ribbon segments of an atomic model are the same color, the ribbons object will not have vertex colors; similarly, if all bonds (or atoms, or all parts of a surface, etc.) are the same color, the bonds (or atoms, or surface, etc.) object will not have vertex colors.

textureColors  true | false
Whether to write texture colors instead of vertex colors. This works for parts of the scene (atoms, bonds, ribbons, etc.) in which each triangle has a single color, but not where the vertices of a triangle may have different colors, as in surfaces colored by map value or distance.

preserveTransparency  true | false
Whether to include any transparency of the objects.

instancing  true | false
Whether to use instancing for atoms and bonds (and a few other types of items at the lowest level of the drawing hierarchy). Instancing can significantly reduce file size, but conversely, it increases the number of GLTF nodes, which may slow down rendering or other downstream processing of the file (e.g., by other programs) for structures with many thousands of atoms. If false (default), all the atoms of model are combined into a single node, but each includes its own geometry or triangulation information, making the file large. If instancing is true, then each atom is made into a separate node, but they all share a single copy of the triangulation, making the file smaller. The meaning for bonds is analogous to that for atoms. Instancing is always used for graphical clones created with sym regardless of this option.

backfaceCulling  true | false
The backfaceCulling option applies to GLTF and VRML formats. It indicates whether the file should specify culling the backfaces of surfaces for faster rendering. Setting this option to false allows viewing surfaces from the inside.

flatLighting  true | false
Whether to omit vertex normal vectors from the file. Omitting the normal vectors results in each triangle being flat-shaded, giving a faceted appearance.

metallicFactor  f_m
Write the specified metallic factor f_m (range 0.0-1.0, default 0.0) into the output file.

roughnessFactor  f_r
Write the specified roughness factor f_r (range 0.0-1.0, default 1.0) into the output file.

[back to top: save]

Save VRML

Usage: save  filename [ format  vrml ] [ models  model-spec ] [ center  true | false ] [ backfaceCulling  true | false ]

The VRML output is very basic and intended specifically for 3D printing. The models are not clipped. Everything in the scene is output as a single shape, a VRML IndexedFaceSet, which is a set of triangles. Primitives such as exact spheres or cylinders are not exported. The number of triangles used for atoms and bonds in ChimeraX (see graphics quality) controls the quality of spheres and cylinders in the VRML output. Colors are always output as vertex colors even if single colors are used in ChimeraX. Textures (e.g., volume image style display) are not handled. Normal vectors used for lighting are not included in the VRML file, so the VRML objects will appear faceted in viewer programs. VRML does not offer per-vertex transparency. If the entire scene has the same transparency, then this will be specified as the VRML material transparency; otherwise, the VRML file will say that the scene is opaque.