*** empty log message ***

[bbtk.git] / kernel / doc / bbtkUsersGuide / bbtkUsersGuide.tex

diff --git a/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex b/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex
index 9cd903ed9037eff38708619414bec320194895d5..322099ad2cc805dea1a82a1104fa8d6ade9889b8 100644 (file)
--- a/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex
+++ b/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex
@@ -10,6 +10,9 @@
 \tableofcontents
 % ==========================================
 
 \tableofcontents
 % ==========================================
 

+\listoftables
+
+\listoffigures

 
 % ==========================================
 %\section*{Abstract}
 
 % ==========================================
 %\section*{Abstract}


@@ -165,7 +168,7 @@ This guide is divided into three parts.
 The first part (\ref{bbStudio}) is a brief presentation of the very intuitive Development
 environment, \bbStudio.
 
 The first part (\ref{bbStudio}) is a brief presentation of the very intuitive Development
 environment, \bbStudio.
 

-The second part (\ref{bbi}) 
+The second part (\ref{bb0}) 

 is devoted to the use of the \emph{black box interpreter} \bbi. 
 This is the highest level of use of the toolkit, which 
 allows to create and execute processing chains by connecting 
 is devoted to the use of the \emph{black box interpreter} \bbi. 
 This is the highest level of use of the toolkit, which 
 allows to create and execute processing chains by connecting 


@@ -187,7 +190,9 @@ involve complex graphical interfaces.
 \section{The Development environment (bbStudio)}
 \label{bbStudio}
 
 \section{The Development environment (bbStudio)}
 \label{bbStudio}
 

-Just run it, typing in a console \texttt{bbed}.
+Just run it, typing in a console \bbStudio 
+or clicking on its icon or its menu entry.
+At start, \bbStudio opens with the 'Help' tab selected.

 You'll get something like in figure 
 \ref{bbi-fig-bbStudio-gui}
 (the exact appearance of \bbStudio is system and \bbtk version dependent)
 You'll get something like in figure 
 \ref{bbi-fig-bbStudio-gui}
 (the exact appearance of \bbStudio is system and \bbtk version dependent)


@@ -199,7 +204,8 @@ You'll get something like in figure
 \end{center}
 \end{figure}
 
 \end{center}
 \end{figure}
 

-All the entries of this Help 'bookmark' are self-explanatory :
+The 'Help' tab of \bbStudio is used to browse the html help of \BBTK.
+All the entries of the starting page are self-explanatory :

 
  \begin{itemize}
    \item {\bf\emph{Wiki}}: Direct link to the bbtk Wiki (intranet only, right now, www
 
  \begin{itemize}
    \item {\bf\emph{Wiki}}: Direct link to the bbtk Wiki (intranet only, right now, www


@@ -214,12 +220,89 @@ All the entries of this Help 'bookmark' are self-explanatory :
    \item {\bf\emph{Doxygen Documentation}}: Doxygen source browser.
    \item {\bf\emph{Boxes}}: Box retrieving on various criterions :
       \begin{itemize}
    \item {\bf\emph{Doxygen Documentation}}: Doxygen source browser.
    \item {\bf\emph{Boxes}}: Box retrieving on various criterions :
       \begin{itemize}

-      \item {\bf\emph{By name}}
-      \item {\bf\emph{By package}}
-      \item {\bf\emph{By category}}
+        \item {\bf\emph{By name}}
+        \item {\bf\emph{By package}} (see table : \ref{bbi-list_of_packages})
+        \item {\bf\emph{By category}} (see table :\ref{categories})
+        \item {\bf\emph{Adaptors}} Used internaly to perform type conversions (not end user intended)     

       \end{itemize}
  \end{itemize}
 
       \end{itemize}
  \end{itemize}
 

+
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{bbi-list_of_packages} List of bbtk supplied packages.}
+\small
+\begin{tabular}{|lp{10cm}|}
+\hline
+Package         & What it's used for \\ \hline
+\texttt{std}    & : the 'standard' package including basic useful boxes \\ \hline 
+\texttt{wx}     & : basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library \\ \hline 
+\texttt{itk}    & : the basic image processing package, based on the \texttt{itk} library. (without description)\\ \hline 
+\texttt{vtk}    & : Prints help on the package \texttt{package-name} and its boxes (with brief description). The package must have been previously loaded\\ \hline 
+\texttt{wxvtk}  & : widget boxes based on the \texttt{vtk} library.\\ \hline 
+\texttt{itkvtk} & : boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally.\\ \hline 
+
+\end{tabular}
+\end{table}
+% ==========================================
+
+
+
+
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{categories} \texttt{Black Box} categories}
+\small
+\begin{tabular}{|lp{10cm}|}
+\hline
+ \texttt{Category name}     & : Meaning                                          \\ \hline \\ \hline
+ \texttt{adaptor}        & : Adaptor box                                      \\ \hline
+ \texttt{application}    & : Final application, end user intended             \\ \hline
+ \texttt{atomic box}     & : System category.
+              Automatically assigned to Atomic Black Boxes (c++ defined)     \\ \hline
+ \texttt{complex box}    & : System category.
+              Automatically assigned to Complex Black Boxes (script defined) \\ \hline  
+ \texttt{command line}   & : Script which defines a command line application \\ 
+                         & :(no embedded GUI, but command line imput parameters) \\ \hline
+ \texttt{demo}           & : Demonstration                             \\ \hline
+ \texttt{devel}          & : Developer tool (bbCreatePackage.bbs, ...) \\ \hline
+ \texttt{dicom}          & : DICOM aware box                            \\ \hline 
+ \texttt{example}        & : Example script showing a box use-case      \\ \hline
+ \texttt{filter}         & : Image processing box                       \\ \hline
+ \texttt{image}          & : Image processing related box               \\ \hline
+ \texttt{interaction}    & :                                            \\ \hline
+ \texttt{math}           & : Mathematical operations                    \\ \hline
+ \texttt{mesh}           & : Mesh processing related box                 \\ \hline
+ \texttt{misc}           & : A box that cannot be put in other category ! \\ \hline
+ \texttt{read/write}     & : Box that read or write data from or to disk  \\ \hline
+ \texttt{viewer}         & : Box which displays some data                \\ \hline
+ \texttt{widget}         & : Piece of graphical interface                \\ \hline 
+ 
+ \texttt{3D object creator} & : Sophisticated 3D widget  \\ \hline  
+ \texttt{toolsbbtk}         & : Component of bbStudio    \\ \hline  
+\end{tabular}
+\end{table}
+
+% ==========================================
+
+\begin{table}[!ht]
+\caption{\label{kinds} \texttt{Black Box} kinds}
+\small
+\begin{tabular}{|ll|}
+\hline
+\texttt{Kind name}                & : Meaning                         \\ \hline \\ \hline
+\texttt{ADAPTOR}                  & : Adaptor Box                     \\ \hline
+\texttt{DEFAULT\_ADAPTOR}         & :                                  \\ \hline
+\texttt{WIDGET\_ADAPTOR}          & :                                  \\ \hline
+\texttt{DEFAULT\_WIDGET\_ADAPTOR} & :                                  \\ \hline
+\texttt{GUI}                      & :                                  \\ \hline
+\texttt{DEFAULT\_GUI}             & :                                  \\ \hline
+\texttt{ALL}                      & : If kind='ALL' then sets the level for all kinds \\ \hline
+\end{tabular}
+\end{table}
+
+
+

 % ==========================================
 % ==========================================
 % ==========================================
 % ==========================================
 % ==========================================
 % ==========================================


@@ -242,18 +325,27 @@ All the entries of this Help 'bookmark' are self-explanatory :
 \end{figure}
 
 Using the lower tool bar, you can :
 \end{figure}
 
 Using the lower tool bar, you can :

+
+\begin{figure}[!ht]
+\caption{\label{lowertoolbar}The lower tool bar}
+\begin{center}
+\includegraphics[width=0.7\textwidth]{lowertoolbar.png}
+\end{center}
+\end{figure}
+
+

  \begin{itemize}
    \item {\bf\emph{new}}: Create a newfile to hold a script
    \item {\bf\emph{open}}: Open a already existing file holding a script 
    \item {\bf\emph{close}}: Close a file holding a script
  \begin{itemize}
    \item {\bf\emph{new}}: Create a newfile to hold a script
    \item {\bf\emph{open}}: Open a already existing file holding a script 
    \item {\bf\emph{close}}: Close a file holding a script

-   \item {\bf\emph{close}}: Save he current file (if modified)
+   \item {\bf\emph{save}}: Save he current file (if modified)

    \item {\bf\emph{save as}}: Save he current file under a different name
    \item {\bf\emph{execute}}: Execute the script you just loaded/modified/written
  \end{itemize}
 
 
 The script language is very simple. 
    \item {\bf\emph{save as}}: Save he current file under a different name
    \item {\bf\emph{execute}}: Execute the script you just loaded/modified/written
  \end{itemize}
 
 
 The script language is very simple. 

-Everything is done with only a few commands.
+Everything is done with only a very few commands (See table \ref{bbi-reference-box}).

 The philosophy of this part is also very simple: 
 it introduces the \bbi commands using examples, 
 starting with the most simple commands.  
 The philosophy of this part is also very simple: 
 it introduces the \bbi commands using examples, 
 starting with the most simple commands.  


@@ -510,13 +602,13 @@ the command \texttt{new}:
 
 The \texttt{'a'} at the end is the \emph{name} of the instance, 
 which will be used to reference it later. 
 
 The \texttt{'a'} at the end is the \emph{name} of the instance, 
 which will be used to reference it later. 

-It is important to distinguish a box \emph{types} 
+It is important to distinguish a box \emph{type} 

 and an \emph{instance} of a box type. 
 The \texttt{Add} box of the package \texttt{std} is actually 
 a \emph{box type} , like \texttt{int} is a data type 
 in \texttt{C} langage. The \texttt{new} command allows to create 
 an instance of a box type, exactly like \texttt{int i;} in 
 and an \emph{instance} of a box type. 
 The \texttt{Add} box of the package \texttt{std} is actually 
 a \emph{box type} , like \texttt{int} is a data type 
 in \texttt{C} langage. The \texttt{new} command allows to create 
 an instance of a box type, exactly like \texttt{int i;} in 

-a \texttt{C} code declares a variable of type \texttt{int} whose 
+a \texttt{C} code, it declares a variable of type \texttt{int} whose 

 name is \texttt{i}. 
 Of course, like in \texttt{C} Language, you can declare multiple boxes of the 
 same type in \bbi. 
 name is \texttt{i}. 
 Of course, like in \texttt{C} Language, you can declare multiple boxes of the 
 same type in \bbi. 


@@ -577,6 +669,7 @@ To process this special substrings, \bbi does:
 \item postpone an implicit 'new line' character to the string
 \end{enumerate}
 
 \item postpone an implicit 'new line' character to the string
 \end{enumerate}
 

+\paragraph

 Box processing is needed if:
 \begin{itemize}
 \item at least input has changed since last processing or
 Box processing is needed if:
 \begin{itemize}
 \item at least input has changed since last processing or


@@ -609,7 +702,7 @@ Good bye !
 \paragraph{Summary}
 %\hrule
 \begin{itemize}
 \paragraph{Summary}
 %\hrule
 \begin{itemize}

-\item The \texttt{include} command allows to load a package.
+\item The \texttt{include} command allows to load a package, and the complex black boxes that come with it..

 \item \texttt{help} gives help on:
 \begin{itemize} 
 \item Available commands if you just type \texttt{help}.
 \item \texttt{help} gives help on:
 \begin{itemize} 
 \item Available commands if you just type \texttt{help}.


@@ -630,6 +723,18 @@ implicit trailing 'new line character' is added at the final string.
 \item \texttt{quit} : quits \bbi.
 \end{itemize}
 \hrule
 \item \texttt{quit} : quits \bbi.
 \end{itemize}
 \hrule

+
+\paragraph{Note :}
+A more 'modern' way to proceed is to run \texttt{bbStudio}, drag and drop the  \texttt{Command} bookmark to the lower \texttt{Welcome to bbStudio!} bar.
+Wou'll get something like in figure \ref{bbCommandPlusHelp} :
+
+\begin{figure}[!ht]
+\caption{\label{bbCommandPlusHelp}
+An other way to run the command interpreter}
+\begin{center}
+\includegraphics[width=0.5\textwidth]{bbCommandPlusHelp.png}
+\end{center}
+\end{figure}

 % ==========================================
 
 % ==========================================
 % ==========================================
 
 % ==========================================


@@ -672,12 +777,17 @@ The \bbi instructions to create and execute this pipeline are:
 > set a.In2 2
 > set b.In2 3
 > print $b.Out$
 > set a.In2 2
 > set b.In2 3
 > print $b.Out$

+\end{verbatim}
+
+You will see the (very expected) result :
+\begin{verbatim}

 6
 \end{verbatim}
 
 The first three commands build the pipeline, 
 the next three set \texttt{a} and \texttt{b} black boxes inputs and the last one 
 6
 \end{verbatim}
 
 The first three commands build the pipeline, 
 the next three set \texttt{a} and \texttt{b} black boxes inputs and the last one 

-executes the pipeline and prints \texttt{b} black boxe output.
+prints \texttt{b} black boxe output (the pipeline is executed before printing, because the interpretor 'knows' he box  \texttt{b}, 
+whose output is requested, is not up to date.

  
 The command \texttt{'connect a.Out b.In1'} ``plugs'' the output 
 \texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the 
  
 The command \texttt{'connect a.Out b.In1'} ``plugs'' the output 
 \texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the 


@@ -689,6 +799,53 @@ This pipeline mechanism can recurse into arbitrary long
 chains of boxes (see \ref{bbi-more-on-pipeline-processing} 
 for details).
 
 chains of boxes (see \ref{bbi-more-on-pipeline-processing} 
 for details).
 

+
+Lets' consider an other, more image oriented, example :
+
+\begin{verbatim}
+> include vtk
+> include wx
+> include itk
+> include wxvtk
+
+> new FileSelector fileDialog
+> new ImageReader  reader 
+> new Slider       slider
+> new Viewer2D     viewer
+
+> connect fileDialog.Out   reader.In 
+> connect reader.Out       viewer.In
+> connect slider.Out       viewer.Slice
+> connect slider.BoxChange viewer.BoxExecute
+
+> exec viewer
+\end{verbatim}
+
+Some explainations : the \texttt{include} instructions load the necessary packages. \\
+
+\texttt{new FileSelector} will pop a File Selector, at run time, that will out the user chosen file name. \\
+\texttt{new Slider} will pop a Slider, at run time, that will out an integer, used later as a slice number.\\ 
+\texttt{new ImageReader} will read any itk readable file, whose name is passed as a std::string, and return a itk::ImagePointer.
+\texttt{new Viewer2D} display a plane, whose number id specified by an integer.\\
+\\
+\texttt{connect fileDialog.Out   reader.In} plugs the output of the File Selector (a std::string) to the input of the reader (a std::string, too).\\
+\texttt{connect reader.Out       viewer.In} plugs the output of the reader (an itk::ImagePointer) to the input of the Viewer (a vtkImageData *)\\
+\texttt{connect slider.Out       viewer.Slice} plugs the output of the slider (an int) to an other output (named Slide) of the viewer.\\
+\texttt{connect slider.BoxChange viewer.BoxExecute} says the viewer it must re process itself any time the slider is modified.\\
+\\
+\texttt{exec viewer} processes the viewer.
+
+
+This would correspond to the graph in figure \ref{bbi-simplegraph}
+
+
+\begin{figure}[!ht]
+\caption{\label{bbi-simplegraph}(Very) simple Graph of a (very) simple pipeline}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{bbi-simplegraph.png}
+\end{center}
+\end{figure}
+   

 Of course, to be able to connect two boxes, 
 the output and the input must be compatibles. 
 You can always connect an output to an input of the \emph{same} type, 
 Of course, to be able to connect two boxes, 
 the output and the input must be compatibles. 
 You can always connect an output to an input of the \emph{same} type, 


@@ -1223,7 +1380,7 @@ You can reproduce the same experiment as above using a
 \texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}.
 See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
 
 \texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}.
 See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
 

-There are two kind of widgets: ``terminal'' widgets and ``container'' widgets.
+There are two kinds of widgets: ``terminal'' widgets and ``container'' widgets.

 The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets 
 are ``terminal'' widgets. 
 ``container'' widgets are of another kind: they are designed to 
 The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets 
 are ``terminal'' widgets. 
 ``container'' widgets are of another kind: they are designed to 


@@ -1307,7 +1464,7 @@ Any widget box has two mandatory Outputs :
 
 \begin{itemize}
   \item {\bf\emph{Widget}} : that is the \texttt{wxWindow} itself. If it's not connected to the \texttt{Widget}\emph{i} of any \emph{Layout box}, it
 
 \begin{itemize}
   \item {\bf\emph{Widget}} : that is the \texttt{wxWindow} itself. If it's not connected to the \texttt{Widget}\emph{i} of any \emph{Layout box}, it

-     will popup. If it's connected to the\bf{Widget}\bf\emph{i} of any \texttt{Layout box}, it will be embedded in its parent window.
+     will popup. If it's connected to the \texttt{Widget}\texttt{\emph{i}} of any \texttt{Layout box}, it will be embedded in its parent window.

   \item {\bf\emph{Boxchange}}  : Signals any modification of the box. This output may be connect if necessary to the \emph{BoxExecute} of an other box,
    further within the execution pipeline.
 \end{itemize}    
   \item {\bf\emph{Boxchange}}  : Signals any modification of the box. This output may be connect if necessary to the \emph{BoxExecute} of an other box,
    further within the execution pipeline.
 \end{itemize}    


@@ -1317,7 +1474,7 @@ Any widget box has two mandatory Inputs :
   \item {\bf\emph{BoxExecute}}     : Any signal received by this input executes the box
   \item {\bf\emph{BoxProcessMode}} : Sets the processing mode of the box :
   \begin{itemize}
   \item {\bf\emph{BoxExecute}}     : Any signal received by this input executes the box
   \item {\bf\emph{BoxProcessMode}} : Sets the processing mode of the box :
   \begin{itemize}

-    \item {\bf\emph{Pipeline}} : bbUpdate() only calls Process if Status == MODIFIED (normal pipeline processing)
+    \item {\bf\emph{Pipeline}} : bbUpdate() calls Process only if Status == MODIFIED (normal pipeline processing)

     \item {\bf\emph{Always}}   : bbUpdate() always calls Process
     \item {\bf\emph{Reactive}} : bbSetModifiedStatus() calls bbUpdate()    
   \end{itemize}   
     \item {\bf\emph{Always}}   : bbUpdate() always calls Process
     \item {\bf\emph{Reactive}} : bbSetModifiedStatus() calls bbUpdate()    
   \end{itemize}   


@@ -1336,21 +1493,11 @@ Any widget box has five Inputs, that will be dealt with only if the box is not c
 
 Any \emph{Layout box} (i.e. \emph{LayoutLine}, \emph{LayoutSplit} or \emph{LayoutTab}) has at one or more mandatory Inputs :
 \begin{itemize}
 
 Any \emph{Layout box} (i.e. \emph{LayoutLine}, \emph{LayoutSplit} or \emph{LayoutTab}) has at one or more mandatory Inputs :
 \begin{itemize}

-  \item \bf{Widget}\bf{\emph{i}} : e.g. a \emph{LayoutSplit} box (Widget which splits a window in two fixed size parts) 
+  \item {\bf\emph{Widget}}\texttt{i} : e.g. a \emph{LayoutSplit} box (Widget which splits a window in two fixed size parts) 

        has two Input parameters \emph{Widget1} and \emph{Widget2}, used to embed the child windows.
 \end{itemize} 
 
 
        has two Input parameters \emph{Widget1} and \emph{Widget2}, used to embed the child windows.
 \end{itemize} 
 
 

-
-TO DO: 
-\begin{enumerate}
-\item Make a tour of ``complex'' widgets of wxvtk 
-\item Explain the role of ProcessMode to update widgets
-\item Explain the creation of complex widgets (containers, contained...)
-\item Explain the ``control'' mechanism in bbi (switch exec commands, e.g. Button)
-\end{enumerate}
-
-

 % ==========================================
 \subsection{More on ...}
 \label{bbi-more-on}
 % ==========================================
 \subsection{More on ...}
 \label{bbi-more-on}


@@ -1362,106 +1509,390 @@ TO DO:
 % ==========================================
 
 There are various others user-intended packages :
 % ==========================================
 
 There are various others user-intended packages :

-
-\paragraph{vtk}
+\begin{itemize}
+\item{vtk} \\

 It contains some vtk based image processing filters :
 %   \begin{enumerate}
 It contains some vtk based image processing filters :
 %   \begin{enumerate}

-     \subparagraph{AppendPolyData}
+
+     \paragraph{AppendPolyData}

      Appends one of more polygonal datasets into a single polygonal dataset 
      Appends one of more polygonal datasets into a single polygonal dataset 

-     \subparagraph{ConeSource}
+
+     \paragraph{ConeSource}

      Creates a Cone 
      Creates a Cone 

-     \subparagraph{ImageAnisotropicDiffusion3D}
-vtkImageAnisotropicDiffusion3D diffuses an volume iteratively. 
-The neighborhood of the diffusion is determined by the instance flags. 
-if 'Faces' is on, the 6 voxels adjoined by faces are included in the neighborhood. 
-If 'Edges' is on the 12 edge connected voxels are included, and if 'Corners' is on, the 8 corner connected voxels are included. 
-'DiffusionFactor' determines how far a pixel value moves toward its neighbors, and is insensitive to the number of neighbors chosen. 
-The diffusion is anisotropic because it only occurs when a gradient measure is below 'GradientThreshold'. 
-Two gradient measures exist and are toggled by the 'GradientMagnitudeThreshold' flag. 
-When 'GradientMagnitudeThreshold' is on, the magnitude of the gradient, computed by central differences, above 'DiffusionThreshold' a voxel is not modified. 
-The alternative measure examines each neighbor independently. 
-The gradient between the voxel and the neighbor must be below the 'DiffusionThreshold' for diffusion to occur with THAT neighbor.
-     \subparagraph{ImageCharacteristics}
+
+     \paragraph{ImageAnisotropicDiffusion3D}
+vtkImageAnisotropicDiffusion3D diffuses an volume iteratively. \\
+The neighborhood of the diffusion is determined by the instance flags. \\
+if 'Faces' is on, the 6 voxels adjoined by faces are included in the neighborhood. \\
+If 'Edges' is on the 12 edge connected voxels are included, and if 'Corners' is on, the 8 corner connected voxels are included. \\
+'DiffusionFactor' determines how far a pixel value moves toward its neighbors, and is insensitive to the number of neighbors chosen.\\ 
+The diffusion is anisotropic because it only occurs when a gradient measure is below 'GradientThreshold'. \\
+Two gradient measures exist and are toggled by the 'GradientMagnitudeThreshold' flag. \\
+When 'GradientMagnitudeThreshold' is on, the magnitude of the gradient, computed by central differences, above 'DiffusionThreshold' a voxel is not
+modified. \\
+The alternative measure examines each neighbor independently.\\ 
+The gradient between the voxel and the neighbor must be below the 'DiffusionThreshold' for diffusion to occur with THAT neighbor.\\
+     Receives : \\
+     - In : an image (vtkImageData*)\\
+     - Diffusion : Difference threshold that stops the diffusion\\
+     Outputs : \\
+     - Out : the isosurface mesh (vtkPolyData*)
+     
+     \paragraph{ImageCharacteristics}

      Exports objet sizes, and Spacings
      Exports objet sizes, and Spacings

-     \subparagraph{ImageDilateErode3D}
-     Dilates one value and erodes another. 
-     vtkImageDilateErode3D will dilate one value and erode another. 
-     It uses an elliptical foot print, and only erodes/dilates on the boundary of the two values. 
-     The filter is restricted to the X, Y, and Z axes for now. 
-     It can degenerate to a 2 or 1 dimensional filter by setting the kernel size to 1 for a specific axis. 
-     (bbfication of vtkImageDilateErode3D) 
-     \subparagraph{ImageGaussianSmooth}
-     Performs a gaussian convolution of the input image
-     \subparagraph{ImagePlanes}
-Creates three 3D planes with the input image mapped onto with which the user can interact. 
-The output vtkImagePlaneWidget objects are to be inserted into a 3D scene (e.g. a Viewer3D      
-     \subparagraph{IsoSurfaceExtractor}
-Extracts an iso-surface of a 3D image and creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D 
-     \subparagraph{MarchingCubes}
-     Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes
-     \subparagraph{MIPCreator}     
-Creates a Maximum Intensity Projection (MIP) view of a 3D image. 
-Creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D
-     \subparagraph{MetaImageReader}
-Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader)     
-     \subparagraph{SegmentationConnectivity}
-Segmentation with min max threshold and connectivity    
-     \subparagraph{SphereSource}
+     
+     \paragraph{ImageDilateErode3D}
+     Dilates one value and erodes another.\\ 
+     vtkImageDilateErode3D will dilate one value and erode another. \\
+     It uses an elliptical foot print, and only erodes/dilates on the boundary of the two values. \\
+     The filter is restricted to the X, Y, and Z axes for now.\\ 
+     It can degenerate to a 2 or 1 dimensional filter by setting the kernel size to 1 for a specific axis. \\
+     (bbfication of vtkImageDilateErode3D) \\
+     Receives : \\
+     - In : an image (vtkImageData*)\\
+     - DilateValue : The dilatation value\\
+     - ErodeValue : The erosion value\\
+     Outputs : \\
+     - Out : the isosurface mesh (vtkPolyData*)     
+     
+     \paragraph{ImageGaussianSmooth}
+     Performs a gaussian convolution of the input image\\
+     Receives : \\
+     - In : an image (vtkImageData*)\\
+     - StdDevX : Standard deviation in X direction\\
+     - StdDevY : Standard deviation in Y direction\\
+     Outputs : \\
+     - Out : the isosurface mesh (vtkPolyData*)       
+     
+     \paragraph{ImagePlanes}
+     Creates three 3D planes with the input image mapped onto with which the user can interact; \\ 
+     The output vtkImagePlaneWidget objects are to be inserted into a 3D scene (e.g. a Viewer3D)
+     Receives : \\
+     - In : an image (vtkImageData*)\\
+     Outputs : \\     
+     - PlaneX : the image plane in X direction (vtkImagePlaneWidget*)\\
+     - PlaneY : the image plane in Y direction (vtkImagePlaneWidget*)\\
+     - PlaneY : the image plane in Z direction (vtkImagePlaneWidget*)\\
+     
+          Outputs : \\
+     - Out : the isosurface mesh (vtkPolyData*)  
+           
+     \paragraph{IsoSurfaceExtractor}
+     Extracts an iso-surface of a 3D image and creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D)
+     Receives : \\
+     - In : an image (vtkImageData*)\\
+     - Isovalue : the isosurface value (double)\\
+     - Colour : Surface colour (vector of 3 doubles)
+     Outputs : \\
+     - Out : the isosurface (vtkProp3D**)
+     
+     \paragraph{MarchingCubes}
+     Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes)\\
+     Receives : \\
+     - In : an image (vtkImageData*)\\
+     - Value : the isosurface value (double)\\
+     Outputs : \\
+     - Out : the isosurface mesh (vtkPolyData*)
+     
+     \paragraph{MIPCreator}     
+     Creates a Maximum Intensity Projection (MIP) view of a 3D image.\\
+     Receives : \\
+     - In : an image (vtkImageData*)\\
+     - Scale : the Gray scale scaling (float) \\
+     - Shift : the Gray scale shift (float) \\    
+     Ouputs : \\
+     - Out : The MIP object (vtkProp3D*) to be plugged into a 3D Viever
+
+     \paragraph{MetaImageReader}
+     Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader) \\
+     Receives : \\
+     - In : the name of the file to be read (std::string)
+     Outputs :
+     - Out : The image (vtkImageData*)     
+     
+     \paragraph{SegmentationConnectivity}
+     Segmentation with min max threshold and connectivity  \\  
+     Receives : \\
+     - In : an image (vtkImageData*)\\
+     - PositionXYZ : initial position (std::vector<int>) \\
+     - ThresholdMinMax : min, max threshold values (std::vector<int>) \\
+     Outputs : \\
+     - Out : The image (vtkImageData*)       
+          
+     \paragraph{SphereSource}

      Creates a Sphere      
 %   \end{enumerate}
 
      Creates a Sphere      
 %   \end{enumerate}
 

-\paragraph{itk}
+\item{itk} \\

 It contains some itk based image processing filters :
  
 It contains some itk based image processing filters :
  

-     \subparagraph{BinaryThresholdImageFilter}
+     \paragraph{BinaryThresholdImageFilter}

      Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter) 
      Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter) 

-     \subparagraph{DICOMSeriesFileNames}
+
+     \paragraph{DICOMSeriesFileNames}

      Reads a series from a DICOM directory as a 3D itk image     
      Reads a series from a DICOM directory as a 3D itk image     

-     \subparagraph{ExtractImageFilter}
+
+     \paragraph{ExtractImageFilter}

      Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)     
      Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)     

-     \subparagraph{ImageProperties}
+
+     \paragraph{ImageProperties}

      Outputs different properties of an image (type, dimension, size, spacing, ...)      
      Outputs different properties of an image (type, dimension, size, spacing, ...)      

-     \subparagraph{ImageRegion}
+
+     \paragraph{ImageRegion}

 Creates a generic ImageRegion (bbtk::any) from two vectors providing the index and size of the region. 
 The dimension D of the actual itk::ImageRegion created is the max of the sizes of Index and Size 
 (the smallest vector is padded by zeros)     
 Creates a generic ImageRegion (bbtk::any) from two vectors providing the index and size of the region. 
 The dimension D of the actual itk::ImageRegion created is the max of the sizes of Index and Size 
 (the smallest vector is padded by zeros)     

-     \subparagraph{ImageReader}
-Generic itk image reader                
-     \subparagraph{ImageWriter}
-Generic itk image writer      
-     \subparagraph{ImageSeriesReader}
-Generic itk image series reader.     
-     \subparagraph{ResampleImageFilter}
+
+     \paragraph{ImageReader}
+Generic itk image reader
+
+     \paragraph{ImageWriter}
+Generic itk image writer
+
+     \paragraph{ImageSeriesReader}
+Generic itk image series reader.
+
+     \paragraph{ResampleImageFilter}

 Resamples an image
 Resamples an image

-\paragraph{itkvtk}
+
+\item{itkvtk} \\

 It doesn't contain any end user intended box, only adaptors : to convert a generic itkImage to a vtkImageData, and vtkImageData* to a generic itkImage pointer 
 
 Sorry nothing is done, right now for meshes. 
 
 It doesn't contain any end user intended box, only adaptors : to convert a generic itkImage to a vtkImageData, and vtkImageData* to a generic itkImage pointer 
 
 Sorry nothing is done, right now for meshes. 
 

-\paragraph{wxvtk}
-It contains two atomic black boxes, and some sophisticated complex black boxes :
+\item{wxvtk} \\

 
 

-     \subparagraph{Viewer2D}
-     Receives a \textless vtkImageData* \textgreater (In), an Orientation(0:yz / 1:xz / 2:xy), and a initial slice number (Slice).
-     Returns a \textgreater vtkRenderer* \textgreater (Renderer)
-     
-     \subparagraph{Viewer3D}
-     Receives up to 5 Input Actors (\textless vtkProp3D* \textgreater), up to 5 Imput Observers (\textless vtkInteractorObserver* \textgreater), 
-     outputs an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact, 
-     and a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
-     Has also a boolean 'Stereo' option, to use Red-Blue filter.
+It contains two atomic black boxes.
+
+     \paragraph{Viewer2D} 
+     Receives : \\
+     - a \textless vtkImageData* \textgreater (In),\\
+     - an Orientation(0:yz / 1:xz / 2:xy),\\
+     - an initial slice number (Slice).\\
+     Outputs :\\
+     - a \textless vtkRenderer* \textgreater (Renderer)

      
      

-     \subparagraph{Viewer3D}     
+     \paragraph{Viewer3D} 
+     Receives :\\
+     - up to 5 Input Actors (\textless vtkProp3D* \textgreater),\\
+     - up to 5 Input Observers (\textless vtkInteractorObserver* \textgreater), \\
+     - a boolean 'Stereo' option, to use Red-Blue filter     
+     Outputs :\\
+     - an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact, \\
+     - a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
+
+It contains too some sophisticated complex black boxes :

  
  

-
+     \paragraph{IsoSurfaceWithControls} 
+     Image iso-surface extractor (vtk::IsoSurfaceExtractor) with associated control panel (isovalue, opacity and colour)\\
+     Receives :\\
+     - an initial isovalue (Isovalue)
+     - an initial opacity  (Opacity)
+     - an initial colour   (Colour)
+     Outputs :\\
+     \textless vtkProp3D* \textgreater (In)\\
+      
+     \paragraph{MIPWithControls}     
+     Maximum Intensity Projection (MIP) creator (vtk::MIPCreator) with associated control panel (shift and scale) \\
+    Receives :\\
+     - an initial scale (Scale)
+     - an initial shift  (Shift) 
+     Outputs :\\
+     \textless vtkProp3D* \textgreater (In)\\
+         
+\item{wx} \\
+
+Some boxes are the bbfication of usefull xwWidgets, some other ones are more
+sophisticated.
+
+    \paragraph{ColourSelector} Colour Selector dialog (bbfication of wxColourSelector) \\
+                       %\begin{verbatim}
+         \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]' 
+                       %\end{verbatim}
+
+    \paragraph{ColourSelectorButton} A button which displays a colour picker dialog when clicked \\
+                       %\begin{verbatim}
+          \texttt{In} :Initial colour \\
+          \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
+                       %\end{verbatim} \\
+
+    \paragraph{CommandButton} Button which executes bbi commands \\
+                       %\begin{verbatim}
+          \texttt{In} : Commands to be executed separated by commas (;). Each single quote (') is replaced by a double quote ("). \\
+          \texttt{Label} : Label of the button  \\
+          \texttt{Widget} : Output widget \\
+                       %\end{verbatim}
+
+    \paragraph{DirectorySelector} Pops up a directory selection dialog (wxDirDialog)\\
+                       %\begin{verbatim}
+          \texttt{DefaultDir} : The default directory\\
+          \texttt{Message} : Message to show on the dialog \\
+          \texttt{Title} : Title of the dialog \\
+          \texttt{Out} : The directory selected by the user\\
+                       %\end{verbatim}
+ 
+    \paragraph{FileSelector} Pops up a file selection dialog for reading or saving (wxFileDialog)\\
+                       %\begin{verbatim}
+          \texttt{DefaultDir} : The default directory \\
+          \texttt{DefaultFile} : The default filename \\
+          \texttt{Message} : Message to show on the dialog \\
+          \texttt{OpenSave} : Open for an open dialog (default) / Save for a save dialog\\ 
+          \texttt{Title} : Title of the dialog \\
+          \texttt{Wildcard} : A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" \\
+          \texttt{Out} : The file selected by the user \\
+                       %\end{verbatim}
+
+    \paragraph{InputText} A zone in which the user can enter a text (wxTextCtrl)\\
+                       %\begin{verbatim}
+          \texttt{In} : Initial text (default '')\\ 
+          \texttt{Title} : Title of the input zone (default '')\\ 
+          \texttt{WinTitle} : Title of the window (*)\\
+          \texttt{Out} :Current text\\
+                       %\end{verbatim}
+
+    \paragraph{LayoutLine} LayoutLine widget (wxBoxSizer)\\
+                       %\begin{verbatim}
+          \texttt{Orientation} Orientation (default V), 0=H=HORIZONTAL , 1=V=VERTICAL \\
+          \texttt{Widget}1 widget 1 \\
+          \texttt{Widget2} widget 2 \\
+          \texttt{Widget3} widget 3 \\
+          \texttt{Widget4} widget 4 \\
+          \texttt{Widget5} widget 5 \\
+          \texttt{Widget6} widget 6 \\
+          \texttt{Widget7} widget 7 \\
+          \texttt{Widget8} widget 8 \\
+          \texttt{Widget9} widget 9\\
+          %\end{verbatim}    
+    
+    \paragraph{LayoutSplit} Widget which splits a window in two fixed size parts (wxSplitterWindow)\\ 
+                       %\begin{verbatim}
+          \texttt{Orientation} : Orientation (default H), 0=H=HORIZONTAL , 1=V=VERTICAL\\ 
+          \texttt{Proportion} : Proportion (in percent) of the first children in the window\\ 
+          \texttt{Widget1} : Upper or left widget\\ 
+          \texttt{Widget2} : Lower or right widget\\
+                       %\end{verbatim}
+
+    \paragraph{LayoutTDown} Creates a 'T like' complex container : Down {UpLeft, UpRight} \\
+                       %\begin{verbatim}
+          \texttt{Widget1} : UpLeft container\\
+          \texttt{Widget2} : UpRight container\\ 
+          \texttt{Widget3} : Down container\\
+                        \begin{verbatim}
+//                       ---------------
+//                       |      |      |
+//                       |  W1  |  W2  |
+//                       |-------------|
+//                       |             |
+//                       |     W3      |
+//                       ---------------
+                       \end{verbatim}
+   
+    \paragraph{LayoutTLeft} Creates a 'T like' complex container :  Left {RigthUp, RightDown}\\
+                       %\begin{verbatim}
+           \texttt{input}  Widget1 : "UpLeft container"\\ 
+           \texttt{input}  Widget2 : "UpRight container"\\  
+           \texttt{input}  Wigdet3 : "Down container"\\ 
+                        \begin{verbatim} 
+//                       ---------------
+//                       |      |  W2  |
+//                       |  W1  |      |
+//                       |      |------|
+//                       |      |  W3  |
+//                       |      |      |
+//                       ---------------   
+                       \end{verbatim}
+
+    \paragraph{LayoutTRight} Creates a 'T like' complex container : Right {LeftUp, LeftDown}\\
+                       %\begin{verbatim}
+          \texttt{input} Widget1 currentBox.Widget1 "Up container"\\
+          \texttt{input} Widget2 down.Widget1       "DownLeft container"\\ 
+          \texttt{input} Widget3 down.Widget2       "DownRight container"\\    
+                        \begin{verbatim}  
+//                       ---------------
+//                       |      |      |
+//                       |  W1  |      |
+//                       |------|  W2  |
+//                       |  W3  |      |
+//                       |      |      |
+//                       ---------------
+                       \end{verbatim}
+  
+    \paragraph{LayoutTUp} Creates a 'T like' complex container : Up {DownLeft, DownRight} as w1{w2,w3}\\ 
+                       \begin{verbatim} 
+         \texttt{ input} Widget1 currentBox.Widget1 "Up"\\
+          \texttt{input} Widget2 down.Widget1       "DownLeft"\\ 
+          \texttt{input} Widget3 down.Widget2       "DownRight"\\
+     
+//                       ----------------
+//                       |    W1        |
+//                       |              |
+//                       |------|-------|
+//                       | W3   |  W2   |
+//                       |      |       |
+//                       ----------------
+               \end{verbatim}
+                         
+    \paragraph{LayoutTab} LayoutTab widget (wxNotebook)\\
+                       %\begin{verbatim}
+          \texttt{Orientation} Orientation (default T), 0=T=TOP , 1=R=RIGHT , 2=B=BOTTON , 3=L=LEFT \\
+          \texttt{Widget1} widget 1 \\
+          \texttt{Widget2} widget 2 \\
+          \texttt{Widget3} widget 3 \\
+          \texttt{Widget4} widget 4 \\
+          \texttt{Widget5} widget 5 \\
+          \texttt{Widget6} widget 6 \\
+          \texttt{Widget7} widget 7 \\
+          \texttt{Widget8} widget 8 \\
+          \texttt{Widget9} widget 9 \\   
+%\end{verbatim}
+   
+    \paragraph{OutputText}             Text zone to be inserted into a window (wxStaticText)\\
+                       %\begin{verbatim}
+          \texttt{In} Text \\
+          \texttt{Title} Title prepended to the text\\   
+                       %\end{verbatim}
+                          
+    \paragraph{RadioButton}            RadioButton group widget 0-9 entries\\
+                       %\begin{verbatim}
+          \texttt{In} Set initial item \\
+          \texttt{In0} option 0\\ 
+          \texttt{In1} option 1\\ 
+          \texttt{In2} option 2\\ 
+          \texttt{In3} option 3\\ 
+          \texttt{In4} option 4\\ 
+          \texttt{In5} option 5 \\
+          \texttt{In6} option 6 \\
+          \texttt{In7} option 7 \\
+          \texttt{In8} option 8 \\
+          \texttt{In9} option 9 \\
+          \texttt{Title} Title of the widget (default '')\\ 
+          \texttt{Out} Number of the selected Item 
+                       %\end{verbatim}
+                          
+    \paragraph{Slider}                 Slider widget (wxSlider)\\
+                       %\begin{verbatim}
+          \texttt{ChangeResolution} Enables the user to change the slider resolution (default FALSE) \\
+          \texttt{In} Initial slider position(default 0) \\
+          \texttt{Label} Show slider labels ? (default FALSE) \\
+          \texttt{Max} Maximum value of the slider (default 500)\\ 
+          \texttt{Min} Minimum value of the slider (default 0)\\ 
+          \texttt{Orientation} Orientation : (default H) 0=H=HORIZONTAL, 1=V=VERTICAL\\ 
+          \texttt{ReactiveOnTrack} Slider sends info when track moves (default 0 = no)\\ 
+          \texttt{Title} Title shown above the slider (default '')\\     
+                       %\end{verbatim}
+\end{itemize}

 % ==========================================
 \subsubsection{Pipeline processing}
 \label{bbi-more-on-pipeline-processing}
 % ==========================================
 % ==========================================
 \subsubsection{Pipeline processing}
 \label{bbi-more-on-pipeline-processing}
 % ==========================================

-
+\begin{itemize}
+\item the ``control'' mechanism in bbi (switch exec commands, e.g. Button)
+\item the role of ProcessMode to update widgets.
+\end{itemize}

 % ==========================================
 \subsubsection{Complex black boxes}
 \label{bbi-more-on-complex-black-boxes}
 % ==========================================
 \subsubsection{Complex black boxes}
 \label{bbi-more-on-complex-black-boxes}

+Creation of complex widgets (containers, contained...)

 
 %\subsubsection{Advanced issues}
 %\paragraph{Reducing the number of inputs of a box}
 
 %\subsubsection{Advanced issues}
 %\paragraph{Reducing the number of inputs of a box}


@@ -1570,6 +2001,10 @@ Executes the box named \texttt{box-name}.
 If needed the boxes 
 connected to its inputs 
 are also processed recursively (pipeline processing).\\ \hline 
 If needed the boxes 
 connected to its inputs 
 are also processed recursively (pipeline processing).\\ \hline 

+\texttt{exec} & \texttt{freeze} & 
+ allows to block execution commands while keeping definition commands active.\\ \hline 
+\texttt{exec} & \texttt{unfreeze} & 
+ turns back to 'normal' mode.\\ \hline 

 \end{tabular}
 \end{table}
 % ==========================================
 \end{tabular}
 \end{table}
 % ==========================================


@@ -1616,6 +2051,15 @@ exactly like if you were typing its content at the place were the
 \texttt{load} & \texttt{<package-name>} & 
 Loads the package \texttt{package-name}\\ \hline 
 
 \texttt{load} & \texttt{<package-name>} & 
 Loads the package \texttt{package-name}\\ \hline 
 

+\texttt{include} & \texttt{<package-name>} & 
+Loads the package \texttt{package-name} and includes all the complex black boxes that comes with it \\ \hline 
+
+\texttt{kind} & \texttt{<box kind>} & 
+Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline 
+
+
+
+

 \texttt{unload} & \texttt{<package-name>}& 
 Unloads the package \texttt{package-name}. 
 The package must have been previously loaded. 
 \texttt{unload} & \texttt{<package-name>}& 
 Unloads the package \texttt{package-name}. 
 The package must have been previously loaded. 


@@ -1660,7 +2104,6 @@ Starts the definition of a complex black box of type
 \texttt{endefine} & - & 
 Ends the definition of a complex black box type\\ \hline 
 
 \texttt{endefine} & - & 
 Ends the definition of a complex black box type\\ \hline 
 

-

 \texttt{author} & \texttt{<string>} & 
 Sets the author(s) of the complex black box currently being defined \\ \hline 
 
 \texttt{author} & \texttt{<string>} & 
 Sets the author(s) of the complex black box currently being defined \\ \hline 
 


@@ -1668,18 +2111,17 @@ Sets the author(s) of the complex black box currently being defined \\ \hline
 Sets the description of the complex black box currently being defined 
 \\ \hline 
 
 Sets the description of the complex black box currently being defined 
 \\ \hline 
 

-

 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} & 
 Defines a new input for the current complex black box, 
 named \texttt{name}. 
 It is defined as corresponding to 
 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} & 
 Defines a new input for the current complex black box, 
 named \texttt{name}. 
 It is defined as corresponding to 

-the input \texttt{input} of the box \texttt{box}. 
+the input \texttt{input} of the box \texttt{box}.
+ 

 \texttt{<help>} is the help string for the new input.
 The box \texttt{box} must already have been created in the complex box 
 and of course have an input named \texttt{input}.
 \\ \hline 
 
 \texttt{<help>} is the help string for the new input.
 The box \texttt{box} must already have been created in the complex box 
 and of course have an input named \texttt{input}.
 \\ \hline 
 

-

 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} & 
 Defines a new output for the current complex black box, 
 named \texttt{name}. 
 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} & 
 Defines a new output for the current complex black box, 
 named \texttt{name}.