Application Overview

Atlas Selection

After starting Cell Locator, the user is prompted with a dialog asking to choose which reference atlas to load.

Resetting Views

The Ctrl + w keyboard shortcut allows to reset views discarding current changes and asking to choose which reference atlas to load.

https://github.com/BICCN/cell-locator/releases/download/docs-resources/app_atlas_selection_dialog.png

Atlas Selection Startup Dialog

Automatic Atlas Selection

Starting the application specifying the --atlas-type command-line argument will skip the atlas selection startup dialog and directly load the requested altas. In this case, resetting the views also skips the atlas selection dialog.

User Interface

Lifecycle

  • New allows to create a new annotation file.

  • Save and Save As allow to save the current annotation(s) to file.

  • Load allows to load annotation(s) from file.

Warning

If the current annotation(s) have been modified, the user is asked if they should be saved to file before creating or loading new ones.

Annotation List

To to add, remove or duplicate an annotation, the user may click on the corresponding button:

  • Add Curve and Add Point allow to add an annotation.

  • Clone allows to duplicate the selected annotation.

  • Remove allows to delete the selected annotation.

To rename an annotation, the user may Double-Left-Click on its name.

To show or hide an annotation in both viewers, the user may click on the eye icon.

Note

  • A Curve annotation is expected to have multiple points and the corresponding type can be set using the Property Editor.

Interaction Modes

  • Explore mode allows to interact with the viewers without updating the orientation of the currently selected annotation.

  • Edit mode allows to update the selected annotation.

    • Position and size can be updated in the 2D Viewer.

    • Orientation can be updated in the 3D Viewer by using the reformat widget or by setting specific angles.

  • Place mode allows to add point(s) to the currently selected annotation by clicking one the slice displayed in the 2D Viewer.

https://github.com/BICCN/cell-locator/releases/download/docs-resources/app_interaction_mode.png

2D Viewer

The 2D viewer (or slice viewer) allows to create or edit annotations on the viewing plane. The slice orientation allows to change the reference from which row, pitch and yaw angles are set in the 3D viewer.

https://github.com/BICCN/cell-locator/releases/download/docs-resources/app_2dviewer.png

  • Slice offset slider allows slicing through the atlas reference volume. Step size is set in the Property Editor.

  • Adjust field of view centers the slice viewer’s field of view to match the extent of the atlas reference volume.

  • Slice orientation allows to choose the orientation of the slice in the 2D and 3D Viewer.

  • Contrast slider allows to adjust the grayscale background contrast associated with the atlas reference volume.

  • Reset contrast allows to reset the grayscale background contrast associated with the atlas reference volume

3D Viewer

The 3D viewer provides an interface to update the slice viewer plane orientation.

https://github.com/BICCN/cell-locator/releases/download/docs-resources/app_3dviewer.png

  • Raw, Pitch and Yaw sliders and input boxes allow to set the 2D Viewer plane angles relative to the selected slice orientation (Axial, Coronal or Sagittal).

  • Apply allows to update the slice orientaton based on the set angles.

  • Reset allows to reset the angles to match the slice orientation selected in the 2D Viewer.

  • Reformat widget allows to update the slice orientation.

Property Editor

  • Slice Step Size configures how the 2D Viewer slicer offset may be adjusted.

  • Annotation Thickess updates the width of selected Curve annotation.

  • Annotation Type updates how the annotation is represented in both viewers.

Numeric Inputs

After clicking in either the Slice Step Size or Annotation Thickess spin box, its value may be updated using a “large” step as described in the Numeric Inputs keyboard shortcuts.

Status Bar

  • Ontology Selector allows to select between None, Structure and Layer (only available for the CFF atlas).

  • Text about what is visible at the current mouse pointer position.

The status bar text is formatted as

x y z | <path> (<label index>)

where:

  • x y z corresponds to the world coordinates (RAS).

  • <path> is formatted as > structure 1 > structure 2 > ... (or > layer 1 > layer 2 > ...).

  • <label index> corresponds to the value in the annotation volume.

Ontology

Example of text

structure

layer

Keyboard and Mouse Shortcuts

On macOS use the Command key (⌘) instead of the Control (Ctrl) key

General

Key

Effect

Ctrl + n

Create a new annotation

Ctrl + s

Save current annotation(s)

Ctrl + o

Load annotation(s) from file

Ctrl + w

Reset views discarding current changes

f

Increment Slice offset

b

Decrement Slice offset

r

Adjust field of view to match the extent of the atlas

The user will be prompted with a save dialog before overwriting unsaved changes.

2D Viewer - Zoom and Pan

These interactions are enabled only in Explore and Edit mode.

Interface Device

Zoom

Pan

3-button mouse

Vertical drag Right-Click

Drag Middle-Click

2-button mouse

Vertical drag Right-Click

Drag Shift + Left-Click

1-button mouse

Vertical drag Ctrl + Left-Click

Drag Shift + Left-Click

Trackpad

Vertical drag two fingers

Drag Shift + Left-Click

2D Viewer - Annotation

These interactions are enabled only in Edit and Place modes.

Key or mouse operation

Effect

Left-Click on annotation line

Add annotation point

Right-Click on point then Delete

Delete currently selected annotation point

Right-Click on point then Interaction

Show/hide the interaction widget

Ctrl + Left-Click on annotation line

Insert annotation point

Drag Alt + Left-Click on annotation line

Rotate annotation

Drag Alt + Right-Click on annotation line

Scale annotation

Drag Middle-Click on annotation line

Translate annotation
https://github.com/BICCN/cell-locator/releases/download/docs-resources/app_2dviewer_point_right_click_context_menu.png

Annotation point right-click context menu.

Numeric Inputs

Left/Right keys increment by 1, and PgUp/PgDn keys increment by a contextual “large” step.

Large step for angle inputs is 5° and for distance inputs is 10mm. The Slice Offset steps in multiples of the Slice Step Size.

Annotation List

Action

Effect

Double-Left-Click annotation

Edit annotation name

Left-Click on eye icon

Show/hide annotation

Command-line arguments

Cell Locator supports the same CLI arguments as 3D Slicer, as well as the following:

General options

--annotation-file <path>

Path to an existing annotation file to be immediately loaded.

--reference-view <view>

Initial slice position. View may be one of Axial, Coronal, Saggital. Default value is Coronal

--view-angle <angle>

View angle in degrees; specifies an angle from –reference-view.

--atlas-type <type>

The atlas type to load. Type may be one of ccf, mni. If not provided, prompt user before startup.

LIMS options

See LIMS Integration for LIMS API documentation.

--lims-specimen-id <id>

LIMS specimen id to retrieve and load.

--lims-specimen-kind <kind>

LIMS specimen kind to load or save. Default is 'IVSCC cell locations'.

--lims-base-url <url>

LIMS base url.