• Open marker set... bring up a dialog for browsing to and opening a marker file
• New marker set - start a new marker set and make it the active set
• Save current marker set - save the active set to the same marker file it was opened from, or if none, to a specified filename
• Save current marker set as... save the active set to a marker file
• Save all marker sets as... save all marker sets to a single marker file
• Save selected marker sets as... save all sets chosen in the marker set list (or if none, the active set) to a single marker file
• Close marker set - delete all sets chosen in the marker set list (or if none, the active set)

• Show markers - show the selected markers, or if none, all markers in the active set
• Hide markers - hide the selected markers, or if none, all markers in the active set
• Delete markers - delete the selected markers

• Show links - show the selected links, or if none, all links in the active set
• Hide links - hide the selected links, or if none, all links in the active set
• Delete links - delete the selected links

• Show marker notes - show annotations for the selected markers, or if no markers are selected, for all markers in the active set
• Hide marker notes - hide annotations for the selected markers, or if no markers are selected, for all markers in the active set
• Delete marker notes - delete annotations for the selected markers

• Transfer selected markers to current set - transfer the selected markers to the active set; this allows markers to be transferred from one set to another

• Place markers on high density (on by default) - when the assigned button is clicked over any volume data display region, add a marker at the nearest local maximum above the threshold along the line of sight (details...)
• Place markers on data planes (on by default) - when the assigned button is clicked over a single-plane display, add a marker in that plane
• Place markers on surfaces - when the assigned button is clicked over a surface, add a marker at the nearest surface point along the line of sight
• Place markers outside data - when the assigned button is clicked, add a marker halfway between the near and far global clipping planes
• Place markers while dragging - create a stream of markers as the cursor is moved with the assigned button held down
• Move and resize markers - allow dragging a marker with the assigned button, including changing its depth when the Shift key is also held down and changing its size when caps lock is on
• Marker color matches volume color - color new markers dropped on data spots to match the spots; color other new markers the specified Marker color
• Link new marker to selected marker - as a new marker is created, link it to the previously selected marker
• Link consecutively selected markers - when an existing marker is selected, link it to the previously selected marker

FEATURES

The Features menu lists potential sections in the Volume Tracer dialog, with checkboxes controlling which sections are shown. A section can be closed by unchecking its entry in the Features menu, unchecking its feature button, or clicking its close button (), if present.

• Feature buttons
• Marker color and radius (shown by default)
• Marker notes
• Marker set list
• Marker set menu (shown by default)
• Mouse button menu (shown by default)
• Mouse mode options
• Rename marker set
• Slice display
• Smooth paths
• Surfaces

• Show only default panels - restore the previously saved state of the Features menu (and thus which sections are present in the Volume Tracer dialog)
• Save default panels - save the state of the Features menu (and thus which sections are present in the Volume Tracer dialog) in the Chimera preferences file
• Save default dialog settings - save many current Volume Tracer settings other than the state of the Features menu in the preferences file
• Use factory default settings - reset the Features menu and other Volume Tracer settings to the factory defaults without changing the preferences file

This section contains a row of small, unlabeled buttons representing the other possible sections of the Volume Tracer dialog. Checking a feature button has the same effect as checking a box in the Features menu. Although arranged horizontally, the buttons are in the same order as the menu entries. Placing the cursor over a feature button shows the name of the feature.

A marker set is a named collection of markers and links, implemented in Chimera as a molecule model.

Multiple marker sets can be present, but only one at a time can be the active set. The Marker set menu shows the name of the active set. Various menu operations apply to the active set, and newly created markers and links are added to this set.

At first, the active (and only) marker set is marker set 1. File... New marker set starts a new marker set and makes it the active set. Marker sets are initially named marker set 1, marker set 2, etc., but can be renamed. Markers can be transferred from one set to another. File... Close marker set removes the active set. A marker set cannot be recovered after it has been removed.

The name of the active set is shown next to the words Marker set. Clicking on the name reveals a menu of all open marker sets, from which a different set can be designated as the active set.

This section is a list of all open Marker Sets. A set can be designated as the active set by clicking its entry in the list. Although only one set at a time can be the active set, multiple sets can be chosen from the list by dragging with the mouse or Ctrl-clicking on individual entries. The chosen sets can then be saved to a single marker file with File... Save selected marker sets as... or deleted with File... Close marker set.

In this section, the active set can be renamed by entering a new name and pressing the return key (Enter).

A marker is a sphere with an associated position, radius, and color, implemented in Chimera as an atom. Each marker belongs to a marker set (molecule model). As markers are created, they are assigned successive residue numbers for convenient command-line specification (for example, #0:10-18 specifies markers 10-18 in model 0). Just like other atoms in Chimera, markers can be selected and their attributes can be inspected and modified.

Markers that are selected can be hidden, shown, deleted, or transferred to the active set using the Volume Tracer Actions menu. When no markers are selected, the hide and show (but not delete) Actions apply to all markers in the active set. A marker cannot be recovered after it has been deleted.

Markers that are selected can also be used to define a zone of volume data display (with Zone in Volume Viewer), other surface display (with Surface Zone), or surface coloring (with Color Zone).

A newly created marker is always added to the active set. When a marker is created, it is selected and any other markers are deselected. The Mouse mode options and Mouse menu control how markers are created, while the Mouse button menu controls which mouse button is used. When more than one mode of marker creation could apply to a single click of the assigned button, the one that gives the frontmost marker will “win.”

Use [button] to place/move markers controls which mouse button will be used for marker operations. This assigned button will cease to perform any previously assigned function while assigned to one or more marker operations in the Mouse mode options or Mouse menu.

This section controls how markers and links are created. The checkbox options are also available in the Mouse menu.

• Place markers on high density (on by default) - when the assigned button is clicked over any volume data display region, add a marker at the nearest local maximum above the threshold along the line of sight. The marker will be placed at the screen (X,Y) position of the cursor at the time of the mouse click, at the depth (Z-coordinate) of the closest local maximum above the detection threshold. If no value along the line of sight exceeds the threshold, or if only a single plane of data is displayed, this option will not generate a marker. A slice display shows the data values along the line of sight and can be used to adjust the threshold. A marker cannot be placed on a data minimum automatically; it must be created first and then manually moved to a minimum.
  
  
• Place markers on data planes (on by default) - when the assigned button is clicked over a single-plane display, add a marker in that plane
  
  
• Place markers on surfaces - when the assigned button is clicked over a surface, add a marker at the nearest surface point along the line of sight
  
  
• Place markers outside data - when the assigned button is clicked, add a marker halfway between the near and far global clipping planes
  
  
• Place markers while dragging - create a stream of markers as the cursor is moved with the assigned button held down. This is primarily useful along with Place markers on data planes for generating strings or loops of markers for subsequent use in surface creation.
  
  
• Dragging marker spacing - how far apart to drop markers as they are created with Place markers while dragging. The spacing is in grid units if volume data is present, otherwise screen pixels. A loop will be closed automatically if its start and end markers are within this distance.
  
  
• Move and resize markers - enable moving and resizing markers by dragging with the assigned button. In the following, the X axis is horizontal in the plane of the screen, Y is vertical in the plane of the screen, and Z is orthogonal to the screen.
  • A marker can be dragged from one (X,Y) position to another with the assigned button. Dragging with both the assigned button and the Shift key held down changes the Z-coordinate of the marker; dragging down pulls the marker closer (out of the screen) while dragging up pushes the marker further away (into the screen). The Shift key can be pressed and released repeatedly during a single dragging motion to switch between (X,Y) and Z-coordinate movement. It is difficult to see marker depth without using stereo, although the Side View may be helpful. Another technique is to watch for intersection of the marker with a volume isosurface as marker depth is adjusted.
    
    
  • A marker can be resized by dragging with the assigned button when caps lock is on; dragging down decreases the radius while dragging up increases it.

  If any marker creation mode is also active, the result of clicking the assigned button depends on the location of the click. Clicking over an existing marker grabs it for movement/resizing, while clicking elsewhere creates a new marker.

  Only one marker can be moved or resized at a time. A marker cannot be grabbed if there is another selectable item (such as an atom, bond, or another marker) in front of it. Volume displays created by Volume Viewer are not selectable, so they will not interfere with marker grabbing.

  A newly created marker can also be moved in what was the Z-dimension at the time of its creation by dragging the vertical line in the slice graph.

• Marker color matches volume color - color new markers placed on data spots to match the spots; color other new markers the specified Marker color
  
  
• Link new marker to selected marker - as a new marker is created, link it to the previously selected marker. One (and only one) marker must have been selected beforehand.
  
  
• Link consecutively selected markers - when an existing marker is selected, link it to the previously selected marker. Only one marker should be selected at a time. This mode allows markers created previously to be linked in any desired pattern.

Slice display

A slice graph shows the data profile along the line of sight (the Z dimension) under the cursor when the assigned button is clicked and marker creation and/or movement is enabled. Near to far is shown from left to right.

In the slice graph, each displayed volume data set under the mouseclick is shown with a solid line and a dotted line. Slice graph color matches volume color indicates that the lines should be shown in the same color as the volume display. The solid line represents data values; the dotted line is the detection threshold for placing markers. When a marker is placed on a data spot, its Z-position is indicated with a vertical black line, The vertical line can be dragged to move the marker to a different depth. This is useful when a marker has been placed on a faint foreground spot rather than its intended destination, a brighter background spot.

The detection threshold is initially the same as the lowest display threshold for that data set in Volume Viewer. As needed, the detection threshold can be dragged higher or lower in the slice graph with the mouse. This does not change the display threshold. Once a detection threshold has been moved, it is shown with longer dashes. Reset sets the detection threshold(s) back to the existing display threshold(s).

When Show slice line using color is on, creating a marker within a volume display region generates a line along the current Z axis that intersects the marker. The color of the line is specified in the adjacent color well. Changing the color will not affect an existing slice line, only those subsequently drawn. If there is no volume data, no slice line will be generated. Because the line follows the line of sight at the time of marker creation, it will not be visible until there has been some rotation. Upon rotation, it should be evident which data spots the line intercepts and whether the marker has been placed on the intended spot. The slice line will disappear when a newer marker is created, and if the newer marker is within a volume display region, a slice line will be drawn for the newer marker. Slice lines are implemented as VRML models.

A marker note is a text annotation associated with a marker, implemented as an atom label in Chimera. Notes on markers that are selected can be hidden, shown, or deleted using the Volume Tracer Actions menu. When no markers are selected, the hide and show (but not delete) Actions apply to all marker notes in the active set. A marker note cannot be recovered after it has been deleted.

Entering text in the Marker note field and pressing the return key labels each selected marker with that text. Notes cannot occupy multiple lines. The adjacent color well specifies the color of the text. Editing the color changes the note color of any selected markers.

The font size of notes (along with all atom labels) can be adjusted collectively in the Labels preferences. For publication/presentation, 2D Labels may be a useful alternative; they can be in multiple sizes and colors, placed anywhere in the graphics window. They do not move when models are rotated or translated.

A link is a connection between markers, implemented in Chimera as a bond and displayed as a cylinder with user-specified radius and color. Only one link can exist for a given pair of markers. Just like other bonds in Chimera, links can be selected and their attributes can be inspected and modified.

Links that are selected can be hidden, shown, or deleted using the Volume Tracer Actions menu. When no links are selected, the hide and show (but not delete) Actions apply to all links in the active set. A link will also be hidden when the markers it connects are hidden. A link cannot be recovered after it has been deleted.

If the command bondzone has been issued, links that are selected can also be used to define a zone of volume data display (with Zone in Volume Viewer), other surface display (with Surface Zone), or surface coloring (with Color Zone).

A newly created link is always added to the active set. When a link is created, it is selected and any other links are deselected. The Mouse mode options and Mouse menu control how links are created.

This section specifies the colors and radii of markers and links.

Editing the Marker color (using the associated color well) changes the color of any selected markers. New markers will also receive the specified Marker color unless Marker color matches volume color is turned on. In that case, new markers placed on data spots will be colored to match the spots, but other new markers will receive the specified Marker color.

Conversely, Color Zone can be used to color volume data surfaces to match nearby selected markers.

When marker radius is not specified, a default value is determined as follows:

• When the marker is within a volume display region and the displayed data is not a subsample, marker radius will be set to the X, Y, or Z grid spacing of the data, whichever is smallest.
• When the marker is within a volume display region and the displayed data is a subsample, marker radius will be set to the X, Y, or Z grid spacing of the subsampled data, whichever is smallest.
• When the first marker in a set is created outside any volume display region or in the absence of any volume data, its radius will be set to 1/100 of the distance between the near and far clipping planes. The clipping plane positions can be viewed and adjusted in the Side View.
• When a subsequent marker (not the first in a set) is created outside any volume display region or in the absence of any volume data, its radius will be set to equal the radius of the first marker in the set, regardless of how that value was determined.

The number of subdivisions used for drawing the markers (and thus the smoothness of the spheres) can be increased by raising subdivision in the Effects tool. Higher values increase smoothness, but may slow performance.

Editing the Link color (using the associated color well) changes the color of any currently selected links and subsequently created links.

Links can be shown as lines (radius = 0) or as cylinders (radius > 0). When link radius is not specified, it is set to half of the default marker radius. Entering a link radius value (with or without pressing the return key) sets the radii of subsequently created links. When the return key is pressed, the radii of any selected links will be changed accordingly.

With this section of the dialog, interpolated paths can be generated for linked chains of markers. Clicking Show generates a curve for each chain of markers in the active set; if multiple links emanate from a marker, so will multiple curve segments. (Links can be hidden with Actions... Hide links.) Each curve is an Overhauser (also called Catmul-Rom) spline, a cubic spline where the tangent at each marker is parallel to the vector between the preceding and following markers. Curves for a marker set are implemented as pieces of a surface model. Unshow removes any curves drawn for the active set.

After a parameter is changed, it is necessary to click Show or press return within any Smooth paths parameter field to apply the change. Paths can be shown as lines (Curve radius = 0) or as tubes constructed from multiple cylinders (Curve radius > 0). The number of line segments or cylinders forming the curve between a linked pair of markers equals Segment subdivisions + 1.

A path is colored based on marker and link colors. Band length specifies the length of curve centered on each marker that should be colored the same as the marker. Parts of the curve further away from a marker receive the color of the corresponding link. Generally, color bands are not exactly the specified length because:

• Curves consist of a finite number of subdivisions. A change from one color to another along the curve occurs linearly over a single line segment when Curve radius = 0 and abruptly between two cylinders when Curve radius > 0.
• When Curve radius > 0, a path consists of cylinders joined by spheres. Even when Band length = 0, there is still one joining sphere at the position of the marker that is the same color as the marker. How much of this sphere is visible depends on the local degree of bending.

A series of connected paths (either closed loops or open curves) can be combined to form a surface. Typically, a path is generated for each of several volume data planes using the settings Place markers on data planes and Place markers while dragging. The stack of paths can then be joined in the orthogonal direction to create a surface. Surfaces created by Volume Tracer are saved in sessions and can be used to segment volume data with the command mask.

Clicking Create uses all selected markers, or if none are selected, all markers in the active set, to generate a surface. The markers must be linked into paths, and the paths used to make a given surface must be either all closed loops or all open-ended. Branched paths are not allowed, and the surface cannot form forked tubes. Cap surface end loops makes the surface cover the ends of tubes formed by closed-loop paths.

Each surface created by Volume Tracer is a single surface piece in the surface model named Traced surfaces. There is only one Traced surfaces model, but it can contain multiple surface pieces created from different collections of markers. Clicking Create repeatedly for the same markers will generate multiple identical surface pieces. Delete closes (removes) any surface pieces of the Traced surfaces model that are selected. It is necessary to delete and recreate a surface to update it after moving a marker.

A marker file includes marker set name(s), marker positions, marker notes, links, colors, and radii (but not smooth paths or surfaces).

Marker files can be read and written using the Volume Tracer File menu. In addition, they can be opened with Chimera's general file-reading mechanisms, just like other registered file types. The Chimera marker file type can be indicated with the suffix .cmm (part of the filename) or the prefix markers: (not part of the filename).

The format is actually XML, a text file that can be viewed and edited with an editor and can be read or created by other programs. Libraries for parsing XML are available in many programming languages. The following marker file describes two markers connected by a link:

<marker_set name="marker set 1">
<marker id="1" x="-6.1267" y="17.44" z="-3.1338"  radius="0.35217"/>
<marker id="2" x="1.5395" y="16.277" z="-3.0339" r="0" g="1" b="1"
               radius="0.5" note="An example note"/>
<link id1="2" id2="1" r="1" g="1" b="0" radius="0.17609"/>
</marker_set>

The r, g, and b attributes are red, green, and blue color components, respectively, with possible values ranging from 0 to 1.

Extra attributes can be present within the marker, link, and marker_set tags. While these are not used by Volume Tracer, they provide a mechanism for retaining information from or passing information to other programs. For example,

<marker id="3" x="3.23" y="4.34" z="5.45" r="0" g="0" b="1" radius=".4"
 note="105" somethingextra="hoola hoop"/>
<link id1="1" id2="2" r="0" g="1" b="0" radius=".2" leprechaun="gold"/>

May place markers on data hidden with Surface Zone. Markers may be placed in regions of volume data that have been hidden with Surface Zone. Markers land at the same locations they would if no surface zone were in effect, possibly in volume regions outside of the displayed zone.

Transparency not saved. Although markers and links can be transparent (when transparent marker and link colors are used), transparency is not saved in marker files.

POSSIBLE DEVELOPMENTS

• enable automatic marker creation/placement on minima
• add option to center markers on local maxima or minima in 3D
• add option to determine link colors from marker color (atom halfbond)
• optimize slice graph display so that marker placement is not slow
• allow definition of different groups of markers within a single marker set
• supply Python code for reading and writing the XML files containing saved marker sets
• make tubes using triangle lists for better resolution control and efficiency
• set curve radius automatically based on marker and/or link radius
• redraw curves automatically when curve parameters are changed
• allow curves to have a uniform color even when not all markers/links are the same color