Back to the ScubaGuide

Starting Up

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 surfaces.

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

$ scuba --help

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

Options: -s, --subject SUBJECT Set the subject for this session. Environment variable

-v, --volume FILE Load a volume file. Can be a file name or a subdir in

-f, --surface FILE Load a surface file Can be a file name or a subdir in

Examples:

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

This does the same thing but specifies the volume explicitly.

This also loads a surface.

This does the same but specifies the files explicitly.

There are also other command line options - check the scuba usage page for details.

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 bottom.

Most control panels allow you to configure settings for an item, such as a layer, view, tool, or data collection. The items you can configure are listed in a pull-down menu at the top of the panel; for example, in the Layers panel, the pull-down menu contains a list of Layers. Make sure you select the item you wish to configure properly.

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.

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 later.

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 deselect-fill.

Straight Path

Use this tool to draw paths to act as boundaries for the fill tools (i.e. the select-fill tool). Click with button 1 to create vertices in the path. Click with button 2 to finish creating a path, and with button 3 to finish the path but connect it to the first vertex. When you're not creating a path, you may also click and drag with button 2 to move a path, or click on it with button 3 to delete it.

Edge Path

This is like the Straight Path 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 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 re-centers 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.

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.

Tools

As you select different tools, you can configure them in the Tools panel. Some tools don't have options. Note that some tools must target a layer, such as editing tools, while other tools affect the entire view, such as the Navigation tool. If an editing tool appears not to be doing anything, make sure the Target Layer pull-down menu is set properly.

Brush Options

These options show up for the Voxel Editing and ROI Editing tools. The brush shape can be set to Voxel, Circle or Square. In the Voxel setting, the brush will only affect a single voxel of the target layer. In Circle or Square mode, it will be a circle or square of the radius set in the slider below, in mm. The "Only brush zero values" values makes the brush only affect voxels whose values are zero. This is helpful for editing segmentations when you only want to affect unlabeled voxels.

Fill Options

These options show up for the Voxel Editing and ROI Editing tools. These tools has a fill function (shift-middle click and shift-right click) that is affected by these settings. When you start a fill, the tool will operate on adjacent voxels based on source data. You must specify a Source Data from which the fill tool will base its comparisons. For example, if you set the Source Data to an anatomical volume and Target Layer to a segmentation volume, you can fill the segmentation volume based on voxel values in the anatomical volume.

You can have the fill operation stop at other ROIs (useful only for the ROI Editing fill, in which case it will stop when it encounters ROIs that aren't the current one) or at paths. The fuzziness affects how similar an adjacent voxel must be to the seed voxel or current voxel for the fill operation to continue there. This fuzziness can also have a type, Seed or Gradient. Seed fuzziness compares the adjacent voxel value to the seed voxel (the one you initially clicked to start the fill) and Gradient fuzziness compares the adjacent voxel to the current one being filled. When fuzziness is set to 0, no comparison will be made.

The fill can also operate in 3D. This is a nice way to find 3D areas, but it's easy to let the fill go out of control. To this end, you may set a "Max Distance" (in mm) to limit the fill.

The "Only fill zero values" option is similar to the brush option in that it only sets voxels whose values are zero.

Voxel Editing Options

This only appears for the Voxel Editing tool. It is used to set the brush value. Note that when brushing into a segmentation volume, you can use the LUT to get a list of structure names from which to get a new value.

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 transform.

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.

If the transform you're using is a registration, you may need to specify the source and destination volumes. If this is the case, click the "Treat as registration" button and select the fixed volume as the source and the movable volume as the destination. Due to contextual confusion, you may need to 'play around' with this to get it to work; if the registration appears to be incorrect, try switching the source and destination volumes. Be sure that you have specified that the destination volume uses this transform in the Data panel, and that the source volume uses no transform.

LUTs

The LUT panel is !! kind of useless right now.

ScubaGuide/GUI (last edited 2008-04-29 11:45:15 by localhost)