updates

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

diff --git a/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex b/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex
index 62590e0bba7bf6b3f776371087a8eb40e1dd4f75..045b66bd9484276c5b16c7bd870c7a41e55d1cbf 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}


@@ -38,7 +41,7 @@ I would add something very important to this definition :
 not only the inputs and outputs are of interest but also 
 \emph{what the box does} !
 Hence, I would say that a black box is any \emph{\bf documented} 
 not only the inputs and outputs are of interest but also 
 \emph{what the box does} !
 Hence, I would say that a black box is any \emph{\bf documented} 

-component of a system, letting know the user 
+component of a system, letting the user know  

 \emph{\bf what} the box is supposed to do and 
 \emph{\bf how to use it}
 but not \emph{\bf how it does it}.
 \emph{\bf what} the box is supposed to do and 
 \emph{\bf how to use it}
 but not \emph{\bf how it does it}.


@@ -67,7 +70,7 @@ I let you think about this\dots)
 
 Of course, symbolic data attached to box can be 
 {\bf queried}: what are the inputs/outputs of the box ? 
 
 Of course, symbolic data attached to box can be 
 {\bf queried}: what are the inputs/outputs of the box ? 

-what are their type ? description ? etc.
+what are their type ? their description ? etc.

 This allows {\bf automatic documentation} of boxes. 
 
 The abstract definition of black boxes is the most basic 
 This allows {\bf automatic documentation} of boxes. 
 
 The abstract definition of black boxes is the most basic 


@@ -108,33 +111,44 @@ have been written by different persons, using different libraries, etc.
 % ==========================================
 \BBTK includes:
 \begin{itemize}
 % ==========================================
 \BBTK includes:
 \begin{itemize}

-\item A \CPP {\bf\emph{library}} - called \bbtk - which defines a framework 
-(abstract classes) to develop black boxes and to store them into 
-dynamic libraries, called black box \emph{packages}.
-\item Different {\bf\emph{black box packages}}:
-\begin{itemize}
-\item {\bf\emph{std}}: the 'standard' package including basic useful boxes.
-\item {\bf\emph{wx}}: basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library).  
-\item {\bf\emph{itk}}: the basic image processing package, based on the \texttt{itk} library.
-\item {\bf\emph{vtk}}: the basic image and surfaces processing package, based on the \texttt{vtk} library.
-\item {\bf\emph{wxvtk}}: widget boxes based on the \texttt{vtk} library.
-\item {\bf\emph{itkvtk}}: boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally. 
-\end{itemize}
-\item An {\bf\emph{interpreter}}, called \bbi, which allows to 
-load black box packages and to define and execute 
-processing chains by connecting various black boxes of the already loaded packages.
-\item {\bf\emph{Utilities}}:
-\begin{itemize}
-\item \bbfy generates the \CPP code of a black box from a 
-description file written in \texttt{xml}.
-%\item \bbdoc generates the html documentation of a black box package 
-%(author, description, description of its black boxes: 
-%author, description, inputs, outputs, and so on).
-\item \bbCreatePackage allows to create the basic file architecture 
-to start the development of a new black box package.
-\end{itemize} 
+  \item A \CPP {\bf\emph{library}} - called \bbtk - which defines a framework 
+    (abstract classes) to develop black boxes and to store them into 
+    dynamic libraries, called black box \emph{packages}.
+  \item Different {\bf\emph{black box packages}}:
+    \begin{itemize}
+      \item {\bf\emph{std}}: the 'standard' package including basic useful boxes.
+      \item {\bf\emph{wx}}: basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library).  
+      \item {\bf\emph{itk}}: the basic image processing package, based on the \texttt{itk} library.
+      \item {\bf\emph{vtk}}: the basic image and surfaces processing package, based on the \texttt{vtk} library.
+      \item {\bf\emph{wxvtk}}: widget boxes based on the \texttt{vtk} library.
+      \item {\bf\emph{itkvtk}}: boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally. 
+    \end{itemize}
+  \item A {\bf\emph{Developement environment}}, called bbStudio, which provides
+    \begin{itemize}
+      \item An online {\bf\emph{script editor}}, called bbed
+      \item A powerfull {\bf\emph{Help environment}}, called bbhelp
+        whith integrated
+        \begin{itemize}
+          \item Online documentation scaning
+          \item Retreiving boxes on various criterions
+          \item Checking Demo and examples
+        \end{itemize}
+
+      \item An {\bf\emph{interpreter}}, called \bbi, which allows to 
+          load black box packages and to define and execute 
+          processing chains by connecting various black boxes of the already loaded packages.
+      \item {\bf\emph{Utilities}}:
+         \begin{itemize}
+            \item \bbfy generates the \CPP code of a black box from a 
+               description file written in \texttt{xml}.
+                %\item \bbdoc generates the html documentation of a black box package 
+                %(author, description, description of its black boxes: 
+                %author, description, inputs, outputs, and so on).
+            \item \bbCreatePackage allows to create the basic file architecture 
+               to start the development of a new black box package.
+         \end{itemize} 
+    \end{itemize}

 \end{itemize}
 \end{itemize}

-

 The general architecture of \BBTK 
 is shown in figure \ref{bb-architecture}.
 
 The general architecture of \BBTK 
 is shown in figure \ref{bb-architecture}.
 


@@ -149,19 +163,22 @@ is shown in figure \ref{bb-architecture}.
 \subsection{Structure of this guide}
 % ==========================================
 
 \subsection{Structure of this guide}
 % ==========================================
 

-This guide is divided into two parts. 
+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{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 
 black boxes of existing packages. 
 
 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 
 black boxes of existing packages. 
 

-The second part (\ref{cpp}) explains how to 
+The third part (\ref{cpp}) explains how to 

 use the black box toolkit framework in \CPP code, 
 typically to develop large applications which 
 involve complex graphical interfaces.
 use the black box toolkit framework in \CPP code, 
 typically to develop large applications which 
 involve complex graphical interfaces.

- 
+

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


@@ -170,16 +187,162 @@ involve complex graphical interfaces.
 % ==========================================
 % ==========================================
 \vspace{0.5cm}\hrule
 % ==========================================
 % ==========================================
 \vspace{0.5cm}\hrule

-\section{The black box interpreter (bbi)}
-\label{bbi}
+\section{The Development environment (bbStudio)}
+\label{bbStudio}
+
+Just run it, typing in a console \texttt{bbed}.
+You'll get something like in figure 
+\ref{bbi-fig-bbStudio-gui}
+(the exact appearance of \bbStudio is system and \bbtk version dependent)
+
+\begin{figure}[!ht]
+\caption{\label{bbi-fig-bbStudio-gui}The bbStudio Development environment interface}
+\begin{center}
+\includegraphics[width=0.7\textwidth]{bbStudioMainPage.png}
+\end{center}
+\end{figure}
+
+All the entries of this Help 'bookmark' are self-explanatory :
+
+ \begin{itemize}
+   \item {\bf\emph{Wiki}}: Direct link to the bbtk Wiki (intranet only, right now, www
+   later).
+   \item {\bf\emph{Demo}}: Link to some demonstrations.
+   \item {\bf\emph{User's Guide}}: Step to step How-to for user who just wants to create his own
+   application, just using already existing boxes.
+   \item {\bf\emph{Package Developper's Guide}}: Step to step How-to for user who wants to create his own
+   black boxes.
+   \item {\bf\emph{Developper's Guide}}: Sorry, not yet written.
+   \item {\bf\emph{Reference Manual}}: Sorry, not yet written. 
+   \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}} (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}
+
+
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{bbi-list_of_packages} List of bbtk supplied packages.}
+\small
+\begin{tabular}{|ll||}
+\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}{|ll|}
+\hline
+ \texttt{Categ 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}
+

 
 

+
+% ==========================================
+% ==========================================
+% ==========================================
+% ==========================================

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

-%\subsection{Structure of this part}

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

+\vspace{0.5cm}\hrule
+\section{The script manager}
+\label{bb0}
+% ==========================================
+
+ Call it with the bookmark \emph{File}.
+ 
+
+\begin{figure}[!ht]
+\caption{\label{bbi-fig-bbStudio-file0}The bbStudio script manager}
+\begin{center}
+\includegraphics[width=0.7\textwidth]{bbFile0.png}
+\end{center}
+\end{figure}
+
+Using the lower tool bar, you can :

 
 

-Using the black box interpreter is very simple. 
-Everything is done with only a few commands.
+\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
+   \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. 
+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.  


@@ -214,7 +377,8 @@ Use it as a reference.
 \subsubsection{Creating and executing black boxes}
 % ==========================================
 
 \subsubsection{Creating and executing black boxes}
 % ==========================================
 

-To run the black box interpreter, 
+To learn interactivelly the script language features, you can use the black box
+interpreter : 

 open a console and type \texttt{bbi} 
 or double click on the application icon.
 You get a window which looks like the one in figure 
 open a console and type \texttt{bbi} 
 or double click on the application icon.
 You get a window which looks like the one in figure 


@@ -226,17 +390,17 @@ graphical interface but a simple prompt}.
 \begin{figure}[!ht]
 \caption{\label{bbi-fig-bbi-gui}The black box interpreter interface}
 \begin{center}
 \begin{figure}[!ht]
 \caption{\label{bbi-fig-bbi-gui}The black box interpreter interface}
 \begin{center}

-\includegraphics[width=0.7\textwidth]{bbi-gui.png}
+\includegraphics[width=0.7\textwidth]{bbi-gui0.png}

 \end{center}
 \end{figure}
 
 The 'Command' tab is subdivided into two parts : 
 one single line zone at the bottom in which you can enter your commands and 
 one multiple line zone in which \bbi prints out the result of your commands.
 \end{center}
 \end{figure}
 
 The 'Command' tab is subdivided into two parts : 
 one single line zone at the bottom in which you can enter your commands and 
 one multiple line zone in which \bbi prints out the result of your commands.

-
+, just using already existing boxes.

 
 Try typing in the input zone (in this manual, 
 
 Try typing in the input zone (in this manual, 

-the commands entered by the user will be preceded by a prompt '>') :
+the commands entered by the user will be preceded by a prompt \textgreater) :

 \begin{verbatim}
 > help 
 \end{verbatim}
 \begin{verbatim}
 > help 
 \end{verbatim}


@@ -248,6 +412,7 @@ Available commands:
  category
  config
  connect
  category
  config
  connect

+ debug

  define
  delete
  description
  define
  delete
  description


@@ -259,9 +424,11 @@ Available commands:
  include
  index
  input
  include
  index
  input

+ kind

  load
  message
  new
  load
  message
  new

+ newgui

  output
  package
  print
  output
  package
  print


@@ -371,14 +538,19 @@ you get something like:
 \begin{verbatim}
 std
   Add 
 \begin{verbatim}
 std
   Add 

-  ... 
+  ConcatStrings          
+  Configuration          
+  Div   
+  ...
+  StringRelay            
+  StringSelect    

 user
   workspace
 > 
 \end{verbatim}
 
 Now \bbi knows the package \texttt{std} and the black boxes it provides,
 user
   workspace
 > 
 \end{verbatim}
 
 Now \bbi knows the package \texttt{std} and the black boxes it provides,

-such as the \texttt{'Add'} box. Remark that the 
+such as the \texttt{'Add'} box, the  \texttt{'ConcatStrings'}. Remark that the 

 content of \texttt{std} may vary from one version to another 
 as new black boxes might be added to it. 
 If you type:  
 content of \texttt{std} may vary from one version to another 
 as new black boxes might be added to it. 
 If you type:  


@@ -389,17 +561,17 @@ If you type:
 You get:
 \begin{verbatim}
 Black Box <std::Add>
 You get:
 \begin{verbatim}
 Black Box <std::Add>

- Adds its inputs
- By: laurent.guigues at creatis.insa-lyon.fr
- Categories : atomic box;math;
- * Inputs: 
-    'BoxExecute'     <bbtk::Void> : Any signal received by this input executes the box
-    'BoxProcessMode' <String>     : Sets the processing mode of the box (Pipeline | Always | Reactive)
-    'In1'            <Double>     : First number to add
-    'In2'            <Double>     : Second number to add
+  Adds its inputs
+  By : laurent.guigues@creatis.insa-lyon.fr
+  Categories : atomic box;math;
+  * Inputs : 
+     'BoxExecute'     <bbtk::Void> [signal] : Any signal received by this input executes the box
+     'BoxProcessMode' <String>     []       : Sets the processing mode of the box (Pipeline | Always | Reactive)
+     'In1'            <Double>     []       : First number to add
+     'In2'            <Double>     []       : Second number to add

   * Outputs : 
   * Outputs : 

-    'BoxChange'      <bbtk::Void> : Signal modifications of the box
-    'Out'            <Double>     : Result'In1'         <double>: First number to add
+     'BoxChange'      <bbtk::Void> [signal] : Signals modifications of the box
+     'Out'            <Double>     []       : Result

 \end{verbatim}
 
 Like previously, 
 \end{verbatim}
 
 Like previously, 


@@ -427,13 +599,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 make the difference between box \emph{types} 
-and \emph{instances} of box types. 
-The \texttt{Add} box of the package \texttt{std} is in fact 
-a \emph{type} of box, like \texttt{int} is a type of data 
+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 
 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. 


@@ -455,8 +627,8 @@ Complex Black Box <user::workspace>
     'a' <std::Add>
 \end{verbatim}
 
     'a' <std::Add>
 \end{verbatim}
 

-which means that \bbi's workspace now contains a black box 
-of type \texttt{std::Add} and name \texttt{a}.
+which means that \bbi workspace now contains a black box named \texttt{a},
+of type \texttt{std::Add}.

 
 Now look back at the help on \texttt{Add} boxes: 
 you can see that this type of box has two inputs, 
 
 Now look back at the help on \texttt{Add} boxes: 
 you can see that this type of box has two inputs, 


@@ -491,8 +663,10 @@ To process this special substrings, \bbi does:
 \item Converts the output of the box to a string if possible 
 (see below)
 \item Substitutes the result in the string to print
 \item Converts the output of the box to a string if possible 
 (see below)
 \item Substitutes the result in the string to print

+\item postpone an implicit 'new line' character to the string

 \end{enumerate}
 
 \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


@@ -525,7 +699,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}.


@@ -535,16 +709,29 @@ Good bye !
 \item A particular black box type (with full description) if you type \texttt{help <box-type-name>}. In particular, \texttt{help workspace} displays information on the content of the \texttt{'workspace'} black box, which stores the boxes created by the user (by \texttt{new}).
 \end{itemize}
 %\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).
 \item A particular black box type (with full description) if you type \texttt{help <box-type-name>}. In particular, \texttt{help workspace} displays information on the content of the \texttt{'workspace'} black box, which stores the boxes created by the user (by \texttt{new}).
 \end{itemize}
 %\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).

-\item \texttt{new} creates an instance of a black box. 
-\item \texttt{set} sets the value of an input of a black box. 
+\item \texttt{new} : creates an instance of a black box. 
+\item \texttt{set} : sets the value of an input of a black box. 

 \item In all \bbi, to reference the input called \texttt{i} 
 of a black box called \texttt{b} you must type \texttt{'b.i'}. 
 The same syntax holds for outputs.
 \item In all \bbi, to reference the input called \texttt{i} 
 of a black box called \texttt{b} you must type \texttt{'b.i'}. 
 The same syntax holds for outputs.

-\item \texttt{print} prints a string, substituting each substring of the form \$b.o\$ by the value of the output \texttt{o} of the black box \texttt{b}. 
-\item \texttt{exec} runs the process of a box if needed. 
-\item \texttt{quit} quits \bbi.
+\item \texttt{print} : prints a string, substituting each substring of the form \$b.o\$ by the value of the output \texttt{o} of the black box \texttt{b}. Note that an
+implicit trailing 'new line character' is added at the final string.
+\item \texttt{exec} : runs the process of a box if needed. 
+\item \texttt{quit} : quits \bbi.

 \end{itemize}
 \hrule
 \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}

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


@@ -552,8 +739,6 @@ The same syntax holds for outputs.
 \label{bbi-connecting-black-boxes}
 % ==========================================
 
 \label{bbi-connecting-black-boxes}
 % ==========================================
 

-LG : THE GUIDE IS UP TO DATE UNTIL HERE
-

 \BBTK allows to create 
 and execute processing chains, 
 also called \emph{pipelines}, 
 \BBTK allows to create 
 and execute processing chains, 
 also called \emph{pipelines}, 


@@ -579,6 +764,7 @@ A simple pipeline which adds 3 numbers}
 \end{center}
 \end{figure}
 
 \end{center}
 \end{figure}
 

+

 The \bbi instructions to create and execute this pipeline are:
 \begin{verbatim}
 > new Add a
 The \bbi instructions to create and execute this pipeline are:
 \begin{verbatim}
 > new Add a


@@ -588,12 +774,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, 
 6
 \end{verbatim}
 
 The first three commands build the pipeline, 

-the next three set its inputs and the last one 
-executes it and prints its output.
+the next three set \texttt{a} and \texttt{b} black boxes inputs and the last one 
+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 


@@ -605,10 +796,57 @@ 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, 

-but you can do more, thanks to particular black boxes called {\bf adaptors}.
+but you can do more, thanks to particular (hidden) black boxes called {\bf adaptors}.

 
 An adaptor is a black box which has at least one input, called \texttt{In}, 
 and at least one ouput called \texttt{Out} and whose role is to convert 
 
 An adaptor is a black box which has at least one input, called \texttt{In}, 
 and at least one ouput called \texttt{Out} and whose role is to convert 


@@ -810,6 +1048,11 @@ and you can use it like any other box, for example type:
 \end{verbatim}
 
 
 \end{verbatim}
 
 

+As a side note, we can say that, for consistency reasons, it would have been better to name  
+\texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3}, 
+since all the 'natural entry' of a box is named \texttt{In}, or\texttt{In}x if there are more than one  'natural
+entry'.
+

 % ==========================================
 \hrule
 \paragraph{Summary}
 % ==========================================
 \hrule
 \paragraph{Summary}


@@ -838,11 +1081,12 @@ into a text file and afterwards include that file in \bbi.
 Doing this, you start writing \bbi scripts.
 The conventionnal extension for such scripts is \texttt{bbs} 
 (black box script).
 Doing this, you start writing \bbi scripts.
 The conventionnal extension for such scripts is \texttt{bbs} 
 (black box script).

+For consistency reasons, you are requested to prepend \texttt{bb} to the name.

 
 For example, the \texttt{Add3} complex box we previously worked on 
 
 For example, the \texttt{Add3} complex box we previously worked on 

-can be defined in the \texttt{Add3.bbs} file:
+can be defined in the \texttt{bbAdd3.bbs} file:

 
 

-\begin{file}{Add3.bbs}
+\begin{file}{bbAdd3.bbs}

 \begin{verbatim}
 # Defines the Add3 black box which adds 3 doubles 
 load std
 \begin{verbatim}
 # Defines the Add3 black box which adds 3 doubles 
 load std


@@ -870,7 +1114,7 @@ are considered as comments by \bbi.
 To use this file in \bbi, use the \texttt{include} command:
 
 \begin{verbatim}
 To use this file in \bbi, use the \texttt{include} command:
 
 \begin{verbatim}

-> include Add3.bbs
+> include bbAdd3.bbs

 > help Add3
 Complex Black Box <user::Add3>
  adds 3 doubles
 > help Add3
 Complex Black Box <user::Add3>
  adds 3 doubles


@@ -896,7 +1140,7 @@ If the file has the \texttt{bbs} extension, you can ommit it and just type:
 Of course, you can include script files in other script files, 
 like in the following example:
 
 Of course, you can include script files in other script files, 
 like in the following example:
 

-\begin{file}{Add4.bbs}
+\begin{file}{bbAdd4.bbs}

 \begin{verbatim}
 # Defines the Add4 black box which adds 4 doubles 
 include Add3
 \begin{verbatim}
 # Defines the Add4 black box which adds 4 doubles 
 include Add3


@@ -916,19 +1160,35 @@ endefine
 \end{verbatim}
 \end{file}
 
 \end{verbatim}
 \end{file}
 

-TO DO: 
+% ==========================================
+\hrule
+\paragraph{Naming Conventions}
+%\hrule

 
 

-- naming conventions:  one cbb per file with the same name
-- search paths 
+\hrule
+% ==========================================
+\begin{itemize}
+\item
+File names: 
+For consistency reasons, you are requested to prepend \texttt{bb}, and postpone an extention \texttt{.bbs},
+to the names of the files that hold a \texttt{complex black box} definition.

 
 

+For example, the \texttt{Add3} complex box we previously worked on 
+can be defined in the \texttt{bbAdd3.bbs} file.
+\item
+Search Paths 
+\end{itemize}

 % ==========================================
 \hrule
 % ==========================================
 \hrule

+

 \paragraph{Summary}
 %\hrule
 \begin{itemize}
 \item The \texttt{include} command allows to include a script file in \bbi.
 \paragraph{Summary}
 %\hrule
 \begin{itemize}
 \item The \texttt{include} command allows to include a script file in \bbi.

-\item Lines starting with a \texttt{\#} are treated as comments in \bbi scripts.
+\item Lines starting with a \texttt{\#} or with a \texttt{\//} are treated as comments in \bbi scripts.
+\item Lines between a line starting with a \texttt{\//*} an a line starting with a \texttt{*\//} are treated as comments in \bbi scripts.

 \end{itemize}
 \end{itemize}

+

 \hrule
 % ==========================================
 
 \hrule
 % ==========================================
 


@@ -1070,6 +1330,11 @@ between double quotes, e.g. \texttt{"parameter with white spaces = gnu's not uni
 \label{bbi-widget}
 % ==========================================
 
 \label{bbi-widget}
 % ==========================================
 

+% ==========================================
+\subsubsection{Overwiew}
+\label{bbi-overview}
+% ==========================================
+

 If \bbi is compiled in graphical mode 
 (option \texttt{BUILD\_bbi\_GRAPHICAL} of \cmake, requires \wx),
 then you can use special black boxes which are 
 If \bbi is compiled in graphical mode 
 (option \texttt{BUILD\_bbi\_GRAPHICAL} of \cmake, requires \wx),
 then you can use special black boxes which are 


@@ -1080,7 +1345,7 @@ such as buttons, sliders, file open/save dialogs, etc.
 As first example, type the following commands in \bbi:
 \begin{verbatim}
 > load wx 
 As first example, type the following commands in \bbi:
 \begin{verbatim}
 > load wx 

-> new TextCtrl t
+> new InputText t

 > print $t.Out$\n
 \end{verbatim}
 
 > print $t.Out$\n
 \end{verbatim}
 


@@ -1091,29 +1356,33 @@ the \texttt{print} command.
 
 Type \texttt{help wx}, you get something like:
 \begin{verbatim}
 
 Type \texttt{help wx}, you get something like:
 \begin{verbatim}

-Package wx v1.0.0- eduardo.davila/laurent.guigues@creatis.insa-lyon.fr
- Basic graphical interface elements (slider, button ...) based on wxWidgets
- Black boxes: 
-   Button      : Button that gives a string 
-   FileDialog  : FileDialog widget (wxFileDialog)
-   RadioButton : RadioButton group widget (wxRadioButton)  0-9 entries
-   Sizer       : Sizer widget (wxSizer)
-   Slider      : Slider widget (wxSlider)
-   Split       : Split widget (wxSplitterWindow)
-   StaticText  : wxWidget Static text
-   TextCtrl    : TextCtrl widget (wxTextCtrl)
+ Package wx v1.0.0- info-dev@creatis.insa-lyon.fr
+ Basic graphical interface elements (sliders, buttons ...) based on wxWidgets
+ Black boxes : 
+   ColourSelector        : Colour Selector dialog (bbfication of wxColourSele...
+   ColourSelectorButton  : A button which displays a colour picker dialog whe...
+   CommandButton         : Button which executes bbi commands
+   DirectorySelector     : Pops up a directory selection dialog (wxDirDialog)
+   FileSelector          : Pops up a file selection dialog for reading or sav...
+   InputText             : A zone in which the user can enter a text (wxTextC...
+   LayoutLine            : LayoutLine widget (wxBoxSizer)
+   LayoutSplit           : Widget which splits a window in two fixed size par...
+   LayoutTab             : LayoutTab widget (wxNotebook)
+   OutputText            : Text zone to be inserted into a window (wxStaticTe...
+   RadioButton           : RadioButton group widget 0-9 entries
+   Slider                : Slider widget (wxSlider)

 \end{verbatim}
 
 You can reproduce the same experiment as above using a 
 \end{verbatim}
 
 You can reproduce the same experiment as above using a 

-\texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{TextCtrl}.
+\texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}.

 See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
 
 See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
 

-There are two kind of widgets: ``terminal'' widgets and ``container'' widgets.
-The \texttt{TextCtrl}, \texttt{FileDialog} or \texttt{Slider} widgets 
+There are two kinds of widgets: ``terminal'' widgets and ``container'' widgets.
+The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets 

 are ``terminal'' widgets. 
 are ``terminal'' widgets. 

-``container'' widgets are of another kind: they are made to 
+``container'' widgets are of another kind: they are designed to 

 contain other widgets in order to build larger dialog boxes. 
 contain other widgets in order to build larger dialog boxes. 

-For example, the \texttt{Split} widget is a container which 
+For example, the \texttt{LayoutSplit} widget is a container which 

 ``splits'' horizontally a window into two parts, 
 each part including another widget. 
 The size of the two parts can be adjusted by the user thanks 
 ``splits'' horizontally a window into two parts, 
 each part including another widget. 
 The size of the two parts can be adjusted by the user thanks 


@@ -1133,9 +1402,9 @@ load wx
 new Slider s1
 new Slider s2
 
 new Slider s1
 new Slider s2
 

-new Split s
-connect s.Child s1.Parent
-connect s.Child s2.Parent
+new LayoutSplit s
+connect  s1.Widget s.Widget1
+connect  s2.Widget s.Widget2

 
 print s1=$s1.Out$\\n
 print s2=$s2.Out$\\n
 
 print s1=$s1.Out$\\n
 print s2=$s2.Out$\\n


@@ -1143,50 +1412,87 @@ print s2=$s2.Out$\\n
 \end{file}
 
 First, the two sliders \texttt{s1} and \texttt{s2} are created.
 \end{file}
 
 First, the two sliders \texttt{s1} and \texttt{s2} are created.

-A \texttt{Split} box \texttt{s} is also created. 
+A \texttt{LayoutSplit} box \texttt{s} is also created. 

 The \texttt{connect} commands then ``includes'' the sliders in the 
 split ``container''. 
 The \texttt{connect} commands then ``includes'' the sliders in the 
 split ``container''. 

-The input \texttt{Parent} is common to all widget boxes: 
+The input \texttt{Widget} is common to all widget boxes: 

 every widget can be inserted into another widget. 
 every widget can be inserted into another widget. 

-The output \texttt{Child} is specific of \emph{container} 
+The outputs \texttt{Widget1},\texttt{Widget2}  are specific of \emph{container} 

 widgets 
 (in \bbi type \texttt{help Slider}: 
 widgets 
 (in \bbi type \texttt{help Slider}: 

-you will see the input \texttt{Parent}; 
-type \texttt{help Split}: 
-you will see the input \texttt{Parent} 
-and the output \texttt{Child}). 
-When you connect the \texttt{Child} output of a container 
-to the \texttt{Parent} input of a widget, 
+you will see the output \texttt{Widget}; 
+type \texttt{help LayoutSplit}: 
+you will see the inputs \texttt{Widget1} and \texttt{Widget2} 
+and the output \texttt{Widget}). 
+When you connect the \texttt{Widget} output of a container 
+to the \texttt{Widget}i input of a widget, 

 you order to include the widget in the container.
 Of course, the order of connection is important. 
 In our case, the slider \texttt{s1} is included first, 
 then the slider \texttt{s2}: \texttt{s1} will be placed 
 you order to include the widget in the container.
 Of course, the order of connection is important. 
 In our case, the slider \texttt{s1} is included first, 
 then the slider \texttt{s2}: \texttt{s1} will be placed 

-on top of \texttt{s2} (the \texttt{Split} box is 
+on top of \texttt{s2} (the \texttt{LayoutSplit} box is 

 implemented that way, but this is arbitrary choice).
 
 implemented that way, but this is arbitrary choice).
 

-For the moment, there are only \emph{two} container widgets in the \texttt{wx} package: 
-the \texttt{Split} widget we just described and the \texttt{Sizer} 
-widget, which can have multiple children and 
+Right now, there are only \emph{three} container widgets in the \texttt{wx} package: 
+the \texttt{LayoutSplit} widget we just described, the \texttt{LayoutLine} , and the \texttt{LayoutTab}
+widget. 
+
+The \texttt{LayoutLine} widget can have multiple children and 

 divides its window into as much parts as children, 
 each part of equal size. 
 divides its window into as much parts as children, 
 each part of equal size. 

-The orientation of the sizer can be changed by the input \texttt{Orientation}.
+The orientation of the \texttt{LayoutSplit} or of the \texttt{LayoutLine}  can be changed by the input \texttt{Orientation}.

 See the example \texttt{test/testSizer.bbs}.
 With only those two containers you can already create 
 complex dialog boxes (of course containers can be nested, which 
 leads to tree-like structures of widgets). 
 See the example \texttt{test/testSizer.bbs}.
 With only those two containers you can already create 
 complex dialog boxes (of course containers can be nested, which 
 leads to tree-like structures of widgets). 

-See the script \texttt{test/testSizerSplit.bbs} for an example.
+See the script \texttt{bbtk/share/bbtk/bbs/wx/appli/ExampleLayoutSplit.bbs} for an example.
+
+The \texttt{LayoutTab}  widget is based on the \texttt{wxNotebook.}

 
 One word about a special widget in the package \texttt{wx}: 
 the \texttt{Button}... to be continued.
 
 
 One word about a special widget in the package \texttt{wx}: 
 the \texttt{Button}... to be continued.
 

+% ==========================================
+\subsubsection{Deeper in the boxes}
+\label{bbi-deep-box}
+% ==========================================
+
+Any widget box has two mandatory Outputs :

 
 

-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}
+\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 \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}    
+
+Any widget box has two mandatory Inputs :
+\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() 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}   
+\end{itemize}
+
+Any widget box has five Inputs, that will be dealt with only if the box is not connected to the \emph{Widget}i of any \emph{Layout box} :  
+\begin{itemize}
+  \item {\bf\emph{WinHeight}} : Height of the window 
+  \item {\bf\emph{WinWidth}}  : Width of the window  
+  \item {\bf\emph{WinTitle}}  : Title of the window
+  \item {\bf\emph{WinClose}}  : Any received signal closes the window
+  \item {\bf\emph{WinHide}}   : Any received signal hides the window
+  \item {\bf\emph{WinDialog}} : When set to 'true', creates a \emph{dialog window}, that blocks the pipeline until it is closed (\emph{modal})   
+\end{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\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} 

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


@@ -1199,14 +1505,391 @@ TO DO:
 \label{bbi-more-on-packages}
 % ==========================================
 
 \label{bbi-more-on-packages}
 % ==========================================
 

+There are various others user-intended packages :
+\begin{itemize}
+\item{vtk} \\
+It contains some vtk based image processing filters :
+%   \begin{enumerate}
+
+     \paragraph{AppendPolyData}
+     Appends one of more polygonal datasets into a single polygonal dataset 
+
+     \paragraph{ConeSource}
+     Creates a Cone 
+
+     \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
+     
+     \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}
+
+\item{itk} \\
+It contains some itk based image processing filters :
+ 
+     \paragraph{BinaryThresholdImageFilter}
+     Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter) 
+
+     \paragraph{DICOMSeriesFileNames}
+     Reads a series from a DICOM directory as a 3D itk image     
+
+     \paragraph{ExtractImageFilter}
+     Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)     
+
+     \paragraph{ImageProperties}
+     Outputs different properties of an image (type, dimension, size, spacing, ...)      
+
+     \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)     
+
+     \paragraph{ImageReader}
+Generic itk image reader
+
+     \paragraph{ImageWriter}
+Generic itk image writer
+
+     \paragraph{ImageSeriesReader}
+Generic itk image series reader.
+
+     \paragraph{ResampleImageFilter}
+Resamples an image
+
+\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. 
+
+\item{wxvtk} \\
+
+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)
+     
+     \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}


@@ -1315,6 +1998,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}
 % ==========================================


@@ -1361,6 +2048,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. 


@@ -1405,7 +2101,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 
 


@@ -1413,18 +2108,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}.