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 \bbStudio
194 or clicking on its icon or its menu entry.
195 At start, \bbStudio opens with the 'Help' tab selected.
196 You'll get something like in figure
197 \ref{bbi-fig-bbStudio-gui}
198 (the exact appearance of \bbStudio is system and \bbtk version dependent)
201 \caption{\label{bbi-fig-bbStudio-gui}The bbStudio Development environment interface}
203 \includegraphics[width=0.7\textwidth]{bbStudioMainPage.png}
207 The 'Help' tab of \bbStudio is used to browse the html help of \BBTK.
208 All the entries of the starting page are self-explanatory :
211 \item {\bf\emph{Wiki}}: Direct link to the bbtk Wiki (intranet only, right now, www
213 \item {\bf\emph{Demo}}: Link to some demonstrations.
214 \item {\bf\emph{User's Guide}}: Step to step How-to for user who just wants to create his own
215 application, just using already existing boxes.
216 \item {\bf\emph{Package Developper's Guide}}: Step to step How-to for user who wants to create his own
218 \item {\bf\emph{Developper's Guide}}: Sorry, not yet written.
219 \item {\bf\emph{Reference Manual}}: Sorry, not yet written.
220 \item {\bf\emph{Doxygen Documentation}}: Doxygen source browser.
221 \item {\bf\emph{Boxes}}: Box retrieving on various criterions :
223 \item {\bf\emph{By name}}
224 \item {\bf\emph{By package}} (see table : \ref{bbi-list_of_packages})
225 \item {\bf\emph{By category}} (see table :\ref{categories})
226 \item {\bf\emph{Adaptors}} Used internaly to perform type conversions (not end user intended)
231 % ==========================================
233 \caption{\label{bbi-list_of_packages} List of bbtk supplied packages.}
235 \begin{tabular}{|lp{10cm}|}
237 Package & What it's used for \\ \hline
238 \texttt{std} & : the 'standard' package including basic useful boxes \\ \hline
239 \texttt{wx} & : basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library \\ \hline
240 \texttt{itk} & : the basic image processing package, based on the \texttt{itk} library. (without description)\\ \hline
241 \texttt{vtk} & : Prints help on the package \texttt{package-name} and its boxes (with brief description). The package must have been previously loaded\\ \hline
242 \texttt{wxvtk} & : widget boxes based on the \texttt{vtk} library.\\ \hline
243 \texttt{itkvtk} & : boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally.\\ \hline
247 % ==========================================
252 % ==========================================
254 \caption{\label{categories} \texttt{Black Box} categories}
256 \begin{tabular}{|lp{10cm}|}
258 \texttt{Category name} & : Meaning \\ \hline \\ \hline
259 \texttt{adaptor} & : Adaptor box \\ \hline
260 \texttt{application} & : Final application, end user intended \\ \hline
261 \texttt{atomic box} & : System category.
262 Automatically assigned to Atomic Black Boxes (c++ defined) \\ \hline
263 \texttt{complex box} & : System category.
264 Automatically assigned to Complex Black Boxes (script defined) \\ \hline
265 \texttt{command line} & : Script which defines a command line application \\
266 & :(no embedded GUI, but command line imput parameters) \\ \hline
267 \texttt{demo} & : Demonstration \\ \hline
268 \texttt{devel} & : Developer tool (bbCreatePackage.bbs, ...) \\ \hline
269 \texttt{dicom} & : DICOM aware box \\ \hline
270 \texttt{example} & : Example script showing a box use-case \\ \hline
271 \texttt{filter} & : Image processing box \\ \hline
272 \texttt{image} & : Image processing related box \\ \hline
273 \texttt{interaction} & : \\ \hline
274 \texttt{math} & : Mathematical operations \\ \hline
275 \texttt{mesh} & : Mesh processing related box \\ \hline
276 \texttt{misc} & : A box that cannot be put in other category ! \\ \hline
277 \texttt{read/write} & : Box that read or write data from or to disk \\ \hline
278 \texttt{viewer} & : Box which displays some data \\ \hline
279 \texttt{widget} & : Piece of graphical interface \\ \hline
281 \texttt{3D object creator} & : Sophisticated 3D widget \\ \hline
282 \texttt{toolsbbtk} & : Component of bbStudio \\ \hline
286 % ==========================================
289 \caption{\label{kinds} \texttt{Black Box} kinds}
291 \begin{tabular}{|ll|}
293 \texttt{Kind name} & : Meaning \\ \hline \\ \hline
294 \texttt{ADAPTOR} & : Adaptor Box \\ \hline
295 \texttt{DEFAULT\_ADAPTOR} & : \\ \hline
296 \texttt{WIDGET\_ADAPTOR} & : \\ \hline
297 \texttt{DEFAULT\_WIDGET\_ADAPTOR} & : \\ \hline
298 \texttt{GUI} & : \\ \hline
299 \texttt{DEFAULT\_GUI} & : \\ \hline
300 \texttt{ALL} & : If kind='ALL' then sets the level for all kinds \\ \hline
306 % ==========================================
307 % ==========================================
308 % ==========================================
309 % ==========================================
310 % ==========================================
311 % ==========================================
313 \section{The script manager}
315 % ==========================================
317 Call it with the bookmark \emph{File}.
321 \caption{\label{bbi-fig-bbStudio-file0}The bbStudio script manager}
323 \includegraphics[width=0.7\textwidth]{bbFile0.png}
327 Using the lower tool bar, you can :
330 \caption{\label{lowertoolbar}The lower tool bar}
332 \includegraphics[width=0.7\textwidth]{lowertoolbar.png}
338 \item {\bf\emph{new}}: Create a newfile to hold a script
339 \item {\bf\emph{open}}: Open a already existing file holding a script
340 \item {\bf\emph{close}}: Close a file holding a script
341 \item {\bf\emph{save}}: Save he current file (if modified)
342 \item {\bf\emph{save as}}: Save he current file under a different name
343 \item {\bf\emph{execute}}: Execute the script you just loaded/modified/written
347 The script language is very simple.
348 Everything is done with only a very few commands (See table \ref{bbi-reference-box}).
349 The philosophy of this part is also very simple:
350 it introduces the \bbi commands using examples,
351 starting with the most simple commands.
352 The first section of this part
353 (\ref{bbi-getting-started})
354 is designed like a tutorial,
355 which progressively introduces all the concepts of \bbi.
356 We suggest you run \bbi and follow the examples,
357 to see how it works in practice.
358 At the end of this section,
359 you will be able to use \bbi and write
360 own black box processing scripts.
363 the section \ref{bbi-more-on}
364 (called \emph{more on...})
365 goes deeper into various issues of \bbi.
366 Read it at your convenience,
367 either linearly to learn more about \bbi,
368 or in random order to get an answer
369 to a particular question.
371 Finally, the section \ref{bbi-reference}
372 summarizes all the commands of \bbi,
373 their parameters and effect.
374 Use it as a reference.
376 % ==========================================
377 \subsection{Getting started}
378 \label{bbi-getting-started}
379 % ==========================================
380 \subsubsection{Creating and executing black boxes}
381 % ==========================================
383 To learn interactivelly the script language features, you can use the black box
385 open a console and type \texttt{bbi}
386 or double click on the application icon.
387 You get a window which looks like the one in figure
388 \ref{bbi-fig-bbi-gui}
389 (the exact appearance of \bbi is system and \bbtk version dependent)
390 \footnote{If you compiled \bbtk without \wx then \bbi does not have a
391 graphical interface but a simple prompt}.
394 \caption{\label{bbi-fig-bbi-gui}The black box interpreter interface}
396 \includegraphics[width=0.7\textwidth]{bbi-gui0.png}
400 The 'Command' tab is subdivided into two parts :
401 one single line zone at the bottom in which you can enter your commands and
402 one multiple line zone in which \bbi prints out the result of your commands.
403 , just using already existing boxes.
405 Try typing in the input zone (in this manual,
406 the commands entered by the user will be preceded by a prompt \textgreater) :
411 you get the list of the commands of the interpreter:
444 To get help on a particular command type \texttt{help <command-name>},
454 Quits the program (during script execution it stops the complete execution)
457 The \texttt{help} command has multiple usages.
458 It is used to get help on almost anything in \bbi !
459 Type \texttt{'help help'} to get help on the \texttt{help} command itself:
464 (2) help <command name>
465 (3) help packages [all]
466 (4) help <package name> [all]
467 (5) help <black box type>
468 (6) help <black box name>
470 (1) Lists all available commands;
471 (2) Prints help on a particular command;
472 (3) Lists the packages loaded and their black boxes.
473 Add 'all' to list adaptors;
474 (4) Prints short help on the black boxes of a package.
475 Add 'all' to include adaptors;
476 (5) Prints full help on a black box type;
477 (6) Prints information on the inputs, outputs and connections of a black box instance.
480 At start \bbi does not know any black box.
481 If you type \texttt{'help packages'}, which is
482 the third form of the \texttt{help} command, you get:
489 which means that \bbi only knows one package
490 (library of black boxes) called \texttt{user}
491 and which contains a black box called \texttt{workspace}.
492 The \texttt{user} package is an internal package to \bbi,
493 which stores user-defined black box types.
494 At start, it already contains
495 one box, called \texttt{workspace}.
496 \texttt{workspace} is a special type of black box,
497 called complex black box, whose purpose is
498 to store other black boxes.
499 Any black box you create in \bbi is stored
500 in \texttt{workspace}
501 (this will be explained in details in sections
502 \ref{bbi-writing-scripts} and
503 \ref{bbi-more-on-complex-black-boxes}).
505 If you type \texttt{'help workspace'}, you get:
508 Complex Black Box <user::workspace>
511 Category(s) : complex box;
517 In the text displayed,
518 the \texttt{user::} prepended to the name \texttt{workspace}
519 means that the box \texttt{workspace}
520 belongs to the \texttt{user} package.
521 Then comes a description and three lines which
522 tell that \texttt{workspace} does not have any input
523 nor output nor boxes yet.
525 In order to let \bbi know of some black boxes,
526 you must load another package.
527 The \texttt{std} package is the ``standard'' package,
528 which contains basic useful black boxes.
540 you get something like:
555 Now \bbi knows the package \texttt{std} and the black boxes it provides,
556 such as the \texttt{'Add'} box, the \texttt{'ConcatStrings'}. Remark that the
557 content of \texttt{std} may vary from one version to another
558 as new black boxes might be added to it.
568 By : laurent.guigues@creatis.insa-lyon.fr
569 Categories : atomic box;math;
571 'BoxExecute' <bbtk::Void> [signal] : Any signal received by this input executes the box
572 'BoxProcessMode' <String> [] : Sets the processing mode of the box (Pipeline | Always | Reactive)
573 'In1' <Double> [] : First number to add
574 'In2' <Double> [] : Second number to add
576 'BoxChange' <bbtk::Void> [signal] : Signals modifications of the box
577 'Out' <Double> [] : Result
581 the \texttt{std::} prepended to the name \texttt{Add}
582 means that the box \texttt{Add}
583 belongs to the \texttt{std} package.
584 Then comes a description
585 (the one which was provided by the author of the box),
586 the author(s) of the box (usually e-mail adress(es)) and
587 the categories to which the box belong.
588 Finally comes the lists of inputs and outputs of the box.
589 For each input or output, \bbi provides
590 its \emph{name} (between quotes, e.g. \texttt{'ProcessMode'}),
591 its \emph{type} (between \texttt{<>}, e.g. \texttt{<Int>})
593 Remark that the box \texttt{Add} is not a 'complex' black box
594 but an 'atomic' box, hence its help does not
595 mention any information concerning possible internal boxes.
597 You can create an \emph{instance} of an \texttt{Add} box by
598 the command \texttt{new}:
603 The \texttt{'a'} at the end is the \emph{name} of the instance,
604 which will be used to reference it later.
605 It is important to distinguish a box \emph{type}
606 and an \emph{instance} of a box type.
607 The \texttt{Add} box of the package \texttt{std} is actually
608 a \emph{box type} , like \texttt{int} is a data type
609 in \texttt{C} langage. The \texttt{new} command allows to create
610 an instance of a box type, exactly like \texttt{int i;} in
611 a \texttt{C} code, it declares a variable of type \texttt{int} whose
613 Of course, like in \texttt{C} Language, you can declare multiple boxes of the
616 After the creation of the box \texttt{a}, type:
623 Complex Black Box <user::workspace>
626 Category(s) : complex box;
633 which means that \bbi workspace now contains a black box named \texttt{a},
634 of type \texttt{std::Add}.
636 Now look back at the help on \texttt{Add} boxes:
637 you can see that this type of box has two inputs,
638 with name \texttt{In1} and \texttt{In2},
639 and an output, with name \texttt{Out}.
641 You can set the input \texttt{In1}
642 of the \texttt{Add} box \texttt{a} to the value $1$
648 Similarly, setting the input \texttt{In2} of \texttt{a} to the value $2$
654 And you print the output \texttt{Out} of the box \texttt{a} with:
656 > print "result=$a.Out$"
660 In the string passed to the \texttt{print} command,
661 each substring enclosed between a couple of \$ is considered
662 as the name of an output of a box.
663 To process this special substrings, \bbi does:
665 \item Processes the box if needed (see below)
666 \item Converts the output of the box to a string if possible
668 \item Substitutes the result in the string to print
669 \item postpone an implicit 'new line' character to the string
673 Box processing is needed if:
675 \item at least input has changed since last processing or
676 \item the input \texttt{'BoxProcessMode'} of the box is set to
677 \texttt{'Always'}, which forces box reprocessing.
680 Note that all boxes have the input \texttt{'BoxProcessMode'}.
682 Another way to process the box \texttt{a} is to issue the command:
687 however this command does not display anything (except if the
688 box itself displays something in its processing).
689 It just processes the box if needed.
690 This command is used to execute boxes that do not have any output,
691 such as boxes that write something to a file or, display a
692 graphical interface, and so on.
700 % ==========================================
705 \item The \texttt{include} command allows to load a package, and the complex black boxes that come with it..
706 \item \texttt{help} gives help on:
708 \item Available commands if you just type \texttt{help}.
709 \item A particular command if you type \texttt{help <command-name>}.
710 \item All available packages and their boxes (without description) if you type \texttt{help packages}.
711 \item A particular package and its boxes (with brief description) if you type \texttt{help <package-name>}.
712 \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}).
714 %\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).
715 \item \texttt{new} : creates an instance of a black box.
716 \item \texttt{set} : sets the value of an input of a black box.
717 \item In all \bbi, to reference the input called \texttt{i}
718 of a black box called \texttt{b} you must type \texttt{'b.i'}.
719 The same syntax holds for outputs.
720 \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
721 implicit trailing 'new line character' is added at the final string.
722 \item \texttt{exec} : runs the process of a box if needed.
723 \item \texttt{quit} : quits \bbi.
728 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.
729 Wou'll get something like in figure \ref{bbCommandPlusHelp} :
732 \caption{\label{bbCommandPlusHelp}
733 An other way to run the command interpreter}
735 \includegraphics[width=0.5\textwidth]{bbCommandPlusHelp.png}
738 % ==========================================
740 % ==========================================
741 \subsubsection{Connecting black boxes}
742 \label{bbi-connecting-black-boxes}
743 % ==========================================
745 \BBTK allows to create
746 and execute processing chains,
747 also called \emph{pipelines},
748 by connecting black boxes.
749 This section explains how to do it with examples.
750 Read section \ref{bbi-more-on-pipeline-processing} to get
751 more information on pipeline processing.
753 First start \bbi and load the package \texttt{std}:
758 Assume you want to compute $1+2+3$. You can do it by
759 chaining two \texttt{Add} boxes, as shown in figure
760 \ref{bbi-fig-connecting-black-boxes-1}.
763 \caption{\label{bbi-fig-connecting-black-boxes-1}
764 A simple pipeline which adds 3 numbers}
766 \includegraphics[width=0.5\textwidth]{1plus2plus3.png}
771 The \bbi instructions to create and execute this pipeline are:
775 > connect a.Out b.In1
782 You will see the (very expected) result :
787 The first three commands build the pipeline,
788 the next three set \texttt{a} and \texttt{b} black boxes inputs and the last one
789 prints \texttt{b} black boxe output (the pipeline is executed before printing, because the interpretor 'knows' he box \texttt{b},
790 whose output is requested, is not up to date.
792 The command \texttt{'connect a.Out b.In1'} ``plugs'' the output
793 \texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the
795 Once the boxes connected, the processing of the two boxes are chained:
796 getting the output of \texttt{b} requires getting its inputs,
797 hence getting the output of \texttt{a} which is connected to it.
798 This pipeline mechanism can recurse into arbitrary long
799 chains of boxes (see \ref{bbi-more-on-pipeline-processing}
803 Lets' consider an other, more image oriented, example :
811 > new FileSelector fileDialog
812 > new ImageReader reader
814 > new Viewer2D viewer
816 > connect fileDialog.Out reader.In
817 > connect reader.Out viewer.In
818 > connect slider.Out viewer.Slice
819 > connect slider.BoxChange viewer.BoxExecute
824 Some explainations : the \texttt{include} instructions load the necessary packages. \\
826 \texttt{new FileSelector} will pop a File Selector, at run time, that will out the user chosen file name. \\
827 \texttt{new Slider} will pop a Slider, at run time, that will out an integer, used later as a slice number.\\
828 \texttt{new ImageReader} will read any itk readable file, whose name is passed as a std::string, and return a itk::ImagePointer.
829 \texttt{new Viewer2D} display a plane, whose number id specified by an integer.\\
831 \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).\\
832 \texttt{connect reader.Out viewer.In} plugs the output of the reader (an itk::ImagePointer) to the input of the Viewer (a vtkImageData *)\\
833 \texttt{connect slider.Out viewer.Slice} plugs the output of the slider (an int) to an other output (named Slide) of the viewer.\\
834 \texttt{connect slider.BoxChange viewer.BoxExecute} says the viewer it must re process itself any time the slider is modified.\\
836 \texttt{exec viewer} processes the viewer.
839 This would correspond to the graph in figure \ref{bbi-simplegraph}
843 \caption{\label{bbi-simplegraph}(Very) simple Graph of a (very) simple pipeline}
845 \includegraphics[width=0.8\textwidth]{bbi-simplegraph.png}
849 Of course, to be able to connect two boxes,
850 the output and the input must be compatibles.
851 You can always connect an output to an input of the \emph{same} type,
852 but you can do more, thanks to particular (hidden) black boxes called {\bf adaptors}.
854 An adaptor is a black box which has at least one input, called \texttt{In},
855 and at least one ouput called \texttt{Out} and whose role is to convert
856 a data of the type of \texttt{In}
857 into a data of the type of \texttt{Out} (other inputs or outputs may serve
858 to parameter the adaptor or retreive other usefull information).
860 In \bbi, if you type:
867 Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
868 Basic useful black boxes
870 Add : Adds its inputs
871 Cast<double,float> [DA] : Casts a double into a float
872 Cast<double,int> [DA] : Casts a double into a int
874 Convert<unsigned int,string> [DA] : Converts a unsigned int into a s...
875 Convert<unsigned short,string> [DA] : Converts a unsigned short into a...
876 Print : Prints its input to standard out...
880 The \texttt{Cast<?,?>} and \texttt{Convert<?,?>} boxes are \emph{default adaptors}, which is signaled by the tag \texttt{[DA]} before their descriptions.
882 Once you have loaded the package \texttt{std}, you can
883 plug an output of type \texttt{char} into an input of type \texttt{double}.
884 When \bbi encounters the \texttt{connect} command,
885 it looks for an adequate \emph{adaptor} in the loaded packages.
886 In our case, as the package \texttt{std} provides the
887 \texttt{Cast<char,double>} adaptor, \bbi automatically creates an
888 instance of this adaptor and place it \emph{between}
889 the output and the input you want to connect
890 (however this adaptor is hidden to you,
891 it is embedded into the created connection and does not appear
892 as an existing black box).
893 When the pipeline is processed the
894 adaptor converts the output data into the required input type,
895 in a totally transparent way.
896 In our example, the \texttt{Cast<char,double>} adaptor
897 would simply cast the value of the \texttt{char} into a \texttt{double},
898 however arbitrarily complex type conversion can be done.
901 if two adaptors with the same input and output types exist
902 in the packages loaded,
903 which one is chosen by \bbi at connection ?
904 -> Role of default adaptors
906 Note that the \texttt{set} and \texttt{print} commands of \bbi
907 work with adaptors from \texttt{string} to the type of the input to set
908 or from the type of the output to print to \texttt{string}.
909 Hence in order to \texttt{set} or \texttt{print} values the adequate
910 adaptors must be available in the packages currently loaded.
912 % ==========================================
917 \item The \texttt{connect} command allows to connect two black boxes
918 \item You can connect two black boxes if (and only if):
920 \item The output and the input are of the same type, or
921 \item There is an adaptor black box in the packages loaded which
922 converts data of the output type into data of the input type
924 \item \texttt{help <package name>} does not display the adaptors of the package. To see them use: \texttt{help <package name> all}.
928 % ==========================================
930 % ==========================================
931 \subsubsection{Creating complex black boxes}
932 \label{bbi-complex-black-boxes}
933 % ==========================================
935 Remember the pipeline of figure
936 \ref{bbi-fig-connecting-black-boxes-1}, which
937 computed the sum of three doubles ?
938 You can view it as a whole and define
939 a new black box type, which will be a \emph{complex black box},
940 having three inputs and one output,
941 as shown in figure \ref{bbi-fig-complex-black-box-1}.
944 \caption{\label{bbi-fig-complex-black-box-1}
945 Creating the complex black box \texttt{Add3}}
947 \includegraphics[width=0.5\textwidth]{Add3.png}
951 The \bbi commands to define this complex black box are
961 > connect a.Out b.In1
964 > description "adds 3 doubles"
965 > input x a.In1 "first double to add"
966 > input y a.In2 "second double to add"
967 > input z b.In2 "third double to add"
968 > output result b.Out "output"
975 As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
977 The command \texttt{define} then starts the definition
978 of the complex box type, which will be called \texttt{Add3}.
980 The next three lines define the pipeline,
981 exactly in the same way than outside a complex box definition.
983 The commands \texttt{author}, \texttt{description}, \texttt{input}
984 and \texttt{output} are commands specific to complex boxes definition:
986 \texttt{author} and \texttt{description} are used for the documentation
987 of the new box. You can provide multiple \texttt{author} or
988 \texttt{description} commands, the arguments of the commands will
989 be concatenated to produce the final author and description strings.
991 \texttt{input} and \texttt{output} are used to define the inputs and outputs
992 of the new complex box.
993 Their syntax is the same: for each new input/output you need to say
994 to which internal input/output it corresponds and to provide
995 a help string documenting the input/output.
996 In our example, we define that the box \texttt{Add3} has
997 three inputs: \texttt{x}, \texttt{y} and \texttt{z}.
998 The input \texttt{x} corresponds to the input \texttt{In1} of the
999 internal box \texttt{a}.
1000 In the same way, the external input \texttt{y}
1001 corresponds to the internal input \texttt{a.In2}, and
1002 the external input \texttt{In3} to \texttt{b.In2}.
1003 The only output of the new box is called \texttt{result}
1004 and corresponds to \texttt{b.Out}.
1005 The figure \ref{bbi-fig-complex-black-box-1}
1006 illustrates the external to internal
1007 input/output correspondence.
1009 Finally, the \texttt{endefine} command ends the definition of the
1012 After this definition, if you ask for help
1013 on packages, you get:
1024 The \texttt{user} package now contains a new black box type, called
1025 \texttt{Add3}. If you ask for help on this type of box, you get:
1028 Complex Black Box <user::Add3>
1032 'x' <double>: first double to add
1033 'y' <double>: second double to add
1034 'z' <double>: third double to add
1036 'result' <double>: output
1042 and you can use it like any other box, for example type:
1054 As a side note, we can say that, for consistency reasons, it would have been better to name
1055 \texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3},
1056 since all the 'natural entry' of a box is named \texttt{In}, or\texttt{In}x if there are more than one 'natural
1059 % ==========================================
1064 \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.
1065 Inside a \texttt{define/endefine} block:
1067 \item The \texttt{author} and \texttt{description} commands allow to document the new type of box
1068 \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
1069 of internal boxes they correspond.
1073 % ==========================================
1075 % ==========================================
1076 \subsubsection{Writing scripts}
1077 \label{bbi-writing-scripts}
1078 % ==========================================
1080 Once you have defined a new type of complex box, you
1081 may like to reuse it. To do this, you can simply
1082 write the \bbi commands defining the new box
1083 into a text file and afterwards include that file in \bbi.
1084 Doing this, you start writing \bbi scripts.
1085 The conventionnal extension for such scripts is \texttt{bbs}
1087 For consistency reasons, you are requested to prepend \texttt{bb} to the name.
1089 For example, the \texttt{Add3} complex box we previously worked on
1090 can be defined in the \texttt{bbAdd3.bbs} file:
1092 \begin{file}{bbAdd3.bbs}
1094 # Defines the Add3 black box which adds 3 doubles
1100 description "adds 3 doubles"
1106 input x a.In1 "first double to add
1107 input y a.In2 "second double to add
1108 input z b.In2 "third double to add"
1110 output result b.Out "output"
1115 Lines starting with a \texttt{\#} character are ignored, they
1116 are considered as comments by \bbi.
1117 To use this file in \bbi, use the \texttt{include} command:
1120 > include bbAdd3.bbs
1122 Complex Black Box <user::Add3>
1126 'x' <double>: first double to add
1127 'y' <double>: second double to add
1128 'z' <double>: third double to add
1130 'result' <double>: output
1138 If the file has the \texttt{bbs} extension, you can ommit it and just type:
1143 Of course, you can include script files in other script files,
1144 like in the following example:
1146 \begin{file}{bbAdd4.bbs}
1148 # Defines the Add4 black box which adds 4 doubles
1153 description "adds 4 doubles"
1157 input In1 a.In1 "first double to add
1158 input In2 a.In2 "second double to add
1159 input In3 a.In3 "third double to add"
1160 input In4 b.In2 "fourth double to add"
1161 output Out b.Out "output"
1166 % ==========================================
1168 \paragraph{Naming Conventions}
1172 % ==========================================
1176 For consistency reasons, you are requested to prepend \texttt{bb}, and postpone an extention \texttt{.bbs},
1177 to the names of the files that hold a \texttt{complex black box} definition.
1179 For example, the \texttt{Add3} complex box we previously worked on
1180 can be defined in the \texttt{bbAdd3.bbs} file.
1184 % ==========================================
1190 \item The \texttt{include} command allows to include a script file in \bbi.
1191 \item Lines starting with a \texttt{\#} or with a \texttt{\//} are treated as comments in \bbi scripts.
1192 \item Lines between a line starting with a \texttt{\//*} an a line starting with a \texttt{*\//} are treated as comments in \bbi scripts.
1196 % ==========================================
1198 % ==========================================
1199 \subsubsection{Creating command line applications}
1200 \label{bbi-command-line-app}
1201 % ==========================================
1203 Now that you now how to create complex black boxes
1204 (with \texttt{define/endefine}), think
1205 back to the \texttt{workspace} object.
1206 Remember that it is also
1207 a \texttt{complex black box}.
1208 In fact what you are doing when you type \bbi commands
1209 outside a \texttt{define/endefine} block
1210 is to progressively define the \texttt{workspace}
1212 You can think of it like if at start
1213 \bbi was issuing a command \texttt{'define workspace'}
1214 and then letting you define the interior of the box
1217 Remember that the command \texttt{inputs}
1218 allows to define an input of a complex box.
1219 Now, if you use the command \texttt{input}
1220 outside a \texttt{define/endefine} block then
1221 it defines an input of the \texttt{workspace} box,
1222 that is an input of the \emph{main program}.
1223 This input will then be connected to the
1224 parameters that the user passes to the command line.
1226 For example, consider the script:
1228 \begin{file}{add.bbs}
1232 input x a.In1 "first number to add"
1233 input y a.In2 "second number to add"
1238 The third and fourth lines define two inputs \texttt{x}
1239 and \texttt{y}. When you execute this script,
1240 you can pass these two arguments on the command line,
1248 You can also invoke \bbi the option \texttt{-h},
1249 which gives help on the \texttt{workspace} box:
1256 'x' <double>: first number to add
1257 'y' <double>: second number to add
1260 To get a better help, use the \texttt{description}
1261 and \texttt{author} commands:
1263 \begin{file}{add.bbs}
1265 description "Adds two numbers"
1266 author "foo@bar.com"
1269 input x a.In1 "first number to add"
1270 input y a.In2 "second number to add"
1275 Now if you ask for help on the \texttt{add} script, you get:
1282 'x' <double>: first number to add
1283 'y' <double>: second number to add
1286 Rather than getting the inputs of a script
1287 from the command line, you can ask \bbi to
1288 prompt the user for the values, using the \texttt{-t}
1293 x=[the program waits for user answer]2
1294 y=[the program waits for user answer]5
1298 If \bbi is compiled in graphical mode (with \wx),
1299 you can also use the \texttt{-g} commutator.
1300 \bbi then prompts the user in graphical mode,
1301 displaying a dialog box for each input,
1302 like in fig. \ref{bb-input-dialog-box}.
1305 \caption{\label{bb-input-dialog-box}Input dialog box}
1307 \includegraphics[width=0.6\textwidth]{enter-the-value-of-x.png}
1311 % ==========================================
1316 \item The \texttt{input}, \texttt{description} and \texttt{author} commands,
1317 when they are used outside a \texttt{define/endefine} block allow
1318 to define the inputs, description and author of the main program.
1319 \item Inputs of the main program can be passed on the command line
1320 using the syntax \texttt{<input-name>=<value>}.
1321 No white space is allowed, if the value or the input name
1322 contains white spaces, enclose them
1323 between double quotes, e.g. \texttt{"parameter with white spaces = gnu's not unix"}.
1324 \item The \texttt{-h} option of \bbi prints help on the main program.
1325 \item The \texttt{-t} option of \bbi orders the program to prompt for its inputs in text mode.
1326 \item The \texttt{-g} option of \bbi orders the program to prompt for its inputs in graphical mode.
1329 % ==========================================
1331 % ==========================================
1332 \subsubsection{Using graphical interface boxes (widget boxes)}
1334 % ==========================================
1336 % ==========================================
1337 \subsubsection{Overwiew}
1338 \label{bbi-overview}
1339 % ==========================================
1341 If \bbi is compiled in graphical mode
1342 (option \texttt{BUILD\_bbi\_GRAPHICAL} of \cmake, requires \wx),
1343 then you can use special black boxes which are
1344 graphical interface components (widgets).
1345 Basic components are provided in the package \texttt{wx},
1346 such as buttons, sliders, file open/save dialogs, etc.
1348 As first example, type the following commands in \bbi:
1355 When you type \texttt{enter} after the last line,
1356 a window pops up in which you can entrer a text.
1357 When you close the window, the text you entered is printed by
1358 the \texttt{print} command.
1360 Type \texttt{help wx}, you get something like:
1362 Package wx v1.0.0- info-dev@creatis.insa-lyon.fr
1363 Basic graphical interface elements (sliders, buttons ...) based on wxWidgets
1365 ColourSelector : Colour Selector dialog (bbfication of wxColourSele...
1366 ColourSelectorButton : A button which displays a colour picker dialog whe...
1367 CommandButton : Button which executes bbi commands
1368 DirectorySelector : Pops up a directory selection dialog (wxDirDialog)
1369 FileSelector : Pops up a file selection dialog for reading or sav...
1370 InputText : A zone in which the user can enter a text (wxTextC...
1371 LayoutLine : LayoutLine widget (wxBoxSizer)
1372 LayoutSplit : Widget which splits a window in two fixed size par...
1373 LayoutTab : LayoutTab widget (wxNotebook)
1374 OutputText : Text zone to be inserted into a window (wxStaticTe...
1375 RadioButton : RadioButton group widget 0-9 entries
1376 Slider : Slider widget (wxSlider)
1379 You can reproduce the same experiment as above using a
1380 \texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}.
1381 See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
1383 There are two kinds of widgets: ``terminal'' widgets and ``container'' widgets.
1384 The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets
1385 are ``terminal'' widgets.
1386 ``container'' widgets are of another kind: they are designed to
1387 contain other widgets in order to build larger dialog boxes.
1388 For example, the \texttt{LayoutSplit} widget is a container which
1389 ``splits'' horizontally a window into two parts,
1390 each part including another widget.
1391 The size of the two parts can be adjusted by the user thanks
1394 The script \texttt{scripts/test/testSplit.bbs} demonstrate its use.
1395 Run it: it displays a window with two sliders.
1396 Move the sliders and close the window.
1397 The final positions of the sliders are printed out.
1398 Now edit the file to see how this is done:
1400 \begin{file}{scripts/test/testSplit.bbs}
1409 connect s1.Widget s.Widget1
1410 connect s2.Widget s.Widget2
1412 print s1=$s1.Out$\\n
1413 print s2=$s2.Out$\\n
1417 First, the two sliders \texttt{s1} and \texttt{s2} are created.
1418 A \texttt{LayoutSplit} box \texttt{s} is also created.
1419 The \texttt{connect} commands then ``includes'' the sliders in the
1420 split ``container''.
1421 The input \texttt{Widget} is common to all widget boxes:
1422 every widget can be inserted into another widget.
1423 The outputs \texttt{Widget1},\texttt{Widget2} are specific of \emph{container}
1425 (in \bbi type \texttt{help Slider}:
1426 you will see the output \texttt{Widget};
1427 type \texttt{help LayoutSplit}:
1428 you will see the inputs \texttt{Widget1} and \texttt{Widget2}
1429 and the output \texttt{Widget}).
1430 When you connect the \texttt{Widget} output of a container
1431 to the \texttt{Widget}i input of a widget,
1432 you order to include the widget in the container.
1433 Of course, the order of connection is important.
1434 In our case, the slider \texttt{s1} is included first,
1435 then the slider \texttt{s2}: \texttt{s1} will be placed
1436 on top of \texttt{s2} (the \texttt{LayoutSplit} box is
1437 implemented that way, but this is arbitrary choice).
1439 Right now, there are only \emph{three} container widgets in the \texttt{wx} package:
1440 the \texttt{LayoutSplit} widget we just described, the \texttt{LayoutLine} , and the \texttt{LayoutTab}
1443 The \texttt{LayoutLine} widget can have multiple children and
1444 divides its window into as much parts as children,
1445 each part of equal size.
1446 The orientation of the \texttt{LayoutSplit} or of the \texttt{LayoutLine} can be changed by the input \texttt{Orientation}.
1447 See the example \texttt{test/testSizer.bbs}.
1448 With only those two containers you can already create
1449 complex dialog boxes (of course containers can be nested, which
1450 leads to tree-like structures of widgets).
1451 See the script \texttt{bbtk/share/bbtk/bbs/wx/appli/ExampleLayoutSplit.bbs} for an example.
1453 The \texttt{LayoutTab} widget is based on the \texttt{wxNotebook.}
1455 One word about a special widget in the package \texttt{wx}:
1456 the \texttt{Button}... to be continued.
1458 % ==========================================
1459 \subsubsection{Deeper in the boxes}
1460 \label{bbi-deep-box}
1461 % ==========================================
1463 Any widget box has two mandatory Outputs :
1466 \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
1467 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.
1468 \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,
1469 further within the execution pipeline.
1472 Any widget box has two mandatory Inputs :
1474 \item {\bf\emph{BoxExecute}} : Any signal received by this input executes the box
1475 \item {\bf\emph{BoxProcessMode}} : Sets the processing mode of the box :
1477 \item {\bf\emph{Pipeline}} : bbUpdate() calls Process only if Status == MODIFIED (normal pipeline processing)
1478 \item {\bf\emph{Always}} : bbUpdate() always calls Process
1479 \item {\bf\emph{Reactive}} : bbSetModifiedStatus() calls bbUpdate()
1483 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} :
1485 \item {\bf\emph{WinHeight}} : Height of the window
1486 \item {\bf\emph{WinWidth}} : Width of the window
1487 \item {\bf\emph{WinTitle}} : Title of the window
1488 \item {\bf\emph{WinClose}} : Any received signal closes the window
1489 \item {\bf\emph{WinHide}} : Any received signal hides the window
1490 \item {\bf\emph{WinDialog}} : When set to 'true', creates a \emph{dialog window}, that blocks the pipeline until it is closed (\emph{modal})
1494 Any \emph{Layout box} (i.e. \emph{LayoutLine}, \emph{LayoutSplit} or \emph{LayoutTab}) has at one or more mandatory Inputs :
1496 \item {\bf\emph{Widget}}\texttt{i} : e.g. a \emph{LayoutSplit} box (Widget which splits a window in two fixed size parts)
1497 has two Input parameters \emph{Widget1} and \emph{Widget2}, used to embed the child windows.
1501 % ==========================================
1502 \subsection{More on ...}
1504 % ==========================================
1506 % ==========================================
1507 \subsubsection{Black box packages}
1508 \label{bbi-more-on-packages}
1509 % ==========================================
1511 There are various others user-intended packages :
1514 It contains some vtk based image processing filters :
1517 \paragraph{AppendPolyData}
1518 Appends one of more polygonal datasets into a single polygonal dataset
1520 \paragraph{ConeSource}
1523 \paragraph{ImageAnisotropicDiffusion3D}
1524 vtkImageAnisotropicDiffusion3D diffuses an volume iteratively. \\
1525 The neighborhood of the diffusion is determined by the instance flags. \\
1526 if 'Faces' is on, the 6 voxels adjoined by faces are included in the neighborhood. \\
1527 If 'Edges' is on the 12 edge connected voxels are included, and if 'Corners' is on, the 8 corner connected voxels are included. \\
1528 'DiffusionFactor' determines how far a pixel value moves toward its neighbors, and is insensitive to the number of neighbors chosen.\\
1529 The diffusion is anisotropic because it only occurs when a gradient measure is below 'GradientThreshold'. \\
1530 Two gradient measures exist and are toggled by the 'GradientMagnitudeThreshold' flag. \\
1531 When 'GradientMagnitudeThreshold' is on, the magnitude of the gradient, computed by central differences, above 'DiffusionThreshold' a voxel is not
1533 The alternative measure examines each neighbor independently.\\
1534 The gradient between the voxel and the neighbor must be below the 'DiffusionThreshold' for diffusion to occur with THAT neighbor.\\
1536 - In : an image (vtkImageData*)\\
1537 - Diffusion : Difference threshold that stops the diffusion\\
1539 - Out : the isosurface mesh (vtkPolyData*)
1541 \paragraph{ImageCharacteristics}
1542 Exports objet sizes, and Spacings
1544 \paragraph{ImageDilateErode3D}
1545 Dilates one value and erodes another.\\
1546 vtkImageDilateErode3D will dilate one value and erode another. \\
1547 It uses an elliptical foot print, and only erodes/dilates on the boundary of the two values. \\
1548 The filter is restricted to the X, Y, and Z axes for now.\\
1549 It can degenerate to a 2 or 1 dimensional filter by setting the kernel size to 1 for a specific axis. \\
1550 (bbfication of vtkImageDilateErode3D) \\
1552 - In : an image (vtkImageData*)\\
1553 - DilateValue : The dilatation value\\
1554 - ErodeValue : The erosion value\\
1556 - Out : the isosurface mesh (vtkPolyData*)
1558 \paragraph{ImageGaussianSmooth}
1559 Performs a gaussian convolution of the input image\\
1561 - In : an image (vtkImageData*)\\
1562 - StdDevX : Standard deviation in X direction\\
1563 - StdDevY : Standard deviation in Y direction\\
1565 - Out : the isosurface mesh (vtkPolyData*)
1567 \paragraph{ImagePlanes}
1568 Creates three 3D planes with the input image mapped onto with which the user can interact; \\
1569 The output vtkImagePlaneWidget objects are to be inserted into a 3D scene (e.g. a Viewer3D)
1571 - In : an image (vtkImageData*)\\
1573 - PlaneX : the image plane in X direction (vtkImagePlaneWidget*)\\
1574 - PlaneY : the image plane in Y direction (vtkImagePlaneWidget*)\\
1575 - PlaneY : the image plane in Z direction (vtkImagePlaneWidget*)\\
1578 - Out : the isosurface mesh (vtkPolyData*)
1580 \paragraph{IsoSurfaceExtractor}
1581 Extracts an iso-surface of a 3D image and creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D)
1583 - In : an image (vtkImageData*)\\
1584 - Isovalue : the isosurface value (double)\\
1585 - Colour : Surface colour (vector of 3 doubles)
1587 - Out : the isosurface (vtkProp3D**)
1589 \paragraph{MarchingCubes}
1590 Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes)\\
1592 - In : an image (vtkImageData*)\\
1593 - Value : the isosurface value (double)\\
1595 - Out : the isosurface mesh (vtkPolyData*)
1597 \paragraph{MIPCreator}
1598 Creates a Maximum Intensity Projection (MIP) view of a 3D image.\\
1600 - In : an image (vtkImageData*)\\
1601 - Scale : the Gray scale scaling (float) \\
1602 - Shift : the Gray scale shift (float) \\
1604 - Out : The MIP object (vtkProp3D*) to be plugged into a 3D Viever
1606 \paragraph{MetaImageReader}
1607 Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader) \\
1609 - In : the name of the file to be read (std::string)
1611 - Out : The image (vtkImageData*)
1613 \paragraph{SegmentationConnectivity}
1614 Segmentation with min max threshold and connectivity \\
1616 - In : an image (vtkImageData*)\\
1617 - PositionXYZ : initial position (std::vector<int>) \\
1618 - ThresholdMinMax : min, max threshold values (std::vector<int>) \\
1620 - Out : The image (vtkImageData*)
1622 \paragraph{SphereSource}
1627 It contains some itk based image processing filters :
1629 \paragraph{BinaryThresholdImageFilter}
1630 Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter)
1632 \paragraph{DICOMSeriesFileNames}
1633 Reads a series from a DICOM directory as a 3D itk image
1635 \paragraph{ExtractImageFilter}
1636 Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)
1638 \paragraph{ImageProperties}
1639 Outputs different properties of an image (type, dimension, size, spacing, ...)
1641 \paragraph{ImageRegion}
1642 Creates a generic ImageRegion (bbtk::any) from two vectors providing the index and size of the region.
1643 The dimension D of the actual itk::ImageRegion created is the max of the sizes of Index and Size
1644 (the smallest vector is padded by zeros)
1646 \paragraph{ImageReader}
1647 Generic itk image reader
1649 \paragraph{ImageWriter}
1650 Generic itk image writer
1652 \paragraph{ImageSeriesReader}
1653 Generic itk image series reader.
1655 \paragraph{ResampleImageFilter}
1659 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
1661 Sorry nothing is done, right now for meshes.
1665 It contains two atomic black boxes.
1667 \paragraph{Viewer2D}
1669 - a \textless vtkImageData* \textgreater (In),\\
1670 - an Orientation(0:yz / 1:xz / 2:xy),\\
1671 - an initial slice number (Slice).\\
1673 - a \textless vtkRenderer* \textgreater (Renderer)
1675 \paragraph{Viewer3D}
1677 - up to 5 Input Actors (\textless vtkProp3D* \textgreater),\\
1678 - up to 5 Input Observers (\textless vtkInteractorObserver* \textgreater), \\
1679 - a boolean 'Stereo' option, to use Red-Blue filter
1681 - an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact, \\
1682 - a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
1684 It contains too some sophisticated complex black boxes :
1686 \paragraph{IsoSurfaceWithControls}
1687 Image iso-surface extractor (vtk::IsoSurfaceExtractor) with associated control panel (isovalue, opacity and colour)\\
1689 - an initial isovalue (Isovalue)
1690 - an initial opacity (Opacity)
1691 - an initial colour (Colour)
1693 \textless vtkProp3D* \textgreater (In)\\
1695 \paragraph{MIPWithControls}
1696 Maximum Intensity Projection (MIP) creator (vtk::MIPCreator) with associated control panel (shift and scale) \\
1698 - an initial scale (Scale)
1699 - an initial shift (Shift)
1701 \textless vtkProp3D* \textgreater (In)\\
1705 Some boxes are the bbfication of usefull xwWidgets, some other ones are more
1708 \paragraph{ColourSelector} Colour Selector dialog (bbfication of wxColourSelector) \\
1710 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
1713 \paragraph{ColourSelectorButton} A button which displays a colour picker dialog when clicked \\
1715 \texttt{In} :Initial colour \\
1716 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
1719 \paragraph{CommandButton} Button which executes bbi commands \\
1721 \texttt{In} : Commands to be executed separated by commas (;). Each single quote (') is replaced by a double quote ("). \\
1722 \texttt{Label} : Label of the button \\
1723 \texttt{Widget} : Output widget \\
1726 \paragraph{DirectorySelector} Pops up a directory selection dialog (wxDirDialog)\\
1728 \texttt{DefaultDir} : The default directory\\
1729 \texttt{Message} : Message to show on the dialog \\
1730 \texttt{Title} : Title of the dialog \\
1731 \texttt{Out} : The directory selected by the user\\
1734 \paragraph{FileSelector} Pops up a file selection dialog for reading or saving (wxFileDialog)\\
1736 \texttt{DefaultDir} : The default directory \\
1737 \texttt{DefaultFile} : The default filename \\
1738 \texttt{Message} : Message to show on the dialog \\
1739 \texttt{OpenSave} : Open for an open dialog (default) / Save for a save dialog\\
1740 \texttt{Title} : Title of the dialog \\
1741 \texttt{Wildcard} : A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" \\
1742 \texttt{Out} : The file selected by the user \\
1745 \paragraph{InputText} A zone in which the user can enter a text (wxTextCtrl)\\
1747 \texttt{In} : Initial text (default '')\\
1748 \texttt{Title} : Title of the input zone (default '')\\
1749 \texttt{WinTitle} : Title of the window (*)\\
1750 \texttt{Out} :Current text\\
1753 \paragraph{LayoutLine} LayoutLine widget (wxBoxSizer)\\
1755 \texttt{Orientation} Orientation (default V), 0=H=HORIZONTAL , 1=V=VERTICAL \\
1756 \texttt{Widget}1 widget 1 \\
1757 \texttt{Widget2} widget 2 \\
1758 \texttt{Widget3} widget 3 \\
1759 \texttt{Widget4} widget 4 \\
1760 \texttt{Widget5} widget 5 \\
1761 \texttt{Widget6} widget 6 \\
1762 \texttt{Widget7} widget 7 \\
1763 \texttt{Widget8} widget 8 \\
1764 \texttt{Widget9} widget 9\\
1767 \paragraph{LayoutSplit} Widget which splits a window in two fixed size parts (wxSplitterWindow)\\
1769 \texttt{Orientation} : Orientation (default H), 0=H=HORIZONTAL , 1=V=VERTICAL\\
1770 \texttt{Proportion} : Proportion (in percent) of the first children in the window\\
1771 \texttt{Widget1} : Upper or left widget\\
1772 \texttt{Widget2} : Lower or right widget\\
1775 \paragraph{LayoutTDown} Creates a 'T like' complex container : Down {UpLeft, UpRight} \\
1777 \texttt{Widget1} : UpLeft container\\
1778 \texttt{Widget2} : UpRight container\\
1779 \texttt{Widget3} : Down container\\
1790 \paragraph{LayoutTLeft} Creates a 'T like' complex container : Left {RigthUp, RightDown}\\
1792 \texttt{input} Widget1 : "UpLeft container"\\
1793 \texttt{input} Widget2 : "UpRight container"\\
1794 \texttt{input} Wigdet3 : "Down container"\\
1805 \paragraph{LayoutTRight} Creates a 'T like' complex container : Right {LeftUp, LeftDown}\\
1807 \texttt{input} Widget1 currentBox.Widget1 "Up container"\\
1808 \texttt{input} Widget2 down.Widget1 "DownLeft container"\\
1809 \texttt{input} Widget3 down.Widget2 "DownRight container"\\
1820 \paragraph{LayoutTUp} Creates a 'T like' complex container : Up {DownLeft, DownRight} as w1{w2,w3}\\
1822 \texttt{ input} Widget1 currentBox.Widget1 "Up"\\
1823 \texttt{input} Widget2 down.Widget1 "DownLeft"\\
1824 \texttt{input} Widget3 down.Widget2 "DownRight"\\
1835 \paragraph{LayoutTab} LayoutTab widget (wxNotebook)\\
1837 \texttt{Orientation} Orientation (default T), 0=T=TOP , 1=R=RIGHT , 2=B=BOTTON , 3=L=LEFT \\
1838 \texttt{Widget1} widget 1 \\
1839 \texttt{Widget2} widget 2 \\
1840 \texttt{Widget3} widget 3 \\
1841 \texttt{Widget4} widget 4 \\
1842 \texttt{Widget5} widget 5 \\
1843 \texttt{Widget6} widget 6 \\
1844 \texttt{Widget7} widget 7 \\
1845 \texttt{Widget8} widget 8 \\
1846 \texttt{Widget9} widget 9 \\
1849 \paragraph{OutputText} Text zone to be inserted into a window (wxStaticText)\\
1852 \texttt{Title} Title prepended to the text\\
1855 \paragraph{RadioButton} RadioButton group widget 0-9 entries\\
1857 \texttt{In} Set initial item \\
1858 \texttt{In0} option 0\\
1859 \texttt{In1} option 1\\
1860 \texttt{In2} option 2\\
1861 \texttt{In3} option 3\\
1862 \texttt{In4} option 4\\
1863 \texttt{In5} option 5 \\
1864 \texttt{In6} option 6 \\
1865 \texttt{In7} option 7 \\
1866 \texttt{In8} option 8 \\
1867 \texttt{In9} option 9 \\
1868 \texttt{Title} Title of the widget (default '')\\
1869 \texttt{Out} Number of the selected Item
1872 \paragraph{Slider} Slider widget (wxSlider)\\
1874 \texttt{ChangeResolution} Enables the user to change the slider resolution (default FALSE) \\
1875 \texttt{In} Initial slider position(default 0) \\
1876 \texttt{Label} Show slider labels ? (default FALSE) \\
1877 \texttt{Max} Maximum value of the slider (default 500)\\
1878 \texttt{Min} Minimum value of the slider (default 0)\\
1879 \texttt{Orientation} Orientation : (default H) 0=H=HORIZONTAL, 1=V=VERTICAL\\
1880 \texttt{ReactiveOnTrack} Slider sends info when track moves (default 0 = no)\\
1881 \texttt{Title} Title shown above the slider (default '')\\
1884 % ==========================================
1885 \subsubsection{Pipeline processing}
1886 \label{bbi-more-on-pipeline-processing}
1887 % ==========================================
1889 \item the ``control'' mechanism in bbi (switch exec commands, e.g. Button)
1890 \item the role of ProcessMode to update widgets.
1892 % ==========================================
1893 \subsubsection{Complex black boxes}
1894 \label{bbi-more-on-complex-black-boxes}
1895 Creation of complex widgets (containers, contained...)
1897 %\subsubsection{Advanced issues}
1898 %\paragraph{Reducing the number of inputs of a box}
1900 % ==========================================
1901 \subsubsection{Errors}
1902 \label{bbi-more-on-errors}
1904 % ==========================================
1905 \subsubsection{\bbtk configuration file and search pathes}
1906 \label{bbi-more-on-configuration}
1908 At start, \bbi tries to open an \texttt{xml}
1909 configuration file named \texttt{bbtk\_config.xml}.
1912 \item The current directory
1913 \item The subdir \texttt{.bbtk} of the user's home directory.
1915 \item On \texttt{Unix}, the home directory is the
1916 one stored by the environnement variable \texttt{HOME},
1917 typically \texttt{/home/username}.
1918 \item On \texttt{Windows}, the home directory is
1919 the user's profile directory stored by the environnement
1920 variable \texttt{USERPROFILE},
1921 typically \texttt{C:\\...}.
1923 \item If none of these two pathes contains the file then it creates
1924 a new one in the \texttt{.bbtk} directory.
1927 Once created, you can edit the \texttt{bbtk\_config.xml} file located
1928 in your \texttt{.bbtk} directory. It contains:
1930 \begin{file}{bbtk\_config.xml}
1932 <?xml version="1.0" encoding="iso-8859-1"?>
1934 <bbtk_url> http://www.creatis.insa-lyon.fr/software/bbtk </bbtk_url>
1935 <bbs_path> </bbs_path>
1936 <package_path> </package_path>
1937 <data_path> </data_path>
1942 You can add pathes to
1944 \item A custom folder in which to search for \texttt{.bbs} scripts (\texttt{include} command of \bbi) by adding an \texttt{xml} tag:
1945 \texttt{<bbs\_path>complete\_path\_to\_folder<\/bbs\_path>}.
1946 \item A custom folder in which to search for packages (\texttt{load} command of \bbi) by adding an \texttt{xml} tag:
1947 \texttt{<package\_path>complete\_path\_to\_folder<\/package\_path>}.
1950 % ==========================================
1951 \subsection{Language reference}
1952 \label{bbi-reference}
1953 % ==========================================
1959 % ==========================================
1961 \caption{\label{bbi-reference-box}
1962 \bbi pipeline creation and execution related commands.}
1964 \begin{tabular}{|lcm{6cm}|}
1966 Command & Parameters & Effect \\ \hline
1968 \texttt{new} & \texttt{<boxtype>} \texttt{<box-name>}&
1969 Creates a box of type \texttt{boxtype} and name
1973 \texttt{delete} & \texttt{<box-name>} &
1974 Destroys the box named \texttt{box-name}.
1977 \texttt{connect} & \texttt{<box1.output>} \texttt{<box2.input>} &
1979 \texttt{output} of the box named \texttt{box1}
1980 to the input \texttt{input} of the box named \texttt{box2} \\ \hline
1982 \texttt{set} & \texttt{<box.input>} \texttt{<value>} &
1983 Sets the input \texttt{input} of
1984 the box named \texttt{box} to the value \texttt{value}.
1985 There must exist an \texttt{adaptor}
1986 in the packages loaded which converts a \texttt{std::string}
1987 to the type of the input \texttt{input}.
1990 \texttt{print} & \texttt{<string>} &
1991 Prints the string after substituting each token of the form \texttt{\$box.output\$} by the adaptation to string of the value of the
1992 output \texttt{output} of the box named \texttt{box}.
1993 There must exist an \texttt{adaptor}
1994 in the packages loaded which converts
1995 the type of the output \texttt{output}
1996 to a \texttt{std::string}.
1999 \texttt{exec} & \texttt{<box-name>} &
2000 Executes the box named \texttt{box-name}.
2002 connected to its inputs
2003 are also processed recursively (pipeline processing).\\ \hline
2004 \texttt{exec} & \texttt{freeze} &
2005 allows to block execution commands while keeping definition commands active.\\ \hline
2006 \texttt{exec} & \texttt{unfreeze} &
2007 turns back to 'normal' mode.\\ \hline
2010 % ==========================================
2014 % ==========================================
2016 \caption{\label{bbi-reference-interpreter}\bbi intepreter related commands.}
2018 \begin{tabular}{|lcm{6cm}|}
2020 Command & Parameters & Effect \\ \hline
2024 Prints help on available commands \\ \hline
2026 & \texttt{<command-name>} &
2027 Prints help on the command \texttt{command-name} \\ \hline
2029 & \texttt{packages} &
2030 Prints help on available packages and their box types
2031 (without description)\\ \hline
2033 & \texttt{<package-name>} &
2034 Prints help on the package \texttt{package-name} and its boxes
2035 (with brief description).
2036 The package must have been previously loaded
2039 & \texttt{<box-type>} &
2040 Prints help (with full description) on the type of box
2042 The box type must belong to a package which has been previously loaded
2045 \texttt{include} & \texttt{<file-name>} &
2046 Includes and executes the content of the file named \texttt{file-name}
2047 exactly like if you were typing its content at the place were the
2048 \texttt{include} command is.
2051 \texttt{load} & \texttt{<package-name>} &
2052 Loads the package \texttt{package-name}\\ \hline
2054 \texttt{include} & \texttt{<package-name>} &
2055 Loads the package \texttt{package-name} and includes all the complex black boxes that comes with it \\ \hline
2057 \texttt{kind} & \texttt{<box kind>} &
2058 Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline
2063 \texttt{unload} & \texttt{<package-name>}&
2064 Unloads the package \texttt{package-name}.
2065 The package must have been previously loaded.
2066 No box of a type defined in this package must still exist.
2069 \texttt{message} & \texttt{<category>} \texttt{<level>} &
2070 Sets the level of verbosity of \bbi for the category of messages
2071 \texttt{category} to \texttt{level}.
2072 %See \ref{verbosity}.
2075 \texttt{config} & - & Displays the Configuration parameters\\ \hline
2077 \texttt{reset} & - & Deletes all boxes and unloads all packages so
2078 that \bbi gets back to its initial state \\ \hline
2080 \texttt{quit} & - & Exits the interpreter\\ \hline
2084 % ==========================================
2090 % ==========================================
2092 \caption{\label{bbi-reference-complex-box}
2093 \bbi complex black box definition related commands.}
2095 \begin{tabular}{|lcm{6cm}|}
2097 Command & Parameters & Effect \\ \hline
2100 \texttt{define} & \texttt{<box-type>} &
2101 Starts the definition of a complex black box of type
2102 \texttt{box-type}\\ \hline
2104 \texttt{endefine} & - &
2105 Ends the definition of a complex black box type\\ \hline
2107 \texttt{author} & \texttt{<string>} &
2108 Sets the author(s) of the complex black box currently being defined \\ \hline
2110 \texttt{description} & \texttt{<string>} &
2111 Sets the description of the complex black box currently being defined
2114 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} &
2115 Defines a new input for the current complex black box,
2116 named \texttt{name}.
2117 It is defined as corresponding to
2118 the input \texttt{input} of the box \texttt{box}.
2120 \texttt{<help>} is the help string for the new input.
2121 The box \texttt{box} must already have been created in the complex box
2122 and of course have an input named \texttt{input}.
2125 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} &
2126 Defines a new output for the current complex black box,
2127 named \texttt{name}.
2128 It is defined as corresponding to
2129 the output \texttt{output} of the box \texttt{box}.
2130 \texttt{<help>} is the help string for the new output.
2131 The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}.
2137 % ==========================================
2142 % ==========================================
2143 \vspace{0.5cm}\hrule
2144 \section{Using black boxes in \CPP programs}
2146 % ==========================================
2155 %\section{Conclusion}