1 % ==========================================
2 \documentclass[11pt,final,a4paper]{article}
5 \title{The Black Box Toolkit\\User's Guide}
7 \author{Laurent Guigues}
9 % ==========================================
11 % ==========================================
14 % ==========================================
16 % ==========================================
18 % ==========================================
20 \section{What is {\bf bbtk} ?}
21 % ==========================================
22 \BBTK(\bbtkns) is a set of tools
23 (\CPP libraries and executables)
24 providing a \CPP framework for the definition
25 of elementary processing \emph{units}, called {\bf black boxes},
26 and the definition and execution of processing \emph{chains}
27 made up of these black boxes.
29 % ==========================================
30 \subsection{The black box philosophy}
31 % ==========================================
32 \href{http://en.wikipedia.org/wiki/Black_box_\%28disambiguation\%29}{Wikipedia}
33 defines a {\bf black box} as
34 \emph{``any component in a system in which only the input and output
35 characteristics are of interest, without regard to its internal mechanism
37 I would add something very important to this definition :
38 not only the inputs and outputs are of interest but also
39 \emph{what the box does} !
40 Hence, I would say that a black box is any \emph{\bf documented}
41 component of a system, letting the user know
42 \emph{\bf what} the box is supposed to do and
43 \emph{\bf how to use it}
44 but not \emph{\bf how it does it}.
46 \BBTK provides a systematic framework
47 to encapsulate (or ``wrap'') any
48 existing \texttt{C} or \CPP processing code into an object
49 (a black box) having a {\bf generic symbolic interface}, where
52 \item{\bf generic} means that the interface is \emph{the same}
53 for all boxes. Hence one does not need to know which particular
54 method allows, say, to set a particular input or
55 get a particular output of the box.
56 One can use a black box in a purely abstract way.
57 \item{\bf symbolic} means that a particular
58 input or output is referenced by a 'name', that is by a symbol
59 which identifies the input or output.
60 It also means that symbolic information (text!) is
61 attached to a box: description of the box, author,
62 description of its inputs and outputs, etc.
65 (in fact, genericity is achieved because the interface is symbolic.
66 I let you think about this\dots)
68 Of course, symbolic data attached to box can be
69 {\bf queried}: what are the inputs/outputs of the box ?
70 what are their type ? their description ? etc.
71 This allows {\bf automatic documentation} of boxes.
73 The abstract definition of black boxes is the most basic
74 aspect of \BBTK architecture.
75 Another key aspect is the groupement of black boxes into
76 so called {\bf packages},
77 which are \emph{dynamic libraries} which can also
78 be queried, in particular about the boxes they provide.
79 The package structure then offers a mechanism which
80 is like a \emph{'plug-in'} mechanism.
81 \BBTK provides the methods to load a package at run-time,
82 and create instances of the boxes it contains.
84 These two mechanisms (black boxes and packages)
85 then gives the way to:
88 \item The definition of an {\bf interpreted language},
89 which allows to manipulate packages and boxes very easily in symbolic way.
90 \BBTK provides one: \bbi (the Black Box Interpreter).
91 \item {\bf Automatic documentation} of existing packages.
92 \texttt{html} documentation of packages is proposed by
96 Finally, these different components allow {\bf efficient}:
99 \item {\bf capitalization and reuse} of existing processing units,
100 including {\bf documentation}
101 \item {\bf testing, prototyping} in a very simple script language
102 \item {\bf inter-operability} between atomic processings which
103 have been written by different persons, using different libraries, etc.
106 % ==========================================
107 \subsection{\bbtk components}
108 % ==========================================
111 \item A \CPP {\bf\emph{library}} - called \bbtk - which defines a framework
112 (abstract classes) to develop black boxes and to store them into
113 dynamic libraries, called black box \emph{packages}.
114 \item Different {\bf\emph{black box packages}}:
116 \item {\bf\emph{std}}: the 'standard' package including basic useful boxes.
117 \item {\bf\emph{wx}}: basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library).
118 \item {\bf\emph{itk}}: the basic image processing package, based on the \texttt{itk} library.
119 \item {\bf\emph{vtk}}: the basic image and surfaces processing package, based on the \texttt{vtk} library.
120 \item {\bf\emph{wxvtk}}: widget boxes based on the \texttt{vtk} library.
121 \item {\bf\emph{itkvtk}}: boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally.
123 \item A {\bf\emph{Developement environment}}, called bbStudio, which provides
125 \item An online {\bf\emph{script editor}}, called bbed
126 \item A powerfull {\bf\emph{Help environment}}, called bbhelp
129 \item Online documentation scaning
130 \item Retreiving boxes on various criterions
131 \item Checking Demo and examples
134 \item An {\bf\emph{interpreter}}, called \bbi, which allows to
135 load black box packages and to define and execute
136 processing chains by connecting various black boxes of the already loaded packages.
137 \item {\bf\emph{Utilities}}:
139 \item \bbfy generates the \CPP code of a black box from a
140 description file written in \texttt{xml}.
141 %\item \bbdoc generates the html documentation of a black box package
142 %(author, description, description of its black boxes:
143 %author, description, inputs, outputs, and so on).
144 \item \bbCreatePackage allows to create the basic file architecture
145 to start the development of a new black box package.
149 The general architecture of \BBTK
150 is shown in figure \ref{bb-architecture}.
153 \caption{\label{bb-architecture}\BBTK architecture}
155 \includegraphics[width=0.6\textwidth]{bb-architecture.png}
159 % ==========================================
160 \subsection{Structure of this guide}
161 % ==========================================
163 This guide is divided into three parts.
165 The first part (\ref{bbStudio}) is a brief presentation of the very intuitive Development
166 environment, \bbStudio.
168 The second part (\ref{bbi})
169 is devoted to the use of the \emph{black box interpreter} \bbi.
170 This is the highest level of use of the toolkit, which
171 allows to create and execute processing chains by connecting
172 black boxes of existing packages.
174 The third part (\ref{cpp}) explains how to
175 use the black box toolkit framework in \CPP code,
176 typically to develop large applications which
177 involve complex graphical interfaces.
180 % ==========================================
181 % ==========================================
182 % ==========================================
183 % ==========================================
184 % ==========================================
185 % ==========================================
187 \section{The Development environment (bbStudio)}
190 Just run it, typing in a console \texttt{bbed}.
191 You'll get something like in figure
192 \ref{bbi-fig-bbStudio-gui}
193 (the exact appearance of \bbStudio is system and \bbtk version dependent)
196 \caption{\label{bbi-fig-bbStudio-gui}The bbStudio Development environment interface}
198 \includegraphics[width=0.7\textwidth]{bbStudioMainPage.png}
202 All the entries of this Help 'bookmark' are self-explanatory :
205 \item {\bf\emph{Wiki}}: Direct link to the bbtk Wiki (intranet only, right now, www
207 \item {\bf\emph{Demo}}: Link to some demonstrations.
208 \item {\bf\emph{User's Guide}}: Step to step How-to for user who just wants to create his own
209 application, just using already existing boxes.
210 \item {\bf\emph{Package Developper's Guide}}: Step to step How-to for user who wants to create his own
212 \item {\bf\emph{Developper's Guide}}: Sorry, not yet written.
213 \item {\bf\emph{Reference Manual}}: Sorry, not yet written.
214 \item {\bf\emph{Doxygen Documentation}}: Doxygen source browser.
215 \item {\bf\emph{Boxes}}: Box retrieving on various criterions :
217 \item {\bf\emph{By name}}
218 \item {\bf\emph{By package}}
219 \item {\bf\emph{By category}}
223 % ==========================================
224 % ==========================================
225 % ==========================================
226 % ==========================================
227 % ==========================================
228 % ==========================================
230 \section{The script manager}
232 % ==========================================
234 Call it with the bookmark \emph{File}.
238 \caption{\label{bbi-fig-bbStudio-file0}The bbStudio script manager}
240 \includegraphics[width=0.7\textwidth]{bbFile0.png}
244 Using the lower tool bar, you can :
246 \item {\bf\emph{new}}: Create a newfile to hold a script
247 \item {\bf\emph{open}}: Open a already existing file holding a script
248 \item {\bf\emph{close}}: Close a file holding a script
249 \item {\bf\emph{close}}: Save he current file (if modified)
250 \item {\bf\emph{save as}}: Save he current file under a different name
251 \item {\bf\emph{execute}}: Execute the script you just loaded/modified/written
255 The script language is very simple.
256 Everything is done with only a few commands.
257 The philosophy of this part is also very simple:
258 it introduces the \bbi commands using examples,
259 starting with the most simple commands.
260 The first section of this part
261 (\ref{bbi-getting-started})
262 is designed like a tutorial,
263 which progressively introduces all the concepts of \bbi.
264 We suggest you run \bbi and follow the examples,
265 to see how it works in practice.
266 At the end of this section,
267 you will be able to use \bbi and write
268 own black box processing scripts.
271 the section \ref{bbi-more-on}
272 (called \emph{more on...})
273 goes deeper into various issues of \bbi.
274 Read it at your convenience,
275 either linearly to learn more about \bbi,
276 or in random order to get an answer
277 to a particular question.
279 Finally, the section \ref{bbi-reference}
280 summarizes all the commands of \bbi,
281 their parameters and effect.
282 Use it as a reference.
284 % ==========================================
285 \subsection{Getting started}
286 \label{bbi-getting-started}
287 % ==========================================
288 \subsubsection{Creating and executing black boxes}
289 % ==========================================
291 To learn interactivelly the script language features, you can use the black box
293 open a console and type \texttt{bbi}
294 or double click on the application icon.
295 You get a window which looks like the one in figure
296 \ref{bbi-fig-bbi-gui}
297 (the exact appearance of \bbi is system and \bbtk version dependent)
298 \footnote{If you compiled \bbtk without \wx then \bbi does not have a
299 graphical interface but a simple prompt}.
302 \caption{\label{bbi-fig-bbi-gui}The black box interpreter interface}
304 \includegraphics[width=0.7\textwidth]{bbi-gui0.png}
308 The 'Command' tab is subdivided into two parts :
309 one single line zone at the bottom in which you can enter your commands and
310 one multiple line zone in which \bbi prints out the result of your commands.
311 , just using already existing boxes.
313 Try typing in the input zone (in this manual,
314 the commands entered by the user will be preceded by a prompt \textgreater) :
319 you get the list of the commands of the interpreter:
352 To get help on a particular command type \texttt{help <command-name>},
362 Quits the program (during script execution it stops the complete execution)
365 The \texttt{help} command has multiple usages.
366 It is used to get help on almost anything in \bbi !
367 Type \texttt{'help help'} to get help on the \texttt{help} command itself:
372 (2) help <command name>
373 (3) help packages [all]
374 (4) help <package name> [all]
375 (5) help <black box type>
376 (6) help <black box name>
378 (1) Lists all available commands;
379 (2) Prints help on a particular command;
380 (3) Lists the packages loaded and their black boxes.
381 Add 'all' to list adaptors;
382 (4) Prints short help on the black boxes of a package.
383 Add 'all' to include adaptors;
384 (5) Prints full help on a black box type;
385 (6) Prints information on the inputs, outputs and connections of a black box instance.
388 At start \bbi does not know any black box.
389 If you type \texttt{'help packages'}, which is
390 the third form of the \texttt{help} command, you get:
397 which means that \bbi only knows one package
398 (library of black boxes) called \texttt{user}
399 and which contains a black box called \texttt{workspace}.
400 The \texttt{user} package is an internal package to \bbi,
401 which stores user-defined black box types.
402 At start, it already contains
403 one box, called \texttt{workspace}.
404 \texttt{workspace} is a special type of black box,
405 called complex black box, whose purpose is
406 to store other black boxes.
407 Any black box you create in \bbi is stored
408 in \texttt{workspace}
409 (this will be explained in details in sections
410 \ref{bbi-writing-scripts} and
411 \ref{bbi-more-on-complex-black-boxes}).
413 If you type \texttt{'help workspace'}, you get:
416 Complex Black Box <user::workspace>
419 Category(s) : complex box;
425 In the text displayed,
426 the \texttt{user::} prepended to the name \texttt{workspace}
427 means that the box \texttt{workspace}
428 belongs to the \texttt{user} package.
429 Then comes a description and three lines which
430 tell that \texttt{workspace} does not have any input
431 nor output nor boxes yet.
433 In order to let \bbi know of some black boxes,
434 you must load another package.
435 The \texttt{std} package is the ``standard'' package,
436 which contains basic useful black boxes.
448 you get something like:
463 Now \bbi knows the package \texttt{std} and the black boxes it provides,
464 such as the \texttt{'Add'} box, the \texttt{'ConcatStrings'}. Remark that the
465 content of \texttt{std} may vary from one version to another
466 as new black boxes might be added to it.
476 By : laurent.guigues@creatis.insa-lyon.fr
477 Categories : atomic box;math;
479 'BoxExecute' <bbtk::Void> [signal] : Any signal received by this input executes the box
480 'BoxProcessMode' <String> [] : Sets the processing mode of the box (Pipeline | Always | Reactive)
481 'In1' <Double> [] : First number to add
482 'In2' <Double> [] : Second number to add
484 'BoxChange' <bbtk::Void> [signal] : Signals modifications of the box
485 'Out' <Double> [] : Result
489 the \texttt{std::} prepended to the name \texttt{Add}
490 means that the box \texttt{Add}
491 belongs to the \texttt{std} package.
492 Then comes a description
493 (the one which was provided by the author of the box),
494 the author(s) of the box (usually e-mail adress(es)) and
495 the categories to which the box belong.
496 Finally comes the lists of inputs and outputs of the box.
497 For each input or output, \bbi provides
498 its \emph{name} (between quotes, e.g. \texttt{'ProcessMode'}),
499 its \emph{type} (between \texttt{<>}, e.g. \texttt{<Int>})
501 Remark that the box \texttt{Add} is not a 'complex' black box
502 but an 'atomic' box, hence its help does not
503 mention any information concerning possible internal boxes.
505 You can create an \emph{instance} of an \texttt{Add} box by
506 the command \texttt{new}:
511 The \texttt{'a'} at the end is the \emph{name} of the instance,
512 which will be used to reference it later.
513 It is important to distinguish a box \emph{types}
514 and an \emph{instance} of a box type.
515 The \texttt{Add} box of the package \texttt{std} is actually
516 a \emph{box type} , like \texttt{int} is a data type
517 in \texttt{C} langage. The \texttt{new} command allows to create
518 an instance of a box type, exactly like \texttt{int i;} in
519 a \texttt{C} code declares a variable of type \texttt{int} whose
521 Of course, like in \texttt{C} Language, you can declare multiple boxes of the
524 After the creation of the box \texttt{a}, type:
531 Complex Black Box <user::workspace>
534 Category(s) : complex box;
541 which means that \bbi workspace now contains a black box named \texttt{a},
542 of type \texttt{std::Add}.
544 Now look back at the help on \texttt{Add} boxes:
545 you can see that this type of box has two inputs,
546 with name \texttt{In1} and \texttt{In2},
547 and an output, with name \texttt{Out}.
549 You can set the input \texttt{In1}
550 of the \texttt{Add} box \texttt{a} to the value $1$
556 Similarly, setting the input \texttt{In2} of \texttt{a} to the value $2$
562 And you print the output \texttt{Out} of the box \texttt{a} with:
564 > print "result=$a.Out$"
568 In the string passed to the \texttt{print} command,
569 each substring enclosed between a couple of \$ is considered
570 as the name of an output of a box.
571 To process this special substrings, \bbi does:
573 \item Processes the box if needed (see below)
574 \item Converts the output of the box to a string if possible
576 \item Substitutes the result in the string to print
577 \item postpone an implicit 'new line' character to the string
580 Box processing is needed if:
582 \item at least input has changed since last processing or
583 \item the input \texttt{'BoxProcessMode'} of the box is set to
584 \texttt{'Always'}, which forces box reprocessing.
587 Note that all boxes have the input \texttt{'BoxProcessMode'}.
589 Another way to process the box \texttt{a} is to issue the command:
594 however this command does not display anything (except if the
595 box itself displays something in its processing).
596 It just processes the box if needed.
597 This command is used to execute boxes that do not have any output,
598 such as boxes that write something to a file or, display a
599 graphical interface, and so on.
607 % ==========================================
612 \item The \texttt{include} command allows to load a package.
613 \item \texttt{help} gives help on:
615 \item Available commands if you just type \texttt{help}.
616 \item A particular command if you type \texttt{help <command-name>}.
617 \item All available packages and their boxes (without description) if you type \texttt{help packages}.
618 \item A particular package and its boxes (with brief description) if you type \texttt{help <package-name>}.
619 \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}).
621 %\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).
622 \item \texttt{new} : creates an instance of a black box.
623 \item \texttt{set} : sets the value of an input of a black box.
624 \item In all \bbi, to reference the input called \texttt{i}
625 of a black box called \texttt{b} you must type \texttt{'b.i'}.
626 The same syntax holds for outputs.
627 \item \texttt{print} : prints a string, substituting each substring of the form \$b.o\$ by the value of the output \texttt{o} of the black box \texttt{b}. Note that an
628 implicit trailing 'new line character' is added at the final string.
629 \item \texttt{exec} : runs the process of a box if needed.
630 \item \texttt{quit} : quits \bbi.
633 % ==========================================
635 % ==========================================
636 \subsubsection{Connecting black boxes}
637 \label{bbi-connecting-black-boxes}
638 % ==========================================
640 \BBTK allows to create
641 and execute processing chains,
642 also called \emph{pipelines},
643 by connecting black boxes.
644 This section explains how to do it with examples.
645 Read section \ref{bbi-more-on-pipeline-processing} to get
646 more information on pipeline processing.
648 First start \bbi and load the package \texttt{std}:
653 Assume you want to compute $1+2+3$. You can do it by
654 chaining two \texttt{Add} boxes, as shown in figure
655 \ref{bbi-fig-connecting-black-boxes-1}.
658 \caption{\label{bbi-fig-connecting-black-boxes-1}
659 A simple pipeline which adds 3 numbers}
661 \includegraphics[width=0.5\textwidth]{1plus2plus3.png}
666 The \bbi instructions to create and execute this pipeline are:
670 > connect a.Out b.In1
678 The first three commands build the pipeline,
679 the next three set \texttt{a} and \texttt{b} black boxes inputs and the last one
680 executes the pipeline and prints \texttt{b} black boxe output.
682 The command \texttt{'connect a.Out b.In1'} ``plugs'' the output
683 \texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the
685 Once the boxes connected, the processing of the two boxes are chained:
686 getting the output of \texttt{b} requires getting its inputs,
687 hence getting the output of \texttt{a} which is connected to it.
688 This pipeline mechanism can recurse into arbitrary long
689 chains of boxes (see \ref{bbi-more-on-pipeline-processing}
692 Of course, to be able to connect two boxes,
693 the output and the input must be compatibles.
694 You can always connect an output to an input of the \emph{same} type,
695 but you can do more, thanks to particular (hidden) black boxes called {\bf adaptors}.
697 An adaptor is a black box which has at least one input, called \texttt{In},
698 and at least one ouput called \texttt{Out} and whose role is to convert
699 a data of the type of \texttt{In}
700 into a data of the type of \texttt{Out} (other inputs or outputs may serve
701 to parameter the adaptor or retreive other usefull information).
703 In \bbi, if you type:
710 Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
711 Basic useful black boxes
713 Add : Adds its inputs
714 Cast<double,float> [DA] : Casts a double into a float
715 Cast<double,int> [DA] : Casts a double into a int
717 Convert<unsigned int,string> [DA] : Converts a unsigned int into a s...
718 Convert<unsigned short,string> [DA] : Converts a unsigned short into a...
719 Print : Prints its input to standard out...
723 The \texttt{Cast<?,?>} and \texttt{Convert<?,?>} boxes are \emph{default adaptors}, which is signaled by the tag \texttt{[DA]} before their descriptions.
725 Once you have loaded the package \texttt{std}, you can
726 plug an output of type \texttt{char} into an input of type \texttt{double}.
727 When \bbi encounters the \texttt{connect} command,
728 it looks for an adequate \emph{adaptor} in the loaded packages.
729 In our case, as the package \texttt{std} provides the
730 \texttt{Cast<char,double>} adaptor, \bbi automatically creates an
731 instance of this adaptor and place it \emph{between}
732 the output and the input you want to connect
733 (however this adaptor is hidden to you,
734 it is embedded into the created connection and does not appear
735 as an existing black box).
736 When the pipeline is processed the
737 adaptor converts the output data into the required input type,
738 in a totally transparent way.
739 In our example, the \texttt{Cast<char,double>} adaptor
740 would simply cast the value of the \texttt{char} into a \texttt{double},
741 however arbitrarily complex type conversion can be done.
744 if two adaptors with the same input and output types exist
745 in the packages loaded,
746 which one is chosen by \bbi at connection ?
747 -> Role of default adaptors
749 Note that the \texttt{set} and \texttt{print} commands of \bbi
750 work with adaptors from \texttt{string} to the type of the input to set
751 or from the type of the output to print to \texttt{string}.
752 Hence in order to \texttt{set} or \texttt{print} values the adequate
753 adaptors must be available in the packages currently loaded.
755 % ==========================================
760 \item The \texttt{connect} command allows to connect two black boxes
761 \item You can connect two black boxes if (and only if):
763 \item The output and the input are of the same type, or
764 \item There is an adaptor black box in the packages loaded which
765 converts data of the output type into data of the input type
767 \item \texttt{help <package name>} does not display the adaptors of the package. To see them use: \texttt{help <package name> all}.
771 % ==========================================
773 % ==========================================
774 \subsubsection{Creating complex black boxes}
775 \label{bbi-complex-black-boxes}
776 % ==========================================
778 Remember the pipeline of figure
779 \ref{bbi-fig-connecting-black-boxes-1}, which
780 computed the sum of three doubles ?
781 You can view it as a whole and define
782 a new black box type, which will be a \emph{complex black box},
783 having three inputs and one output,
784 as shown in figure \ref{bbi-fig-complex-black-box-1}.
787 \caption{\label{bbi-fig-complex-black-box-1}
788 Creating the complex black box \texttt{Add3}}
790 \includegraphics[width=0.5\textwidth]{Add3.png}
794 The \bbi commands to define this complex black box are
804 > connect a.Out b.In1
807 > description "adds 3 doubles"
808 > input x a.In1 "first double to add"
809 > input y a.In2 "second double to add"
810 > input z b.In2 "third double to add"
811 > output result b.Out "output"
818 As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
820 The command \texttt{define} then starts the definition
821 of the complex box type, which will be called \texttt{Add3}.
823 The next three lines define the pipeline,
824 exactly in the same way than outside a complex box definition.
826 The commands \texttt{author}, \texttt{description}, \texttt{input}
827 and \texttt{output} are commands specific to complex boxes definition:
829 \texttt{author} and \texttt{description} are used for the documentation
830 of the new box. You can provide multiple \texttt{author} or
831 \texttt{description} commands, the arguments of the commands will
832 be concatenated to produce the final author and description strings.
834 \texttt{input} and \texttt{output} are used to define the inputs and outputs
835 of the new complex box.
836 Their syntax is the same: for each new input/output you need to say
837 to which internal input/output it corresponds and to provide
838 a help string documenting the input/output.
839 In our example, we define that the box \texttt{Add3} has
840 three inputs: \texttt{x}, \texttt{y} and \texttt{z}.
841 The input \texttt{x} corresponds to the input \texttt{In1} of the
842 internal box \texttt{a}.
843 In the same way, the external input \texttt{y}
844 corresponds to the internal input \texttt{a.In2}, and
845 the external input \texttt{In3} to \texttt{b.In2}.
846 The only output of the new box is called \texttt{result}
847 and corresponds to \texttt{b.Out}.
848 The figure \ref{bbi-fig-complex-black-box-1}
849 illustrates the external to internal
850 input/output correspondence.
852 Finally, the \texttt{endefine} command ends the definition of the
855 After this definition, if you ask for help
856 on packages, you get:
867 The \texttt{user} package now contains a new black box type, called
868 \texttt{Add3}. If you ask for help on this type of box, you get:
871 Complex Black Box <user::Add3>
875 'x' <double>: first double to add
876 'y' <double>: second double to add
877 'z' <double>: third double to add
879 'result' <double>: output
885 and you can use it like any other box, for example type:
897 As a side note, we can say that, for consistency reasons, it would have been better to name
898 \texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3},
899 since all the 'natural entry' of a box is named \texttt{In}, or\texttt{In}x if there are more than one 'natural
902 % ==========================================
907 \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.
908 Inside a \texttt{define/endefine} block:
910 \item The \texttt{author} and \texttt{description} commands allow to document the new type of box
911 \item The \texttt{input} and \texttt{output} commands allow to define the inputs and outputs of the new type of box, that is to which inputs and outputs
912 of internal boxes they correspond.
916 % ==========================================
918 % ==========================================
919 \subsubsection{Writing scripts}
920 \label{bbi-writing-scripts}
921 % ==========================================
923 Once you have defined a new type of complex box, you
924 may like to reuse it. To do this, you can simply
925 write the \bbi commands defining the new box
926 into a text file and afterwards include that file in \bbi.
927 Doing this, you start writing \bbi scripts.
928 The conventionnal extension for such scripts is \texttt{bbs}
930 For consistency reasons, you are requested to prepend \texttt{bb} to the name.
932 For example, the \texttt{Add3} complex box we previously worked on
933 can be defined in the \texttt{bbAdd3.bbs} file:
935 \begin{file}{bbAdd3.bbs}
937 # Defines the Add3 black box which adds 3 doubles
943 description "adds 3 doubles"
949 input x a.In1 "first double to add
950 input y a.In2 "second double to add
951 input z b.In2 "third double to add"
953 output result b.Out "output"
958 Lines starting with a \texttt{\#} character are ignored, they
959 are considered as comments by \bbi.
960 To use this file in \bbi, use the \texttt{include} command:
965 Complex Black Box <user::Add3>
969 'x' <double>: first double to add
970 'y' <double>: second double to add
971 'z' <double>: third double to add
973 'result' <double>: output
981 If the file has the \texttt{bbs} extension, you can ommit it and just type:
986 Of course, you can include script files in other script files,
987 like in the following example:
989 \begin{file}{bbAdd4.bbs}
991 # Defines the Add4 black box which adds 4 doubles
996 description "adds 4 doubles"
1000 input In1 a.In1 "first double to add
1001 input In2 a.In2 "second double to add
1002 input In3 a.In3 "third double to add"
1003 input In4 b.In2 "fourth double to add"
1004 output Out b.Out "output"
1009 % ==========================================
1011 \paragraph{Naming Conventions}
1015 % ==========================================
1019 For consistency reasons, you are requested to prepend \texttt{bb}, and postpone an extention \texttt{.bbs},
1020 to the names of the files that hold a \texttt{complex black box} definition.
1022 For example, the \texttt{Add3} complex box we previously worked on
1023 can be defined in the \texttt{bbAdd3.bbs} file.
1027 % ==========================================
1033 \item The \texttt{include} command allows to include a script file in \bbi.
1034 \item Lines starting with a \texttt{\#} or with a \texttt{\//} are treated as comments in \bbi scripts.
1035 \item Lines between a line starting with a \texttt{\//*} an a line starting with a \texttt{*\//} are treated as comments in \bbi scripts.
1039 % ==========================================
1041 % ==========================================
1042 \subsubsection{Creating command line applications}
1043 \label{bbi-command-line-app}
1044 % ==========================================
1046 Now that you now how to create complex black boxes
1047 (with \texttt{define/endefine}), think
1048 back to the \texttt{workspace} object.
1049 Remember that it is also
1050 a \texttt{complex black box}.
1051 In fact what you are doing when you type \bbi commands
1052 outside a \texttt{define/endefine} block
1053 is to progressively define the \texttt{workspace}
1055 You can think of it like if at start
1056 \bbi was issuing a command \texttt{'define workspace'}
1057 and then letting you define the interior of the box
1060 Remember that the command \texttt{inputs}
1061 allows to define an input of a complex box.
1062 Now, if you use the command \texttt{input}
1063 outside a \texttt{define/endefine} block then
1064 it defines an input of the \texttt{workspace} box,
1065 that is an input of the \emph{main program}.
1066 This input will then be connected to the
1067 parameters that the user passes to the command line.
1069 For example, consider the script:
1071 \begin{file}{add.bbs}
1075 input x a.In1 "first number to add"
1076 input y a.In2 "second number to add"
1081 The third and fourth lines define two inputs \texttt{x}
1082 and \texttt{y}. When you execute this script,
1083 you can pass these two arguments on the command line,
1091 You can also invoke \bbi the option \texttt{-h},
1092 which gives help on the \texttt{workspace} box:
1099 'x' <double>: first number to add
1100 'y' <double>: second number to add
1103 To get a better help, use the \texttt{description}
1104 and \texttt{author} commands:
1106 \begin{file}{add.bbs}
1108 description "Adds two numbers"
1109 author "foo@bar.com"
1112 input x a.In1 "first number to add"
1113 input y a.In2 "second number to add"
1118 Now if you ask for help on the \texttt{add} script, you get:
1125 'x' <double>: first number to add
1126 'y' <double>: second number to add
1129 Rather than getting the inputs of a script
1130 from the command line, you can ask \bbi to
1131 prompt the user for the values, using the \texttt{-t}
1136 x=[the program waits for user answer]2
1137 y=[the program waits for user answer]5
1141 If \bbi is compiled in graphical mode (with \wx),
1142 you can also use the \texttt{-g} commutator.
1143 \bbi then prompts the user in graphical mode,
1144 displaying a dialog box for each input,
1145 like in fig. \ref{bb-input-dialog-box}.
1148 \caption{\label{bb-input-dialog-box}Input dialog box}
1150 \includegraphics[width=0.6\textwidth]{enter-the-value-of-x.png}
1154 % ==========================================
1159 \item The \texttt{input}, \texttt{description} and \texttt{author} commands,
1160 when they are used outside a \texttt{define/endefine} block allow
1161 to define the inputs, description and author of the main program.
1162 \item Inputs of the main program can be passed on the command line
1163 using the syntax \texttt{<input-name>=<value>}.
1164 No white space is allowed, if the value or the input name
1165 contains white spaces, enclose them
1166 between double quotes, e.g. \texttt{"parameter with white spaces = gnu's not unix"}.
1167 \item The \texttt{-h} option of \bbi prints help on the main program.
1168 \item The \texttt{-t} option of \bbi orders the program to prompt for its inputs in text mode.
1169 \item The \texttt{-g} option of \bbi orders the program to prompt for its inputs in graphical mode.
1172 % ==========================================
1174 % ==========================================
1175 \subsubsection{Using graphical interface boxes (widget boxes)}
1177 % ==========================================
1179 % ==========================================
1180 \subsubsection{Overwiew}
1181 \label{bbi-overview}
1182 % ==========================================
1184 If \bbi is compiled in graphical mode
1185 (option \texttt{BUILD\_bbi\_GRAPHICAL} of \cmake, requires \wx),
1186 then you can use special black boxes which are
1187 graphical interface components (widgets).
1188 Basic components are provided in the package \texttt{wx},
1189 such as buttons, sliders, file open/save dialogs, etc.
1191 As first example, type the following commands in \bbi:
1198 When you type \texttt{enter} after the last line,
1199 a window pops up in which you can entrer a text.
1200 When you close the window, the text you entered is printed by
1201 the \texttt{print} command.
1203 Type \texttt{help wx}, you get something like:
1205 Package wx v1.0.0- info-dev@creatis.insa-lyon.fr
1206 Basic graphical interface elements (sliders, buttons ...) based on wxWidgets
1208 ColourSelector : Colour Selector dialog (bbfication of wxColourSele...
1209 ColourSelectorButton : A button which displays a colour picker dialog whe...
1210 CommandButton : Button which executes bbi commands
1211 DirectorySelector : Pops up a directory selection dialog (wxDirDialog)
1212 FileSelector : Pops up a file selection dialog for reading or sav...
1213 InputText : A zone in which the user can enter a text (wxTextC...
1214 LayoutLine : LayoutLine widget (wxBoxSizer)
1215 LayoutSplit : Widget which splits a window in two fixed size par...
1216 LayoutTab : LayoutTab widget (wxNotebook)
1217 OutputText : Text zone to be inserted into a window (wxStaticTe...
1218 RadioButton : RadioButton group widget 0-9 entries
1219 Slider : Slider widget (wxSlider)
1222 You can reproduce the same experiment as above using a
1223 \texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}.
1224 See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
1226 There are two kind of widgets: ``terminal'' widgets and ``container'' widgets.
1227 The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets
1228 are ``terminal'' widgets.
1229 ``container'' widgets are of another kind: they are designed to
1230 contain other widgets in order to build larger dialog boxes.
1231 For example, the \texttt{LayoutSplit} widget is a container which
1232 ``splits'' horizontally a window into two parts,
1233 each part including another widget.
1234 The size of the two parts can be adjusted by the user thanks
1237 The script \texttt{scripts/test/testSplit.bbs} demonstrate its use.
1238 Run it: it displays a window with two sliders.
1239 Move the sliders and close the window.
1240 The final positions of the sliders are printed out.
1241 Now edit the file to see how this is done:
1243 \begin{file}{scripts/test/testSplit.bbs}
1252 connect s1.Widget s.Widget1
1253 connect s2.Widget s.Widget2
1255 print s1=$s1.Out$\\n
1256 print s2=$s2.Out$\\n
1260 First, the two sliders \texttt{s1} and \texttt{s2} are created.
1261 A \texttt{LayoutSplit} box \texttt{s} is also created.
1262 The \texttt{connect} commands then ``includes'' the sliders in the
1263 split ``container''.
1264 The input \texttt{Widget} is common to all widget boxes:
1265 every widget can be inserted into another widget.
1266 The outputs \texttt{Widget1},\texttt{Widget2} are specific of \emph{container}
1268 (in \bbi type \texttt{help Slider}:
1269 you will see the output \texttt{Widget};
1270 type \texttt{help LayoutSplit}:
1271 you will see the inputs \texttt{Widget1} and \texttt{Widget2}
1272 and the output \texttt{Widget}).
1273 When you connect the \texttt{Widget} output of a container
1274 to the \texttt{Widget}i input of a widget,
1275 you order to include the widget in the container.
1276 Of course, the order of connection is important.
1277 In our case, the slider \texttt{s1} is included first,
1278 then the slider \texttt{s2}: \texttt{s1} will be placed
1279 on top of \texttt{s2} (the \texttt{LayoutSplit} box is
1280 implemented that way, but this is arbitrary choice).
1282 Right now, there are only \emph{three} container widgets in the \texttt{wx} package:
1283 the \texttt{LayoutSplit} widget we just described, the \texttt{LayoutLine} , and the \texttt{LayoutTab}
1286 The \texttt{LayoutLine} widget can have multiple children and
1287 divides its window into as much parts as children,
1288 each part of equal size.
1289 The orientation of the \texttt{LayoutSplit} or of the \texttt{LayoutLine} can be changed by the input \texttt{Orientation}.
1290 See the example \texttt{test/testSizer.bbs}.
1291 With only those two containers you can already create
1292 complex dialog boxes (of course containers can be nested, which
1293 leads to tree-like structures of widgets).
1294 See the script \texttt{bbtk/share/bbtk/bbs/wx/appli/ExampleLayoutSplit.bbs} for an example.
1296 The \texttt{LayoutTab} widget is based on the \texttt{wxNotebook.}
1298 One word about a special widget in the package \texttt{wx}:
1299 the \texttt{Button}... to be continued.
1301 % ==========================================
1302 \subsubsection{Deeper in the boxes}
1303 \label{bbi-deep-box}
1304 % ==========================================
1306 Any widget box has two mandatory Outputs :
1309 \item {\bf\emph{Widget}} : that is the \texttt{wxWindow} itself. If it's not connected to the \texttt{Widget}\emph{i} of any \emph{Layout box}, it
1310 will popup. If it's connected to the\bf{Widget}\bf\emph{i} of any \texttt{Layout box}, it will be embedded in its parent window.
1311 \item {\bf\emph{Boxchange}} : Signals any modification of the box. This output may be connect if necessary to the \emph{BoxExecute} of an other box,
1312 further within the execution pipeline.
1315 Any widget box has two mandatory Inputs :
1317 \item {\bf\emph{BoxExecute}} : Any signal received by this input executes the box
1318 \item {\bf\emph{BoxProcessMode}} : Sets the processing mode of the box :
1320 \item {\bf\emph{Pipeline}} : bbUpdate() only calls Process if Status == MODIFIED (normal pipeline processing)
1321 \item {\bf\emph{Always}} : bbUpdate() always calls Process
1322 \item {\bf\emph{Reactive}} : bbSetModifiedStatus() calls bbUpdate()
1326 Any widget box has five Inputs, that will be dealt with only if the box is not connected to the \emph{Widget}i of any \emph{Layout box} :
1328 \item {\bf\emph{WinHeight}} : Height of the window
1329 \item {\bf\emph{WinWidth}} : Width of the window
1330 \item {\bf\emph{WinTitle}} : Title of the window
1331 \item {\bf\emph{WinClose}} : Any received signal closes the window
1332 \item {\bf\emph{WinHide}} : Any received signal hides the window
1333 \item {\bf\emph{WinDialog}} : When set to 'true', creates a \emph{dialog window}, that blocks the pipeline until it is closed (\emph{modal})
1337 Any \emph{Layout box} (i.e. \emph{LayoutLine}, \emph{LayoutSplit} or \emph{LayoutTab}) has at one or more mandatory Inputs :
1339 \item \bf{Widget}\bf{\emph{i}} : e.g. a \emph{LayoutSplit} box (Widget which splits a window in two fixed size parts)
1340 has two Input parameters \emph{Widget1} and \emph{Widget2}, used to embed the child windows.
1347 \item Make a tour of ``complex'' widgets of wxvtk
1348 \item Explain the role of ProcessMode to update widgets
1349 \item Explain the creation of complex widgets (containers, contained...)
1350 \item Explain the ``control'' mechanism in bbi (switch exec commands, e.g. Button)
1354 % ==========================================
1355 \subsection{More on ...}
1357 % ==========================================
1359 % ==========================================
1360 \subsubsection{Black box packages}
1361 \label{bbi-more-on-packages}
1362 % ==========================================
1364 There are various others user-intended packages :
1367 It contains some vtk based image processing filters :
1369 \subparagraph{AppendPolyData}
1370 Appends one of more polygonal datasets into a single polygonal dataset
1371 \subparagraph{ConeSource}
1373 \subparagraph{ImageAnisotropicDiffusion3D}
1374 vtkImageAnisotropicDiffusion3D diffuses an volume iteratively.
1375 The neighborhood of the diffusion is determined by the instance flags.
1376 if 'Faces' is on, the 6 voxels adjoined by faces are included in the neighborhood.
1377 If 'Edges' is on the 12 edge connected voxels are included, and if 'Corners' is on, the 8 corner connected voxels are included.
1378 'DiffusionFactor' determines how far a pixel value moves toward its neighbors, and is insensitive to the number of neighbors chosen.
1379 The diffusion is anisotropic because it only occurs when a gradient measure is below 'GradientThreshold'.
1380 Two gradient measures exist and are toggled by the 'GradientMagnitudeThreshold' flag.
1381 When 'GradientMagnitudeThreshold' is on, the magnitude of the gradient, computed by central differences, above 'DiffusionThreshold' a voxel is not modified.
1382 The alternative measure examines each neighbor independently.
1383 The gradient between the voxel and the neighbor must be below the 'DiffusionThreshold' for diffusion to occur with THAT neighbor.
1384 \subparagraph{ImageCharacteristics}
1385 Exports objet sizes, and Spacings
1386 \subparagraph{ImageDilateErode3D}
1387 Dilates one value and erodes another.
1388 vtkImageDilateErode3D will dilate one value and erode another.
1389 It uses an elliptical foot print, and only erodes/dilates on the boundary of the two values.
1390 The filter is restricted to the X, Y, and Z axes for now.
1391 It can degenerate to a 2 or 1 dimensional filter by setting the kernel size to 1 for a specific axis.
1392 (bbfication of vtkImageDilateErode3D)
1393 \subparagraph{ImageGaussianSmooth}
1394 Performs a gaussian convolution of the input image
1395 \subparagraph{ImagePlanes}
1396 Creates three 3D planes with the input image mapped onto with which the user can interact.
1397 The output vtkImagePlaneWidget objects are to be inserted into a 3D scene (e.g. a Viewer3D
1398 \subparagraph{IsoSurfaceExtractor}
1399 Extracts an iso-surface of a 3D image and creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D
1400 \subparagraph{MarchingCubes}
1401 Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes
1402 \subparagraph{MIPCreator}
1403 Creates a Maximum Intensity Projection (MIP) view of a 3D image.
1404 Creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D
1405 \subparagraph{MetaImageReader}
1406 Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader)
1407 \subparagraph{SegmentationConnectivity}
1408 Segmentation with min max threshold and connectivity
1409 \subparagraph{SphereSource}
1414 It contains some itk based image processing filters :
1416 \subparagraph{BinaryThresholdImageFilter}
1417 Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter)
1418 \subparagraph{DICOMSeriesFileNames}
1419 Reads a series from a DICOM directory as a 3D itk image
1420 \subparagraph{ExtractImageFilter}
1421 Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)
1422 \subparagraph{ImageProperties}
1423 Outputs different properties of an image (type, dimension, size, spacing, ...)
1424 \subparagraph{ImageRegion}
1425 Creates a generic ImageRegion (bbtk::any) from two vectors providing the index and size of the region.
1426 The dimension D of the actual itk::ImageRegion created is the max of the sizes of Index and Size
1427 (the smallest vector is padded by zeros)
1428 \subparagraph{ImageReader}
1429 Generic itk image reader
1430 \subparagraph{ImageWriter}
1431 Generic itk image writer
1432 \subparagraph{ImageSeriesReader}
1433 Generic itk image series reader.
1434 \subparagraph{ResampleImageFilter}
1437 It doesn't contain any end user intended box, only adaptors : to convert a generic itkImage to a vtkImageData, and vtkImageData* to a generic itkImage pointer
1439 Sorry nothing is done, right now for meshes.
1442 It contains two atomic black boxes, and some sophisticated complex black boxes :
1444 \subparagraph{Viewer2D}
1445 Receives a \textless vtkImageData* \textgreater (In), an Orientation(0:yz / 1:xz / 2:xy), and a initial slice number (Slice).
1446 Returns a \textgreater vtkRenderer* \textgreater (Renderer)
1448 \subparagraph{Viewer3D}
1449 Receives up to 5 Input Actors (\textless vtkProp3D* \textgreater), up to 5 Imput Observers (\textless vtkInteractorObserver* \textgreater),
1450 outputs an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact,
1451 and a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
1452 Has also a boolean 'Stereo' option, to use Red-Blue filter.
1454 \subparagraph{Viewer3D}
1457 % ==========================================
1458 \subsubsection{Pipeline processing}
1459 \label{bbi-more-on-pipeline-processing}
1460 % ==========================================
1462 % ==========================================
1463 \subsubsection{Complex black boxes}
1464 \label{bbi-more-on-complex-black-boxes}
1466 %\subsubsection{Advanced issues}
1467 %\paragraph{Reducing the number of inputs of a box}
1469 % ==========================================
1470 \subsubsection{Errors}
1471 \label{bbi-more-on-errors}
1473 % ==========================================
1474 \subsubsection{\bbtk configuration file and search pathes}
1475 \label{bbi-more-on-configuration}
1477 At start, \bbi tries to open an \texttt{xml}
1478 configuration file named \texttt{bbtk\_config.xml}.
1481 \item The current directory
1482 \item The subdir \texttt{.bbtk} of the user's home directory.
1484 \item On \texttt{Unix}, the home directory is the
1485 one stored by the environnement variable \texttt{HOME},
1486 typically \texttt{/home/username}.
1487 \item On \texttt{Windows}, the home directory is
1488 the user's profile directory stored by the environnement
1489 variable \texttt{USERPROFILE},
1490 typically \texttt{C:\\...}.
1492 \item If none of these two pathes contains the file then it creates
1493 a new one in the \texttt{.bbtk} directory.
1496 Once created, you can edit the \texttt{bbtk\_config.xml} file located
1497 in your \texttt{.bbtk} directory. It contains:
1499 \begin{file}{bbtk\_config.xml}
1501 <?xml version="1.0" encoding="iso-8859-1"?>
1503 <bbtk_url> http://www.creatis.insa-lyon.fr/software/bbtk </bbtk_url>
1504 <bbs_path> </bbs_path>
1505 <package_path> </package_path>
1506 <data_path> </data_path>
1511 You can add pathes to
1513 \item A custom folder in which to search for \texttt{.bbs} scripts (\texttt{include} command of \bbi) by adding an \texttt{xml} tag:
1514 \texttt{<bbs\_path>complete\_path\_to\_folder<\/bbs\_path>}.
1515 \item A custom folder in which to search for packages (\texttt{load} command of \bbi) by adding an \texttt{xml} tag:
1516 \texttt{<package\_path>complete\_path\_to\_folder<\/package\_path>}.
1519 % ==========================================
1520 \subsection{Language reference}
1521 \label{bbi-reference}
1522 % ==========================================
1528 % ==========================================
1530 \caption{\label{bbi-reference-box}
1531 \bbi pipeline creation and execution related commands.}
1533 \begin{tabular}{|lcm{6cm}|}
1535 Command & Parameters & Effect \\ \hline
1537 \texttt{new} & \texttt{<boxtype>} \texttt{<box-name>}&
1538 Creates a box of type \texttt{boxtype} and name
1542 \texttt{delete} & \texttt{<box-name>} &
1543 Destroys the box named \texttt{box-name}.
1546 \texttt{connect} & \texttt{<box1.output>} \texttt{<box2.input>} &
1548 \texttt{output} of the box named \texttt{box1}
1549 to the input \texttt{input} of the box named \texttt{box2} \\ \hline
1551 \texttt{set} & \texttt{<box.input>} \texttt{<value>} &
1552 Sets the input \texttt{input} of
1553 the box named \texttt{box} to the value \texttt{value}.
1554 There must exist an \texttt{adaptor}
1555 in the packages loaded which converts a \texttt{std::string}
1556 to the type of the input \texttt{input}.
1559 \texttt{print} & \texttt{<string>} &
1560 Prints the string after substituting each token of the form \texttt{\$box.output\$} by the adaptation to string of the value of the
1561 output \texttt{output} of the box named \texttt{box}.
1562 There must exist an \texttt{adaptor}
1563 in the packages loaded which converts
1564 the type of the output \texttt{output}
1565 to a \texttt{std::string}.
1568 \texttt{exec} & \texttt{<box-name>} &
1569 Executes the box named \texttt{box-name}.
1571 connected to its inputs
1572 are also processed recursively (pipeline processing).\\ \hline
1575 % ==========================================
1579 % ==========================================
1581 \caption{\label{bbi-reference-interpreter}\bbi intepreter related commands.}
1583 \begin{tabular}{|lcm{6cm}|}
1585 Command & Parameters & Effect \\ \hline
1589 Prints help on available commands \\ \hline
1591 & \texttt{<command-name>} &
1592 Prints help on the command \texttt{command-name} \\ \hline
1594 & \texttt{packages} &
1595 Prints help on available packages and their box types
1596 (without description)\\ \hline
1598 & \texttt{<package-name>} &
1599 Prints help on the package \texttt{package-name} and its boxes
1600 (with brief description).
1601 The package must have been previously loaded
1604 & \texttt{<box-type>} &
1605 Prints help (with full description) on the type of box
1607 The box type must belong to a package which has been previously loaded
1610 \texttt{include} & \texttt{<file-name>} &
1611 Includes and executes the content of the file named \texttt{file-name}
1612 exactly like if you were typing its content at the place were the
1613 \texttt{include} command is.
1616 \texttt{load} & \texttt{<package-name>} &
1617 Loads the package \texttt{package-name}\\ \hline
1619 \texttt{unload} & \texttt{<package-name>}&
1620 Unloads the package \texttt{package-name}.
1621 The package must have been previously loaded.
1622 No box of a type defined in this package must still exist.
1625 \texttt{message} & \texttt{<category>} \texttt{<level>} &
1626 Sets the level of verbosity of \bbi for the category of messages
1627 \texttt{category} to \texttt{level}.
1628 %See \ref{verbosity}.
1631 \texttt{config} & - & Displays the Configuration parameters\\ \hline
1633 \texttt{reset} & - & Deletes all boxes and unloads all packages so
1634 that \bbi gets back to its initial state \\ \hline
1636 \texttt{quit} & - & Exits the interpreter\\ \hline
1640 % ==========================================
1646 % ==========================================
1648 \caption{\label{bbi-reference-complex-box}
1649 \bbi complex black box definition related commands.}
1651 \begin{tabular}{|lcm{6cm}|}
1653 Command & Parameters & Effect \\ \hline
1656 \texttt{define} & \texttt{<box-type>} &
1657 Starts the definition of a complex black box of type
1658 \texttt{box-type}\\ \hline
1660 \texttt{endefine} & - &
1661 Ends the definition of a complex black box type\\ \hline
1664 \texttt{author} & \texttt{<string>} &
1665 Sets the author(s) of the complex black box currently being defined \\ \hline
1667 \texttt{description} & \texttt{<string>} &
1668 Sets the description of the complex black box currently being defined
1672 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} &
1673 Defines a new input for the current complex black box,
1674 named \texttt{name}.
1675 It is defined as corresponding to
1676 the input \texttt{input} of the box \texttt{box}.
1677 \texttt{<help>} is the help string for the new input.
1678 The box \texttt{box} must already have been created in the complex box
1679 and of course have an input named \texttt{input}.
1683 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} &
1684 Defines a new output for the current complex black box,
1685 named \texttt{name}.
1686 It is defined as corresponding to
1687 the output \texttt{output} of the box \texttt{box}.
1688 \texttt{<help>} is the help string for the new output.
1689 The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}.
1695 % ==========================================
1700 % ==========================================
1701 \vspace{0.5cm}\hrule
1702 \section{Using black boxes in \CPP programs}
1704 % ==========================================
1713 %\section{Conclusion}