= 3d Brain Atlas Reconstructor standalone =

[[PageOutline(2-3,,inline,unnumbered)]]

== Detailed description of gap-filling algorithm ==

=== Introduction ===

The most common defect encountered in digital (e.g. PDF) versions of published atlases are gaps in structures' outlines. It commonly happens when two contour lines which should touch are drawn so that they leave a little space in between. Such an arrangement may not be visible in a printed atlas but it greatly disturbs tracing process where every pixel may influence the results. In this case the structure being traced overtakes the space of its neighbour through the broken contour which we call leaking of the structure (see figure below).

[[Image(debug_100_99_vBrain_step_0.gif)]]

Fragment of rasterized contour slide based on Paxinos and Franklin ''The Mouse Brain In Stereotaxic Coordinates, third edition''.

Leaking structures are handled in 3dBAR by gap filling algorithm, an extension of the basic tracing procedure. The algorithm requires single input parameter – `MaxGrowLevel` describing maximal size of the gaps that will be closed during tracing of a particular area. The algorithm creates multiple (`n=MaxGrowLevel`) copies of initial input bitmap, each with the contours expanded using the [http://en.wikipedia.org/wiki/Dilation_%28morphology%29 dilation filter]  approximately by one pixel.

[[Image(debug_460_461_VO_step_0-anim.gif)]]

Consecutive flood-filled areas are dilated the same number of times as the boundaries were grown to make the area of the resulting path unbiased. If it remains stable or slightly lowers (less than 2% in our implementation) at consecutive stages of the algorithm it means that most probably the boundaries of the structure in question do not have any gaps (see Fig. 3).

=== Structures without gaps ===

[[Image(debug_460_461_VO_step_0-anim-AOP.gif)]]

  '''Figure 3''': Structure without gaps does not express significant changes of its area across different stages of algorithm (see table below).
  ||= growlevel =||= area of the structure in pixels =||
  ||  0          ||  51124  ||
  ||  1          ||  51124  ||
  ||  2          ||  51124  ||
  ||  3          ||  51124  ||
  ||  4          ||  51124  ||
  ||  5          ||  51112  ||


=== Leaking strutcures ===

[[Image(debug_460_461_VO_step_0-anim-VO.gif)]]

  '''Figure 4''': Structure with gap(s) in it's contour expresses significant changes of its area.
  We can see sudden drop of the number of pixels at certain stage (here at `growlevel=2`) of the algorithm application when the gap is closed (see table below).

  ||= growlevel =||= area of the structure in pixels =||
  ||  0          ||  196243  ||
  ||  1          ||  '''196232'''  ||
  ||  '''2'''    ||  '''84384'''  ||
  ||  3          ||  84331  ||
  ||  4          ||  84331  ||
  ||  5          ||  84309  ||

If the reduction of flooded area at certain stage of filter application is grated than defined threshold (2% in our implementation), it means that boundary gap must have been closed. After finding the optimal number of border expansions (denoted by `growlevel`) and the bitmap is passed to [http://potrace.sourceforge.net/ PoTrace]. 

The gap filling algorithm is applied individually for each seed label thus different regions may be processed with different value of `GrowLevel`. Information about which `GrowLevel` was used to trace a particular path is stored in its attributes.

=== Preconfiguration ===

The gap filling algorithm may also be preconfigured during the preparation of a contour slide. Preconfiguration is carried out by assigning `bar:growlevel`
attribute to the label used as the seed for tracing. The value of this attribute
should be an integer between -1 and `MaxGrowLevel`.  Assigning `-1` means
that `GrowLevel` is undefined and has to be selected automatically, `0` means
that gap filling should not be used for this particular label.  Other values
denote the number of dilation filter applications. 

=== Algorithm efficacy and limitations ===

Exemplary result of the gap filling algorithm applied to 47 paths from 13th coronal section (2.1mm ant. from bregma) from Paxinos and Franklin ''The Mouse Brain In Stereotaxic Coordinates, third edition''.

||= optimal grow level =||= number of paths =||
||  0       ||  28  ||
||  1       ||  9   ||
||  2       ||  10  ||

The performance of the algorithm depends on the initial size of the structure and on the resolution of input data but in practice, already for structures on the order of diameter around 10 pixels, gap detection works well. Intensive use of this algorithm may distort or even erase the some (particularly narrow) structures. There is no specific mechanism implemented against such behaviour but in practice we have not encountered problems of this type. If a very accurate reconstruction is required, the best policy is to prepare a precise contour slide so there is no need to apply gap filling.

{{{
#!comment
Add reference to 3dBAR paper.
}}}