Analysis operators
==================

Label operators
---------------

clean-borders [-l]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This operator removes the image contents touching the borders. This is obtained by subtracting from the input image its morphological reconstruction from the border. The operator can be applied to both intensity and label images; however, its typical application is the removal of segmented objects that intersect the image border.

The ``-l`` option must be used when processing label images.

click-select [-d max-distance] <positions.vx>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This operator selects labels in the input image based on specified positions. The algorithm works by determining for each position the closest label, i.e. the label having the pixel/voxel closest to the specified position. Proximity is measured using Euclidean distance, taking into account the spatial calibration of the image.

The file ``<positions.vx>`` contains the positions to be used for the selection, following the ``sviewer`` in-house shape file format. The positions should be defined in the physical space of the image.

The ``-d`` option allows to set a maximum distance, above which labels are simply ignored.

click-replace [-d max-distance] <positions.vx> <new-value>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This operator replace labels in the input image based on specified positions. The algorithm works by determining for each position the closest label, i.e. the label having the pixel/voxel closest to the specified position, and replaces this label by a new value. Proximity is measured using Euclidean distance, taking into account the spatial calibration of the image.

The file ``<positions.vx>`` contains the positions to be used for the selection, following the ``sviewer`` in-house shape file format. The positions should be defined in the physical space of the image. The parameter <new-value> specifies the value to assign to the selected labels.

The ``-d`` option allows to set a maximum distance, above which labels are simply ignored.

label-boundaries [-a]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This operator computes the boundaries between labels in an image. By default, the output is a binary image of the boundaries. If the ``-a`` option is specified, the boundaries are overlaid to the labels of the input image.

.. figure:: ../../include/root-label-boundaries.png
   :width: 75.0%

   Computing boundaries between labels with ``label-boundaries``.

label-defragmentation [-n 4,6|8,26]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator takes as input a label image in which each label may appear as several connected components. The operator retains the largest component for each label and removes all the other ones. The discarded components are removed by filling the holes they make in the largest components of other labels.

The connectivity used to define connected sets is set with the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option.

replace largest|<label>[,<label2>,...,<labelN>] <value>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This operator replaces one or several label values in an image by the specified ``value``. Several values to be replaced can be specified using a comma-separated list of values. The ’\ ``-``\ ’ character can be used to specify label ranges in the list. For example:

::

   bip replace 17,19-21,largest,37 0 image.tif

replaces all occurrences of labels 17, 19, 20, 21, 37 plus the most represented label by 0.

The keyword ``largest`` can be used anywhere in the list to refer to the label that is the most represented in the image. Remind that 0 is not considered as a label value, which implies that the background cannot be selected as the largest label.

select [-r <range>] largest|max|<label>[,<label2>,...,<labelN>]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator selects one or several labels in an image. All values not appearing in the specified list are set to 0. The values of the listed labels are left unchanged.

The option ``-r`` can be used to set the range of neighbours to be included in the selection. For example, specifying ``-r 1`` also includes in the selection all the immediate neighbours of the specified labels. Only first-order neighbourhood is supported in the current implementation.

.. figure:: ../../include/cpm-select.png
   :width: 75.0%

   Selection of labels and of their immediate neighbours.

The keyword ``max`` can be used anywhere in the list to refer to the label with the largest value in the image.

Similarly, the keyword ``largest`` can be used anywhere in the list to refer to the label that is the most represented in the image. Remind that 0 is not considered as a label value, which implies that the background cannot be selected as the largest label.

To select the background of a label image (i.e., to obtain a binary mask of the background alone), one should use for example the following pipeline:

::

   bip pipeline -e "threshold 1 | invert auto" image.tif

select-fringe
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator selects the labels located at the fringes in a segmented image. A label is a fringe label if the graph of its neighbours is not cyclic. Note that this is not systematically the same as outer labels (labels having contacts with the background). Outer labels are not necessarily fringe labels. Conversely, fringe labels will generally be outer labels, but there are rare configurations where they may not.

In practice, users will probably need the ``select-outer`` operator for most applications. The ``select-fringe`` operator will be particularly useful to select the outer rim of a cell layer in 3D.

.. figure:: ../../include/select-fringe.png

   Selection of fringe labels in 2 and 3 dimensions.

select-inner
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator selects the inner labels in a segmentation. A label is an inner label if it is not in contact with the image background. The set of obtained labels is the complement of those obtained with operator ``select-outer``.

select-outer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator selects the outer labels in a segmentation. A label is an outer label if it contacts the image background. Note that this is not systematically the same as fringe labels. Outer labels are not necessarily fringe labels. Conversely, fringe labels will generally be outer labels, but there are rare configurations where they may not.

.. figure:: ../../include/figure-cpm-select-outer.png
   :width: 50.0%

shuffle-labels
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator randomly shuffles the label values in an image. The background (label value 0) is left unchanged. This operator is for example useful to modify the contrast at the boundaries between the labeled objects (both when displaying labels as gray levels or as false colors).

.. figure:: ../../include/figure-root-shuffle-labels.png
   :width: 50.0%

split [-h <tolerance>]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This operator separates objects that are touching each other in a binary image. The optional tolerance parameter can be set to control the degree of separation (default tolerance value is 0.5). The higher the tolerance, the less the objects are split (:numref:`fig:split`).

.. figure:: ../../include/figure-beans-split.png
   :name: fig:split
   :width: 75.0%

   Separating touching objects using the ``split`` operator.

The ``split`` operator can also process label images of segmented objects. In this case, the original labelling is lost because a thresholding of values above 0 is applied as a first step in this operator.

swap-labels <list1> <list2>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator swaps values in an image. The values to swap are specified by two lists of comma-separated values. The two lists must have the same size. All image positions having a value from ``list1`` are assigned the corresponding value in ``list2``, and reciprocally.

zmap [-l]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator performs a Z-front detection in the input 3D label image. Z-front detection is a 2D projection of the 3D image: at each XY position, it determines and retains the first Z position with a non-null value. Used in conjunction with the reverse operator ``izmap``, this operator is typically used to extract the uppermost layer in a label image.

If the ``-l`` option is set (“label mode”), then the operator retains the first encountered label rather than its Z position.

Distance maps
-------------

chamfer-distance <foreground>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator computes an integer-valued map of the approximate distance between each image position and the closest position with value ``foreground``. The input image is not necessarily binary, as every non-foreground position will be considered as background. The implementation follows algorithms given by Borgefors :cite:p:`Borgefors1986,Borgefors1996`.

This operator is provided for historical and pedagogical reasons. Users will in general opt instead for the Euclidean distance operator, which is very efficient and provides exact distance values.

euclidean-distance [--physical] <foreground>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator computes a real-valued map of the exact Euclidean distance between each image position and the closest position with value ``foreground``. The input image is not necessarily binary, as every non-foreground position will be considered as background. The implementation is based on Felzenszwalb and Huttenlocher’s algorithm :cite:p:`Felzenszwalb2012` that we have modified to take into account the spatial calibration of the image.

By default, the distance is computed in pixels (2D) or voxels (3D). If the ``--physical`` option is set, the distance is instead computed in physical units, taking into account the spatial calibration of the image and its anisotropy, if any.

The numerical type of the output image is 32-bit floating point.

.. figure:: ../../include/figure-nuclei-euclidean-distance.png
   :width: 75.0%

Measurements
------------

intensity-analysis [-b <boundary>] [-p <parameters>] [-o <output.tsv>] [-s] <intensity-path>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator performs intensity measurements on objects in a segmented image. Each label in the input image defines an object. In practice, an object will generally correspond to a unique connect component in the input label image, but BIP imposes no restriction on the number of components per object.

For each input image, the measurements are performed on the paired image specified by ``intensity-path``. This path can be either a path to a single filename or a directory name. In the second case, BIP will look in the specified directory for a file matching the input filename. Modifiers can be used to pair images with systematic differences in their filenames. See :ref:`sec-pairing-images` to learn more about pairing images.

**Example 1.** Assume we have the following organization of project files, with separate directories for intensities and labels, but identical filenames for each image pair:

::

   project/
     raw/
       image1.tif
       image2.tif
       image3.tif
     labels/
       image1.tif
       image2.tif
       image3.tif
     results/

Then, from the ``results`` directory, intensity analysis can be invoked as:

::

   bip intensity-analysis ../raw ../labels/*.tif

**Example 2.** Assume we have instead different filenames for intensities and labels:

::

   project/
     raw/
       image1.tif
       image2.tif
       image3.tif
     labels/
       labels1.tif
       labels2.tif
       labels3.tif
     results/

Then intensity analysis would be invoked using a pattern substitution:

::

   bip intensity-analysis ../raw:s/labels/image/ ../labels/*.tif

**Explicit boundary value.**
By default, it is assumed there is no specific label for the boundaries between objects. This corresponds to the situation where different object labels may be in contact. If a specific label has been used to label boundaries at the segmentation stage (as done for example when computing the dams in a watershed transform), then this value must be specified using the ``-b`` option.

**Parameter selection.**
By default, BIP performs measurements for all available intensity parameters (:numref:`tab-intensity-parameters`). This behaviour can be overridden by using the ``-p`` option to specify a comma-separated list of desired parameters. For example, the following call will only measure the average and median intensity within each object:

::

   bip intensity-analyis -p mean,median ../raw ../labels/*.tif


.. table:: Intensity measurements available in BIP.
   :name: tab-intensity-parameters

   ========== ================================================
   Parameter  Definition
   ========== ================================================
   ``sum``    Sum of intensity values
   ``mean``   Average of intensity values
   ``median`` Median of intensity values
   ``min``    Minimum intensity value
   ``max``    Maximum intensity value
   ``stddev`` Standard-deviation of intensity values
   ``mad``    Median of absolute deviation of intensity values
   ========== ================================================

**Output files**. On output, BIP writes a ``intensity-analysis.tsv`` text file, which obeys the TSV format (columns of measured values separated by tabulations). This file can be loaded in software such as Excel, LibreOffice Calc, gnuplot, or R for downstream statistical analysis and graphical plotting. The name of the output file can be changed using the ``-o`` option.

If the ``-s`` option (“split”) is set, BIP will instead save the measurements in a different file for each input image. The output files are named from the basenames of the input files (``<basename>.tsv``). In this mode, the ``-o`` option is ignored.

region-analysis [-p <parameters>][-b <boundary-value>]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator performs quantitative measurements on objects in a labelled image. Each label in the input image is considered as defining an object. In practice, an object will generally correspond to a unique connected component in the input label image, but BIP imposes no restriction on the number of components per object.

By default, it is assumed there is no specific label for the boundaries between objects. This corresponds to the situation when different object labels may be in contact. If a specific label has been used to label boundaries at the segmentation stage (as done for example when computing the dams in a watershed transform), then this value must be specified using the ``-b`` option.

By default, BIP performs measurements for a large number of parameters. This behaviour can be overridden by using the ``-p`` option to specify a comma-separated list of desired parameters. For example, the following call will only measure the number of voxels, the volume and the sphericity of objects in a 3D image:

::

   bip region-analyis -p count,volume,sphericity image3D.tif

Available parameters in BIP fall into one out of three categories. Most parameters are simple parameters, for which a single numerical value is obtained (e.g., ``area``). :numref:`tab-simple-parameters` lists the available simple parameters. Some other parameters are vector parameters, which provide several values corresponding to as many simple parameters that are components of a vector (such as a position or a direction). One example is the ``centroid`` parameter, which provides on output 2 or 3 parameters (``centroid-x``, ``centroid-y`` and ``centroid-z``), corresponding to the coordinates of the average position of an object. Lastly, group parameters are short-cuts for specifying groups of related simple or vector parameters, without having to specify each parameter individually. For example, asking for the ``size`` parameter triggers the measurements of the ``count``, ``area``, and ``volume`` parameters. :numref:`tab-composite-parameters` lists the available vector and group parameters.


.. table:: Simple parameters available in BIP. Dimension indicates in which dimension(s) each parameter is defined. Parameters not defined for a given dimension will appear as ``NaN`` in the measurement file.
   :name: tab-simple-parameters

   +----------------------------+----------------------------+-----------+
   | Parameter                  | Definition                 | Dimension |
   +============================+============================+===========+
   |                            |                            |           |
   +----------------------------+----------------------------+-----------+
   | *Size measurements*        |                            |           |
   +----------------------------+----------------------------+-----------+
   | ``area``                   | Object area in physical    | 2D        |
   |                            | units                      |           |
   +----------------------------+----------------------------+-----------+
   | ``count``                  | Number of pixels (2D) or   | 2D,3D     |
   |                            | voxels (3D)                |           |
   +----------------------------+----------------------------+-----------+
   | ``volume``                 | Object volume in physical  | 3D        |
   |                            | units                      |           |
   +----------------------------+----------------------------+-----------+
   | ``equiv-radius``           | Radius of disk (or sphere) | 2D,3D     |
   |                            | of same area (volume)      |           |
   +----------------------------+----------------------------+-----------+
   | ``major-radius``           | Radius along the first     | 2D,3D     |
   |                            | principal axis             |           |
   +----------------------------+----------------------------+-----------+
   | ``medium-radius``          | Radius along the 2nd       | 3D        |
   |                            | principal axis             |           |
   +----------------------------+----------------------------+-----------+
   | ``minor-radius``           | Radius along the smallest  | 2D,3D     |
   |                            | principal axis             |           |
   +----------------------------+----------------------------+-----------+
   | ``gyration-radius``        | Root mean squared distance | 2D,3D     |
   |                            | to object centroid         |           |
   +----------------------------+----------------------------+-----------+
   | ``perimeter``              | Length of the object       | 2D        |
   |                            | boundary                   |           |
   +----------------------------+----------------------------+-----------+
   | ``surface-area``           | Surface area of the object | 3D        |
   |                            | boundary                   |           |
   +----------------------------+----------------------------+-----------+
   | ``box-diagonal``           | Diagonal of the            | 2D,3D     |
   |                            | axis-aligned bounding box  |           |
   +----------------------------+----------------------------+-----------+
   |                            |                            |           |
   +----------------------------+----------------------------+-----------+
   | *Position measurements*    |                            |           |
   +----------------------------+----------------------------+-----------+
   | ``centroid-x``             | Centroid: x-coordinate     | 2D,3D     |
   +----------------------------+----------------------------+-----------+
   | ``centroid-y``             | Centroid: y-coordinate     | 2D,3D     |
   +----------------------------+----------------------------+-----------+
   | ``centroid-z``             | Centroid: z-coordinate     | 3D        |
   +----------------------------+----------------------------+-----------+
   | ``box-x1``                 | Axis-aligned bounding box: | 2D,3D     |
   |                            | x-coordinate of 1st corner |           |
   +----------------------------+----------------------------+-----------+
   | ``box-y1``                 | Axis-aligned bounding box: | 2D,3D     |
   |                            | y-coordinate of 1st corner |           |
   +----------------------------+----------------------------+-----------+
   | ``box-z1``                 | Axis-aligned bounding box: | 3D        |
   |                            | z-coordinate of 1st corner |           |
   +----------------------------+----------------------------+-----------+
   | ``box-x2``                 | Axis-aligned bounding box: | 2D,3D     |
   |                            | x-coordinate of 2nd corner |           |
   +----------------------------+----------------------------+-----------+
   | ``box-y2``                 | Axis-aligned bounding box: | 2D,3D     |
   |                            | y-coordinate of 2nd corner |           |
   +----------------------------+----------------------------+-----------+
   | ``box-z2``                 | Axis-aligned bounding box: | 3D        |
   |                            | z-coordinate of 2nd corner |           |
   +----------------------------+----------------------------+-----------+
   |                            |                            |           |
   +----------------------------+----------------------------+-----------+
   | *Orientation measurements* |                            |           |
   +----------------------------+----------------------------+-----------+
   | ``major-vector-x``         | Largest principal axis:    | 2D,3D     |
   |                            | x-coordinate               |           |
   +----------------------------+----------------------------+-----------+
   | ``major-vector-y``         | Largest principal axis:    | 2D,3D     |
   |                            | y-coordinate               |           |
   +----------------------------+----------------------------+-----------+
   | ``major-vector-z``         | Largest principal axis:    | 3D        |
   |                            | z-coordinate               |           |
   +----------------------------+----------------------------+-----------+
   | ``minor-vector-x``         | Smallest principal axis:   | 2D,3D     |
   |                            | x-coordinate               |           |
   +----------------------------+----------------------------+-----------+
   | ``minor-vector-y``         | Smallest principal axis:   | 2D,3D     |
   |                            | y-coordinate               |           |
   +----------------------------+----------------------------+-----------+
   | ``minor-vector-z``         | Smallest principal axis:   | 3D        |
   |                            | z-coordinate               |           |
   +----------------------------+----------------------------+-----------+
   | ``medium-vector-x``        | Intermediate principal     | 3D        |
   |                            | axis: x-coordinate         |           |
   +----------------------------+----------------------------+-----------+
   | ``medium-vector-y``        | Intermediate principal     | 3D        |
   |                            | axis: y-coordinate         |           |
   +----------------------------+----------------------------+-----------+
   | ``medium-vector-z``        | Intermediate principal     | 3D        |
   |                            | axis: z-coordinate         |           |
   +----------------------------+----------------------------+-----------+
   |                            |                            |           |
   +----------------------------+----------------------------+-----------+
   | *Shape measurements*       |                            |           |
   +----------------------------+----------------------------+-----------+
   | ``elongation``             | Length-ratio between       | 2D,3D     |
   |                            | largest and intermediate   |           |
   |                            | axes                       |           |
   +----------------------------+----------------------------+-----------+
   | ``flatness``               | Length-ratio between       | 3D        |
   |                            | intermediate and smallest  |           |
   |                            | axes                       |           |
   +----------------------------+----------------------------+-----------+
   | ``circularity``            | Matching with a disk       | 2D        |
   |                            | having the same area       |           |
   +----------------------------+----------------------------+-----------+
   | ``sphericity``             | Matching with a sphere     | 3D        |
   |                            | having the same volume     |           |
   +----------------------------+----------------------------+-----------+
   | ``globularity``            | (Experimental)             | 2D,3D     |
   +----------------------------+----------------------------+-----------+
   |                            |                            |           |
   +----------------------------+----------------------------+-----------+
   | *Topological measurements* |                            |           |
   +----------------------------+----------------------------+-----------+
   | ``degree``                 | Number of neighbouring     | 2D,3D     |
   |                            | labels                     |           |
   +----------------------------+----------------------------+-----------+
   | ``outer``                  | Indicator of contact with  | 2D,3D     |
   |                            | the background             |           |
   +----------------------------+----------------------------+-----------+
   | ``fringe``                 | Indicator of localization  | 2D,3D     |
   |                            | at the periphery of the    |           |
   |                            | tissue                     |           |
   +----------------------------+----------------------------+-----------+
   | ``layer``                  | Number of the containing   | 2D,3D     |
   |                            | tissue layer               |           |
   +----------------------------+----------------------------+-----------+


.. table:: Vector and meta-parameters available in BIP.
   :name: tab-composite-parameters

   +--------------+---------------------------+---------------------------+
   | Parameter    | Definition                | Associated simple         |
   |              |                           | parameters                |
   +==============+===========================+===========================+
   | ``centroid`` | Object average position   | ``centroid-x``,           |
   |              |                           | ``centroid-y``,           |
   |              |                           | ``centroid-z``            |
   +--------------+---------------------------+---------------------------+
   | ``size``     | Object size               | ``count``, ``area``,      |
   |              |                           | ``volume``                |
   +--------------+---------------------------+---------------------------+
   | ``box``      | Axis-aligned bounding box | ``box-x1``, ``box-y1``,   |
   |              |                           | ``box-z1``,               |
   |              |                           | ``box-x2``, ``box-y2``,   |
   |              |                           | ``box-z2``,               |
   |              |                           | ``box-diagonal``          |
   +--------------+---------------------------+---------------------------+

On output, BIP writes a ``region-analysis.tsv`` file, which obeys a TSV format (columns of measured values separated by tabulations). This file can be loaded in software such as Excel, LibreOffice Calc, gnuplot, or R for downstream statistical analysis and graphical plotting.

As a for most BIP operators, both 2D and 3D images can be passed upon a same call to the ``region-analysis`` operator. Some parameters are defined in both 2 and 3 dimensions (such as ``count``, the number of times the label is observed in the image), while others are specific to either the 2D (such as ``area``) or the 3D case (such as ``volume``). BIP reports a ``NaN`` (not-a-number) value in the output file for undefined parameters.

Images with multiple channels and/or multiple timepoints can be passed to the operator, in which case labelled regions will be quantified in the different channels and time frames. A ``channel`` column is added in the output file in case the input image contains several channels. Similarly, a ``timepoint`` column is added in the output file in case the input image contains several timepoints. Images with different numbers of channels or timepoints can be mixed during a same call.

Export operators
----------------

export-bboxes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator computes the bounding boxes of the labelled regions in the input image. The coordinates of the bounding boxes are expressed in the physical space (i.e., taking into account the spatial calibration of the image). For each label, the corresponding box is stored in a file named by appending the label to the input filename. The channel and the timepoint are also added to the filename if the input image contains several channels or timepoints. The output file format is Free-D’s shape viewer format.

export-shapes [--stl]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator computes the triangular meshes corresponding to the boundaries of labelled regions in a 3D image. One mesh is computed for each label and stored in a file named by appending the label to the input image filename. The mesh is obtained by applying the Marching Cubes algorithm :cite:p:`Lorensen1987` to the binary mask of the label.

The default output file format is an in-house shape file format (``.tm`` files) suitable for loading and display with ``sviewer``, the ``Free-D``\ ’s standalone 3D shape viewer :cite:p:`Biot2016`.

You can switch to the STL file format using the ``--stl`` option.

export-rag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This operator computes the region adjacency graph (RAG) of the input image.
In the RAG, each labelled region of the input image is represented by a node placed at the centroid (geometrical center) of the region. The nodes that correspond to neighbouring regions are connected by edges.

The computed RAG is stored in a format (file with extension ``.cs``) suitable for opening with ``sviewer``, the ``Free-D``\ ’s standalone 3D shape viewer :cite:p:`Biot2016`. A typical sequence of operations to compute and display the RAG is thus:

::

   bip export-rag image3D.tif
   sviewer image3D-rag.cs

See :numref:`fig:export-shapes-rag` for a typical example of 3D display.

.. figure:: ../../include/figure-meristem-export-shapes-and-rag.png
   :name: fig:export-shapes-rag
   :width: 50.0%

   Exporting and displaying shapes and RAG in a 3D label image.