Differences between revisions 2 and 3
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= Starting Up = There are different guides here for different user tasks. Everybody
should read the GUI guide first to get up to speed. After that, pick a
guide that best suits what you're trying to do.
Line 3: Line 5:
Start scuba by typing {{{scuba}}} on the command line. Make sure to have
the environment variable FREESURFER_HOME set to a freesurfer
installation that includes scuba (FreeSurferDev).

== Loading data ==

You can load data in one of three ways:

=== Command Line ===

Specify data to load on the command line with the -s,
-v, and -f options. -s will specify a subject. This sets the 'main'
subject name for scuba, and all subsequent requests to load data will
first look in this subject's data directories. Use -v to load a
volume. You can specify an entire path, or a data name in a subject
directory, if you have specified -s. Use -f to similarly load

You can get a reference by typing scuba --help:

$ scuba --help

Usage: scuba [OPTION]...
Data viewer for the FreeSurfer package.

-s, --subject SUBJECT Set the subject for this session. Environment variable
                      SUBJECTS_DIR should be set.
-v, --volume FILE Load a volume file. Can be a file name or a subdir in
                      the subject's directory specified with -s.
-f, --surface FILE Load a surface file Can be a file name or a subdir in
                      the subject's directory specified with -s.


   scuba -s bert -v T1

Specify bert as the main subject and load bert's T1 volume. This
mimics the tkmedit style of 'tkmedit subject volume'.

   scuba -v $SUBJECTS_DIR/bert/mri/T1

This does the same thing but specifies the volume explicitly.

   scuba -s bert -v T1 -f lh.white

This also loads a surface.

   scuba -v $SUBJECTS_DIR/bert/mri/T1 -f $SUBJECTS_DIR/bert/surf/lh.white

This does the same but specifies the files explicitly.

=== Menu Commands ===

You can also load data through the File menu once scuba is
loaded. Scuba, unlike tkmedit, does not need to load data to start
up. The file menu contains menu items for loading volumes, surfaces,
and labels (which get imported into ROIs).

=== Subjects Panel ===

You can load volumes and surfaces from subjects in your SUBJECTS_DIR
with the Subjects panel. When you run scuba, you will see a set of
buttons on the right side. Clicking these show the various control
panels. The Subjects panel is shown automatically. It scans your
SUBJECTS_DIR and puts all subjects and their volumes and surface in
pull-down menus. Select the subject name in the first menu, then
select a volume or surface and click the Load button next to it.

= Data Collections, Layers, and Views =

It helps to know how scuba creates views of data out of pieces of data.

Data collections are volumes or surfaces or other major data types and
its associated data, like ROIs. A data collection might be one volume
and a few ROIs, or just a volume. Creating a new ROI for a volume adds
it to the volume's data collection. Loading a new volume or surface
creates a new data collection.

A layer is rendering of a data collection with certain attributes. A
layer can draw a volume in grayscale or with a color table, using a
certain opacity, and with different brightness and contrast
settings. Two layers might draw the same data collection but with
different settings. Normally, there is a one-to-one correspondence
between data collections and layers, and they even have the same name.

A view is a collection of layers that are drawn, composited, to an
area in the scuba graphics window. A view has 10 draw levels, and a
layer can be set at each level. They are drawn from 0 - 9 with higher
numbers on top. For example, put a volume into level 0 and a surface
into level 1 so the surface will draw on top of the volume.

Views are always in RAS 'world' space. This is different from index
based viewers like tkmedit. Volumes are 'registered' into RAS space
based on the origin specified by the scanner. Therefore, when you load
up a volume, it may appear off-center in the view. (These RAS
coordinates correspond to the 'scanner coordinates' in tkmedit.)

= The Main Window =

The scuba window has a menu bar at the top, a row of toolbar buttons,
the main view on the left, the control panels on the right, an
information area below the main window, and a status bar at the

The toolbar contains buttons for selecting a tool, for setting the view
configuration or number of views in the window, and buttons for
setting the orientation of the current view.

== The Toolbar ==

The toolbar contains the following tools. You can also see the
settings available for each tool if you click on the Tools panel.

Navigation: For moving the view. Click and drag with button 1 to pan
the view around, button 2 to move perpendicularly to the view plane,
and button 3 to zoom in and out. Note that button 2 does not
necessarily change slices, as the view is in RAS space. More on this

Plane: The plane tool is for changing the slice plane of a view. You
must have two or more views in the window to use this tool. In a view,
click near or on a plane intersection line to affect that plane. The
intersection lines are color coded; note the corresponding color around
the view. Click and drag with button 1 to translate the plane in the
view. Click and drag with button 2 to rotate. Click with button 3 to
restore the plane to its normal rotation. The best way to learn about
this tool is to play with it in the 2x2 view configuration.

Cursor: This tool is for setting the cursor and markers. Click with
button 1 will set the cursor. The first time this is done, a new
column of info will appear in the information area in the window,
displaying the info at the cursor location. Note that by default the
views don't follow the cursor like tkmedit, but this is an option in
the View panel. Button 2 sets markers. (!! These are kind of useless
right now but will be fun later.)

Edit Volume: This tool is for editing volumes, mainly for editing segmentation volumes (a volume that is being displayed with an LUT). The Tools panel can be used to configure the size and shape of the brush as well what layer it's affecting. This panel also selects the new 'color' or value to 'paint' with.

Painting with button 2 will set the color and button 3 will set the value to 0. In the context of editing a segmentation volume, this will set the structure and erase it.

Edit ROI: This tool is for editing ROIs. Each volume may have multiple
ROIs. To select the one you are editing, select its name in the
pull-down menu in the Data panel. You can also make a new ROI there,
though one is created for you by default.

Button 2 selects voxels and button 3 deselects them. Note the brush
options in the Tools panel. Shift-button 2 will select-fill an area
based on the fill options in the Tools panel. Shift-button 3 will

Straight Path: Use this tool to draw paths to act as boundaries for
the fill tools (i.e. the select-fill tool). Click and drag button 1 to
draw a line. Click a line with button 2 and drag to move it, or with
button 3 to delete it.

Edge Line: This is like the straight line tool but it follows the
edges of the intensity values in the volume. The first time you use it
there may be a delay while scuba calculates the edges.

== View Configurations ==

These three buttons on the toolbar are used to set the number of views
in the window. Click the one that looks like a cross to create 4 views
in a 2x2 configuration. scuba will automatically copy the layer
settings into these three new views from your first view, and set them
to different orientations.

== View Orientations ==

These buttons set the view orientation for the current view (the
current view is the one with a green border drawn around it, and has
its name showing in the pull-down menu in the Views panel). Though the
buttons are labeled S, C, and H for sagittal, coronal, and horizontal,
depending on the orientation of the data, you may get different
views. These buttons really set the in-plane direction to x, y, and z,
respectively. Pressing one will also set the slice plane rotation to
its original position, orthogonal to the viewing plane.

== Navigation ==

Navigation can be done with the keyboard, the navigate tool, and with
ctrl-clicks that are usable when any tool is active.

To pan the view with the keyboard, use the arrow keys to move 1 mm in
RAS coordinates. Use the page up and page down keys to move into and
out of a view by the in-plane increment for that view (usually the
voxel size for the volume, see below). Use the minus and equal keys to
zoom out and in. Hold down the control key with any of these keys to
move by a factor of 10.

The navigate tool is described above.

Control clicks mimic tkmedit's style of navigation. Ctrl-button 1
zooms in and recenters around the point clicked. Ctrl-button 2 only
centers, and ctrl-button 3 zooms out and centers. These controls are
usable when any tool is active.

= Setting Up a View =

To make a view, load your data collections, configure your layers, and
then set the layers in the views. Scuba does some of this
automatically for you, for example you should normally not have to set
draw levels in views.

If you specified data on the command line, it may not be ordered like
you expect in the view. You can change the data collections in the
view draw level slots in the Views panel. Each draw level has a
pull-down menu in which you can select a layer. The layer name will be
the same as the data collection name by default.

The pull-down menu at the top of the Views panel shows the view you
are configuring. The two numbers are the column and row position of
the view, with the top left view being 0, 0. You can also see a view's
column and row by moving the mouse inside that view and looking at the
information area.

The Linked checkbox allows you to link views together so that certain
navigational changes made in one view apply to all of them. (!! This
is kind of useless right now.)

The Locked on Cursor checkbox allows you to force a view to stay
centered on the cursor, which is particularly useful in the 2x2 view
configuration to look at the same point in multiple orientations.

The Transform pull-down menu allows you to specify a viewing
transform. Note that this is applied to the view; it's not a data or
volume transform (this is in the Data panel) and it's not used to
change the slice plane (this is done with the plane tool).

Use the Copy Layers to Other Views button to copy the draw level
settings in this view to other visible views.

The In-plane key increment specifies how much the view changes when
the move in and out keys are used. Normally it is set to the smallest
in-plane voxel size of all the volumes in the view.

= Setting Up a Layer =

Use the Layers panel to set up the rendering of a data collection in a
layer. Select the layer to be configured in the pull-down menu at the
top of the panel. You can use the edit field beneath it to change the
label for this layer.

The opacity slider is available for all layers and controls the
opacity at which a layer is drawn. The rest of the controls in this
panel are similarly self-explanatory.

Use the Editable ROI checkbox to enable or disable ROI editing for
this layer. For example, you may have two volume layers, a hires and a
lowres volume, overlayed on each other, and may want to edit an ROI in
only one of them.

Note that different options will be available depending on what kind
of data collection this layer is rendering.

= Data Collections and ROIs =

The Data panel lets you configure a data collection. As in the other
panels, select the data collection in the pull-down menu at the top of
the panel.

There is pull-down menu for selecting a data transform. This can be
the talairach transform for this volume, or a registration transform
for functional data.

The ROIs for this data collection are also listed here. ROIs are
always associated with a data collection because they are in same
resolution as that data collection.

You select an ROI from the pull-down menu in the panel. You can edit
the ROIs name in the field under that. Each ROI can be 'free' or can
be a structure. If it is free, you can select its color with the
button near the bottom of the panel. If it's a structure, you can
choose a structure to assign to it from the list underneath. You
should also select an LUT from which to get the list of structures.

Use the Make New ROI button at the button to create a new ROI for this
data structure.

Keep in mind what the current ROI is. This is the one you will be
editing with the Edit ROI tool, and which ROI will be saved as a label
with the Save Label menu command.

= Transforms =

The Transforms panel is where you view and modify transforms. This
pool of transforms is used when specifying a view transform or a data

Load a transform with the command in the File menu or click on the
Make New Transform button. You can set the transform's name with the
edit field under the pull-down menu. To change its values, edit the
number fields. Note that after changing the value, it will become red,
signifying that you have to press return to commit the change. Then
the Set Values button will turn red, reminding you to click to button
to commit the changes and update all users of the transform.

You can click the Inverse button to invert the matrix. This
automatically commits the changes.

= LUTs =

The LUT panel is !! kind of useless right now.
  * [wiki:/GUI Introduction to the GUI]
  * [wiki:/Transforms Viewing a hi-res volume on a normal volume with a transform]
  * [wiki:/Segmentations Making a segmentation volume]

There are different guides here for different user tasks. Everybody should read the GUI guide first to get up to speed. After that, pick a guide that best suits what you're trying to do.

  • [wiki:/GUI Introduction to the GUI]
  • [wiki:/Transforms Viewing a hi-res volume on a normal volume with a transform]
  • [wiki:/Segmentations Making a segmentation volume]

ScubaGuide (last edited 2008-04-29 11:45:31 by localhost)