ChimeraX docs icon

Command: segmentation

The segmentation command does not calculate map segmentations; instead it shows an existing segmentation as surfaces or with coloring. Users should be aware that there is another, different command named segmentations, which performs functions associated with the Segmentations tool for interactive plane-by-plane segmentation.

See also: color byattribute, color map, color zone, volume mask, segger, Segment Map, EMDB segmentation file format (SFF)

For display with this command, a segmentation can be read from an index map, a specific type of volume data that consists of non-negative integer values defining segmentation regions. In the index map, a value of zero means the grid point is not assigned to a region, a value of 1 means the grid point is part of region 1, etc. Segmentation regions are automatically assigned an attribute named segment with integer segment-id values.

For index maps read from the HDF5-based Chimera map format, additional attributes of the segmentation regions can be assigned from one-dimensional integer arrays with lengths equal to the number of regions. The array names are used as the attribute names. For example, a brain segmentation file could contain an array named “neuron” containing different integers for different neurons This would allow showing all neuron surfaces collectively, or the surface of a specific neuron, as shown in the examples below.

Showing Segmentation Regions as Surfaces

Usage: segmentation  surfaces  seg-map  where  segment-id-list | attribute-name | attribute-name=attribute-value ]each  attribute-name ] [ color  color-spec ] [ region  all | name | i1,j1,k1,i2,j2,k2 ] [ step  N | Nx,Ny,Nz ] [ smooth  true | false ] [ smoothingFactor  f ] [ smoothingIterations  N ]

Create one or more surface models enclosing segmentation regions defined in seg-map. The where option limits surface generation to a subset of the segmentation regions:


seg surf #1 where 2
seg surf #1 where 3,7,8-10
seg surf #1 where neuron
seg surf #1 where neuron=5
seg surf #1 where neuron=5-12,17,21
seg surf #1 where neuron=1-10 where spinehead

As shown in the last example, the where option can be used multiple times in the same command to limit the specification to regions meeting multiple criteria (intersection). The example specifies only the regions with a “neuron” attribute value in the range 1-10 that also have a nonzero “spinehead” attribute.

The each option controls how many surface models will be created, either a single model (default) or a separate (sub)model for each value of a specified attribute. Example:

seg surf #3 each segment

The color option gives a single color; omitting it uses colors chosen randomly for different values of the segment attribute unless a different attribute was specified with where (see also segmentation colors below).

The region option does not refer to a segmentation region, but instead a spatial subregion of the segmentation map: the full dimensions (all, default) or a subregion previously assigned name, or the subregion with 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.

The step option indicates density of sampling the segmentation map; 1 means to use the full resolution (default), 2 means to use every other point along each axis, etc.. Step values must be integers. If a single integer is supplied, it is used in all three directions; if three integers are supplied (separated by commas but not spaces), they are used in the X, Y, and Z directions, respectively.

The smooth option indicates whether to smooth the surface (default false). It works by moving each vertex a fraction of the way (default smoothingFactor 1.0) toward the average position of the vertices connected to it by triangle edges, and cycling over vertices a specified number of times (default smoothingIterations 10). Each vertex is moved once per iteration. Example:

seg surf #1 smooth true smoothingIterations 3 smoothingFactor 0.5

Coloring a Map by Segmentation Region

Usage: segmentation  colors  seg-map  [ color-spec ] [ map  map-model ] [ surfaces  surface-spec ] [ byAttribute  attribute-name ] [ outsideColor  color-spec ] [ maxSegmentId  N ] [ step  N | Nx,Ny,Nz ]

Color a map or surfaces by the segmentation regions defined in seg-map, or if neither is given, color seg-map itself. The map option should only be used for maps shown in the image display style, and the size of the image map (grid dimensions in X,Y,Z) must match that of the segmentation map. For maps shown as contour surfaces, the surface option should be used instead. If color-spec is omitted, random coloring is applied according to values of the attribute specified with the byAttribute option (default attribute segment). The outsideColor color is used for parts the map or surface that fall outside of the extents of seg-map or that correspond to zero values of the attribute within seg-map. If outsideColor is not specified, those parts will retain their pre-existing colors.

The maxSegmentId is only used to speed coloring by restricting it to only the lowest-numbered subset of a very high number of segmentation regions.

The step option indicates sampling density of the segmentation map, as described above.

UCSF Resource for Biocomputing, Visualization, and Informatics / May 2024