From 6e6b9b173b1eedc7402a778fb6d3b00e8a942fd3 Mon Sep 17 00:00:00 2001 From: maciej orkisz Date: Thu, 12 Mar 2009 15:10:08 +0000 Subject: [PATCH] connecting boxes --- kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex | 132 ++++++++++++------- 1 file changed, 81 insertions(+), 51 deletions(-) diff --git a/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex b/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex index d5b97b0..2bb41de 100644 --- a/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex +++ b/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex @@ -696,7 +696,7 @@ to create and execute pipelines. % ========================================== \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 @@ -783,14 +783,14 @@ gives: 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, @@ -806,7 +806,7 @@ in \texttt{workspace} \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 @@ -890,7 +890,7 @@ Now, if you type: > 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 Adds its inputs @@ -952,7 +952,7 @@ name of which is \texttt{i}. 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} @@ -970,7 +970,51 @@ Complex Black Box \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' + * 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' + * 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} @@ -992,7 +1036,7 @@ result=7.8 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 @@ -1003,27 +1047,15 @@ To process this special substrings, the interpretor : %\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} @@ -1039,14 +1071,15 @@ graphical interface, and so on. \newline \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 }. \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 }. \item A particular black box type (with full description) if you type \texttt{help }. 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 }. \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. @@ -1088,13 +1121,12 @@ This section explains how to do it with examples. 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}. @@ -1123,8 +1155,8 @@ You will see the (very expected) result : \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 @@ -1136,8 +1168,7 @@ 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 @@ -1158,21 +1189,20 @@ Lets' consider an other, more image oriented, example : > 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 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} 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} @@ -1185,15 +1215,15 @@ 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} -- 2.45.0