.. _rasterroi_top:

Draw Raster ROIs
================

.. only:: html

   .. sidebar:: Tutorials & Sample Data

      Watch on YouTube: |br|
      `Tutorial 3: Raster ROIs <https://youtu.be/LBfPI0H0hYY>`_ |br|
      `Tutorial 5: Advanced Raster ROIs <https://youtu.be/IpkbeEFrVps>`_ |br|

      :download:`Tut3data.zip (6.5MB) <https://www.firevoxel.org/im/Tut3data.zip>`
      :download:`Tut5data.zip (0.3MB) <https://www.firevoxel.org/im/Tut5data.zip>`

.. contents::
   :depth: 1
   :local:
   :backlinks: top

Region of interest (ROI) is a binary layer, or mask, in which each voxel
takes values 1 or 0. ROI voxels that have the value of 1 have attributes
of *foreground color* and *transparency* (alpha value). Voxels that have
the value of 0 are always completely transparent, regardless of the
transparency value of the entire ROI layer. In FireVoxel, ROI layers are
treated as 3D or 4D raster images.

Raster ROIs may be created manually or as a result of various commands.

.. _paintbrush_create_roi:

Drawing and editing ROIs with Paintbrush tool
---------------------------------------------

Raster ROIs can be drawn manually using the paintbrush tool. Drawing is
done on the active ROI layer. If there are no visible ROI layers (i.e.,
the document has ROI layers, but they are unmarked), a new ROI layer is
created by default and the ROI is drawn on that layer. The ROI layer has
the same matrix dimensions and voxel size as the underlying base image.

   .. _fig_paintbrush_animation:
   .. figure:: ../images/roi_paintbrush.*
      :alt: Paintbrush in Action
      :align: center
      :figclass: align-center

      Paintbrush tool for drawing and editing raster ROIs.

To draw an ROI, press and hold down Ctrl key and click and hold down the
*left mouse button*. The cursor turns into a green ring filled with the
ROI color (at 20% transparency), the paintbrush. Move the mouse to paint
voxels that need to be included in the ROI. Any voxels touched by the
green circle will be painted the ROI color (assigned the values of 1).
Release the mouse button and Ctrl key to finish
(:numref:`fig_paintbrush_animation`).

.. _paintbrush_erase:

To erase voxels from an ROI, hold down Ctrl key and click and hold down
the *right mouse button*. The cursor turns into a red ring (without
color inside), the eraser brush. Move the cursor to erase voxels. Any
voxels touched by the eraser will be returned to zero state and become
transparent. Release the mouse button (and Ctrl key) to finish.

Manually drawn ROIs do not need to be contiguous and consist of areas
drawn on several different slices.

.. _paintbrush_size:

Adjust paintbrush size
~~~~~~~~~~~~~~~~~~~~~~

While holding down Ctrl key, scroll the mouse wheel forward and backward
to increase or decrease the diameter of the paintbrush/eraser.

.. _paintbrush_settings:

Raster Paintbrush properties
----------------------------

The paintbrush properties panel (:numref:`fig_paintbrush_panel`)
can be accessed by clicking |paintbrush|
icon on the main toolbar. The panel must be closed before the paintbrush
can be used. The paintbrush settings are retained for one session.
Closing and reopening FireVoxel restores the default settings.

   .. _fig_paintbrush_panel:
   .. figure:: ../images/roi_paintbrush_panel.png
      :alt: Paintbrush Properties Panel
      :align: center
      :figclass: align-center

      Paintbrush properties panel.

The top portion marked **Paint/Erase** controls the grayscale value of
the brush/eraser (and size). This option can be used for drawing on
integer layers (images). It does not affect the paintbrush on ROI
layers.

By default, the brush grayscale value is set to white (Signal = 255 and
the eraser to black (Signal = 0)). Changing these values allows painting
and erasing voxels with other grayscale values. The grayscale value can be
entered into the text box labeled **Signal** or by clicking to the left
or right of the circle in increments of 1. Clicking the square field
above and below the central circle increases and decreases the brush
radius by 0.25 mm.

**Paintbrush allowed on** **Integer Volumes/ROIs/Real Volumes**
checkboxes control the types of layers the paintbrush is allowed to
change. By default, the paintbrush is allowed only on ROI layers. If
**Integer Volumes** box is checked, the brush can on paint image layers
and may alter the base images, which is often undesirable. Users should
exercise care when using this option.

**Radius (mm)** box sets the size of the paintbrush to a specified value
(2 mm by default). This allows the user to control the paintbrush/eraser
size more precisely than adjusting it by scrolling the mouse wheel.
Entering the radius of 0 sets the brush size equal to 1 voxel.

**Constrain by lower ROI layer** – :red:`ADD DETAILS`.

**Use 3D** checkbox when checked makes the paintbrush a sphere of the
set radius. By default, this box is unchecked, and the ROIs are drawn on
one slice at a time.

**Modify all timepoints** checkbox extends the ROI to all frames in a
dynamic experiment. This results in a 4D ROI. The box is unchecked by
default.

**SmartZoom** checkbox – The box is unchecked by default. :red:`ADD DETAILS`.
|top|

.. |paintbrush| image:: ../images/toolbar_paintbrush_icon.png