1 % ==========================================
2 \documentclass[11pt,final,a4paper]{article}
5 \title{The Black Box Toolkit\\User's Guide}
7 \author{Laurent Guigues}
9 % ==========================================
11 % ==========================================
17 % ==========================================
19 % ==========================================
21 % ==========================================
23 \section{What is {\bf bbtk} ?}
24 % ==========================================
25 \BBTK(\bbtkns) is a set of tools
26 (\CPP libraries and executables)
27 providing a \CPP framework for the definition
28 of elementary processing \emph{units}, called {\bf black boxes},
29 and the definition and execution of processing \emph{chains}
30 made up of these black boxes.
32 % ==========================================
33 \subsection{The black box philosophy}
34 % ==========================================
35 \href{http://en.wikipedia.org/wiki/Black_box_\%28disambiguation\%29}{Wikipedia}
36 defines a {\bf black box} as
37 \emph{``any component in a system in which only the input and output
38 characteristics are of interest, without regard to its internal mechanism
40 I would add something very important to this definition :
41 not only the inputs and outputs are of interest but also
42 \emph{what the box does} !
43 Hence, I would say that a black box is any \emph{\bf documented}
44 component of a system, letting the user know
45 \emph{\bf what} the box is supposed to do and
46 \emph{\bf how to use it}
47 but not \emph{\bf how it does it}.
49 \BBTK provides a systematic framework
50 to encapsulate (or ``wrap'') any
51 existing \texttt{C} or \CPP processing code into an object
52 (a black box) having a {\bf generic symbolic interface}, where
55 \item{\bf generic} means that the interface is \emph{the same}
56 for all boxes. Hence one does not need to know which particular
57 method allows, say, to set a particular input or
58 get a particular output of the box.
59 One can use a black box in a purely abstract way.
60 \item{\bf symbolic} means that a particular
61 input or output is referenced by a 'name', that is by a symbol
62 which identifies the input or output.
63 It also means that symbolic information (text!) is
64 attached to a box: description of the box, author,
65 description of its inputs and outputs, etc.
68 (in fact, genericity is achieved because the interface is symbolic.
69 I let you think about this\dots)
71 Of course, symbolic data attached to box can be
72 {\bf queried}: what are the inputs/outputs of the box ?
73 what are their type ? their description ? etc.
74 This allows {\bf automatic documentation} of boxes.
76 The abstract definition of black boxes is the most basic
77 aspect of \BBTK architecture.
78 Another key aspect is the groupement of black boxes into
79 so called {\bf packages},
80 which are \emph{dynamic libraries} which can also
81 be queried, in particular about the boxes they provide.
82 The package structure then offers a mechanism which
83 is like a \emph{'plug-in'} mechanism.
84 \BBTK provides the methods to load a package at run-time,
85 and create instances of the boxes it contains.
87 These two mechanisms (black boxes and packages)
88 then gives the way to:
91 \item The definition of an {\bf interpreted language},
92 which allows to manipulate packages and boxes very easily in symbolic way.
93 \BBTK provides one: \bbi (the Black Box Interpreter).
94 \item {\bf Automatic documentation} of existing packages.
95 \texttt{html} documentation of packages is proposed by
99 Finally, these different components allow {\bf efficient}:
102 \item {\bf capitalization and reuse} of existing processing units,
103 including {\bf documentation}
104 \item {\bf testing, prototyping} in a very simple script language
105 \item {\bf inter-operability} between atomic processings which
106 have been written by different persons, using different libraries, etc.
109 % ==========================================
110 \subsection{\bbtk components}
111 % ==========================================
114 \item A \CPP {\bf\emph{library}} - called \bbtk - which defines a framework
115 (abstract classes) to develop black boxes and to store them into
116 dynamic libraries, called black box \emph{packages}.
117 \item Different {\bf\emph{black box packages}}:
119 \item {\bf\emph{std}}: the 'standard' package including basic useful boxes.
120 \item {\bf\emph{wx}}: basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library).
121 \item {\bf\emph{itk}}: the basic image processing package, based on the \texttt{itk} library.
122 \item {\bf\emph{vtk}}: the basic image and surfaces processing package, based on the \texttt{vtk} library.
123 \item {\bf\emph{wxvtk}}: widget boxes based on the \texttt{vtk} library.
124 \item {\bf\emph{itkvtk}}: boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally.
126 \item A {\bf\emph{Developement environment}}, called bbStudio, which provides
128 \item An online {\bf\emph{script editor}}, called bbed
129 \item A powerfull {\bf\emph{Help environment}}, called bbhelp
132 \item Online documentation scaning
133 \item Retreiving boxes on various criterions
134 \item Checking Demo and examples
137 \item An {\bf\emph{interpreter}}, called \bbi, which allows to
138 load black box packages and to define and execute
139 processing chains by connecting various black boxes of the already loaded packages.
140 \item {\bf\emph{Utilities}}:
142 \item \bbfy generates the \CPP code of a black box from a
143 description file written in \texttt{xml}.
144 %\item \bbdoc generates the html documentation of a black box package
145 %(author, description, description of its black boxes:
146 %author, description, inputs, outputs, and so on).
147 \item \bbCreatePackage allows to create the basic file architecture
148 to start the development of a new black box package.
152 The general architecture of \BBTK
153 is shown in figure \ref{bb-architecture}.
156 \caption{\label{bb-architecture}\BBTK architecture}
158 \includegraphics[width=0.6\textwidth]{bb-architecture.png}
162 % ==========================================
163 \subsection{Structure of this guide}
164 % ==========================================
166 This guide is divided into three parts.
168 The first part (\ref{bbStudio}) is a brief presentation of the very intuitive Development
169 environment, \bbStudio.
171 The second part (\ref{bb0})
172 is devoted to the use of the \emph{black box interpreter} \bbi.
173 This is the highest level of use of the toolkit, which
174 allows to create and execute processing chains by connecting
175 black boxes of existing packages.
177 The third part (\ref{cpp}) explains how to
178 use the black box toolkit framework in \CPP code,
179 typically to develop large applications which
180 involve complex graphical interfaces.
183 % ==========================================
184 % ==========================================
185 % ==========================================
186 % ==========================================
187 % ==========================================
188 % ==========================================
190 \section{The Development environment (bbStudio)}
193 Just run it, typing in a console \texttt{bbed}.
194 You'll get something like in figure
195 \ref{bbi-fig-bbStudio-gui}
196 (the exact appearance of \bbStudio is system and \bbtk version dependent)
199 \caption{\label{bbi-fig-bbStudio-gui}The bbStudio Development environment interface}
201 \includegraphics[width=0.7\textwidth]{bbStudioMainPage.png}
205 All the entries of this Help 'bookmark' are self-explanatory :
208 \item {\bf\emph{Wiki}}: Direct link to the bbtk Wiki (intranet only, right now, www
210 \item {\bf\emph{Demo}}: Link to some demonstrations.
211 \item {\bf\emph{User's Guide}}: Step to step How-to for user who just wants to create his own
212 application, just using already existing boxes.
213 \item {\bf\emph{Package Developper's Guide}}: Step to step How-to for user who wants to create his own
215 \item {\bf\emph{Developper's Guide}}: Sorry, not yet written.
216 \item {\bf\emph{Reference Manual}}: Sorry, not yet written.
217 \item {\bf\emph{Doxygen Documentation}}: Doxygen source browser.
218 \item {\bf\emph{Boxes}}: Box retrieving on various criterions :
220 \item {\bf\emph{By name}}
221 \item {\bf\emph{By package}} (see table : \ref{bbi-list_of_packages})
222 \item {\bf\emph{By category}} (see table :\ref{categories})
223 \item {\bf\emph{Adaptors}} Used internaly to perform type conversions (not end user intended)
228 % ==========================================
230 \caption{\label{bbi-list_of_packages} List of bbtk supplied packages.}
232 \begin{tabular}{|ll||}
234 Package & What it's used for \\ \hline
235 \texttt{std} & : the 'standard' package including basic useful boxes \\ \hline
236 \texttt{wx} & : basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library \\ \hline
237 \texttt{itk} & : the basic image processing package, based on the \texttt{itk} library. (without description)\\ \hline
238 \texttt{vtk} & : Prints help on the package \texttt{package-name} and its boxes (with brief description). The package must have been previously loaded\\ \hline
239 \texttt{wxvtk} & : widget boxes based on the \texttt{vtk} library.\\ \hline
240 \texttt{itkvtk} & : boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally.\\ \hline
244 % ==========================================
249 % ==========================================
251 \caption{\label{categories} \texttt{Black Box} categories}
253 \begin{tabular}{|ll|}
255 \texttt{Categ name} & : Meaning \\ \hline \\ \hline
256 \texttt{adaptor} & : Adaptor box \\ \hline
257 \texttt{application} & : Final application, end user intended \\ \hline
258 \texttt{atomic box} & : System category.
259 Automatically assigned to Atomic Black Boxes (c++ defined) \\ \hline
260 \texttt{complex box} & : System category.
261 Automatically assigned to Complex Black Boxes (script defined) \\ \hline
262 \texttt{command line} & : Script which defines a command line application \\
263 & :(no embedded GUI, but command line imput parameters) \\ \hline
264 \texttt{demo} & : Demonstration \\ \hline
265 \texttt{devel} & : Developer tool (bbCreatePackage.bbs, ...) \\ \hline
266 \texttt{dicom} & : DICOM aware box \\ \hline
267 \texttt{example} & : Example script showing a box use-case \\ \hline
268 \texttt{filter} & : Image processing box \\ \hline
269 \texttt{image} & : Image processing related box \\ \hline
270 \texttt{interaction} & : \\ \hline
271 \texttt{math} & : Mathematical operations \\ \hline
272 \texttt{mesh} & : Mesh processing related box \\ \hline
273 \texttt{misc} & : A box that cannot be put in other category ! \\ \hline
274 \texttt{read/write} & : Box that read or write data from or to disk \\ \hline
275 \texttt{viewer} & : Box which displays some data \\ \hline
276 \texttt{widget} & : Piece of graphical interface \\ \hline
278 \texttt{3D object creator} & : Sophisticated 3D widget \\ \hline
279 \texttt{toolsbbtk} & : Component of bbStudio \\ \hline
283 % ==========================================
286 \caption{\label{kinds} \texttt{Black Box} kinds}
288 \begin{tabular}{|ll|}
290 \texttt{Kind name} & : Meaning \\ \hline \\ \hline
291 \texttt{ADAPTOR} & : Adaptor Box \\ \hline
292 \texttt{DEFAULT\_ADAPTOR} & : \\ \hline
293 \texttt{WIDGET\_ADAPTOR} & : \\ \hline
294 \texttt{DEFAULT\_WIDGET\_ADAPTOR} & : \\ \hline
295 \texttt{GUI} & : \\ \hline
296 \texttt{DEFAULT\_GUI} & : \\ \hline
297 \texttt{ALL} & : If kind='ALL' then sets the level for all kinds \\ \hline
303 % ==========================================
304 % ==========================================
305 % ==========================================
306 % ==========================================
307 % ==========================================
308 % ==========================================
310 \section{The script manager}
312 % ==========================================
314 Call it with the bookmark \emph{File}.
318 \caption{\label{bbi-fig-bbStudio-file0}The bbStudio script manager}
320 \includegraphics[width=0.7\textwidth]{bbFile0.png}
324 Using the lower tool bar, you can :
327 \caption{\label{lowertoolbar}The lower tool bar}
329 \includegraphics[width=0.7\textwidth]{lowertoolbar.png}
335 \item {\bf\emph{new}}: Create a newfile to hold a script
336 \item {\bf\emph{open}}: Open a already existing file holding a script
337 \item {\bf\emph{close}}: Close a file holding a script
338 \item {\bf\emph{save}}: Save he current file (if modified)
339 \item {\bf\emph{save as}}: Save he current file under a different name
340 \item {\bf\emph{execute}}: Execute the script you just loaded/modified/written
344 The script language is very simple.
345 Everything is done with only a very few commands (See table \ref{bbi-reference-box}).
346 The philosophy of this part is also very simple:
347 it introduces the \bbi commands using examples,
348 starting with the most simple commands.
349 The first section of this part
350 (\ref{bbi-getting-started})
351 is designed like a tutorial,
352 which progressively introduces all the concepts of \bbi.
353 We suggest you run \bbi and follow the examples,
354 to see how it works in practice.
355 At the end of this section,
356 you will be able to use \bbi and write
357 own black box processing scripts.
360 the section \ref{bbi-more-on}
361 (called \emph{more on...})
362 goes deeper into various issues of \bbi.
363 Read it at your convenience,
364 either linearly to learn more about \bbi,
365 or in random order to get an answer
366 to a particular question.
368 Finally, the section \ref{bbi-reference}
369 summarizes all the commands of \bbi,
370 their parameters and effect.
371 Use it as a reference.
373 % ==========================================
374 \subsection{Getting started}
375 \label{bbi-getting-started}
376 % ==========================================
377 \subsubsection{Creating and executing black boxes}
378 % ==========================================
380 To learn interactivelly the script language features, you can use the black box
382 open a console and type \texttt{bbi}
383 or double click on the application icon.
384 You get a window which looks like the one in figure
385 \ref{bbi-fig-bbi-gui}
386 (the exact appearance of \bbi is system and \bbtk version dependent)
387 \footnote{If you compiled \bbtk without \wx then \bbi does not have a
388 graphical interface but a simple prompt}.
391 \caption{\label{bbi-fig-bbi-gui}The black box interpreter interface}
393 \includegraphics[width=0.7\textwidth]{bbi-gui0.png}
397 The 'Command' tab is subdivided into two parts :
398 one single line zone at the bottom in which you can enter your commands and
399 one multiple line zone in which \bbi prints out the result of your commands.
400 , just using already existing boxes.
402 Try typing in the input zone (in this manual,
403 the commands entered by the user will be preceded by a prompt \textgreater) :
408 you get the list of the commands of the interpreter:
441 To get help on a particular command type \texttt{help <command-name>},
451 Quits the program (during script execution it stops the complete execution)
454 The \texttt{help} command has multiple usages.
455 It is used to get help on almost anything in \bbi !
456 Type \texttt{'help help'} to get help on the \texttt{help} command itself:
461 (2) help <command name>
462 (3) help packages [all]
463 (4) help <package name> [all]
464 (5) help <black box type>
465 (6) help <black box name>
467 (1) Lists all available commands;
468 (2) Prints help on a particular command;
469 (3) Lists the packages loaded and their black boxes.
470 Add 'all' to list adaptors;
471 (4) Prints short help on the black boxes of a package.
472 Add 'all' to include adaptors;
473 (5) Prints full help on a black box type;
474 (6) Prints information on the inputs, outputs and connections of a black box instance.
477 At start \bbi does not know any black box.
478 If you type \texttt{'help packages'}, which is
479 the third form of the \texttt{help} command, you get:
486 which means that \bbi only knows one package
487 (library of black boxes) called \texttt{user}
488 and which contains a black box called \texttt{workspace}.
489 The \texttt{user} package is an internal package to \bbi,
490 which stores user-defined black box types.
491 At start, it already contains
492 one box, called \texttt{workspace}.
493 \texttt{workspace} is a special type of black box,
494 called complex black box, whose purpose is
495 to store other black boxes.
496 Any black box you create in \bbi is stored
497 in \texttt{workspace}
498 (this will be explained in details in sections
499 \ref{bbi-writing-scripts} and
500 \ref{bbi-more-on-complex-black-boxes}).
502 If you type \texttt{'help workspace'}, you get:
505 Complex Black Box <user::workspace>
508 Category(s) : complex box;
514 In the text displayed,
515 the \texttt{user::} prepended to the name \texttt{workspace}
516 means that the box \texttt{workspace}
517 belongs to the \texttt{user} package.
518 Then comes a description and three lines which
519 tell that \texttt{workspace} does not have any input
520 nor output nor boxes yet.
522 In order to let \bbi know of some black boxes,
523 you must load another package.
524 The \texttt{std} package is the ``standard'' package,
525 which contains basic useful black boxes.
537 you get something like:
552 Now \bbi knows the package \texttt{std} and the black boxes it provides,
553 such as the \texttt{'Add'} box, the \texttt{'ConcatStrings'}. Remark that the
554 content of \texttt{std} may vary from one version to another
555 as new black boxes might be added to it.
565 By : laurent.guigues@creatis.insa-lyon.fr
566 Categories : atomic box;math;
568 'BoxExecute' <bbtk::Void> [signal] : Any signal received by this input executes the box
569 'BoxProcessMode' <String> [] : Sets the processing mode of the box (Pipeline | Always | Reactive)
570 'In1' <Double> [] : First number to add
571 'In2' <Double> [] : Second number to add
573 'BoxChange' <bbtk::Void> [signal] : Signals modifications of the box
574 'Out' <Double> [] : Result
578 the \texttt{std::} prepended to the name \texttt{Add}
579 means that the box \texttt{Add}
580 belongs to the \texttt{std} package.
581 Then comes a description
582 (the one which was provided by the author of the box),
583 the author(s) of the box (usually e-mail adress(es)) and
584 the categories to which the box belong.
585 Finally comes the lists of inputs and outputs of the box.
586 For each input or output, \bbi provides
587 its \emph{name} (between quotes, e.g. \texttt{'ProcessMode'}),
588 its \emph{type} (between \texttt{<>}, e.g. \texttt{<Int>})
590 Remark that the box \texttt{Add} is not a 'complex' black box
591 but an 'atomic' box, hence its help does not
592 mention any information concerning possible internal boxes.
594 You can create an \emph{instance} of an \texttt{Add} box by
595 the command \texttt{new}:
600 The \texttt{'a'} at the end is the \emph{name} of the instance,
601 which will be used to reference it later.
602 It is important to distinguish a box \emph{type}
603 and an \emph{instance} of a box type.
604 The \texttt{Add} box of the package \texttt{std} is actually
605 a \emph{box type} , like \texttt{int} is a data type
606 in \texttt{C} langage. The \texttt{new} command allows to create
607 an instance of a box type, exactly like \texttt{int i;} in
608 a \texttt{C} code, it declares a variable of type \texttt{int} whose
610 Of course, like in \texttt{C} Language, you can declare multiple boxes of the
613 After the creation of the box \texttt{a}, type:
620 Complex Black Box <user::workspace>
623 Category(s) : complex box;
630 which means that \bbi workspace now contains a black box named \texttt{a},
631 of type \texttt{std::Add}.
633 Now look back at the help on \texttt{Add} boxes:
634 you can see that this type of box has two inputs,
635 with name \texttt{In1} and \texttt{In2},
636 and an output, with name \texttt{Out}.
638 You can set the input \texttt{In1}
639 of the \texttt{Add} box \texttt{a} to the value $1$
645 Similarly, setting the input \texttt{In2} of \texttt{a} to the value $2$
651 And you print the output \texttt{Out} of the box \texttt{a} with:
653 > print "result=$a.Out$"
657 In the string passed to the \texttt{print} command,
658 each substring enclosed between a couple of \$ is considered
659 as the name of an output of a box.
660 To process this special substrings, \bbi does:
662 \item Processes the box if needed (see below)
663 \item Converts the output of the box to a string if possible
665 \item Substitutes the result in the string to print
666 \item postpone an implicit 'new line' character to the string
670 Box processing is needed if:
672 \item at least input has changed since last processing or
673 \item the input \texttt{'BoxProcessMode'} of the box is set to
674 \texttt{'Always'}, which forces box reprocessing.
677 Note that all boxes have the input \texttt{'BoxProcessMode'}.
679 Another way to process the box \texttt{a} is to issue the command:
684 however this command does not display anything (except if the
685 box itself displays something in its processing).
686 It just processes the box if needed.
687 This command is used to execute boxes that do not have any output,
688 such as boxes that write something to a file or, display a
689 graphical interface, and so on.
697 % ==========================================
702 \item The \texttt{include} command allows to load a package, and the complex black boxes that come with it..
703 \item \texttt{help} gives help on:
705 \item Available commands if you just type \texttt{help}.
706 \item A particular command if you type \texttt{help <command-name>}.
707 \item All available packages and their boxes (without description) if you type \texttt{help packages}.
708 \item A particular package and its boxes (with brief description) if you type \texttt{help <package-name>}.
709 \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}).
711 %\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).
712 \item \texttt{new} : creates an instance of a black box.
713 \item \texttt{set} : sets the value of an input of a black box.
714 \item In all \bbi, to reference the input called \texttt{i}
715 of a black box called \texttt{b} you must type \texttt{'b.i'}.
716 The same syntax holds for outputs.
717 \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
718 implicit trailing 'new line character' is added at the final string.
719 \item \texttt{exec} : runs the process of a box if needed.
720 \item \texttt{quit} : quits \bbi.
725 A more 'modern' way to proceed is to run \texttt{bbStudio}, drag and drop the \texttt{Command} bookmark to the lower \texttt{Welcome to bbStudio!} bar.
726 Wou'll get something like in figure \ref{bbCommandPlusHelp} :
729 \caption{\label{bbCommandPlusHelp}
730 An other way to run the command interpreter}
732 \includegraphics[width=0.5\textwidth]{bbCommandPlusHelp.png}
735 % ==========================================
737 % ==========================================
738 \subsubsection{Connecting black boxes}
739 \label{bbi-connecting-black-boxes}
740 % ==========================================
742 \BBTK allows to create
743 and execute processing chains,
744 also called \emph{pipelines},
745 by connecting black boxes.
746 This section explains how to do it with examples.
747 Read section \ref{bbi-more-on-pipeline-processing} to get
748 more information on pipeline processing.
750 First start \bbi and load the package \texttt{std}:
755 Assume you want to compute $1+2+3$. You can do it by
756 chaining two \texttt{Add} boxes, as shown in figure
757 \ref{bbi-fig-connecting-black-boxes-1}.
760 \caption{\label{bbi-fig-connecting-black-boxes-1}
761 A simple pipeline which adds 3 numbers}
763 \includegraphics[width=0.5\textwidth]{1plus2plus3.png}
768 The \bbi instructions to create and execute this pipeline are:
772 > connect a.Out b.In1
779 You will see the (very expected) result :
784 The first three commands build the pipeline,
785 the next three set \texttt{a} and \texttt{b} black boxes inputs and the last one
786 prints \texttt{b} black boxe output (the pipeline is executed before printing, because the interpretor 'knows' he box \texttt{b},
787 whose output is requested, is not up to date.
789 The command \texttt{'connect a.Out b.In1'} ``plugs'' the output
790 \texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the
792 Once the boxes connected, the processing of the two boxes are chained:
793 getting the output of \texttt{b} requires getting its inputs,
794 hence getting the output of \texttt{a} which is connected to it.
795 This pipeline mechanism can recurse into arbitrary long
796 chains of boxes (see \ref{bbi-more-on-pipeline-processing}
800 Lets' consider an other, more image oriented, example :
808 > new FileSelector fileDialog
809 > new ImageReader reader
811 > new Viewer2D viewer
813 > connect fileDialog.Out reader.In
814 > connect reader.Out viewer.In
815 > connect slider.Out viewer.Slice
816 > connect slider.BoxChange viewer.BoxExecute
821 Some explainations : the \texttt{include} instructions load the necessary packages. \\
823 \texttt{new FileSelector} will pop a File Selector, at run time, that will out the user chosen file name. \\
824 \texttt{new Slider} will pop a Slider, at run time, that will out an integer, used later as a slice number.\\
825 \texttt{new ImageReader} will read any itk readable file, whose name is passed as a std::string, and return a itk::ImagePointer.
826 \texttt{new Viewer2D} display a plane, whose number id specified by an integer.\\
828 \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).\\
829 \texttt{connect reader.Out viewer.In} plugs the output of the reader (an itk::ImagePointer) to the input of the Viewer (a vtkImageData *)\\
830 \texttt{connect slider.Out viewer.Slice} plugs the output of the slider (an int) to an other output (named Slide) of the viewer.\\
831 \texttt{connect slider.BoxChange viewer.BoxExecute} says the viewer it must re process itself any time the slider is modified.\\
833 \texttt{exec viewer} processes the viewer.
836 This would correspond to the graph in figure \ref{bbi-simplegraph}
840 \caption{\label{bbi-simplegraph}(Very) simple Graph of a (very) simple pipeline}
842 \includegraphics[width=0.8\textwidth]{bbi-simplegraph.png}
846 Of course, to be able to connect two boxes,
847 the output and the input must be compatibles.
848 You can always connect an output to an input of the \emph{same} type,
849 but you can do more, thanks to particular (hidden) black boxes called {\bf adaptors}.
851 An adaptor is a black box which has at least one input, called \texttt{In},
852 and at least one ouput called \texttt{Out} and whose role is to convert
853 a data of the type of \texttt{In}
854 into a data of the type of \texttt{Out} (other inputs or outputs may serve
855 to parameter the adaptor or retreive other usefull information).
857 In \bbi, if you type:
864 Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
865 Basic useful black boxes
867 Add : Adds its inputs
868 Cast<double,float> [DA] : Casts a double into a float
869 Cast<double,int> [DA] : Casts a double into a int
871 Convert<unsigned int,string> [DA] : Converts a unsigned int into a s...
872 Convert<unsigned short,string> [DA] : Converts a unsigned short into a...
873 Print : Prints its input to standard out...
877 The \texttt{Cast<?,?>} and \texttt{Convert<?,?>} boxes are \emph{default adaptors}, which is signaled by the tag \texttt{[DA]} before their descriptions.
879 Once you have loaded the package \texttt{std}, you can
880 plug an output of type \texttt{char} into an input of type \texttt{double}.
881 When \bbi encounters the \texttt{connect} command,
882 it looks for an adequate \emph{adaptor} in the loaded packages.
883 In our case, as the package \texttt{std} provides the
884 \texttt{Cast<char,double>} adaptor, \bbi automatically creates an
885 instance of this adaptor and place it \emph{between}
886 the output and the input you want to connect
887 (however this adaptor is hidden to you,
888 it is embedded into the created connection and does not appear
889 as an existing black box).
890 When the pipeline is processed the
891 adaptor converts the output data into the required input type,
892 in a totally transparent way.
893 In our example, the \texttt{Cast<char,double>} adaptor
894 would simply cast the value of the \texttt{char} into a \texttt{double},
895 however arbitrarily complex type conversion can be done.
898 if two adaptors with the same input and output types exist
899 in the packages loaded,
900 which one is chosen by \bbi at connection ?
901 -> Role of default adaptors
903 Note that the \texttt{set} and \texttt{print} commands of \bbi
904 work with adaptors from \texttt{string} to the type of the input to set
905 or from the type of the output to print to \texttt{string}.
906 Hence in order to \texttt{set} or \texttt{print} values the adequate
907 adaptors must be available in the packages currently loaded.
909 % ==========================================
914 \item The \texttt{connect} command allows to connect two black boxes
915 \item You can connect two black boxes if (and only if):
917 \item The output and the input are of the same type, or
918 \item There is an adaptor black box in the packages loaded which
919 converts data of the output type into data of the input type
921 \item \texttt{help <package name>} does not display the adaptors of the package. To see them use: \texttt{help <package name> all}.
925 % ==========================================
927 % ==========================================
928 \subsubsection{Creating complex black boxes}
929 \label{bbi-complex-black-boxes}
930 % ==========================================
932 Remember the pipeline of figure
933 \ref{bbi-fig-connecting-black-boxes-1}, which
934 computed the sum of three doubles ?
935 You can view it as a whole and define
936 a new black box type, which will be a \emph{complex black box},
937 having three inputs and one output,
938 as shown in figure \ref{bbi-fig-complex-black-box-1}.
941 \caption{\label{bbi-fig-complex-black-box-1}
942 Creating the complex black box \texttt{Add3}}
944 \includegraphics[width=0.5\textwidth]{Add3.png}
948 The \bbi commands to define this complex black box are
958 > connect a.Out b.In1
961 > description "adds 3 doubles"
962 > input x a.In1 "first double to add"
963 > input y a.In2 "second double to add"
964 > input z b.In2 "third double to add"
965 > output result b.Out "output"
972 As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
974 The command \texttt{define} then starts the definition
975 of the complex box type, which will be called \texttt{Add3}.
977 The next three lines define the pipeline,
978 exactly in the same way than outside a complex box definition.
980 The commands \texttt{author}, \texttt{description}, \texttt{input}
981 and \texttt{output} are commands specific to complex boxes definition:
983 \texttt{author} and \texttt{description} are used for the documentation
984 of the new box. You can provide multiple \texttt{author} or
985 \texttt{description} commands, the arguments of the commands will
986 be concatenated to produce the final author and description strings.
988 \texttt{input} and \texttt{output} are used to define the inputs and outputs
989 of the new complex box.
990 Their syntax is the same: for each new input/output you need to say
991 to which internal input/output it corresponds and to provide
992 a help string documenting the input/output.
993 In our example, we define that the box \texttt{Add3} has
994 three inputs: \texttt{x}, \texttt{y} and \texttt{z}.
995 The input \texttt{x} corresponds to the input \texttt{In1} of the
996 internal box \texttt{a}.
997 In the same way, the external input \texttt{y}
998 corresponds to the internal input \texttt{a.In2}, and
999 the external input \texttt{In3} to \texttt{b.In2}.
1000 The only output of the new box is called \texttt{result}
1001 and corresponds to \texttt{b.Out}.
1002 The figure \ref{bbi-fig-complex-black-box-1}
1003 illustrates the external to internal
1004 input/output correspondence.
1006 Finally, the \texttt{endefine} command ends the definition of the
1009 After this definition, if you ask for help
1010 on packages, you get:
1021 The \texttt{user} package now contains a new black box type, called
1022 \texttt{Add3}. If you ask for help on this type of box, you get:
1025 Complex Black Box <user::Add3>
1029 'x' <double>: first double to add
1030 'y' <double>: second double to add
1031 'z' <double>: third double to add
1033 'result' <double>: output
1039 and you can use it like any other box, for example type:
1051 As a side note, we can say that, for consistency reasons, it would have been better to name
1052 \texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3},
1053 since all the 'natural entry' of a box is named \texttt{In}, or\texttt{In}x if there are more than one 'natural
1056 % ==========================================
1061 \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.
1062 Inside a \texttt{define/endefine} block:
1064 \item The \texttt{author} and \texttt{description} commands allow to document the new type of box
1065 \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
1066 of internal boxes they correspond.
1070 % ==========================================
1072 % ==========================================
1073 \subsubsection{Writing scripts}
1074 \label{bbi-writing-scripts}
1075 % ==========================================
1077 Once you have defined a new type of complex box, you
1078 may like to reuse it. To do this, you can simply
1079 write the \bbi commands defining the new box
1080 into a text file and afterwards include that file in \bbi.
1081 Doing this, you start writing \bbi scripts.
1082 The conventionnal extension for such scripts is \texttt{bbs}
1084 For consistency reasons, you are requested to prepend \texttt{bb} to the name.
1086 For example, the \texttt{Add3} complex box we previously worked on
1087 can be defined in the \texttt{bbAdd3.bbs} file:
1089 \begin{file}{bbAdd3.bbs}
1091 # Defines the Add3 black box which adds 3 doubles
1097 description "adds 3 doubles"
1103 input x a.In1 "first double to add
1104 input y a.In2 "second double to add
1105 input z b.In2 "third double to add"
1107 output result b.Out "output"
1112 Lines starting with a \texttt{\#} character are ignored, they
1113 are considered as comments by \bbi.
1114 To use this file in \bbi, use the \texttt{include} command:
1117 > include bbAdd3.bbs
1119 Complex Black Box <user::Add3>
1123 'x' <double>: first double to add
1124 'y' <double>: second double to add
1125 'z' <double>: third double to add
1127 'result' <double>: output
1135 If the file has the \texttt{bbs} extension, you can ommit it and just type:
1140 Of course, you can include script files in other script files,
1141 like in the following example:
1143 \begin{file}{bbAdd4.bbs}
1145 # Defines the Add4 black box which adds 4 doubles
1150 description "adds 4 doubles"
1154 input In1 a.In1 "first double to add
1155 input In2 a.In2 "second double to add
1156 input In3 a.In3 "third double to add"
1157 input In4 b.In2 "fourth double to add"
1158 output Out b.Out "output"
1163 % ==========================================
1165 \paragraph{Naming Conventions}
1169 % ==========================================
1173 For consistency reasons, you are requested to prepend \texttt{bb}, and postpone an extention \texttt{.bbs},
1174 to the names of the files that hold a \texttt{complex black box} definition.
1176 For example, the \texttt{Add3} complex box we previously worked on
1177 can be defined in the \texttt{bbAdd3.bbs} file.
1181 % ==========================================
1187 \item The \texttt{include} command allows to include a script file in \bbi.
1188 \item Lines starting with a \texttt{\#} or with a \texttt{\//} are treated as comments in \bbi scripts.
1189 \item Lines between a line starting with a \texttt{\//*} an a line starting with a \texttt{*\//} are treated as comments in \bbi scripts.
1193 % ==========================================
1195 % ==========================================
1196 \subsubsection{Creating command line applications}
1197 \label{bbi-command-line-app}
1198 % ==========================================
1200 Now that you now how to create complex black boxes
1201 (with \texttt{define/endefine}), think
1202 back to the \texttt{workspace} object.
1203 Remember that it is also
1204 a \texttt{complex black box}.
1205 In fact what you are doing when you type \bbi commands
1206 outside a \texttt{define/endefine} block
1207 is to progressively define the \texttt{workspace}
1209 You can think of it like if at start
1210 \bbi was issuing a command \texttt{'define workspace'}
1211 and then letting you define the interior of the box
1214 Remember that the command \texttt{inputs}
1215 allows to define an input of a complex box.
1216 Now, if you use the command \texttt{input}
1217 outside a \texttt{define/endefine} block then
1218 it defines an input of the \texttt{workspace} box,
1219 that is an input of the \emph{main program}.
1220 This input will then be connected to the
1221 parameters that the user passes to the command line.
1223 For example, consider the script:
1225 \begin{file}{add.bbs}
1229 input x a.In1 "first number to add"
1230 input y a.In2 "second number to add"
1235 The third and fourth lines define two inputs \texttt{x}
1236 and \texttt{y}. When you execute this script,
1237 you can pass these two arguments on the command line,
1245 You can also invoke \bbi the option \texttt{-h},
1246 which gives help on the \texttt{workspace} box:
1253 'x' <double>: first number to add
1254 'y' <double>: second number to add
1257 To get a better help, use the \texttt{description}
1258 and \texttt{author} commands:
1260 \begin{file}{add.bbs}
1262 description "Adds two numbers"
1263 author "foo@bar.com"
1266 input x a.In1 "first number to add"
1267 input y a.In2 "second number to add"
1272 Now if you ask for help on the \texttt{add} script, you get:
1279 'x' <double>: first number to add
1280 'y' <double>: second number to add
1283 Rather than getting the inputs of a script
1284 from the command line, you can ask \bbi to
1285 prompt the user for the values, using the \texttt{-t}
1290 x=[the program waits for user answer]2
1291 y=[the program waits for user answer]5
1295 If \bbi is compiled in graphical mode (with \wx),
1296 you can also use the \texttt{-g} commutator.
1297 \bbi then prompts the user in graphical mode,
1298 displaying a dialog box for each input,
1299 like in fig. \ref{bb-input-dialog-box}.
1302 \caption{\label{bb-input-dialog-box}Input dialog box}
1304 \includegraphics[width=0.6\textwidth]{enter-the-value-of-x.png}
1308 % ==========================================
1313 \item The \texttt{input}, \texttt{description} and \texttt{author} commands,
1314 when they are used outside a \texttt{define/endefine} block allow
1315 to define the inputs, description and author of the main program.
1316 \item Inputs of the main program can be passed on the command line
1317 using the syntax \texttt{<input-name>=<value>}.
1318 No white space is allowed, if the value or the input name
1319 contains white spaces, enclose them
1320 between double quotes, e.g. \texttt{"parameter with white spaces = gnu's not unix"}.
1321 \item The \texttt{-h} option of \bbi prints help on the main program.
1322 \item The \texttt{-t} option of \bbi orders the program to prompt for its inputs in text mode.
1323 \item The \texttt{-g} option of \bbi orders the program to prompt for its inputs in graphical mode.
1326 % ==========================================
1328 % ==========================================
1329 \subsubsection{Using graphical interface boxes (widget boxes)}
1331 % ==========================================
1333 % ==========================================
1334 \subsubsection{Overwiew}
1335 \label{bbi-overview}
1336 % ==========================================
1338 If \bbi is compiled in graphical mode
1339 (option \texttt{BUILD\_bbi\_GRAPHICAL} of \cmake, requires \wx),
1340 then you can use special black boxes which are
1341 graphical interface components (widgets).
1342 Basic components are provided in the package \texttt{wx},
1343 such as buttons, sliders, file open/save dialogs, etc.
1345 As first example, type the following commands in \bbi:
1352 When you type \texttt{enter} after the last line,
1353 a window pops up in which you can entrer a text.
1354 When you close the window, the text you entered is printed by
1355 the \texttt{print} command.
1357 Type \texttt{help wx}, you get something like:
1359 Package wx v1.0.0- info-dev@creatis.insa-lyon.fr
1360 Basic graphical interface elements (sliders, buttons ...) based on wxWidgets
1362 ColourSelector : Colour Selector dialog (bbfication of wxColourSele...
1363 ColourSelectorButton : A button which displays a colour picker dialog whe...
1364 CommandButton : Button which executes bbi commands
1365 DirectorySelector : Pops up a directory selection dialog (wxDirDialog)
1366 FileSelector : Pops up a file selection dialog for reading or sav...
1367 InputText : A zone in which the user can enter a text (wxTextC...
1368 LayoutLine : LayoutLine widget (wxBoxSizer)
1369 LayoutSplit : Widget which splits a window in two fixed size par...
1370 LayoutTab : LayoutTab widget (wxNotebook)
1371 OutputText : Text zone to be inserted into a window (wxStaticTe...
1372 RadioButton : RadioButton group widget 0-9 entries
1373 Slider : Slider widget (wxSlider)
1376 You can reproduce the same experiment as above using a
1377 \texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}.
1378 See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
1380 There are two kinds of widgets: ``terminal'' widgets and ``container'' widgets.
1381 The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets
1382 are ``terminal'' widgets.
1383 ``container'' widgets are of another kind: they are designed to
1384 contain other widgets in order to build larger dialog boxes.
1385 For example, the \texttt{LayoutSplit} widget is a container which
1386 ``splits'' horizontally a window into two parts,
1387 each part including another widget.
1388 The size of the two parts can be adjusted by the user thanks
1391 The script \texttt{scripts/test/testSplit.bbs} demonstrate its use.
1392 Run it: it displays a window with two sliders.
1393 Move the sliders and close the window.
1394 The final positions of the sliders are printed out.
1395 Now edit the file to see how this is done:
1397 \begin{file}{scripts/test/testSplit.bbs}
1406 connect s1.Widget s.Widget1
1407 connect s2.Widget s.Widget2
1409 print s1=$s1.Out$\\n
1410 print s2=$s2.Out$\\n
1414 First, the two sliders \texttt{s1} and \texttt{s2} are created.
1415 A \texttt{LayoutSplit} box \texttt{s} is also created.
1416 The \texttt{connect} commands then ``includes'' the sliders in the
1417 split ``container''.
1418 The input \texttt{Widget} is common to all widget boxes:
1419 every widget can be inserted into another widget.
1420 The outputs \texttt{Widget1},\texttt{Widget2} are specific of \emph{container}
1422 (in \bbi type \texttt{help Slider}:
1423 you will see the output \texttt{Widget};
1424 type \texttt{help LayoutSplit}:
1425 you will see the inputs \texttt{Widget1} and \texttt{Widget2}
1426 and the output \texttt{Widget}).
1427 When you connect the \texttt{Widget} output of a container
1428 to the \texttt{Widget}i input of a widget,
1429 you order to include the widget in the container.
1430 Of course, the order of connection is important.
1431 In our case, the slider \texttt{s1} is included first,
1432 then the slider \texttt{s2}: \texttt{s1} will be placed
1433 on top of \texttt{s2} (the \texttt{LayoutSplit} box is
1434 implemented that way, but this is arbitrary choice).
1436 Right now, there are only \emph{three} container widgets in the \texttt{wx} package:
1437 the \texttt{LayoutSplit} widget we just described, the \texttt{LayoutLine} , and the \texttt{LayoutTab}
1440 The \texttt{LayoutLine} widget can have multiple children and
1441 divides its window into as much parts as children,
1442 each part of equal size.
1443 The orientation of the \texttt{LayoutSplit} or of the \texttt{LayoutLine} can be changed by the input \texttt{Orientation}.
1444 See the example \texttt{test/testSizer.bbs}.
1445 With only those two containers you can already create
1446 complex dialog boxes (of course containers can be nested, which
1447 leads to tree-like structures of widgets).
1448 See the script \texttt{bbtk/share/bbtk/bbs/wx/appli/ExampleLayoutSplit.bbs} for an example.
1450 The \texttt{LayoutTab} widget is based on the \texttt{wxNotebook.}
1452 One word about a special widget in the package \texttt{wx}:
1453 the \texttt{Button}... to be continued.
1455 % ==========================================
1456 \subsubsection{Deeper in the boxes}
1457 \label{bbi-deep-box}
1458 % ==========================================
1460 Any widget box has two mandatory Outputs :
1463 \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
1464 will popup. If it's connected to the \texttt{Widget}\texttt{\emph{i}} of any \texttt{Layout box}, it will be embedded in its parent window.
1465 \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,
1466 further within the execution pipeline.
1469 Any widget box has two mandatory Inputs :
1471 \item {\bf\emph{BoxExecute}} : Any signal received by this input executes the box
1472 \item {\bf\emph{BoxProcessMode}} : Sets the processing mode of the box :
1474 \item {\bf\emph{Pipeline}} : bbUpdate() calls Process only if Status == MODIFIED (normal pipeline processing)
1475 \item {\bf\emph{Always}} : bbUpdate() always calls Process
1476 \item {\bf\emph{Reactive}} : bbSetModifiedStatus() calls bbUpdate()
1480 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} :
1482 \item {\bf\emph{WinHeight}} : Height of the window
1483 \item {\bf\emph{WinWidth}} : Width of the window
1484 \item {\bf\emph{WinTitle}} : Title of the window
1485 \item {\bf\emph{WinClose}} : Any received signal closes the window
1486 \item {\bf\emph{WinHide}} : Any received signal hides the window
1487 \item {\bf\emph{WinDialog}} : When set to 'true', creates a \emph{dialog window}, that blocks the pipeline until it is closed (\emph{modal})
1491 Any \emph{Layout box} (i.e. \emph{LayoutLine}, \emph{LayoutSplit} or \emph{LayoutTab}) has at one or more mandatory Inputs :
1493 \item {\bf\emph{Widget}}\texttt{i} : e.g. a \emph{LayoutSplit} box (Widget which splits a window in two fixed size parts)
1494 has two Input parameters \emph{Widget1} and \emph{Widget2}, used to embed the child windows.
1498 % ==========================================
1499 \subsection{More on ...}
1501 % ==========================================
1503 % ==========================================
1504 \subsubsection{Black box packages}
1505 \label{bbi-more-on-packages}
1506 % ==========================================
1508 There are various others user-intended packages :
1511 It contains some vtk based image processing filters :
1514 \paragraph{AppendPolyData}
1515 Appends one of more polygonal datasets into a single polygonal dataset
1517 \paragraph{ConeSource}
1520 \paragraph{ImageAnisotropicDiffusion3D}
1521 vtkImageAnisotropicDiffusion3D diffuses an volume iteratively. \\
1522 The neighborhood of the diffusion is determined by the instance flags. \\
1523 if 'Faces' is on, the 6 voxels adjoined by faces are included in the neighborhood. \\
1524 If 'Edges' is on the 12 edge connected voxels are included, and if 'Corners' is on, the 8 corner connected voxels are included. \\
1525 'DiffusionFactor' determines how far a pixel value moves toward its neighbors, and is insensitive to the number of neighbors chosen.\\
1526 The diffusion is anisotropic because it only occurs when a gradient measure is below 'GradientThreshold'. \\
1527 Two gradient measures exist and are toggled by the 'GradientMagnitudeThreshold' flag. \\
1528 When 'GradientMagnitudeThreshold' is on, the magnitude of the gradient, computed by central differences, above 'DiffusionThreshold' a voxel is not
1530 The alternative measure examines each neighbor independently.\\
1531 The gradient between the voxel and the neighbor must be below the 'DiffusionThreshold' for diffusion to occur with THAT neighbor.\\
1533 - In : an image (vtkImageData*)\\
1534 - Diffusion : Difference threshold that stops the diffusion\\
1536 - Out : the isosurface mesh (vtkPolyData*)
1538 \paragraph{ImageCharacteristics}
1539 Exports objet sizes, and Spacings
1541 \paragraph{ImageDilateErode3D}
1542 Dilates one value and erodes another.\\
1543 vtkImageDilateErode3D will dilate one value and erode another. \\
1544 It uses an elliptical foot print, and only erodes/dilates on the boundary of the two values. \\
1545 The filter is restricted to the X, Y, and Z axes for now.\\
1546 It can degenerate to a 2 or 1 dimensional filter by setting the kernel size to 1 for a specific axis. \\
1547 (bbfication of vtkImageDilateErode3D) \\
1549 - In : an image (vtkImageData*)\\
1550 - DilateValue : The dilatation value\\
1551 - ErodeValue : The erosion value\\
1553 - Out : the isosurface mesh (vtkPolyData*)
1555 \paragraph{ImageGaussianSmooth}\\
1556 Performs a gaussian convolution of the input image\\
1558 - In : an image (vtkImageData*)\\
1559 - StdDevX : Standard deviation in X direction\\
1560 - StdDevY : Standard deviation in Y direction\\
1562 - Out : the isosurface mesh (vtkPolyData*)
1564 \paragraph{ImagePlanes}
1565 Creates three 3D planes with the input image mapped onto with which the user can interact; \\
1566 The output vtkImagePlaneWidget objects are to be inserted into a 3D scene (e.g. a Viewer3D)
1568 - In : an image (vtkImageData*)\\
1570 - PlaneX : the image plane in X direction (vtkImagePlaneWidget*)\\
1571 - PlaneY : the image plane in Y direction (vtkImagePlaneWidget*)\\
1572 - PlaneY : the image plane in Z direction (vtkImagePlaneWidget*)\\
1575 - Out : the isosurface mesh (vtkPolyData*)
1577 \paragraph{IsoSurfaceExtractor}
1578 Extracts an iso-surface of a 3D image and creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D)
1580 - In : an image (vtkImageData*)\\
1581 - Isovalue : the isosurface value (double)\\
1582 - Colour : Surface colour (vector of 3 doubles)
1584 - Out : the isosurface (vtkProp3D**)
1586 \paragraph{MarchingCubes}
1587 Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes)\\
1589 - In : an image (vtkImageData*)\\
1590 - Value : the isosurface value (double)\\
1592 - Out : the isosurface mesh (vtkPolyData*)
1594 \paragraph{MIPCreator}
1595 Creates a Maximum Intensity Projection (MIP) view of a 3D image.\\
1597 - In : an image (vtkImageData*)\\
1598 - Scale : the Gray scale scaling (float) \\
1599 - Shift : the Gray scale shift (float) \\
1601 - Out : The MIP object (vtkProp3D*) to be plugged into a 3D Viever
1603 \paragraph{MetaImageReader}
1604 Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader) \\
1606 - In : the name of the file to be read (std::string)
1608 - Out : The image (vtkImageData*)
1610 \paragraph{SegmentationConnectivity} \\
1611 Segmentation with min max threshold and connectivity \\
1613 - In : an image (vtkImageData*)\\
1614 - PositionXYZ : initial position (std::vector<int>) \\
1615 - ThresholdMinMax : min, max threshold values (std::vector<int>) \\
1617 - Out : The image (vtkImageData*)
1619 \paragraph{SphereSource}
1624 It contains some itk based image processing filters :
1626 \paragraph{BinaryThresholdImageFilter}
1627 Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter)
1629 \paragraph{DICOMSeriesFileNames}
1630 Reads a series from a DICOM directory as a 3D itk image
1632 \paragraph{ExtractImageFilter}
1633 Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)
1635 \paragraph{ImageProperties}
1636 Outputs different properties of an image (type, dimension, size, spacing, ...)
1638 \paragraph{ImageRegion}
1639 Creates a generic ImageRegion (bbtk::any) from two vectors providing the index and size of the region.
1640 The dimension D of the actual itk::ImageRegion created is the max of the sizes of Index and Size
1641 (the smallest vector is padded by zeros)
1643 \paragraph{ImageReader}
1644 Generic itk image reader
1646 \paragraph{ImageWriter}
1647 Generic itk image writer
1649 \paragraph{ImageSeriesReader}
1650 Generic itk image series reader.
1652 \paragraph{ResampleImageFilter}
1656 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
1658 Sorry nothing is done, right now for meshes.
1662 It contains two atomic black boxes.
1664 \paragraph{Viewer2D}
1666 - a \textless vtkImageData* \textgreater (In),\\
1667 - an Orientation(0:yz / 1:xz / 2:xy),\\
1668 - an initial slice number (Slice).\\
1670 - a \textless vtkRenderer* \textgreater (Renderer)
1672 \paragraph{Viewer3D}
1674 - up to 5 Input Actors (\textless vtkProp3D* \textgreater),\\
1675 - up to 5 Input Observers (\textless vtkInteractorObserver* \textgreater), \\
1676 - a boolean 'Stereo' option, to use Red-Blue filter
1678 - an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact, \\
1679 - a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
1681 It contains too some sophisticated complex black boxes :
1683 \paragraph{IsoSurfaceWithControls}
1684 Image iso-surface extractor (vtk::IsoSurfaceExtractor) with associated control panel (isovalue, opacity and colour)\\
1686 - an initial isovalue (Isovalue)
1687 - an initial opacity (Opacity)
1688 - an initial colour (Colour)
1690 \textless vtkProp3D* \textgreater (In)\\
1692 \paragraph{MIPWithControls}
1693 Maximum Intensity Projection (MIP) creator (vtk::MIPCreator) with associated control panel (shift and scale) \\
1695 - an initial scale (Scale)
1696 - an initial shift (Shift)
1698 \textless vtkProp3D* \textgreater (In)\\
1702 Some boxes are the bbfication of usefull xwWidgets, some other ones are more
1705 \paragraph{ColourSelector} Colour Selector dialog (bbfication of wxColourSelector) \\
1707 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
1710 \paragraph{ColourSelectorButton} A button which displays a colour picker dialog when clicked \\
1712 \texttt{In} :Initial colour \\
1713 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
1716 \paragraph{CommandButton} Button which executes bbi commands \\
1718 \texttt{In} : Commands to be executed separated by commas (;). Each single quote (') is replaced by a double quote ("). \\
1719 \texttt{Label} : Label of the button \\
1720 \texttt{Widget} : Output widget \\
1723 \paragraph{DirectorySelector} Pops up a directory selection dialog (wxDirDialog)\\
1725 \texttt{DefaultDir} : The default directory\\
1726 \texttt{Message} : Message to show on the dialog \\
1727 \texttt{Title} : Title of the dialog \\
1728 \texttt{Out} : The directory selected by the user\\
1731 \paragraph{FileSelector} Pops up a file selection dialog for reading or saving (wxFileDialog)\\
1733 \texttt{DefaultDir} : The default directory \\
1734 \texttt{DefaultFile} : The default filename \\
1735 \texttt{Message} : Message to show on the dialog \\
1736 \texttt{OpenSave} : Open for an open dialog (default) / Save for a save dialog\\
1737 \texttt{Title} : Title of the dialog \\
1738 \texttt{Wildcard} : A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" \\
1739 \texttt{Out} : The file selected by the user \\
1742 \paragraph{InputText} A zone in which the user can enter a text (wxTextCtrl)\\
1744 \texttt{In} : Initial text (default '')\\
1745 \texttt{Title} : Title of the input zone (default '')\\
1746 \texttt{WinTitle} : Title of the window (*)\\
1747 \texttt{Out} :Current text\\
1750 \paragraph{LayoutLine} LayoutLine widget (wxBoxSizer)\\
1752 \texttt{Orientation} Orientation (default V), 0=H=HORIZONTAL , 1=V=VERTICAL \\
1753 \texttt{Widget}1 widget 1 \\
1754 \texttt{Widget2} widget 2 \\
1755 \texttt{Widget3} widget 3 \\
1756 \texttt{Widget4} widget 4 \\
1757 \texttt{Widget5} widget 5 \\
1758 \texttt{Widget6} widget 6 \\
1759 \texttt{Widget7} widget 7 \\
1760 \texttt{Widget8} widget 8 \\
1761 \texttt{Widget9} widget 9\\
1764 \paragraph{LayoutSplit} Widget which splits a window in two fixed size parts (wxSplitterWindow)\\
1766 \texttt{Orientation} : Orientation (default H), 0=H=HORIZONTAL , 1=V=VERTICAL\\
1767 \texttt{Proportion} : Proportion (in percent) of the first children in the window\\
1768 \texttt{Widget1} : Upper or left widget\\
1769 \texttt{Widget2} : Lower or right widget\\
1772 \paragraph{LayoutTDown} Creates a 'T like' complex container : Down {UpLeft, UpRight} \\
1774 \texttt{Widget1} : UpLeft container\\
1775 \texttt{Widget2} : UpRight container\\
1776 \texttt{Widget3} : Down container\\
1787 \paragraph{LayoutTLeft} Creates a 'T like' complex container : Left {RigthUp, RightDown}\\
1789 \texttt{input} Widget1 : "UpLeft container"\\
1790 \texttt{input} Widget2 : "UpRight container"\\
1791 \texttt{input} Wigdet3 : "Down container"\\
1802 \paragraph{LayoutTRight} Creates a 'T like' complex container : Right {LeftUp, LeftDown}\\
1804 \texttt{input} Widget1 currentBox.Widget1 "Up container"\\
1805 \texttt{input} Widget2 down.Widget1 "DownLeft container"\\
1806 \texttt{input} Widget3 down.Widget2 "DownRight container"\\
1817 \paragraph{LayoutTUp} Creates a 'T like' complex container : Up {DownLeft, DownRight} as w1{w2,w3}\\
1819 \texttt{ input} Widget1 currentBox.Widget1 "Up"\\
1820 \texttt{input} Widget2 down.Widget1 "DownLeft"\\
1821 \texttt{input} Widget3 down.Widget2 "DownRight"\\
1832 \paragraph{LayoutTab} LayoutTab widget (wxNotebook)\\
1834 \texttt{Orientation} Orientation (default T), 0=T=TOP , 1=R=RIGHT , 2=B=BOTTON , 3=L=LEFT \\
1835 \texttt{Widget1} widget 1 \\
1836 \texttt{Widget2} widget 2 \\
1837 \texttt{Widget3} widget 3 \\
1838 \texttt{Widget4} widget 4 \\
1839 \texttt{Widget5} widget 5 \\
1840 \texttt{Widget6} widget 6 \\
1841 \texttt{Widget7} widget 7 \\
1842 \texttt{Widget8} widget 8 \\
1843 \texttt{Widget9} widget 9 \\
1846 \paragraph{OutputText} Text zone to be inserted into a window (wxStaticText)\\
1849 \texttt{Title} Title prepended to the text\\
1852 \paragraph{RadioButton} RadioButton group widget 0-9 entries\\
1854 \texttt{In} Set initial item \\
1855 \texttt{In0} option 0\\
1856 \texttt{In1} option 1\\
1857 \texttt{In2} option 2\\
1858 \texttt{In3} option 3\\
1859 \texttt{In4} option 4\\
1860 \texttt{In5} option 5 \\
1861 \texttt{In6} option 6 \\
1862 \texttt{In7} option 7 \\
1863 \texttt{In8} option 8 \\
1864 \texttt{In9} option 9 \\
1865 \texttt{Title} Title of the widget (default '')\\
1866 \texttt{Out} Number of the selected Item
1869 \paragraph{Slider} Slider widget (wxSlider)\\
1871 \texttt{ChangeResolution} Enables the user to change the slider resolution (default FALSE) \\
1872 \texttt{In} Initial slider position(default 0) \\
1873 \texttt{Label} Show slider labels ? (default FALSE) \\
1874 \texttt{Max} Maximum value of the slider (default 500)\\
1875 \texttt{Min} Minimum value of the slider (default 0)\\
1876 \texttt{Orientation} Orientation : (default H) 0=H=HORIZONTAL, 1=V=VERTICAL\\
1877 \texttt{ReactiveOnTrack} Slider sends info when track moves (default 0 = no)\\
1878 \texttt{Title} Title shown above the slider (default '')\\
1881 % ==========================================
1882 \subsubsection{Pipeline processing}
1883 \label{bbi-more-on-pipeline-processing}
1884 % ==========================================
1886 \item the ``control'' mechanism in bbi (switch exec commands, e.g. Button)
1887 \item the role of ProcessMode to update widgets.
1889 % ==========================================
1890 \subsubsection{Complex black boxes}
1891 \label{bbi-more-on-complex-black-boxes}
1892 Creation of complex widgets (containers, contained...)
1894 %\subsubsection{Advanced issues}
1895 %\paragraph{Reducing the number of inputs of a box}
1897 % ==========================================
1898 \subsubsection{Errors}
1899 \label{bbi-more-on-errors}
1901 % ==========================================
1902 \subsubsection{\bbtk configuration file and search pathes}
1903 \label{bbi-more-on-configuration}
1905 At start, \bbi tries to open an \texttt{xml}
1906 configuration file named \texttt{bbtk\_config.xml}.
1909 \item The current directory
1910 \item The subdir \texttt{.bbtk} of the user's home directory.
1912 \item On \texttt{Unix}, the home directory is the
1913 one stored by the environnement variable \texttt{HOME},
1914 typically \texttt{/home/username}.
1915 \item On \texttt{Windows}, the home directory is
1916 the user's profile directory stored by the environnement
1917 variable \texttt{USERPROFILE},
1918 typically \texttt{C:\\...}.
1920 \item If none of these two pathes contains the file then it creates
1921 a new one in the \texttt{.bbtk} directory.
1924 Once created, you can edit the \texttt{bbtk\_config.xml} file located
1925 in your \texttt{.bbtk} directory. It contains:
1927 \begin{file}{bbtk\_config.xml}
1929 <?xml version="1.0" encoding="iso-8859-1"?>
1931 <bbtk_url> http://www.creatis.insa-lyon.fr/software/bbtk </bbtk_url>
1932 <bbs_path> </bbs_path>
1933 <package_path> </package_path>
1934 <data_path> </data_path>
1939 You can add pathes to
1941 \item A custom folder in which to search for \texttt{.bbs} scripts (\texttt{include} command of \bbi) by adding an \texttt{xml} tag:
1942 \texttt{<bbs\_path>complete\_path\_to\_folder<\/bbs\_path>}.
1943 \item A custom folder in which to search for packages (\texttt{load} command of \bbi) by adding an \texttt{xml} tag:
1944 \texttt{<package\_path>complete\_path\_to\_folder<\/package\_path>}.
1947 % ==========================================
1948 \subsection{Language reference}
1949 \label{bbi-reference}
1950 % ==========================================
1956 % ==========================================
1958 \caption{\label{bbi-reference-box}
1959 \bbi pipeline creation and execution related commands.}
1961 \begin{tabular}{|lcm{6cm}|}
1963 Command & Parameters & Effect \\ \hline
1965 \texttt{new} & \texttt{<boxtype>} \texttt{<box-name>}&
1966 Creates a box of type \texttt{boxtype} and name
1970 \texttt{delete} & \texttt{<box-name>} &
1971 Destroys the box named \texttt{box-name}.
1974 \texttt{connect} & \texttt{<box1.output>} \texttt{<box2.input>} &
1976 \texttt{output} of the box named \texttt{box1}
1977 to the input \texttt{input} of the box named \texttt{box2} \\ \hline
1979 \texttt{set} & \texttt{<box.input>} \texttt{<value>} &
1980 Sets the input \texttt{input} of
1981 the box named \texttt{box} to the value \texttt{value}.
1982 There must exist an \texttt{adaptor}
1983 in the packages loaded which converts a \texttt{std::string}
1984 to the type of the input \texttt{input}.
1987 \texttt{print} & \texttt{<string>} &
1988 Prints the string after substituting each token of the form \texttt{\$box.output\$} by the adaptation to string of the value of the
1989 output \texttt{output} of the box named \texttt{box}.
1990 There must exist an \texttt{adaptor}
1991 in the packages loaded which converts
1992 the type of the output \texttt{output}
1993 to a \texttt{std::string}.
1996 \texttt{exec} & \texttt{<box-name>} &
1997 Executes the box named \texttt{box-name}.
1999 connected to its inputs
2000 are also processed recursively (pipeline processing).\\ \hline
2001 \texttt{exec} & \texttt{freeze} &
2002 allows to block execution commands while keeping definition commands active.\\ \hline
2003 \texttt{exec} & \texttt{unfreeze} &
2004 turns back to 'normal' mode.\\ \hline
2007 % ==========================================
2011 % ==========================================
2013 \caption{\label{bbi-reference-interpreter}\bbi intepreter related commands.}
2015 \begin{tabular}{|lcm{6cm}|}
2017 Command & Parameters & Effect \\ \hline
2021 Prints help on available commands \\ \hline
2023 & \texttt{<command-name>} &
2024 Prints help on the command \texttt{command-name} \\ \hline
2026 & \texttt{packages} &
2027 Prints help on available packages and their box types
2028 (without description)\\ \hline
2030 & \texttt{<package-name>} &
2031 Prints help on the package \texttt{package-name} and its boxes
2032 (with brief description).
2033 The package must have been previously loaded
2036 & \texttt{<box-type>} &
2037 Prints help (with full description) on the type of box
2039 The box type must belong to a package which has been previously loaded
2042 \texttt{include} & \texttt{<file-name>} &
2043 Includes and executes the content of the file named \texttt{file-name}
2044 exactly like if you were typing its content at the place were the
2045 \texttt{include} command is.
2048 \texttt{load} & \texttt{<package-name>} &
2049 Loads the package \texttt{package-name}\\ \hline
2051 \texttt{include} & \texttt{<package-name>} &
2052 Loads the package \texttt{package-name} and includes all the complex black boxes that comes with it \\ \hline
2054 \texttt{kind} & \texttt{<box kind>} &
2055 Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline
2060 \texttt{unload} & \texttt{<package-name>}&
2061 Unloads the package \texttt{package-name}.
2062 The package must have been previously loaded.
2063 No box of a type defined in this package must still exist.
2066 \texttt{message} & \texttt{<category>} \texttt{<level>} &
2067 Sets the level of verbosity of \bbi for the category of messages
2068 \texttt{category} to \texttt{level}.
2069 %See \ref{verbosity}.
2072 \texttt{config} & - & Displays the Configuration parameters\\ \hline
2074 \texttt{reset} & - & Deletes all boxes and unloads all packages so
2075 that \bbi gets back to its initial state \\ \hline
2077 \texttt{quit} & - & Exits the interpreter\\ \hline
2081 % ==========================================
2087 % ==========================================
2089 \caption{\label{bbi-reference-complex-box}
2090 \bbi complex black box definition related commands.}
2092 \begin{tabular}{|lcm{6cm}|}
2094 Command & Parameters & Effect \\ \hline
2097 \texttt{define} & \texttt{<box-type>} &
2098 Starts the definition of a complex black box of type
2099 \texttt{box-type}\\ \hline
2101 \texttt{endefine} & - &
2102 Ends the definition of a complex black box type\\ \hline
2104 \texttt{author} & \texttt{<string>} &
2105 Sets the author(s) of the complex black box currently being defined \\ \hline
2107 \texttt{description} & \texttt{<string>} &
2108 Sets the description of the complex black box currently being defined
2111 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} &
2112 Defines a new input for the current complex black box,
2113 named \texttt{name}.
2114 It is defined as corresponding to
2115 the input \texttt{input} of the box \texttt{box}.
2117 \texttt{<help>} is the help string for the new input.
2118 The box \texttt{box} must already have been created in the complex box
2119 and of course have an input named \texttt{input}.
2122 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} &
2123 Defines a new output for the current complex black box,
2124 named \texttt{name}.
2125 It is defined as corresponding to
2126 the output \texttt{output} of the box \texttt{box}.
2127 \texttt{<help>} is the help string for the new output.
2128 The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}.
2134 % ==========================================
2139 % ==========================================
2140 \vspace{0.5cm}\hrule
2141 \section{Using black boxes in \CPP programs}
2143 % ==========================================
2152 %\section{Conclusion}