.. |command_key| unicode:: U+2318
.. |shift_key|   unicode:: U+21E7
.. |control_key| unicode:: U+2303
.. |alt_key|     unicode:: U+2325

.. |up_arrow|    unicode:: U+25B2
.. |down_arrow|  unicode:: U+25BC

.. |right_arrow| unicode:: U+21D2

.. |information_icon| image:: images/information_icon.png
.. |chainlink_icon|   image:: images/chainlink_icon.png
.. |camera_icon|      image:: images/camera_icon.png
.. |gear_icon|        image:: images/gear_icon.png
.. |spanner_icon|     image:: images/spanner_icon.png


.. _quick_start:

Quick start
===========


Help!
-----


If you get stuck:

 - Search through these help pages to see if your problem is discussed
   anywhere.

 - If you can't figure out how to do something, see if it is covered in the
   :ref:`How do i ... <quick_start_how_do_i>` section, below.

 - If something has gone wrong, check the :ref:`troubleshooting` page to
   see if you problem is covered there.


Most FSLeyes buttons and controls also have tooltips which contain useful
information, and which will pop up if your hover the mouse over a control
for a couple of seconds:


.. image:: images/quick_start_tooltip.png
   :align: center


The interface
-------------


When you first start FSLeyes, you will be presented with something that
looks like this:


.. image:: images/quick_start_interface_1.png
   :align: center


This is slightly boring, so let's load an image. Select the *File*
|right_arrow| *Add overlay from file* menu option, and choose a ``.nii.gz``
image to load.


Now things are a bit more interesting:


.. image:: images/quick_start_interface_2.png
   :align: center


Let's take a closer look at the components of the FSLeyes interface...


.. image:: images/quick_start_interface_overview.png
   :align: center


The view
^^^^^^^^


.. sidebar:: What is an *overlay*?
             :subtitle: And why aren't they just called *images* instead?

             An :ref:`overlay <overview_overlays>` is an image, or other data
             file, that you have loaded into FSLeyes.  While FSLeyes is first
             and foremost a NIFTI image viewer, the term *overlay* is used,
             instead of *image*, because FSLeyes supports other non-volumetric
             data types, and will hopefully support more in the future.


The view is where your overlays are displayed. By default, an
:ref:`orthographic view <ortho_lightbox_views_ortho>` is shown; you can also
select a :ref:`lightbox view <ortho_lightbox_views_lightbox>`, or some
:ref:`plot views <plot_views>`, from the *View* menu.


Let's stick with the orthographic view for now. It displays your overlay on
three *canvases*, along the three primary axes. For a NIFTI image which is
oriented acording to the MNI152 template, these canvases will correspond to
the sagittal, coronal, and axial planes.

You can interact with an ortho view in a number of ways. Use the mouse to
click, or click and drag, to change the current location. Hold down the
|command_key| key (OSX) or |control_key| key (Linux), and use your mouse wheel
to zoom in and out of a canvas.  You can also middle-click and drag, or hold
down the |alt_key| key and drag with the left mouse button, to pan around.


See the section on :ref:`ortho view interaction
<ortho_lightbox_views_ortho_interaction>` for more hints on working with an
ortho view.


.. sidebar:: Modifier keys

             Throughout this page, and the rest of the FSLeyes documentation,
             we will use the following symbols to represent keyboard modifiers
             keys:

             - |shift_key|:   Shift
             - |control_key|: Control
             - |command_key|: Command (on OSX; Control on other platforms)
             - |alt_key|:     Option (on OSX; Alt on other platforms)


The overlay list
^^^^^^^^^^^^^^^^


The :ref:`overlay list <ortho_lightbox_views_overlay_list>` displays a list of
all overlays that you have loaded. Amongst other things, this list allows you
to add and remove overlays, toggle overlay visibility, and change the overlay
display order.


The location panel
^^^^^^^^^^^^^^^^^^


The :ref:`location panel <ortho_lightbox_views_location_panel>` shows the
current display location, in terms of the currently selected overlay. It also
shows the overlay data value at the current location, for every loaded
overlay.



The toolbars
^^^^^^^^^^^^


The :ref:`overlay toolbar <overlays_overlay_display_toolbar>` allows you to
adjust display properties of the currently selected overlay. Pushing the
|gear_icon| button will open a dialog containing all of the overlay display
settings. Pushing the |information_icon| button opens a dialog containing
information about the overlay.


The :ref:`ortho toolbar <ortho_lightbox_views_ortho_toolbar>` allows you to
adjust the layout of the ortho view. For example, you can toggle each of the
canvases on and off, and switch between vertical, horizontal, or grid
layouts. Pushing the |spanner_icon| button will open a dialog containing all
of the ortho view settings.


.. _quick_start_how_do_i:

How do I ...
------------


Load an overlay?
^^^^^^^^^^^^^^^^

See :ref:`overlays_loading_an_overlay`.


Open another ortho/lightbox view?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The *View* menu allows you to open another view. You can open as many views as
you like.


Open/close control panels/toolbars?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The *Settings* menu contains a sub-menu for every open view, which allows you
to toggle the control panels and toolbars for that view, and perform a few
other tasks. For example, if you want to add an :ref:`atlas panel <atlases>`,
you would select the *Settings* |right_arrow| *Ortho view 1* |right_arrow|
*Atlas panel* menu option. See :ref:`overview_views_and_controls` for more
information.


Change the background colour?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


You can change the background and cursor colours via the :ref:`view settings
panel <ortho_lightbox_views_view_settings>` (the |spanner_icon| button on the
ortho toolbar).


Show/hide the cursor/anatomical labels?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


You can toggle the cursor and labels simultaneously via the + button on the
ortho toolbar, or toggle them independently via checkboxes in the :ref:`view
settings panel <ortho_lightbox_views_view_settings>` (the |spanner_icon|
button).


View images in neurological/radiological orientation?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


You can switch between a radiological or neurological display, in the
:ref:`view settings panel <ortho_lightbox_views_view_settings>` (the
|spanner_icon| button).


Take a screenshot?
^^^^^^^^^^^^^^^^^^


Click the |camera_icon| button on the ortho toolbar, or select the *Settings*
|right_arrow| *Ortho view 1* |right_arrow| *Take screenshot* menu item.


Link/unlink the display properties across multiple views?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


If you have more than one view open (e.g. an ortho view and a lightbox view),
and you want the overlay display settings to be the same across all views,
open the :ref:`view settings panel <ortho_lightbox_views_view_settings>` for
each view (via the toolbar |spanner_icon| button, or the *Settings*
|right_arrow| *<view name>* |right_arrow| *View settings panel* menu option),
and make sure that the *Link overlay display settings* box is checked or
unchecked.


Link the volumes on two or more 4D images?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


If you want to view the same volumes from two or more 4D NIFTI images, click
the |chainlink_icon| buttons, for each image, in the :ref:`overlay list
<ortho_lightbox_views_overlay_list>`.


Set up a positive/negative colour map for Z statistics?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


You can set up a negative colour map through the :ref:`overlay display panel
<overlays_overlay_display_panel>` (the |gear_icon| button on the :ref:`overlay
display toolbar <overlays_overlay_display_toolbar>`). See the section on
:ref:`volume display settings <overlays_volume>` for more details.


My image is tilted/oblique! How do I make it oriented/rectangular?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Open the :ref:`view settings panel <ortho_lightbox_views_view_settings>` (the
|spanner_icon| button) and set the *Display space* to the image which you want
oriented.


Edit a NIFTI image?
^^^^^^^^^^^^^^^^^^^


You can edit NIFTI image data from within an orthographic view. Switch to edit
mode via the *Settings* |right_arrow| *Ortho view* |right_arrow| *Edit mode*
menu option. This will open a new toolbar which contains editing
functionality. See the page on :ref:`editing images <editing_images>` for more
details.


Classify ICA components?
^^^^^^^^^^^^^^^^^^^^^^^^


Load your ``.ica`` directory (or the ``.ica/melodic_IC`` image file), then
open the melodic perspective (the *View* |right_arrow| *Perspectives*
|right_arrow| *MELODIC mode* menu option). See :ref:`ic_classification` for
more information.


Save the current view/control panel layout?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


You can save a layout at any time by defining a new :ref:`perspective
<overview_layout_and_perspectives>`: Choose the *View* |right_arrow|
*Perspectives* |right_arrow| *Save current perspective* menu item, and give
your layout a name. You can then restore it at any time by selecting it in the
*View* |right_arrow| *Perspectives* menu.
