Note: pdf version of this User's Guide can be retrieved from the following URL:\\
\url{http://www.creatis.insa-lyon.fr/creatools/documentation}
% ==========================================
-\subsection{What is bbtk ?}
+\subsection{What is bbtk?}
% ==========================================
-\BBTK(\bbtkns) is a set of tools
-(\CPP libraries and executables)
-providing a \CPP framework for the definition
-of elementary processing \emph{units}, called {\bf black boxes},
-and the definition and execution of processing \emph{chains}
+\BBTK(\bbtkns) is a set of tools (\CPP libraries and executables)
+providing a \CPP framework for the definition of elementary processing \emph{units}, called {\bf black boxes}, and the definition and execution of processing \emph{chains}
made up of these black boxes. \\
%It's a part of the \texttt{Creatools suite} composed mainly of :
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 boxe, 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. 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}
\label{Package_Browser}
% ==========================================
-The package browser is a standalone application that
+The package browser is a standalone application \texttt{bbPackageBrowser}, which
dynamically loads and queries the available packages.
It is thus a smarter tool than the static html documentation.
-You can run it with the command \texttt{bbPackageBrowser}
-or in \bbStudio using either the button of the 'Command' part
-or the menu entry 'Windows$>$Start Package Browser'.
-Remark that it may take some time to start because it loads all available
+You can run it independently or from \bbStudio using either the button labeled \texttt{Start Package Browser} of the 'Command' part or the corresponding entry in the menu 'Windows'.
+Note that it may take some time to start because it loads all available
packages at start.
Its appearance is reproduced in figure \ref{imPackage_Browser}.
\begin{figure}[!ht]
-\caption{\label{imPackage_Browser}The Package Browser}
+\caption{The Package Browser}
\begin{center}
\includegraphics[width=0.6\textwidth]{Package_Browser.png}
\end{center}
+\label{imPackage_Browser}
\end{figure}
-It allows you to find boxes using a multi-criteria filtering principle :
-The boxes listed are the one whose attributes match \emph{all} the
+It allows you to find boxes by use of a multi-criteria filtering principle:
+the boxes listed are the ones the attributes of which match \emph{all} the
words entered in the 'Filter' part.
-You can get the whole description of a given box clicking on its name.
-
-Warnings :
+You can get the whole description of a given box by clicking on its name.
+\\
+Warnings:
\begin{itemize}
-\item It's case sensitive, i.e '\texttt{Button}'
-will give different results than '\texttt{button}'
-\item You have to press enter in the filter zone to update the boxes list
-\item A filtering string only has to match a subpart of the related attribute of a box.
+\item It is case sensitive, i.e '\texttt{Button}'
+will give different results than '\texttt{button}'.
+\item After typing a filtering string, you have to validate it by pressing the 'Enter' key, in order to update the display of the boxes list.
+\item A filtering string only needs to match a subpart of the related attribute of a box.
For example, entering 'utt' in the 'Name' attribute will match a box called 'Button'.
\end{itemize}
-Attributes :
+Attributes:
\begin {itemize}
-\item Package : The name of the package to which the box belongs (e.g. \texttt{wxvtk}, \texttt{std})
-\item Name : The name of a box or an application (e.g. \texttt{Reader}, \texttt{example})
-\item Description : A part of the description of a box (e.g. \texttt{3D}, \texttt{image})
-\item Category : The categories of the box (e.g. \texttt{demo})
-\item Input/Output Type : The \CPP type of an input or output (e.g. \texttt{int}, \texttt{vtkImageData*}, \texttt{std::string})
-\item Input/Output Nature : The \texttt{nature} of an input or output (e.g. \texttt{file name}, \texttt{signal})
+\item \texttt{Package}: The name of the package to which the box belongs (e.g. \texttt{wxvtk}, \texttt{std}).
+\item \texttt{Name}: The name of a box or an application (e.g. \texttt{Reader}, \texttt{example}).
+\item \texttt{Description}: A part of the description of a box (e.g. \texttt{3D}, \texttt{image}).
+\item \texttt{Category}: The categories of the box (e.g. \texttt{demo}).
+\item \texttt{Input/Output Type}: The \CPP type of an input or output (e.g. \texttt{vtkImageData*}, \texttt{std::string}).
+\item \texttt{Input/Output Nature}: The \texttt{nature} of an input or output (e.g. \texttt{file name}, \texttt{signal}).
\end {itemize}
%If 'Show widgets' is selected then
\label{sec:demos_examples}
% ==============================================
-In the 'Help' part (See figure \ref{HelpContents}), select \texttt{Examples} link.
+As previously mentioned, the links \texttt{Demos} and \texttt{Examples} in the 'Help' part (See figure \ref{HelpContents}), give access to special complex boxes from the respective categories. Here, we use an example, both to illustrate the use of this help and to explain a short \bbs script.\\
\begin{figure}[!ht]
\caption{\bbStudio 'Help' panel}
\end{figure}
%\newpage
-
-You will get a list of examples (See figure \ref{example}).
+Select \texttt{Examples} link. You will get a list of examples (See figure \ref{example}).
Note: due to an unfixed bug in Linux, you have to click on 'reload' to get it. \\
\label{exampleSlider}
\end{figure}
-You can see information on the example and
+You can see information about the example and
the graphical representation of the workflow defined by the script
(the elementary boxes that compose it, and their connections, see figure \ref{exampleSlider}).
%\newpage
-Just a few words on what you saw :
+Just a few words on what you saw:
\begin{itemize}
-\item{In the source code of the script}: \\
+\item{In the source code of the script}:
\begin{verbatim}
load std
load wx
\end{verbatim}
- These \bbs commands load the packages std and wx
+ These \bbs commands load the packages \texttt{std} and \texttt{wx}
\begin{verbatim}
new Slider slider
set slider.ReactiveOnTrack 1
\emph{slider} passes \emph{text} its output value)\footnote{Yes, we know : all the arrows (graphical interface pipeline arrows and data processing arrows)
are blue; using different colors is planned for next release...}.
- You can get a much more detailled graph,
+ You can get a much more detailed graph,
like in figure \ref{LargeGraph},
just clicking on the button
- '\texttt{graph (detailled)}' in the toolbar of the \texttt{Command} part.
+ '\texttt{graph (detailed)}' in the toolbar of the \texttt{Command} part.
\begin{figure}[!ht]
- \caption{Detailled graphical representation of a pipeline}
+ \caption{Detailed graphical representation of a pipeline}
\begin{center}
\includegraphics[width=0.75\textwidth]{LargeGraph.png}
\end{center}
\subsection{The Menu}
% ==============================================
-At last, let us have a look at \bbStudio menu.(See figure \ref{themenu})
+At last, let us have a look at \bbStudio menu (see figure \ref{themenu}).
\begin{figure}[!ht]
\caption{The bbStudio menu}
% ==========================================
\subsection{The commands}
% ==========================================
-In \bbStudio, try typing in the \texttt{Command} area (in what follows,
-the commands entered by the user will be preceded by a prompt \textgreater):
+In the sequel the commands entered by the user will be preceded by a prompt (\texttt{>}).
+To get started, type in the \texttt{Command} area:
\begin{verbatim}
> help
\end{verbatim}
-you get the list of the commands of the interpreter :
+you get the following list of the commands recognized by the interpreter:
\begin{verbatim}
Available commands :
author
unload
\end{verbatim}
-To get help on a particular command type \texttt{help <command-name>},
-for example:
+To get the help on a particular command, type \texttt{help <command name>}, e.g.:
\begin{verbatim}
> help author
\end{verbatim}
-gives :
+gives:
\begin{verbatim}
usage : author <string>
- Adds the string <string> to the author information of the black box being defined
+ Adds the string <string> to the author information
+of the black box being defined
\end{verbatim}
The \texttt{help} command has multiple usages.
-It is used to get help about almost anything in the interpreter!
-Type \texttt{'help help'} to get help on the \texttt{help} command itself :
+It is used to get help about almost anything in the interpreter, including the \texttt{help} command itself! Indeed:
\begin{verbatim}
> help help
+\end{verbatim}
+
+gives:
+\begin{verbatim}
usage :
- (1) help
- (2) help <command name>
- (3) help packages [all]
-
(4) help <package name> [all]
- (5) help <black box type>
- (6) help <black box name>
+ (1) help
+ (2) help <command name>
+ (3) help packages [all]
+ (4) help <package name> [all]
+ (5) help <black box type>
+ (6) help <black box name>
Effect :
- (1) Lists all available commands;
- (2) Prints help on a particular command;
- (3) Lists the packages loaded and their black boxes.
- Add 'all' to list adaptors;
- (4) Prints short help on the black boxes of a package.
- Add 'all' to include adaptors;
- (5) Prints full help on a black box type;
- (6) Prints information on the inputs, outputs and connectionns
+ (1) Lists all available commands;
+ (2) Prints help on a particular command;
+ (3) Lists the packages loaded and their black boxes.
+ Add 'all' to list adaptors;
+ (4) Prints short help on the black boxes of a package.
+ Add 'all' to include adaptors;
+ (5) Prints full help on a black box type;
+ (6) Prints information on the inputs, outputs and connections
of a black box instance.
\end{verbatim}
At start the interpreter does not know any black box.
If you type \texttt{'help packages'}, which is
-the third form of the \texttt{help} command, you get :
+the third form of the \texttt{help} command, you get:
\begin{verbatim}
> help packages
user
workspace
\end{verbatim}
-which means that the interpretor only knows one package
+which means that the interpreter only knows one package
(library of black boxes) called \texttt{user}
and which contains a black box called \texttt{workspace}.
The \texttt{user} package is an internal package of the interpreter,
which stores user-defined black box types.
At start, it already contains
-one box, called \texttt{workspace}.
-\texttt{workspace} is a special type of black box,
-called complex black box, whose purpose is
+one box, called \texttt{workspace},
+which is a special type of black box,
+called complex black box, the purpose of which is
to store other black boxes.
Any black box you create in \bbStudio is stored
in \texttt{workspace}
(this will be explained in details in sections
\ref{bbi-writing-scripts} and
-\ref{bbi-more-on-complex-black-boxes}).
+\ref{bbi-command-line-app}).
-If you type \texttt{'help workspace'}, you get :
+If you type \texttt{'help workspace'}, you get:
\begin{verbatim}
> help workspace
Complex Black Box <user::workspace>
The \texttt{std} package is the ``standard'' package,
which contains basic useful black boxes.
-To load it, type :
+To load it, type:
\begin{verbatim}
> include std
\end{verbatim}
-Then if you type :
+Then if you type:
\begin{verbatim}
> help packages
\end{verbatim}
-you get something like :
+you get something like:
\begin{verbatim}
-
std
- ASCII : ascii codes sequence to string - string to ascii...
- Add : Adds its inputs
- ConcatStrings : String concatenation
- Configuration : Gets configuration informations
- Div : Divides its inputs
- ExecBbiCommand : Executes bbi commands
- ExecSystemCommand : Executes system (O.S.) commands
- GetVectorCharElement : Gets the i-th element from the input vector (std...
+ ASCII
+ Add
+ ConcatStrings
+ Configuration
+ Div
+ ExecBbiCommand
+ ExecSystemCommand
+ GetVectorCharElement
...
- MagicBox : Takes *any kind* of data and copies it to its ou...
- MakeFileName : Makes a kosher file name
- Mul : Multiplies its inputs
- MultipleInputs : This box has multiple Void inputs and one Void o...
- StringRelay : Just copies the value of its input to its output...
- StringSelect : Outputs the string set to the ith input Ini (In0...
+ MagicBox
+ MakeFileName
+ Mul
+ MultipleInputs
+ StringRelay
+ StringSelect
user
workspace
\end{verbatim}
Now the interpreter knows the package \texttt{std} and the black boxes it provides,
such as the \texttt{Add} box, the \texttt{ConcatStrings} box, and so on. 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 :
+as new black boxes might be added to it. Note that you will get a more detailed information about the package loaded (here \texttt{std}) if you type:
+\begin{verbatim}
+> help std
+\end{verbatim}
+
+Indeed, each of the items listed is followed by its short description:
+\begin{verbatim}
+ Package std v1.0.0- laurent.guigues at creatis.insa-lyon.fr
+ Basic useful boxes
+ Black boxes :
+ ASCII : ascii codes sequence to string - ...
+ Add : Adds its inputs
+ ConcatStrings : String concatenation
+ Configuration : Gets configuration informations
+ ...
+\end{verbatim}
+Additionally, in the right part of the screen ('Help' zone) the corresponding html page is displayed.
+
+Now, if you type:
\begin{verbatim}
> help Add
\end{verbatim}
-You'll get a text help, in the 'Message' part :
+{\bbStudions} displays the appropriate html page in the 'Help' part (see figure : \ref{HelpAdd}), and the following text in the 'Message' part:
\begin{verbatim}
Black Box <std::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
+ Adds its inputs
+ By : laurent.guigues@creatis.insa-lyon.fr
+ Categories : atomic box;math;
+ * Inputs :
+ 'BoxExecute' <bbtk::Void> [signal] : Any signal received...
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 :
- 'BoxChange' <bbtk::VoidS> [signal] : Signals modifications of the box
- 'Out' <Double> [] : Result
+ 'BoxProcessMode' <String> [] : Sets the processing mode...
+ (Pipeline | Always |...
+ 'In1' <Double> [] : First number to add
+ 'In2' <Double> [] : Second number to add
+ * Outputs :
+ 'BoxChange' <bbtk::VoidS> [signal]: Signals modifications...
+ 'Out' <Double> [] : Result
\end{verbatim}
-After loading the package it belongs to, you can create an \emph{instance} of an \texttt{Add} box by
-the command \texttt{new}:
+\begin{figure}[!ht]
+\caption{The html Help}
+\begin{center}
+\includegraphics[width=0.7\textwidth]{HelpAdd.png}
+\end{center}
+\label{HelpAdd}
+\end{figure}
+
+These descriptions
+(provided by the author of the box) include:
+the author(s) of the box (usually e-mail address(es)) and
+the categories to which the box belongs,
+the lists of inputs and outputs of the box.
+For each input or output, \bbi provides
+its \emph{name} ,
+its \emph{type} (between \texttt{<} and \texttt{>}, e.g. \texttt{<Int>})
+and a description.
+Remark that the box \texttt{Add} is not a 'complex' black box
+but an 'atomic' box, hence its help does not
+include a pipeline graph.
+
+You can see that \texttt{Add} boxes have two inputs,
+with name \texttt{In1} and \texttt{In2},
+and an output, named \texttt{Out}.
+
+After loading the package it belongs to, you can create an \emph{instance} of an \texttt{Add} box, by use of the command \texttt{new}:
\begin{verbatim}
> new Add a
\end{verbatim}
-The \texttt{'a'} at the end is the \emph{name} of the instance,
+Here \texttt{'a'} is the \emph{name} of the instance,
which will be used to reference it later.
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
+a \emph{box type}, like \texttt{int} is a data type
+in \texttt{C} language. 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
-name is \texttt{i}.
+a \texttt{C} code declares a variable of type \texttt{int}, the
+name of which is \texttt{i}.
Of course, like in \texttt{C} Language, you can declare multiple boxes of the
-same type in \bbi. \\
+same type in \bbs.
-After the creation of the box \texttt{a}, type :
+After the creation of the box \texttt{a}, type:
\begin{verbatim}
> help workspace
\end{verbatim}
'a' <std::Add>
\end{verbatim}
-which means that \bbi workspace now contains a black box named \texttt{a},
-of type \texttt{std::Add}.
-
-
-Type
+This means that \bbi workspace now contains a black box named \texttt{a},
+of type \texttt{std::Add}. If you type:
\begin{verbatim}
-Help Add
+> help workspace
\end{verbatim}
- and have a look to the 'Help' Part (see figure : \ref{HelpAdd})
-
-\begin{figure}[!ht]
-\caption{\label{HelpAdd}The html Help}
-\begin{center}
-\includegraphics[width=0.7\textwidth]{HelpAdd.png}
-\end{center}
-\end{figure}
-
-You can see a description
-(the one which was provided by the author of the box),
-the author(s) of the box (usually e-mail adress(es)) and
-the categories to which the box belongs.
-Finally comes the lists of inputs and outputs of the box.
-For each input or output, \bbi provides
-its \emph{name} ,
-its \emph{type} (between \texttt{<} and \texttt{>}, e.g. \texttt{<Int>})
-and a description.
-Remark that the box \texttt{Add} is not a 'complex' black box
-but an 'atomic' box, hence its help does not
-include a pipeline graph.
+You get information about the actual instance \texttt{a} of the box type \texttt{std::Add}. It gives something like this:
+\begin{verbatim}
+> help a
+ Black Box 'a' <std::Add>
+ * Inputs :
+ 'BoxExecute' = '? (no adaptor found)' [Modified]
+ 'BoxProcessMode' = 'Pipeline' [Modified]
+ 'In1' = '0' [Modified]
+ 'In2' = '0' [Modified]
+ * Outputs :
+ 'BoxChange' = '? (no adaptor found)' [Out-of-date]
+ 'Out' = '0' [Out-of-date]
+\end{verbatim}
+Note that the inputs appear as \texttt{[Modified]}, since the code defining the box type includes an initialization of the inputs. On the other hand, the outputs appear as \texttt{[Out-of-date]}, as the box has not yet been executed and therefore its outputs have not been updated. See the second part of this section to learn more about the updating. For a moment, just note that one way to process the box \texttt{a} is to use the command:
+\begin{verbatim}
+> exec a
+\end{verbatim}
-You can see that \texttt{Add} boxes have two inputs,
-with name \texttt{In1} and \texttt{In2},
-and an output, with name \texttt{Out}.
+This command does not display anything (except if the
+box itself displays something in its processing).
+It just processes the box if needed. In our case, the result can be seen as follows:
+\begin{verbatim}
+> exec a
+> help a
+ Black Box 'a' <std::Add>
+ * Inputs :
+ 'BoxExecute' = '? (no adaptor found)' [Up-to-date]
+ 'BoxProcessMode' = 'Pipeline' [Up-to-date]
+ 'In1' = '0' [Up-to-date]
+ 'In2' = '0' [Up-to-date]
+ * Outputs :
+ 'BoxChange' = '? (no adaptor found)' [Up-to-date]
+ 'Out' = '0' [Up-to-date]
+\end{verbatim}
+Note the change of status of all the inputs and outputs (\texttt{[Up-to-date]}).
+In practice, the command \texttt{exec} is useful to execute boxes that do not have any output,
+such as boxes that write something to a file or, display a
+graphical interface, and so on.
-You can set the input \texttt{In1}
-of the \texttt{Add} box \texttt{a} to the value $1$
-by the command :
+Now, let us set the input \texttt{In1}
+of the \texttt{Add} box \texttt{a} to the value $3.5$
+by the command:
\begin{verbatim}
-> set a.In1 1
+> set a.In1 3.5
\end{verbatim}
-Similarly, setting the input \texttt{In2} of \texttt{a} to the value $2$
-is done with :
+Similarly, setting the input \texttt{In2} of \texttt{a} to the value $4.3$
+is done with:
\begin{verbatim}
-> set a.In2 2
+> set a.In2 4.3
\end{verbatim}
-And you print the output \texttt{Out} of the box \texttt{a} with :
+And you print the output \texttt{Out} of the box \texttt{a} with:
\begin{verbatim}
> print "result=$a.Out$"
-result=3
+result=7.8
\end{verbatim}
In the string passed to the \texttt{print} command,
each substring enclosed between a couple of \$ is considered
as the name of an output of a box.
-To process this special substrings, the interpretor :
+To process these special substrings, the interpreter:
\begin{enumerate}
\item Processes the box if needed (see below)
\item Converts the output of the box to a string if possible
%\paragraph
-Box processing is needed if :
+Box processing is needed if:
\begin{itemize}
-\item either at least input has changed since last processing
+\item either at least one input has changed since last processing
\item or the input \texttt{'BoxProcessMode'} of the box is set to
\texttt{'Always'}, which forces box reprocessing.
\end{itemize}
-Note that all boxes have an input named \texttt{'BoxProcessMode'}.
-
-Another way to process the box \texttt{a} is to issue the command :
-\begin{verbatim}
-> exec a
-\end{verbatim}
-
-however this command does not display anything (except if the
-box itself displays something in its processing).
-It just processes the box if needed.
-This command is used to execute boxes that do not have any output,
-such as boxes that write something to a file or, display a
-graphical interface, and so on. \newline
+Note that all boxes have an input named \texttt{'BoxProcessMode'}. \newline
%To exit \bbi, type :
%\begin{verbatim}
\paragraph{Summary}
%\hrule
\begin{itemize}
-\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 :
+\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 A particular command if you type \texttt{help <command-name>}.
\item All available packages and their boxes (without description) if you type \texttt{help packages}.
\item A particular package and its boxes (with brief description) if you type \texttt{help <package-name>}.
\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}).
+\item A particular black box instance (with full description, as well as the values and the status of the inputs/outputs) if you type \texttt{help <box-name>}.
\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.
also called \emph{pipelines},
by connecting black boxes.
This section explains how to do it with examples.
-Read section \ref{bbi-more-on-pipeline-processing} to get
+Read section \ref{bbi-deep-box} to get
more information on pipeline processing.
-First start \bbStudio and load the package \texttt{std}, typing :
+First start \bbStudio and load the package \texttt{std}, i.e. type in the 'Command' part the following command:
\begin{verbatim}
> include std
\end{verbatim}
-in the 'Command' part.
-Assume you want to compute $1+2+3$. You can do it by
+Assume you want to compute a sum of three numbers (e.g. $1+2+3$). You can do it by
chaining two \texttt{Add} boxes, as shown in figure
\ref{bbi-fig-connecting-black-boxes-1}.
\begin{figure}[!ht]
-\caption{\label{bbi-fig-connecting-black-boxes-1} A simple pipeline which adds 3 numbers}
+\caption{ A simple pipeline that adds 3 numbers}
\begin{center}
\includegraphics[width=0.5\textwidth]{1plus2plus3.png}
\end{center}
+\label{bbi-fig-connecting-black-boxes-1}
\end{figure}
-
-The \bbi instructions to create and execute this pipeline are :
+The \bbs instructions to create and execute this pipeline are :
\begin{verbatim}
> new Add a
> new Add b
> 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
-prints \texttt{b} black box output (the pipeline is executed before printing, because the interpretor 'knows' the box \texttt{b},
-whose output is requested, is not up to date).
+the next three set \texttt{a} and \texttt{b} black boxes' inputs and the last one
+prints the output of the black box \texttt{b}. The pipeline is executed before printing, because the interpreter 'knows' that the box \texttt{b}, the output of which 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
box \texttt{b}.
-Once the boxes are connected, the processing of the two boxes are chained :
+Once the boxes are connected, the processings of the two boxes are chained:
getting the output of \texttt{b} requires getting its inputs,
hence getting the output of \texttt{a} which is connected to it.
-This pipeline mechanism can recurse into arbitrary long
-chains of boxes (see \ref{bbi-more-on-pipeline-processing}
+This pipeline mechanism can recurse into arbitrarily long
+chains of boxes (see \ref{bbi-deep-box}
for details).
-
-Lets' consider an other, more image oriented, example :
+Let us consider another, more image-oriented, example :
\begin{verbatim}
> include vtk
> exec viewer
\end{verbatim}
-Some explainations : the \texttt{include} instructions load the necessary packages. \\
-
-\texttt{FileSelector} will pop a File Selector, at run time, that will out the user chosen file name. \\
-\texttt{Slider} will pop a Slider, at run time, that will out an integer, used later as a slice number.\\
-\texttt{ImageReader} will read any itk readable file, whose name is passed as a std::string, and return a pointer on an itk image.\\
-\texttt{Viewer2D} displays a plane, whose number is 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 bbtk::any<bbitk::ImagePointer> which is a type defined by the
-itk package which can hold any itk image pointer) 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 that it must re process itself any time the slider is modified.\\
-\\
-\texttt{exec viewer} processes the viewer.
-
+Some explanations:
+\begin{itemize}
+ \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
+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.
+\end{itemize}
This would correspond to the graph in figure \ref{bbi-simplegraph}
\end{figure}
Of course, to be able to connect two boxes,
-the output and the input must be compatibles.
+the output and the input must be compatible.
You can always connect an output to an input of the \emph{same} type,
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 that has at least one input, called \texttt{In},
+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 retreive other useful information).
+to parameter the adaptor or retrieve other useful information).
Under \bbStudions, if you type :
\begin{verbatim}
Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
Basic useful black boxes
Black boxes :
- ...
+ ASCII : ascii codes sequence to string - ...
+ Add : Adds its inputs
BoolToString [DA] : Converts a Bool (bool) into a string
- CastBoolToChar [DA] : Static cast from Bool (bool) to Char (signed c...
- CastBoolToDouble [DA] : Static cast from Bool (bool) to Double (double...
+ CastBoolToChar [DA] : Static cast from Bool (bool) to ...
+ CastBoolToDouble [DA] : Static cast from Bool (bool) to ...
...
- CastBoolToUChar [DA] : Static cast from Bool (bool) to UChar (unsigne...
- CastBoolToUInt [DA] : Static cast from Bool (bool) to UInt (unsigned...
+ CastBoolToUChar [DA] : Static cast from Bool (bool) to ...
+ CastBoolToUInt [DA] : Static cast from Bool (bool) to ...
...
- CastUIntToBool [DA] : Static cast from UInt (unsigned int) to Bool (...
- CastUIntToChar [DA] : Static cast from UInt (unsigned int) to Char (...
- CastUIntToDouble [DA] : Static cast from UInt (unsigned int) to Double...
+ CastUIntToBool [DA] : Static cast from UInt (unsigned ...
+ CastUIntToChar [DA] : Static cast from UInt (unsigned ...
+ CastUIntToDouble [DA] : Static cast from UInt (unsigned ...
...
\end{verbatim}
-\texttt{[DA]} stands for \emph{default adaptor}.
+In this long list you find many items marked \texttt{[DA]}, which stands for \emph{default adaptor}.
Once you have loaded the package \texttt{std}, you can
plug an output of type \texttt{char} into an input of type \texttt{double}.
it looks for an adequate \emph{adaptor} in the loaded packages.
In our case, as the package \texttt{std} provides the
\texttt{CastUCharToDouble} adaptor, the interpreter automatically creates an
-instance of this adaptor and place it \emph{between}
+instance of this adaptor and places it \emph{between}
the output and the input you want to connect
(however this adaptor is hidden to you,
it is embedded into the created connection and does not appear
would simply cast the value of the \texttt{char} into a \texttt{double},
however arbitrarily complex type conversion may be done.\\
\texttt{WARNING}: these adaptors are \texttt{C++ static cast}, i.e., there is, right now,
- no 'intelligent' conversion (only truncation) e.g. think to \texttt{CastDoubleToUChar}!
+ no 'intelligent' conversion (only truncation) e.g. think of \texttt{CastDoubleToUChar}!
%\begin{verbatim}
%Question (for info-dev):
\item There is an adaptor black box in the packages loaded which
converts data of the output type into data of the input type
\end{itemize}
-\item \texttt{help <package name>} does not display the adaptors of the package. To see them use : \texttt{help <package name> all}.
-including adaptors
+\item \texttt{help <package name>} does not display the adaptors of the package. To see them use: \texttt{help <package name> all}
+including adaptors.
\end{itemize}
\hrule
% ==========================================
\label{bbi-complex-black-boxes}
% ==========================================
-Remember the pipeline of figure
+Remind the pipeline of figure
\ref{bbi-fig-connecting-black-boxes-1}, which
computed the sum of three doubles.
You can consider it as a whole and define
\end{center}
\end{figure}
-The \bbi commands to define this complex black box are
-the following :
+The \bbs commands to define this complex black box are
+the following:
\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
\end{verbatim}
-Explainations :
-
-As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
-
-The command \texttt{define} then starts the definition
-of the complex box type, which will be called \texttt{Add3}.
-
-The next three lines define the pipeline,
-exactly in the same way than outside a complex box definition.
-
-The commands \texttt{author}, \texttt{description}, \texttt{input}
-and \texttt{output} are commands specific to complex boxes definition :
-
-\texttt{author} and \texttt{description} are used for the documentation
+Explanations:
+\begin{itemize}
+ \item As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in the first line.
+ \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.
+ \item The commands \texttt{author}, \texttt{description}, \texttt{input}
+and \texttt{output} are specific to complex boxes definition:
+ \begin{itemize}
+ \item \texttt{author} and \texttt{description} are used for the documentation
of the new box. You can provide multiple \texttt{author} or
\texttt{description} commands, the arguments of the commands will
be concatenated to produce the final author and description strings.
-
-\texttt{input} and \texttt{output} are used to define the inputs and outputs
-of the new complex box.
-Their syntax is the same : for each new input/output you need to say
+ \item \texttt{input} and \texttt{output} are used to define the inputs and outputs
+of the new complex box. Their syntax is the same: for each new input/output you need to say
to which internal input/output it corresponds and to provide
a help string documenting the input/output.
In our example, we define that the box \texttt{Add3} has
-three inputs : \texttt{x}, \texttt{y} and \texttt{z}.
+three inputs: \texttt{x}, \texttt{y} and \texttt{z}.
The input \texttt{x} corresponds to the input \texttt{In1} of the
internal box \texttt{a}.
In the same way, the external input \texttt{y}
The figure \ref{bbi-fig-complex-black-box-1}
illustrates the external to internal
input/output correspondence.
-
-Finally, the \texttt{endefine} command ends the definition of the
+ \end{itemize}
+ \item Finally, the \texttt{endefine} command ends the definition of the
new box type.
+\end{itemize}
After this definition, if you ask for help
-on packages, you get :
+on packages, you get:
\begin{verbatim}
> help packages
std
\end{verbatim}
The \texttt{user} package now contains a new black box type, called
-\texttt{Add3}. If you ask for help on this type of box, you get :
+\texttt{Add3}. If you ask for help on this type of box, you get:
\begin{verbatim}
> 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
+ 'x' <double> [] : first double to add
+ 'y' <double> [] : second double to add
+ 'z' <double> [] : third double to add
* Outputs :
- 'result' <double> : output
+ 'result' <double> [] : output
* Boxes :
'a' <std::Add>
'b' <std::Add>
\end{verbatim}
-and you can use it like any other box, for example type :
+and you can use it like any other box, for example:
\begin{verbatim}
> new Add3 a
6
\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}\emph{x} if there are more than one 'natural
-entry'
-.
+\texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3}. Indeed,
+by convention all the 'natural entries' of a box are named \texttt{In}, or \texttt{In}\emph{x} if there is more than one 'natural entry'.
\newline
% ==========================================
\hrule
\paragraph{Summary}
%\hrule
\begin{itemize}
-\item The \texttt{define/endefine} commands allows to define complex black box types, i.e. types of black boxes made up of other black boxes.
+\item The \texttt{define/endefine} commands allow to define complex black box types, i.e. types of black boxes made up of other black boxes.
Inside a \texttt{define/endefine} block :
\begin{itemize}
\item The \texttt{author} and \texttt{description} commands allow to document the new type of box
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 :
+can be defined in the \texttt{bbAdd3.bbs} file:
\begin{file}{bbAdd3.bbs}
\begin{verbatim}
adds 3 doubles
By : myself
* Inputs :
- 'x' <double> : first double to add
- 'y' <double> : second double to add
- 'z' <double> : third double to add
+ 'x' <double> [] : first double to add
+ 'y' <double> [] : second double to add
+ 'z' <double> [] : third double to add
* Outputs :
- 'result' <double> : output
+ 'result' <double> [] : output
* Boxes :
'a' <std::Add>
'b' <std::Add>
->
-and so on ...
\end{verbatim}
-If the file has the \texttt{bbs} extension, you can ommit it and just type :
+If the file has the \texttt{bbs} extension, you can omit it and just type:
\begin{verbatim}
> include Add3
\end{verbatim}
+provided that {\bbStudions} 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 {\bbStudions} and run it again, so that the new configuration be taken into account.
\subsection{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 :
+like in the following example:
\begin{file}{bbAdd4.bbs}
\begin{verbatim}
description "adds 4 doubles"
new Add3 a
new Add b
- connect a.Out b.In1
- input In1 a.In1 "first double to add
- input In2 a.In2 "second double to add
- input In3 a.In3 "third double to add"
+ connect a.result b.In1
+ input In1 a.x "first double to add
+ input In2 a.y "second double to add
+ input In3 a.z "third double to add"
input In4 b.In2 "fourth double to add"
output Out b.Out "output"
endefine
\end{verbatim}
\end{file}
-
-The inner boxes have they own entries (In1, In2, In3 for box a, In1, In2 for box b )\\
-Only the inputs In1, In2, In3 of box a and the input In2 of box b is of interest for the end user, but he dosn't want to have to
-care neither about the inner boxes name, nor about the names of their Inputs.\\
-The writer of the complex box has the ability to give these inputs a meaningfull name !
-\begin{verbatim}
- input In3 a.In3 "third double to add"
- input In4 b.In2 "fourth double to add"
-\end{verbatim}
-
+Here we kept the \texttt{bbAdd3.bbs} file unchanged, so the inner box of type \texttt{Add3} \texttt{a} has the entries \texttt{x, y, z}, while the entries of the inner box \texttt{b} of type \texttt{Add} are \texttt{In1, In2}.\\
+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}
\label{bbi-Naming Conventions}
git://git.creatis.insa-lyon.fr / bbtk.git / blobdiff