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 \textgreater){\bbStudio}.
+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}
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 :
\begin{verbatim}
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 \bbi.
After the creation of the box \texttt{a}, type :
\begin{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
-\begin{verbatim}
-Help Add
-\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 can see that \texttt{Add} boxes have two inputs,
-with name \texttt{In1} and \texttt{In2},
-and an output, with name \texttt{Out}.
-
-You can set the input \texttt{In1}
-of the \texttt{Add} box \texttt{a} to the value $1$
-by the command :
+This means that \bbi workspace now contains a black box named \texttt{a},
+of type \texttt{std::Add}. You can 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,
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 :
\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 :
\begin{verbatim}
> new Add a
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).
+prints \texttt{b} black box output. 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).
> endefine
\end{verbatim}
-Explainations :
+Explanations :
As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
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
+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 does not 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 !
+The writer of the complex box has the ability to give these inputs a meaningful name !
\begin{verbatim}
input In3 a.In3 "third double to add"
input In4 b.In2 "fourth double to add"
git://git.creatis.insa-lyon.fr / bbtk.git / commitdiff