% ==========================================
% ==========================================
-\subsubsection{\bbtk components}
+\subsubsection{{\bbtk} components}
% ==========================================
\BBTK includes:
\begin{itemize}
Remark that the list of categories is 'auto-extensible': each time a new box is created which belongs to a new category and the boxes list is regenerated, the new category appears in the list, holding the new box. The above list only contains the categories used in the packages provided with current \bbtk release.
\item {\bf\emph{ List of adaptors}}: The adaptors are a special type of black boxes that are used internally to perform type conversions. Although they are not end user intended, you may see their list. Adaptors belong to the \texttt{adaptor} category.
\end {itemize}
- For each box, the html \texttt{Help} provides the informations necessary to use it: its name, its purpose, the descriptions of its inputs/outputs and the name of the package (or script file) that is to be loaded. Additionally, for all boxes but the atomic ones (i.e. for all boxes defined in \bbs script language), the corresponding script is available via [\texttt{source}] link. Actually, by clicking on this link, one loads the script into the \texttt{Files} area where it can be analyzed, edited and executed.
+ For each box, the html \texttt{Help} provides the informations necessary to use it: its name, its purpose, the descriptions of its inputs/outputs and the name of the package (or script file) that is to be loaded. Note that for a given box only the inputs/outputs listed in white cells are of actual interest. The remaining ones, grouped after them in colored cells, are standard (have the same names and purpose) in all atomic boxes. Additionally, for all boxes but the atomic ones (i.e. for all boxes defined in \bbs script language), the corresponding script is available via [\texttt{source}] link. Actually, by clicking on this link, one loads the script into the \texttt{Files} area where it can be analyzed, edited and executed.
% ==========================================
\subsubsection{The Package Browser}
> 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}
\item The \texttt{include} instructions load the necessary packages.
\item \texttt{FileSelector} will pop, at run time, a File Selector dialog box that will output the user-selected file name.
\item \texttt{ImageReader} will read any itk readable file, the name of which is passed as a std::string, and return a pointer on an itk image.
- \item \texttt{Slider} will pop, at run time, a Slider widget that will output an integer number, used later as a slice number.
- \item \texttt{Viewer2D} displays a plane, the number of which is specified by an integer.
- \item \texttt{connect fileDialog.Out reader.In} plugs the output of the File Selector (a \texttt{std::string}) to the input of the reader (a \texttt{std::string}, too).
- \item \texttt{connect reader.Out viewer.In} plugs the output of the reader \\(a \texttt{bbtk::any<bbitk::ImagePointer>} which is a type defined by the
+ \item \texttt{Viewer2D} will display a two-dimensional image.
+ \item \texttt{connect fileDialog.Out reader.In} plugs the output of the File Selector (a \texttt{std::string}) to the input of the Image Reader (a \texttt{std::string}, too).
+ \item \texttt{connect reader.Out viewer.In} plugs the output of the Image Reader \\(a \texttt{bbtk::any<bbitk::ImagePointer>} which is a type defined by the
itk package, and which can hold any itk image pointer) to the input of the Viewer (a \texttt{vtkImageData *})
-\item \texttt{connect slider.Out viewer.Slice} plugs the output of the slider (an \texttt{int}) to an other output (named Slide) of the viewer.
- \item \texttt{connect slider.BoxChange viewer.BoxExecute} says the viewer that it must re process itself any time the slider is modified.
-\item \texttt{exec viewer} processes the viewer.
+ \item \texttt{exec viewer} processes the Viewer.
\end{itemize}
-This would correspond to the graph in figure \ref{bbi-simplegraph}
-
+This would correspond to the graph in figure \ref{bbi-verysimplegraph}.
\begin{figure}[!ht]
-\caption{\label{bbi-simplegraph}(Very) simple Graph of a (very) simple pipeline}
+\caption{\label{bbi-verysimplegraph}(Very) simple Graph of a (very) simple pipeline}
\begin{center}
-\includegraphics[width=0.8\textwidth]{bbi-simplegraph.png}
+\includegraphics[width=0.8\textwidth]{bbi-verysimplegraph.png}
\end{center}
\end{figure}
and at least one output called \texttt{Out} and the role of which is to convert
a data of the type of \texttt{In}
into a data of the type of \texttt{Out} (other inputs or outputs may serve
-to parameter the adaptor or retrieve other useful information).
+to parameter the adaptor or retrieve other useful information). In the example above the appropriate adaptor that converts \texttt{bbtk::any<bbitk::ImagePointer>} into \texttt{vtkImageData *} is provided in the package \texttt{itkvtk}.
-Under \bbStudions, if you type :
+Most of the useful standard adaptors are provided in the package \texttt{std}. Under \bbStudions, if you type :
\begin{verbatim}
> load std
> help std all
% ==========================================
% ==========================================
-\subsection{Creating complex black boxes}
+\subsection{Writing scripts files}
+\label{bbi-writing-scripts}
+% ==========================================
+
+Now that you know how to connect the existing black boxes, you will soon realize that you want to save and reuse some sequences of commands that you are particularly glad of. In the following subsections you will learn how to write ``simple'' pipeline applications and new complex black boxes built of existing black boxes.
+
+% ==========================================
+\subsubsection{Stand-alone pipeline applications}
+\label{sec:pipeline-appli}
+% ==========================================
+
+Let us take an example similar to that from section \ref{bbi-connecting-black-boxes}:
+
+\begin{verbatim}
+> include vtk
+> include wx
+> include itk
+> include wxvtk
+> include itkvtk
+
+> new DirectorySelector dirSelect
+> new DICOMDirReader reader
+> new Slider slider
+> new Viewer2D viewer
+
+> connect dirSelect.Out reader.In
+> connect reader.Out viewer.In
+> connect slider.Out viewer.Slice
+> connect slider.BoxChange viewer.BoxExecute
+> set slider.ReactiveOnTrack 1
+
+> exec viewer
+\end{verbatim}
+
+This is an elementary DICOM-image slicer (fig.~\ref{fig:simpleslicer}) designed to view 3D medical images slice-by-slice. The image is to be composed of a series of DICOM files contained in a separate directory. The index of the slice to be displayed is selected by means of a slider. The command \texttt{connect slider.BoxChange viewer.BoxExecute} permits the Viewer to update the display every time the output of the Slider changes. The command \texttt{set slider.ReactiveOnTrack 1} on its turn makes that the output of the Slider changes every time its cursor is moved, while the default behavior is to change only when the mouse-button is released after moving the cursor.\\
+
+\begin{figure}[!ht]
+\caption{ Graph of a (very) simple 3D slicer}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{bbi-simplegraph.png}
+\end{center}
+\label{fig:simpleslicer}
+\end{figure}
+
+Despite its simplicity, this application may already be useful. If you want to reuse it, you have to save the \bbs commands in a text file. The conventional (and mandatory) extension for such script files is \texttt{bbs}
+(black box script). For example, our elementary 3D DICOM-image slicer
+can be defined in the following file:
+
+\begin{file}{my\_slicer.bbs}
+\begin{verbatim}
+# my_slicer.bbs: elementary 3D image slicer"
+/*
+ the 3D image has to be stored in a separate directory
+ as a series of DICOM files representing the 2D slices
+*/
+
+include vtk
+include wx
+include itk
+include wxvtk
+include itkvtk
+
+new DirectorySelector dirSelect
+new DICOMDirReader reader
+new Slider slider
+new Viewer2D viewer
+
+connect dirSelect.Out reader.In
+connect reader.Out viewer.In
+connect slider.Out viewer.Slice
+connect slider.BoxChange viewer.BoxExecute
+set slider.ReactiveOnTrack 1
+
+exec viewer
+\end{verbatim}
+\end{file}
+
+Lines starting with a \texttt{\#} character or with double slash (\texttt{\//\//}) are ignored, they
+are considered as comments by the interpreter. A longer comment can be placed between the marks \texttt{\//*} and \texttt{*\//}. Each of this mark is to be placed alone in a separate line, like in the example.\par
+
+To use this file in \bbStudions, click on the \texttt{include} button, and browse your filestore to find the file. You can also type the command:
+
+\begin{verbatim}
+> include my_slicer.bbs
+\end{verbatim}
+
+provided that \bbStudio knows the path to the desired \texttt{bbs} file.
+See the section \ref{The_configuration_file} to learn about the configuration file and the way to add a new path to it. Note that, if you modify the configuration file, you will have to close \bbStudio and run it again, so that the new configuration be taken into account.
+
+Actually, since the file has the \texttt{bbs} extension, you can omit it and just type:
+\begin{verbatim}
+> include my_slicer
+\end{verbatim}
+
+% ==========================================
+\hrule
+
+\paragraph{Summary}
+%\hrule
+\begin{itemize}
+\item The \texttt{include} command tells the interpreter to include a script file.
+\item Lines starting with \texttt{\#} or \texttt{\//\//} are considered as comments by the interpreter.
+\item A longer comment can be written between a line marked \texttt{\//*} and a line marked \texttt{*\//}.
+\end{itemize}
+
+\hrule
+% ==========================================
+
+% ==========================================
+\subsubsection{Creating complex black boxes}
\label{bbi-complex-black-boxes}
% ==========================================
\end{center}
\end{figure}
-The \bbs commands to define this complex black box are
-the following:
+The \bbs script file defining this complex black box will be as follows:
\begin{verbatim}
-> load std
-> define Add3
-> new Add a
-> new Add b
-> connect a.Out b.In1
-> author "myself"
-> description "adds 3 doubles"
-> input x a.In1 "first double to add"
-> input y a.In2 "second double to add"
-> input z b.In2 "third double to add"
-> output result b.Out "output"
-> endefine
+# bbAdd3.bbs: defines the Add3 black box which adds 3 doubles
+load std
+
+define Add3
+ author "myself"
+ description "adds 3 doubles"
+
+ # Pipeline creation
+ new Add a
+ new Add b
+ connect a.Out b.In1
+
+ # Inputs definition
+ input x a.In1 "first double to add
+ input y a.In2 "second double to add
+ input z b.In2 "third double to add"
+ # Output definition
+ output result b.Out "output"
+endefine
\end{verbatim}
Explanations:
\item The command \texttt{define} then starts the definition
of the complex box type that will be called \texttt{Add3}.
\item The next three lines define the pipeline,
-exactly in the same way as outside a complex box definition.
+exactly in the same way as outside of a complex box definition.
\item The commands \texttt{author}, \texttt{description}, \texttt{input}
and \texttt{output} are specific to complex boxes definition:
\begin{itemize}
new box type.
\end{itemize}
-After this definition, if you ask for help
-on packages, you get:
+If you type the command \texttt{include bbAdd3} and then you ask for help
+on the contens of the \texttt{user} package, you get:
+
\begin{verbatim}
-> help packages
-std
- Add
- ...
-user
- Add3
- workspace
+> help user
+ Package user - internal
+ User defined black boxes
+ Black boxes :
+ Add3 : adds three numbers
+ workspace : User's workspace
\end{verbatim}
The \texttt{user} package now contains a new black box type, called
% ==========================================
% ==========================================
-\subsection{Writing scripts files}
-\label{bbi-writing-scripts}
-% ==========================================
-
-Once you have defined a new type of complex box, you
-may like to reuse it. To do this, you can simply
-write the \bbs commands defining the new box
-into a text file and afterwards include that file anywhere you need.
-Doing this, you start writing \bbs scripts.
-The conventional (and mandatory) 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
-can be defined in the \texttt{bbAdd3.bbs} file:
-
-\begin{file}{bbAdd3.bbs}
-\begin{verbatim}
-# Defines the Add3 black box which adds 3 doubles
-load std
-
-define Add3
- # I am the author
- author "myself"
- description "adds 3 doubles"
- # Pipeline creation
- new Add a
- new Add b
- connect a.Out b.In1
- # Inputs definition
- input x a.In1 "first double to add
- input y a.In2 "second double to add
- input z b.In2 "third double to add"
- # Output definition
- output result b.Out "output"
-endefine
-\end{verbatim}
-\end{file}
-
-Lines starting with a \texttt{\#} character or a \texttt{\//\//} character are ignored, they
-are considered as comments by the interpreter.
-To use this file in \bbStudions, click on the \texttt{include} button, and browse your filestore to find the file.
-
-\begin{verbatim}
-> include bbAdd3.bbs
-> help Add3
-Complex Black Box <user::Add3>
- adds 3 doubles
- By : myself
- * Inputs :
- 'x' <double> [] : first double to add
- 'y' <double> [] : second double to add
- 'z' <double> [] : third double to add
- * Outputs :
- 'result' <double> [] : output
- * Boxes :
- 'a' <std::Add>
- 'b' <std::Add>
-\end{verbatim}
-
-If the file has the \texttt{bbs} extension, you can omit it and just type:
-\begin{verbatim}
-> include bbAdd3
-\end{verbatim}
-provided that \bbStudio knows the path to the desired \texttt{bbs} file.
-See the section \ref{The_configuration_file} to learn about the configuration file and the way to add a new path to it. Note that, if you modify the configuration file, you will have to close \bbStudio and run it again, so that the new configuration be taken into account.
-
-\subsection{Creating complex black boxes that use complex black boxes}
+\subsubsection{Creating complex black boxes that use complex black boxes}
\label{bbi-complex-complex-black-boxes}
-
+% ==========================================
Of course, you can include script files in other script files,
like in the following example:
Only the inputs \texttt{x, y, z} of box the \texttt{a} and the input \texttt{In2} of the box \texttt{b} are of interest for the end user, but he/she does not need to care neither about the inner boxes name, nor about the names of their inputs.\\
The author of the complex box has the ability to give these inputs meaningful names (here \texttt{In1, In2, In3, In4}) and to properly document them.
-\subsection{Naming Conventions}
+\subsubsection{Naming Conventions}
\label{bbi-Naming Conventions}
% ==========================================
% ==========================================
-\subsection{Creating and using command-line applications}
+\subsubsection{Creating and using command-line applications}
\label{bbi-command-line-app}
% ==========================================
git://git.creatis.insa-lyon.fr / bbtk.git / commitdiff
