% ==========================================
\subsection{The commands}
% ==========================================
-In the sequel the commands entered by the user will be preceded by a prompt \textgreater){\bbStudio}.
+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
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,
\ref{bbi-writing-scripts} and
\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>
> help Add
\end{verbatim}
-{\bbStudions} displays the appropriate html page in the 'Help' part (see figure : \ref{HelpAdd}), and the following text 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
Of course, like in \texttt{C} Language, you can declare multiple boxes of the
same type in \bbi.
-After the creation of the box \texttt{a}, type :
+After the creation of the box \texttt{a}, type:
\begin{verbatim}
> help workspace
\end{verbatim}
\end{verbatim}
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 type \texttt{std::Add}. If you type:
+\begin{verbatim}
+> help workspace
+\end{verbatim}
+
+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}
+
+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.
+
+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}
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.
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}.
\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 interpreter 'knows' that the box \texttt{b}, the output of which 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
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}
git://git.creatis.insa-lyon.fr / bbtk.git / commitdiff