Overlays & Wires

Overlays are associated with voxel indices and are the basis for all averages across regions of interest. There are multiple ways to create an overlay:

  1. Draw a rectangular overlay on the image by clicking the right mouse button and dragging down and to the right.
  2. If an activation is overlaid on the image, left-click on the "n" button above the image, and then select an activated area. Contiguous voxels above the activation threshold will be combined into an overlay.
  3. When a 2D wire frame is drawn, closing the wire will cause the end-points to be joined to form a closed loop, and the loop will be filled with an overlay. This method enables overlays of arbitrary shape to be created.  Alternatively, a pre-existing closed wire frame can be filled at any time using the "F" text button.
  4. Read an overlay from a file. An overlay file is simply an ASCII file in which each line contains 3 required integers specifying the (x,y,z) voxel indices, plus an optional fourth argument between 0 and 1 specifying a fractional weight to use in image-based averages.

Wire frames

Wire frames employ spatial coordinates and thus translate across different resolutions. These can be useful for

  1. Visualizing a region without completely occluding it (unlike an overlay).
  2. Defining overlays of arbitrary shape by filling a closed wire frame.
  3. Creating a wire frame at high resolution (e.g., atlas or anatomical image) and then translating the region to lower resolution (directly, using a wire frame, or indirectly by down-sampling an overlay created at the higher resolution).

To create a wire frame, right-click on the "n" or "N" text button. You will be prompted by "L-button=draw, <esc>=cancel". Use mouse buttons to click on the image. For the first line segment, 4 clicks are required to define a smoothly curved segment using Cubic Bezier curves. Subsequently, only 3 clicks are required, because the 4th point is the endpoint of the previous segment. Any segments can be "undone" without exiting the drawing routine whenever the prompt includes "u=undo". A wire can be closed into a loop whenever the prompt includes "c=close"; closing a wire joins the first and last points and fills the wire with an overlay. Currently, wire frames can only be drawn on the x-y plane (usually coronal for rodent, axial for primate).


Loading overlays & wire frames

Pre-defined overlays and wire frames are useful for standardizing analysis. Predefined overlays are specific to a particular resolution. Predefined wire frames are specific to a particular space.  Presumably, both are associated with a defined template/atlas space. Lists of overlays and wire frames are loaded at run time from the unix command line:

xd data.nii -o overlay-list.dat -w wire-frame


Often one wishes to load a single overlay; e.g., to transfer an overlay from one xd process to a different xd process. A single overlay can be loaded by keyboard-“r” (left-click “r” button), which will read file “.ovl”. A single wire frame can be loaded by keyboard-“R” (right-click “r” button), which will read “.wire”.


The mirror function is useful when working with atlases or in standardized spaces.  To create an overlay with x symmetry across hemispheres, create an overlay, write it to disk (“w”), mirror the overlay (“m”), read the disk overlay (“r”), and then write the symmetric overlay (“w”). Rename the file from “.ovl” to something else (e.g, motor.ovl).


Overlay and wire frame functions keys are grouped together on the top-left part of the image window. However, one useful function of overlays that may not be obvious is windowing grayscale images. Create an overlay by right-clicking on the image and dragging down and to the left, and hit keyboard-”i” (or click on “i” text button) to auto-scale the image using only the signal intensities included in the overlay.

Joseph B. Mandeville, Athinoula A. Martinos Center for Biomedical Imaging at MGH/MIT/Harvard