1 % ==========================================
2 \documentclass[11pt,final,a4paper]{article}
19 Laurent Guigues, Jean-Pierre Roux
22 % ==========================================
24 % ==========================================
30 % ==========================================
32 % ==========================================
34 % ==========================================
36 \section{What is {\bf bbtk} ?}
37 % ==========================================
38 \BBTK(\bbtkns) is a set of tools
39 (\CPP libraries and executables)
40 providing a \CPP framework for the definition
41 of elementary processing \emph{units}, called {\bf black boxes},
42 and the definition and execution of processing \emph{chains}
43 made up of these black boxes.
45 % ==========================================
46 \subsection{The black box philosophy}
47 % ==========================================
48 \href{http://en.wikipedia.org/wiki/Black_box_\%28disambiguation\%29}{Wikipedia}
49 defines a {\bf black box} as
50 \emph{``any component in a system in which only the input and output
51 characteristics are of interest, without regard to its internal mechanism
53 I would add something very important to this definition :
54 not only the inputs and outputs are of interest but also
55 \emph{what the box does} !
56 Hence, I would say that a black box is any \emph{\bf documented}
57 component of a system, letting the user know
58 \emph{\bf what} the box is supposed to do and
59 \emph{\bf how to use it}
60 but not \emph{\bf how it does it}.
62 \BBTK provides a systematic framework
63 to encapsulate (or ``wrap'') any
64 existing \texttt{C} or \CPP processing code into an object
65 (a black box) having a {\bf generic symbolic interface}, where
68 \item{\bf generic} means that the interface is \emph{the same}
69 for all boxes. Hence one does not need to know which particular
70 method allows, say, to set a particular input or
71 get a particular output of the box.
72 One can use a black box in a purely abstract way.
73 \item{\bf symbolic} means that a particular
74 input or output is referenced by a 'name', that is by a symbol
75 which identifies the input or output.
76 It also means that symbolic information (text!) is
77 attached to a box: description of the box, author,
78 description of its inputs and outputs, etc.
81 (in fact, genericity is achieved because the interface is symbolic.
82 I let you think about this\dots)
84 Of course, symbolic data attached to box can be
85 {\bf queried}: what are the inputs/outputs of the box ?
86 what are their type ? their description ? etc.
87 This allows {\bf automatic documentation} of boxes.
89 The abstract definition of black boxes is the most basic
90 aspect of \BBTK architecture.
91 Another key aspect is the groupement of black boxes into
92 so called {\bf packages},
93 which are \emph{dynamic libraries} which can also
94 be queried, in particular about the boxes they provide.
95 The package structure then offers a mechanism which
96 is like a \emph{'plug-in'} mechanism.
97 \BBTK provides the methods to load a package at run-time,
98 and create instances of the boxes it contains.
100 These two mechanisms (black boxes and packages)
101 then gives the way to:
104 \item The definition of an {\bf interpreted language},
105 which allows to manipulate packages and boxes very easily in symbolic way.
106 \BBTK provides one: \bbi (the Black Box Interpreter).
107 \item {\bf Automatic documentation} of existing packages.
108 \texttt{html} documentation of packages is proposed by
112 Finally, these different components allow {\bf efficient}:
115 \item {\bf capitalization and reuse} of existing processing units,
116 including {\bf documentation}
117 \item {\bf testing, prototyping} in a very simple script language
118 \item {\bf inter-operability} between atomic processings which
119 have been written by different persons, using different libraries, etc.
122 % ==========================================
123 \subsection{\bbtk components}
124 % ==========================================
127 \item A \CPP {\bf\emph{library}} - called \bbtk - which defines a framework
128 (abstract classes) to develop black boxes and to store them into
129 dynamic libraries, called black box \emph{packages}.
130 \item Different {\bf\emph{black box packages}}:
132 \item {\bf\emph{std}}: the 'standard' package including basic useful boxes.
133 \item {\bf\emph{wx}}: basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library).
134 \item {\bf\emph{itk}}: the basic image processing package, based on the \texttt{itk} library.
135 \item {\bf\emph{vtk}}: the basic image and surfaces processing package, based on the \texttt{vtk} library.
136 \item {\bf\emph{wxvtk}}: widget boxes based on the \texttt{vtk} library.
137 \item {\bf\emph{itkvtk}}: boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally.
139 \item A {\bf\emph{Developement environment}}, called bbStudio, which provides
141 \item An online {\bf\emph{script editor}}, called bbed
142 \item A powerfull {\bf\emph{Help environment}}, called bbhelp
145 \item Online documentation scaning
146 \item Retreiving boxes on various criterions
147 \item Checking Demo and examples
150 \item An {\bf\emph{interpreter}}, called \bbi, which allows to
151 load black box packages and to define and execute
152 processing chains by connecting various black boxes of the already loaded packages.
153 \item {\bf\emph{Utilities}}:
155 \item \bbfy generates the \CPP code of a black box from a
156 description file written in \texttt{xml}.
157 %\item \bbdoc generates the html documentation of a black box package
158 %(author, description, description of its black boxes:
159 %author, description, inputs, outputs, and so on).
160 \item \bbCreatePackage allows to create the basic file architecture
161 to start the development of a new black box package.
165 The general architecture of \BBTK
166 is shown in figure \ref{bb-architecture}.
169 \caption{\label{bb-architecture}\BBTK architecture}
171 \includegraphics[width=0.6\textwidth]{bb-architecture.png}
175 % ==========================================
176 \subsection{Structure of this guide}
177 % ==========================================
179 This guide is divided into three parts.
181 The first part (\ref{bbStudio}) is a brief presentation of the very intuitive Development
182 environment, \bbStudio.
184 The second part (\ref{bb0})
185 is devoted to the use of the \emph{black box interpreter} \bbi.
186 This is the highest level of use of the toolkit, which
187 allows to create and execute processing chains by connecting
188 black boxes of existing packages.
190 The third part (\ref{cpp}) explains how to
191 use the black box toolkit framework in \CPP code,
192 typically to develop large applications which
193 involve complex graphical interfaces.
196 % ==========================================
197 % ==========================================
198 % ==========================================
199 % ==========================================
200 % ==========================================
201 % ==========================================
203 \section{The Development environment (bbStudio)}
206 Just run it, typing in a console \bbStudio
207 or clicking on its icon or its menu entry.
208 At start, \bbStudio opens with the 'Help' tab selected.
209 You'll get something like in figure
210 \ref{bbi-fig-bbStudio-gui}
211 (the exact appearance of \bbStudio is system and \bbtk version dependent)
214 \caption{\label{bbi-fig-bbStudio-gui}The bbStudio Development environment interface}
216 \includegraphics[width=0.7\textwidth]{bbStudioMainPage.png}
220 The 'Help' tab of \bbStudio is used to browse the html help of \BBTK.
221 All the entries of the starting page are self-explanatory :
224 \item {\bf\emph{Wiki}}: Direct link to the bbtk Wiki (intranet only, right now, www
226 \item {\bf\emph{Demo}}: Link to some demonstrations.
227 \item {\bf\emph{User's Guide}}: Step to step How-to for user who just wants to create his own
228 application, just using already existing boxes.
229 \item {\bf\emph{Package Developper's Guide}}: Step to step How-to for user who wants to create his own
231 \item {\bf\emph{Developper's Guide}}: Sorry, not yet written.
232 \item {\bf\emph{Reference Manual}}: Sorry, not yet written.
233 \item {\bf\emph{Doxygen Documentation}}: Doxygen source browser.
234 \item {\bf\emph{Boxes}}: Box retrieving on various criterions :
236 \item {\bf\emph{By name}}
237 \item {\bf\emph{By package}} (see table : \ref{bbi-list_of_packages})
238 \item {\bf\emph{By category}} (see table :\ref{categories})
239 \item {\bf\emph{Adaptors}} Used internaly to perform type conversions (not end user intended)
244 % ==========================================
246 \caption{\label{bbi-list_of_packages} List of bbtk supplied packages.}
248 \begin{tabular}{|lp{10cm}|}
250 Package & What it's used for \\ \hline
251 \texttt{std} & : the 'standard' package including basic useful boxes \\ \hline
252 \texttt{wx} & : basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library \\ \hline
253 \texttt{itk} & : the basic image processing package, based on the \texttt{itk} library. (without description)\\ \hline
254 \texttt{vtk} & : Prints help on the package \texttt{package-name} and its boxes (with brief description). The package must have been previously loaded\\ \hline
255 \texttt{wxvtk} & : widget boxes based on the \texttt{vtk} library.\\ \hline
256 \texttt{itkvtk} & : boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally.\\ \hline
260 % ==========================================
265 % ==========================================
267 \caption{\label{categories} \texttt{Black Box} categories}
269 \begin{tabular}{|lp{10cm}|}
271 \texttt{Category name} & : Meaning \\ \hline \\ \hline
272 \texttt{adaptor} & : Adaptor box \\ \hline
273 \texttt{application} & : Final application, end user intended \\ \hline
274 \texttt{atomic box} & : System category.
275 Automatically assigned to Atomic Black Boxes (c++ defined) \\ \hline
276 \texttt{complex box} & : System category.
277 Automatically assigned to Complex Black Boxes (script defined) \\ \hline
278 \texttt{command line} & : Script which defines a command line application \\
279 & :(no embedded GUI, but command line imput parameters) \\ \hline
280 \texttt{demo} & : Demonstration \\ \hline
281 \texttt{devel} & : Developer tool (bbCreatePackage.bbs, ...) \\ \hline
282 \texttt{dicom} & : DICOM aware box \\ \hline
283 \texttt{example} & : Example script showing a box use-case \\ \hline
284 \texttt{filter} & : Image processing box \\ \hline
285 \texttt{image} & : Image processing related box \\ \hline
286 \texttt{interaction} & : \\ \hline
287 \texttt{math} & : Mathematical operations \\ \hline
288 \texttt{mesh} & : Mesh processing related box \\ \hline
289 \texttt{misc} & : A box that cannot be put in other category ! \\ \hline
290 \texttt{read/write} & : Box that read or write data from or to disk \\ \hline
291 \texttt{viewer} & : Box which displays some data \\ \hline
292 \texttt{widget} & : Piece of graphical interface \\ \hline
294 \texttt{3D object creator} & : Sophisticated 3D widget \\ \hline
295 \texttt{toolsbbtk} & : Component of bbStudio \\ \hline
299 % ==========================================
302 \caption{\label{kinds} \texttt{Black Box} kinds}
304 \begin{tabular}{|ll|}
306 \texttt{Kind name} & : Meaning \\ \hline \\ \hline
307 \texttt{ADAPTOR} & : Adaptor Box \\ \hline
308 \texttt{DEFAULT\_ADAPTOR} & : \\ \hline
309 \texttt{WIDGET\_ADAPTOR} & : \\ \hline
310 \texttt{DEFAULT\_WIDGET\_ADAPTOR} & : \\ \hline
311 \texttt{GUI} & : \\ \hline
312 \texttt{DEFAULT\_GUI} & : \\ \hline
313 \texttt{ALL} & : If kind='ALL' then sets the level for all kinds \\ \hline
319 % ==========================================
320 % ==========================================
321 % ==========================================
322 % ==========================================
323 % ==========================================
324 % ==========================================
326 \section{The script manager}
328 % ==========================================
330 Call it with the bookmark \emph{File}.
334 \caption{\label{bbi-fig-bbStudio-file0}The bbStudio script manager}
336 \includegraphics[width=0.7\textwidth]{bbFile0.png}
340 Using the lower tool bar, you can :
343 \caption{\label{lowertoolbar}The lower tool bar}
345 \includegraphics[width=0.7\textwidth]{lowertoolbar.png}
351 \item {\bf\emph{new}}: Create a newfile to hold a script
352 \item {\bf\emph{open}}: Open a already existing file holding a script
353 \item {\bf\emph{close}}: Close a file holding a script
354 \item {\bf\emph{save}}: Save he current file (if modified)
355 \item {\bf\emph{save as}}: Save he current file under a different name
356 \item {\bf\emph{execute}}: Execute the script you just loaded/modified/written
360 The script language is very simple.
361 Everything is done with only a very few commands (See table \ref{bbi-reference-box}).
362 The philosophy of this part is also very simple:
363 it introduces the \bbi commands using examples,
364 starting with the most simple commands.
365 The first section of this part
366 (\ref{bbi-getting-started})
367 is designed like a tutorial,
368 which progressively introduces all the concepts of \bbi.
369 We suggest you run \bbi and follow the examples,
370 to see how it works in practice.
371 At the end of this section,
372 you will be able to use \bbi and write
373 own black box processing scripts.
376 the section \ref{bbi-more-on}
377 (called \emph{more on...})
378 goes deeper into various issues of \bbi.
379 Read it at your convenience,
380 either linearly to learn more about \bbi,
381 or in random order to get an answer
382 to a particular question.
384 Finally, the section \ref{bbi-reference}
385 summarizes all the commands of \bbi,
386 their parameters and effect.
387 Use it as a reference.
389 % ==========================================
390 \subsection{Getting started}
391 \label{bbi-getting-started}
392 % ==========================================
393 \subsubsection{Creating and executing black boxes}
394 % ==========================================
396 To learn interactivelly the script language features, you can use the black box
398 open a console and type \texttt{bbi}
399 or double click on the application icon.
400 You get a window which looks like the one in figure
401 \ref{bbi-fig-bbi-gui}
402 (the exact appearance of \bbi is system and \bbtk version dependent)
403 \footnote{If you compiled \bbtk without \wx then \bbi does not have a
404 graphical interface but a simple prompt}.
407 \caption{\label{bbi-fig-bbi-gui}The black box interpreter interface}
409 \includegraphics[width=0.7\textwidth]{bbi-gui0.png}
413 The 'Command' tab is subdivided into two parts :
414 one single line zone at the bottom in which you can enter your commands and
415 one multiple line zone in which \bbi prints out the result of your commands.
416 , just using already existing boxes.
418 Try typing in the input zone (in this manual,
419 the commands entered by the user will be preceded by a prompt \textgreater) :
424 you get the list of the commands of the interpreter:
457 To get help on a particular command type \texttt{help <command-name>},
467 Quits the program (during script execution it stops the complete execution)
470 The \texttt{help} command has multiple usages.
471 It is used to get help on almost anything in \bbi !
472 Type \texttt{'help help'} to get help on the \texttt{help} command itself:
477 (2) help <command name>
478 (3) help packages [all]
479 (4) help <package name> [all]
480 (5) help <black box type>
481 (6) help <black box name>
483 (1) Lists all available commands;
484 (2) Prints help on a particular command;
485 (3) Lists the packages loaded and their black boxes.
486 Add 'all' to list adaptors;
487 (4) Prints short help on the black boxes of a package.
488 Add 'all' to include adaptors;
489 (5) Prints full help on a black box type;
490 (6) Prints information on the inputs, outputs and connections of a black box instance.
493 At start \bbi does not know any black box.
494 If you type \texttt{'help packages'}, which is
495 the third form of the \texttt{help} command, you get:
502 which means that \bbi only knows one package
503 (library of black boxes) called \texttt{user}
504 and which contains a black box called \texttt{workspace}.
505 The \texttt{user} package is an internal package to \bbi,
506 which stores user-defined black box types.
507 At start, it already contains
508 one box, called \texttt{workspace}.
509 \texttt{workspace} is a special type of black box,
510 called complex black box, whose purpose is
511 to store other black boxes.
512 Any black box you create in \bbi is stored
513 in \texttt{workspace}
514 (this will be explained in details in sections
515 \ref{bbi-writing-scripts} and
516 \ref{bbi-more-on-complex-black-boxes}).
518 If you type \texttt{'help workspace'}, you get:
521 Complex Black Box <user::workspace>
524 Category(s) : complex box;
530 In the text displayed,
531 the \texttt{user::} prepended to the name \texttt{workspace}
532 means that the box \texttt{workspace}
533 belongs to the \texttt{user} package.
534 Then comes a description and three lines which
535 tell that \texttt{workspace} does not have any input
536 nor output nor boxes yet.
538 In order to let \bbi know of some black boxes,
539 you must load another package.
540 The \texttt{std} package is the ``standard'' package,
541 which contains basic useful black boxes.
553 you get something like:
568 Now \bbi knows the package \texttt{std} and the black boxes it provides,
569 such as the \texttt{'Add'} box, the \texttt{'ConcatStrings'}. Remark that the
570 content of \texttt{std} may vary from one version to another
571 as new black boxes might be added to it.
581 By : laurent.guigues@creatis.insa-lyon.fr
582 Categories : atomic box;math;
584 'BoxExecute' <bbtk::Void> [signal] : Any signal received by this input executes the box
585 'BoxProcessMode' <String> [] : Sets the processing mode of the box (Pipeline | Always | Reactive)
586 'In1' <Double> [] : First number to add
587 'In2' <Double> [] : Second number to add
589 'BoxChange' <bbtk::Void> [signal] : Signals modifications of the box
590 'Out' <Double> [] : Result
594 the \texttt{std::} prepended to the name \texttt{Add}
595 means that the box \texttt{Add}
596 belongs to the \texttt{std} package.
597 Then comes a description
598 (the one which was provided by the author of the box),
599 the author(s) of the box (usually e-mail adress(es)) and
600 the categories to which the box belong.
601 Finally comes the lists of inputs and outputs of the box.
602 For each input or output, \bbi provides
603 its \emph{name} (between quotes, e.g. \texttt{'ProcessMode'}),
604 its \emph{type} (between \texttt{<>}, e.g. \texttt{<Int>})
606 Remark that the box \texttt{Add} is not a 'complex' black box
607 but an 'atomic' box, hence its help does not
608 mention any information concerning possible internal boxes.
610 You can create an \emph{instance} of an \texttt{Add} box by
611 the command \texttt{new}:
616 The \texttt{'a'} at the end is the \emph{name} of the instance,
617 which will be used to reference it later.
618 It is important to distinguish a box \emph{type}
619 and an \emph{instance} of a box type.
620 The \texttt{Add} box of the package \texttt{std} is actually
621 a \emph{box type} , like \texttt{int} is a data type
622 in \texttt{C} langage. The \texttt{new} command allows to create
623 an instance of a box type, exactly like \texttt{int i;} in
624 a \texttt{C} code, it declares a variable of type \texttt{int} whose
626 Of course, like in \texttt{C} Language, you can declare multiple boxes of the
629 After the creation of the box \texttt{a}, type:
636 Complex Black Box <user::workspace>
639 Category(s) : complex box;
646 which means that \bbi workspace now contains a black box named \texttt{a},
647 of type \texttt{std::Add}.
649 Now look back at the help on \texttt{Add} boxes:
650 you can see that this type of box has two inputs,
651 with name \texttt{In1} and \texttt{In2},
652 and an output, with name \texttt{Out}.
654 You can set the input \texttt{In1}
655 of the \texttt{Add} box \texttt{a} to the value $1$
661 Similarly, setting the input \texttt{In2} of \texttt{a} to the value $2$
667 And you print the output \texttt{Out} of the box \texttt{a} with:
669 > print "result=$a.Out$"
673 In the string passed to the \texttt{print} command,
674 each substring enclosed between a couple of \$ is considered
675 as the name of an output of a box.
676 To process this special substrings, \bbi does:
678 \item Processes the box if needed (see below)
679 \item Converts the output of the box to a string if possible
681 \item Substitutes the result in the string to print
682 \item postpone an implicit 'new line' character to the string
687 Box processing is needed if:
690 \item at least input has changed since last processing or
691 \item the input \texttt{'BoxProcessMode'} of the box is set to
692 \texttt{'Always'}, which forces box reprocessing.
695 Note that all boxes have the input \texttt{'BoxProcessMode'}.
697 Another way to process the box \texttt{a} is to issue the command:
702 however this command does not display anything (except if the
703 box itself displays something in its processing).
704 It just processes the box if needed.
705 This command is used to execute boxes that do not have any output,
706 such as boxes that write something to a file or, display a
707 graphical interface, and so on.
715 % ==========================================
720 \item The \texttt{include} command allows to load a package, and the complex black boxes that come with it..
721 \item \texttt{help} gives help on:
723 \item Available commands if you just type \texttt{help}.
724 \item A particular command if you type \texttt{help <command-name>}.
725 \item All available packages and their boxes (without description) if you type \texttt{help packages}.
726 \item A particular package and its boxes (with brief description) if you type \texttt{help <package-name>}.
727 \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}).
729 %\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).
730 \item \texttt{new} : creates an instance of a black box.
731 \item \texttt{set} : sets the value of an input of a black box.
732 \item In all \bbi, to reference the input called \texttt{i}
733 of a black box called \texttt{b} you must type \texttt{'b.i'}.
734 The same syntax holds for outputs.
735 \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
736 implicit trailing 'new line character' is added at the final string.
737 \item \texttt{exec} : runs the process of a box if needed.
738 \item \texttt{quit} : quits \bbi.
743 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.
744 Wou'll get something like in figure \ref{bbCommandPlusHelp} :
747 \caption{\label{bbCommandPlusHelp}
748 An other way to run the command interpreter}
750 \includegraphics[width=0.5\textwidth]{bbCommandPlusHelp.png}
753 % ==========================================
755 % ==========================================
756 \subsubsection{Connecting black boxes}
757 \label{bbi-connecting-black-boxes}
758 % ==========================================
760 \BBTK allows to create
761 and execute processing chains,
762 also called \emph{pipelines},
763 by connecting black boxes.
764 This section explains how to do it with examples.
765 Read section \ref{bbi-more-on-pipeline-processing} to get
766 more information on pipeline processing.
768 First start \bbi and load the package \texttt{std}:
773 Assume you want to compute $1+2+3$. You can do it by
774 chaining two \texttt{Add} boxes, as shown in figure
775 \ref{bbi-fig-connecting-black-boxes-1}.
778 \caption{\label{bbi-fig-connecting-black-boxes-1}
779 A simple pipeline which adds 3 numbers}
781 \includegraphics[width=0.5\textwidth]{1plus2plus3.png}
786 The \bbi instructions to create and execute this pipeline are:
790 > connect a.Out b.In1
797 You will see the (very expected) result :
802 The first three commands build the pipeline,
803 the next three set \texttt{a} and \texttt{b} black boxes inputs and the last one
804 prints \texttt{b} black boxe output (the pipeline is executed before printing, because the interpretor 'knows' he box \texttt{b},
805 whose output is requested, is not up to date.
807 The command \texttt{'connect a.Out b.In1'} ``plugs'' the output
808 \texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the
810 Once the boxes connected, the processing of the two boxes are chained:
811 getting the output of \texttt{b} requires getting its inputs,
812 hence getting the output of \texttt{a} which is connected to it.
813 This pipeline mechanism can recurse into arbitrary long
814 chains of boxes (see \ref{bbi-more-on-pipeline-processing}
818 Lets' consider an other, more image oriented, example :
826 > new FileSelector fileDialog
827 > new ImageReader reader
829 > new Viewer2D viewer
831 > connect fileDialog.Out reader.In
832 > connect reader.Out viewer.In
833 > connect slider.Out viewer.Slice
834 > connect slider.BoxChange viewer.BoxExecute
839 Some explainations : the \texttt{include} instructions load the necessary packages. \\
841 \texttt{new FileSelector} will pop a File Selector, at run time, that will out the user chosen file name. \\
842 \texttt{new Slider} will pop a Slider, at run time, that will out an integer, used later as a slice number.\\
843 \texttt{new ImageReader} will read any itk readable file, whose name is passed as a std::string, and return a itk::ImagePointer.
844 \texttt{new Viewer2D} display a plane, whose number id specified by an integer.\\
846 \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).\\
847 \texttt{connect reader.Out viewer.In} plugs the output of the reader (an itk::ImagePointer) to the input of the Viewer (a vtkImageData *)\\
848 \texttt{connect slider.Out viewer.Slice} plugs the output of the slider (an int) to an other output (named Slide) of the viewer.\\
849 \texttt{connect slider.BoxChange viewer.BoxExecute} says the viewer it must re process itself any time the slider is modified.\\
851 \texttt{exec viewer} processes the viewer.
854 This would correspond to the graph in figure \ref{bbi-simplegraph}
858 \caption{\label{bbi-simplegraph}(Very) simple Graph of a (very) simple pipeline}
860 \includegraphics[width=0.8\textwidth]{bbi-simplegraph.png}
864 Of course, to be able to connect two boxes,
865 the output and the input must be compatibles.
866 You can always connect an output to an input of the \emph{same} type,
867 but you can do more, thanks to particular (hidden) black boxes called {\bf adaptors}.
869 An adaptor is a black box which has at least one input, called \texttt{In},
870 and at least one ouput called \texttt{Out} and whose role is to convert
871 a data of the type of \texttt{In}
872 into a data of the type of \texttt{Out} (other inputs or outputs may serve
873 to parameter the adaptor or retreive other usefull information).
875 In \bbi, if you type:
882 Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
883 Basic useful black boxes
885 Add : Adds its inputs
886 Cast<double,float> [DA] : Casts a double into a float
887 Cast<double,int> [DA] : Casts a double into a int
889 Convert<unsigned int,string> [DA] : Converts a unsigned int into a s...
890 Convert<unsigned short,string> [DA] : Converts a unsigned short into a...
891 Print : Prints its input to standard out...
895 The \texttt{Cast<?,?>} and \texttt{Convert<?,?>} boxes are \emph{default adaptors}, which is signaled by the tag \texttt{[DA]} before their descriptions.
897 Once you have loaded the package \texttt{std}, you can
898 plug an output of type \texttt{char} into an input of type \texttt{double}.
899 When \bbi encounters the \texttt{connect} command,
900 it looks for an adequate \emph{adaptor} in the loaded packages.
901 In our case, as the package \texttt{std} provides the
902 \texttt{Cast<char,double>} adaptor, \bbi automatically creates an
903 instance of this adaptor and place it \emph{between}
904 the output and the input you want to connect
905 (however this adaptor is hidden to you,
906 it is embedded into the created connection and does not appear
907 as an existing black box).
908 When the pipeline is processed the
909 adaptor converts the output data into the required input type,
910 in a totally transparent way.
911 In our example, the \texttt{Cast<char,double>} adaptor
912 would simply cast the value of the \texttt{char} into a \texttt{double},
913 however arbitrarily complex type conversion can be done.
916 if two adaptors with the same input and output types exist
917 in the packages loaded,
918 which one is chosen by \bbi at connection ?
919 -> Role of default adaptors
921 Note that the \texttt{set} and \texttt{print} commands of \bbi
922 work with adaptors from \texttt{string} to the type of the input to set
923 or from the type of the output to print to \texttt{string}.
924 Hence in order to \texttt{set} or \texttt{print} values the adequate
925 adaptors must be available in the packages currently loaded.
927 % ==========================================
932 \item The \texttt{connect} command allows to connect two black boxes
933 \item You can connect two black boxes if (and only if):
935 \item The output and the input are of the same type, or
936 \item There is an adaptor black box in the packages loaded which
937 converts data of the output type into data of the input type
939 \item \texttt{help <package name>} does not display the adaptors of the package. To see them use: \texttt{help <package name> all}.
943 % ==========================================
945 % ==========================================
946 \subsubsection{Creating complex black boxes}
947 \label{bbi-complex-black-boxes}
948 % ==========================================
950 Remember the pipeline of figure
951 \ref{bbi-fig-connecting-black-boxes-1}, which
952 computed the sum of three doubles ?
953 You can view it as a whole and define
954 a new black box type, which will be a \emph{complex black box},
955 having three inputs and one output,
956 as shown in figure \ref{bbi-fig-complex-black-box-1}.
959 \caption{\label{bbi-fig-complex-black-box-1}
960 Creating the complex black box \texttt{Add3}}
962 \includegraphics[width=0.5\textwidth]{Add3.png}
966 The \bbi commands to define this complex black box are
976 > connect a.Out b.In1
979 > description "adds 3 doubles"
980 > input x a.In1 "first double to add"
981 > input y a.In2 "second double to add"
982 > input z b.In2 "third double to add"
983 > output result b.Out "output"
990 As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
992 The command \texttt{define} then starts the definition
993 of the complex box type, which will be called \texttt{Add3}.
995 The next three lines define the pipeline,
996 exactly in the same way than outside a complex box definition.
998 The commands \texttt{author}, \texttt{description}, \texttt{input}
999 and \texttt{output} are commands specific to complex boxes definition:
1001 \texttt{author} and \texttt{description} are used for the documentation
1002 of the new box. You can provide multiple \texttt{author} or
1003 \texttt{description} commands, the arguments of the commands will
1004 be concatenated to produce the final author and description strings.
1006 \texttt{input} and \texttt{output} are used to define the inputs and outputs
1007 of the new complex box.
1008 Their syntax is the same: for each new input/output you need to say
1009 to which internal input/output it corresponds and to provide
1010 a help string documenting the input/output.
1011 In our example, we define that the box \texttt{Add3} has
1012 three inputs: \texttt{x}, \texttt{y} and \texttt{z}.
1013 The input \texttt{x} corresponds to the input \texttt{In1} of the
1014 internal box \texttt{a}.
1015 In the same way, the external input \texttt{y}
1016 corresponds to the internal input \texttt{a.In2}, and
1017 the external input \texttt{In3} to \texttt{b.In2}.
1018 The only output of the new box is called \texttt{result}
1019 and corresponds to \texttt{b.Out}.
1020 The figure \ref{bbi-fig-complex-black-box-1}
1021 illustrates the external to internal
1022 input/output correspondence.
1024 Finally, the \texttt{endefine} command ends the definition of the
1027 After this definition, if you ask for help
1028 on packages, you get:
1039 The \texttt{user} package now contains a new black box type, called
1040 \texttt{Add3}. If you ask for help on this type of box, you get:
1043 Complex Black Box <user::Add3>
1047 'x' <double>: first double to add
1048 'y' <double>: second double to add
1049 'z' <double>: third double to add
1051 'result' <double>: output
1057 and you can use it like any other box, for example type:
1069 As a side note, we can say that, for consistency reasons, it would have been better to name
1070 \texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3},
1071 since all the 'natural entry' of a box is named \texttt{In}, or\texttt{In}x if there are more than one 'natural
1074 % ==========================================
1079 \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.
1080 Inside a \texttt{define/endefine} block:
1082 \item The \texttt{author} and \texttt{description} commands allow to document the new type of box
1083 \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
1084 of internal boxes they correspond.
1088 % ==========================================
1090 % ==========================================
1091 \subsubsection{Writing scripts}
1092 \label{bbi-writing-scripts}
1093 % ==========================================
1095 Once you have defined a new type of complex box, you
1096 may like to reuse it. To do this, you can simply
1097 write the \bbi commands defining the new box
1098 into a text file and afterwards include that file in \bbi.
1099 Doing this, you start writing \bbi scripts.
1100 The conventionnal extension for such scripts is \texttt{bbs}
1102 For consistency reasons, you are requested to prepend \texttt{bb} to the name.
1104 For example, the \texttt{Add3} complex box we previously worked on
1105 can be defined in the \texttt{bbAdd3.bbs} file:
1107 \begin{file}{bbAdd3.bbs}
1109 # Defines the Add3 black box which adds 3 doubles
1115 description "adds 3 doubles"
1121 input x a.In1 "first double to add
1122 input y a.In2 "second double to add
1123 input z b.In2 "third double to add"
1125 output result b.Out "output"
1130 Lines starting with a \texttt{\#} character are ignored, they
1131 are considered as comments by \bbi.
1132 To use this file in \bbi, use the \texttt{include} command:
1135 > include bbAdd3.bbs
1137 Complex Black Box <user::Add3>
1141 'x' <double>: first double to add
1142 'y' <double>: second double to add
1143 'z' <double>: third double to add
1145 'result' <double>: output
1153 If the file has the \texttt{bbs} extension, you can ommit it and just type:
1158 Of course, you can include script files in other script files,
1159 like in the following example:
1161 \begin{file}{bbAdd4.bbs}
1163 # Defines the Add4 black box which adds 4 doubles
1168 description "adds 4 doubles"
1172 input In1 a.In1 "first double to add
1173 input In2 a.In2 "second double to add
1174 input In3 a.In3 "third double to add"
1175 input In4 b.In2 "fourth double to add"
1176 output Out b.Out "output"
1181 % ==========================================
1183 \paragraph{Naming Conventions}
1187 % ==========================================
1191 For consistency reasons, you are requested to prepend \texttt{bb}, and postpone an extention \texttt{.bbs},
1192 to the names of the files that hold a \texttt{complex black box} definition.
1194 For example, the \texttt{Add3} complex box we previously worked on
1195 can be defined in the \texttt{bbAdd3.bbs} file.
1199 % ==========================================
1205 \item The \texttt{include} command allows to include a script file in \bbi.
1206 \item Lines starting with a \texttt{\#} or with a \texttt{\//} are treated as comments in \bbi scripts.
1207 \item Lines between a line starting with a \texttt{\//*} an a line starting with a \texttt{*\//} are treated as comments in \bbi scripts.
1211 % ==========================================
1213 % ==========================================
1214 \subsubsection{Creating command line applications}
1215 \label{bbi-command-line-app}
1216 % ==========================================
1218 Now that you now how to create complex black boxes
1219 (with \texttt{define/endefine}), think
1220 back to the \texttt{workspace} object.
1221 Remember that it is also
1222 a \texttt{complex black box}.
1223 In fact what you are doing when you type \bbi commands
1224 outside a \texttt{define/endefine} block
1225 is to progressively define the \texttt{workspace}
1227 You can think of it like if at start
1228 \bbi was issuing a command \texttt{'define workspace'}
1229 and then letting you define the interior of the box
1232 Remember that the command \texttt{inputs}
1233 allows to define an input of a complex box.
1234 Now, if you use the command \texttt{input}
1235 outside a \texttt{define/endefine} block then
1236 it defines an input of the \texttt{workspace} box,
1237 that is an input of the \emph{main program}.
1238 This input will then be connected to the
1239 parameters that the user passes to the command line.
1241 For example, consider the script:
1243 \begin{file}{add.bbs}
1247 input x a.In1 "first number to add"
1248 input y a.In2 "second number to add"
1253 The third and fourth lines define two inputs \texttt{x}
1254 and \texttt{y}. When you execute this script,
1255 you can pass these two arguments on the command line,
1263 You can also invoke \bbi the option \texttt{-h},
1264 which gives help on the \texttt{workspace} box:
1271 'x' <double>: first number to add
1272 'y' <double>: second number to add
1275 To get a better help, use the \texttt{description}
1276 and \texttt{author} commands:
1278 \begin{file}{add.bbs}
1280 description "Adds two numbers"
1281 author "foo@bar.com"
1284 input x a.In1 "first number to add"
1285 input y a.In2 "second number to add"
1290 Now if you ask for help on the \texttt{add} script, you get:
1297 'x' <double>: first number to add
1298 'y' <double>: second number to add
1301 Rather than getting the inputs of a script
1302 from the command line, you can ask \bbi to
1303 prompt the user for the values, using the \texttt{-t}
1308 x=[the program waits for user answer]2
1309 y=[the program waits for user answer]5
1313 If \bbi is compiled in graphical mode (with \wx),
1314 you can also use the \texttt{-g} commutator.
1315 \bbi then prompts the user in graphical mode,
1316 displaying a dialog box for each input,
1317 like in fig. \ref{bb-input-dialog-box}.
1320 \caption{\label{bb-input-dialog-box}Input dialog box}
1322 \includegraphics[width=0.6\textwidth]{enter-the-value-of-x.png}
1326 % ==========================================
1331 \item The \texttt{input}, \texttt{description} and \texttt{author} commands,
1332 when they are used outside a \texttt{define/endefine} block allow
1333 to define the inputs, description and author of the main program.
1334 \item Inputs of the main program can be passed on the command line
1335 using the syntax \texttt{<input-name>=<value>}.
1336 No white space is allowed, if the value or the input name
1337 contains white spaces, enclose them
1338 between double quotes, e.g. \texttt{"parameter with white spaces = gnu's not unix"}.
1339 \item The \texttt{-h} option of \bbi prints help on the main program.
1340 \item The \texttt{-t} option of \bbi orders the program to prompt for its inputs in text mode.
1341 \item The \texttt{-g} option of \bbi orders the program to prompt for its inputs in graphical mode.
1344 % ==========================================
1346 % ==========================================
1347 \subsubsection{Using graphical interface boxes (widget boxes)}
1349 % ==========================================
1351 % ==========================================
1352 \subsubsection{Overwiew}
1353 \label{bbi-overview}
1354 % ==========================================
1356 If \bbi is compiled in graphical mode
1357 (option \texttt{BUILD\_bbi\_GRAPHICAL} of \cmake, requires \wx),
1358 then you can use special black boxes which are
1359 graphical interface components (widgets).
1360 Basic components are provided in the package \texttt{wx},
1361 such as buttons, sliders, file open/save dialogs, etc.
1363 As first example, type the following commands in \bbi:
1370 When you type \texttt{enter} after the last line,
1371 a window pops up in which you can entrer a text.
1372 When you close the window, the text you entered is printed by
1373 the \texttt{print} command.
1375 Type \texttt{help wx}, you get something like:
1377 Package wx v1.0.0- info-dev@creatis.insa-lyon.fr
1378 Basic graphical interface elements (sliders, buttons ...) based on wxWidgets
1380 ColourSelector : Colour Selector dialog (bbfication of wxColourSele...
1381 ColourSelectorButton : A button which displays a colour picker dialog whe...
1382 CommandButton : Button which executes bbi commands
1383 DirectorySelector : Pops up a directory selection dialog (wxDirDialog)
1384 FileSelector : Pops up a file selection dialog for reading or sav...
1385 InputText : A zone in which the user can enter a text (wxTextC...
1386 LayoutLine : LayoutLine widget (wxBoxSizer)
1387 LayoutSplit : Widget which splits a window in two fixed size par...
1388 LayoutTab : LayoutTab widget (wxNotebook)
1389 OutputText : Text zone to be inserted into a window (wxStaticTe...
1390 RadioButton : RadioButton group widget 0-9 entries
1391 Slider : Slider widget (wxSlider)
1394 You can reproduce the same experiment as above using a
1395 \texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{InputText}.
1396 See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
1398 There are two kinds of widgets: ``terminal'' widgets and ``container'' widgets.
1399 The \texttt{InputText}, \texttt{FileDialog} or \texttt{Slider} widgets
1400 are ``terminal'' widgets.
1401 ``container'' widgets are of another kind: they are designed to
1402 contain other widgets in order to build larger dialog boxes.
1403 For example, the \texttt{LayoutSplit} widget is a container which
1404 ``splits'' horizontally a window into two parts,
1405 each part including another widget.
1406 The size of the two parts can be adjusted by the user thanks
1409 The script \texttt{scripts/test/testSplit.bbs} demonstrate its use.
1410 Run it: it displays a window with two sliders.
1411 Move the sliders and close the window.
1412 The final positions of the sliders are printed out.
1413 Now edit the file to see how this is done:
1415 \begin{file}{scripts/test/testSplit.bbs}
1424 connect s1.Widget s.Widget1
1425 connect s2.Widget s.Widget2
1427 print s1=$s1.Out$\\n
1428 print s2=$s2.Out$\\n
1432 First, the two sliders \texttt{s1} and \texttt{s2} are created.
1433 A \texttt{LayoutSplit} box \texttt{s} is also created.
1434 The \texttt{connect} commands then ``includes'' the sliders in the
1435 split ``container''.
1436 The input \texttt{Widget} is common to all widget boxes:
1437 every widget can be inserted into another widget.
1438 The outputs \texttt{Widget1},\texttt{Widget2} are specific of \emph{container}
1440 (in \bbi type \texttt{help Slider}:
1441 you will see the output \texttt{Widget};
1442 type \texttt{help LayoutSplit}:
1443 you will see the inputs \texttt{Widget1} and \texttt{Widget2}
1444 and the output \texttt{Widget}).
1445 When you connect the \texttt{Widget} output of a container
1446 to the \texttt{Widget}i input of a widget,
1447 you order to include the widget in the container.
1448 Of course, the order of connection is important.
1449 In our case, the slider \texttt{s1} is included first,
1450 then the slider \texttt{s2}: \texttt{s1} will be placed
1451 on top of \texttt{s2} (the \texttt{LayoutSplit} box is
1452 implemented that way, but this is arbitrary choice).
1454 Right now, there are only \emph{three} container widgets in the \texttt{wx} package:
1455 the \texttt{LayoutSplit} widget we just described, the \texttt{LayoutLine} , and the \texttt{LayoutTab}
1458 The \texttt{LayoutLine} widget can have multiple children and
1459 divides its window into as much parts as children,
1460 each part of equal size.
1461 The orientation of the \texttt{LayoutSplit} or of the \texttt{LayoutLine} can be changed by the input \texttt{Orientation}.
1462 See the example \texttt{test/testSizer.bbs}.
1463 With only those two containers you can already create
1464 complex dialog boxes (of course containers can be nested, which
1465 leads to tree-like structures of widgets).
1466 See the script \texttt{bbtk/share/bbtk/bbs/wx/appli/ExampleLayoutSplit.bbs} for an example.
1468 The \texttt{LayoutTab} widget is based on the \texttt{wxNotebook.}
1470 One word about a special widget in the package \texttt{wx}:
1471 the \texttt{Button}... to be continued.
1473 % ==========================================
1474 \subsubsection{Deeper in the boxes}
1475 \label{bbi-deep-box}
1476 % ==========================================
1478 Any widget box has two mandatory Outputs :
1481 \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
1482 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.
1483 \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,
1484 further within the execution pipeline.
1487 Any widget box has two mandatory Inputs :
1489 \item {\bf\emph{BoxExecute}} : Any signal received by this input executes the box
1490 \item {\bf\emph{BoxProcessMode}} : Sets the processing mode of the box :
1492 \item {\bf\emph{Pipeline}} : bbUpdate() calls Process only if Status == MODIFIED (normal pipeline processing)
1493 \item {\bf\emph{Always}} : bbUpdate() always calls Process
1494 \item {\bf\emph{Reactive}} : bbSetModifiedStatus() calls bbUpdate()
1498 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} :
1500 \item {\bf\emph{WinHeight}} : Height of the window
1501 \item {\bf\emph{WinWidth}} : Width of the window
1502 \item {\bf\emph{WinTitle}} : Title of the window
1503 \item {\bf\emph{WinClose}} : Any received signal closes the window
1504 \item {\bf\emph{WinHide}} : Any received signal hides the window
1505 \item {\bf\emph{WinDialog}} : When set to 'true', creates a \emph{dialog window}, that blocks the pipeline until it is closed (\emph{modal})
1509 Any \emph{Layout box} (i.e. \emph{LayoutLine}, \emph{LayoutSplit} or \emph{LayoutTab}) has at one or more mandatory Inputs :
1511 \item {\bf\emph{Widget}}\texttt{i} : e.g. a \emph{LayoutSplit} box (Widget which splits a window in two fixed size parts)
1512 has two Input parameters \emph{Widget1} and \emph{Widget2}, used to embed the child windows.
1516 % ==========================================
1517 \subsection{More on ...}
1519 % ==========================================
1521 % ==========================================
1522 \subsubsection{Black box packages}
1523 \label{bbi-more-on-packages}
1524 % ==========================================
1526 There are various others user-intended packages :
1529 It contains some vtk based image processing filters :
1532 \paragraph{AppendPolyData}
1533 Appends one of more polygonal datasets into a single polygonal dataset
1535 \paragraph{ConeSource}
1538 \paragraph{ImageAnisotropicDiffusion3D}
1539 vtk\-Image\-Anisotropic\-Diffusion\-3D dif\-fuses a volume iteratively. \\
1540 The neighborhood of the diffusion is determined by the instance flags. \\
1541 if 'Faces' is on, the 6 voxels adjoined by faces are included in the neighborhood. \\
1542 If 'Edges' is on the 12 edge connected voxels are included, and if 'Corners' is on, the 8 corner connected voxels are included. \\
1543 'DiffusionFactor' determines how far a pixel value moves toward its neighbors, and is insensitive to the number of neighbors chosen.\\
1544 The diffusion is anisotropic because it only occurs when a gradient measure is below 'GradientThreshold'. \\
1545 Two gradient measures exist and are toggled by the 'GradientMagnitudeThreshold' flag. \\
1546 When 'GradientMagnitudeThreshold' is on, the magnitude of the gradient, computed by central differences, above 'DiffusionThreshold' a voxel is not
1548 The alternative measure examines each neighbor independently.\\
1549 The gradient between the voxel and the neighbor must be below the 'DiffusionThreshold' for diffusion to occur with THAT neighbor.\\
1551 - In : an image (vtkImageData*)\\
1552 - Diffusion : Difference threshold that stops the diffusion\\
1554 - Out : the isosurface mesh (vtkPolyData*)
1556 \paragraph{ImageCharacteristics}
1557 Exports objet sizes, and Spacings
1559 \paragraph{ImageDilateErode3D}
1561 Dilates one value and erodes another.\\
1562 vtkImageDilateErode3D will dilate one value and erode another. \\
1563 It uses an elliptical foot print, and only erodes/dilates on the boundary of the two values. \\
1564 The filter is restricted to the X, Y, and Z axes for now.\\
1565 It can degenerate to a 2 or 1 dimensional filter by setting the kernel size to 1 for a specific axis. \\
1566 (bbfication of vtkImageDilateErode3D) \\
1568 - In : an image (vtkImageData*)\\
1569 - DilateValue : The dilatation value\\
1570 - ErodeValue : The erosion value\\
1572 - Out : the isosurface mesh (vtkPolyData*)
1574 \paragraph{ImageGaussianSmooth}
1575 Performs a gaussian convolution of the input image\\
1577 - In : an image (vtkImageData*)\\
1578 - StdDevX : Standard deviation in X direction\\
1579 - StdDevY : Standard deviation in Y direction\\
1581 - Out : the isosurface mesh (vtkPolyData*)
1583 \paragraph{ImagePlanes}
1584 Creates three 3D planes with the input image mapped onto with which the user can interact; \\
1585 The output vtkImagePlaneWidget objects are to be inserted into a 3D scene (e.g. a Viewer3D)
1587 - In : an image (vtkImageData*)\\
1589 - PlaneX : the image plane in X direction (vtkImagePlaneWidget*)\\
1590 - PlaneY : the image plane in Y direction (vtkImagePlaneWidget*)\\
1591 - PlaneY : the image plane in Z direction (vtkImagePlaneWidget*)\\
1594 - Out : the isosurface mesh (vtkPolyData*)
1596 \paragraph{IsoSurfaceExtractor}
1597 Extracts an iso-surface of a 3D image and creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D)
1599 - In : an image (vtkImageData*)\\
1600 - Isovalue : the isosurface value (double)\\
1601 - Colour : Surface colour (vector of 3 doubles)
1603 - Out : the isosurface (vtkProp3D**)
1605 \paragraph{MarchingCubes}
1606 Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes)\\
1608 - In : an image (vtkImageData*)\\
1609 - Value : the isosurface value (double)\\
1611 - Out : the isosurface mesh (vtkPolyData*)
1613 \paragraph{MIPCreator}
1614 Creates a Maximum Intensity Projection (MIP) view of a 3D image.\\
1616 - In : an image (vtkImageData*)\\
1617 - Scale : the Gray scale scaling (float) \\
1618 - Shift : the Gray scale shift (float) \\
1620 - Out : The MIP object (vtkProp3D*) to be plugged into a 3D Viever
1622 \paragraph{MetaImageReader}
1623 Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader) \\
1625 - In : the name of the file to be read (std::string)
1627 - Out : The image (vtkImageData*)
1629 \paragraph{SegmentationConnectivity}
1630 Segmentation with min max threshold and connectivity \\
1632 - In : an image (vtkImageData*)\\
1633 - PositionXYZ : initial position (std::vector<int>) \\
1634 - ThresholdMinMax : min, max threshold values (std::vector<int>) \\
1636 - Out : The image (vtkImageData*)
1638 \paragraph{SphereSource}
1643 It contains some itk based image processing filters :
1645 \paragraph{BinaryThresholdImageFilter}
1646 Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter)
1648 \paragraph{DICOMSeriesFileNames}
1649 Reads a series from a DICOM directory as a 3D itk image
1651 \paragraph{ExtractImageFilter}
1652 Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)
1654 \paragraph{ImageProperties}
1655 Outputs different properties of an image (type, dimension, size, spacing, ...)
1657 \paragraph{ImageRegion}
1658 Creates a generic ImageRegion (bbtk::any) from two vectors providing the index and size of the region.
1659 The dimension D of the actual itk::ImageRegion created is the max of the sizes of Index and Size
1660 (the smallest vector is padded by zeros)
1662 \paragraph{ImageReader}
1663 Generic itk image reader
1665 \paragraph{ImageWriter}
1666 Generic itk image writer
1668 \paragraph{ImageSeriesReader}
1669 Generic itk image series reader.
1671 \paragraph{ResampleImageFilter}
1675 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
1677 Sorry nothing is done, right now for meshes.
1681 It contains two atomic black boxes.
1683 \paragraph{Viewer2D}
1685 - a \textless vtkImageData* \textgreater (In),\\
1686 - an Orientation(0:yz / 1:xz / 2:xy),\\
1687 - an initial slice number (Slice).\\
1689 - a \textless vtkRenderer* \textgreater (Renderer)
1691 \paragraph{Viewer3D}
1693 - up to 5 Input Actors (\textless vtkProp3D* \textgreater),\\
1694 - up to 5 Input Observers (\textless vtkInteractorObserver* \textgreater), \\
1695 - a boolean 'Stereo' option, to use Red-Blue filter
1697 - an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact, \\
1698 - a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
1700 It contains too some sophisticated complex black boxes :
1702 \paragraph{IsoSurfaceWithControls}
1703 Image iso-surface extractor (vtk::IsoSurfaceExtractor) with associated control panel (isovalue, opacity and colour)\\
1705 - an initial isovalue (Isovalue)
1706 - an initial opacity (Opacity)
1707 - an initial colour (Colour)
1709 \textless vtkProp3D* \textgreater (In)\\
1711 \paragraph{MIPWithControls}
1712 Maximum Intensity Projection (MIP) creator (vtk::MIPCreator) with associated control panel (shift and scale) \\
1714 - an initial scale (Scale)
1715 - an initial shift (Shift)
1717 \textless vtkProp3D* \textgreater (In)\\
1721 Some boxes are the bbfication of usefull xwWidgets, some other ones are more
1724 \paragraph{ColourSelector} Colour Selector dialog (bbfication of wxColourSelector) \\
1726 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
1729 \paragraph{ColourSelectorButton} A button which displays a colour picker dialog when clicked \\
1731 \texttt{In} :Initial colour \\
1732 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
1735 \paragraph{CommandButton} Button which executes bbi commands \\
1737 \texttt{In} : Commands to be executed separated by commas (;). Each single quote (') is replaced by a double quote ("). \\
1738 \texttt{Label} : Label of the button \\
1739 \texttt{Widget} : Output widget \\
1742 \paragraph{DirectorySelector} Pops up a directory selection dialog (wxDirDialog)\\
1744 \texttt{DefaultDir} : The default directory\\
1745 \texttt{Message} : Message to show on the dialog \\
1746 \texttt{Title} : Title of the dialog \\
1747 \texttt{Out} : The directory selected by the user\\
1750 \paragraph{FileSelector} Pops up a file selection dialog for reading or saving (wxFileDialog)\\
1752 \texttt{DefaultDir} : The default directory \\
1753 \texttt{DefaultFile} : The default filename \\
1754 \texttt{Message} : Message to show on the dialog \\
1755 \texttt{OpenSave} : Open for an open dialog (default) / Save for a save dialog\\
1756 \texttt{Title} : Title of the dialog \\
1757 \texttt{Wildcard} : A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" \\
1758 \texttt{Out} : The file selected by the user \\
1761 \paragraph{InputText} A zone in which the user can enter a text (wxTextCtrl)\\
1763 \texttt{In} : Initial text (default '')\\
1764 \texttt{Title} : Title of the input zone (default '')\\
1765 \texttt{WinTitle} : Title of the window (*)\\
1766 \texttt{Out} :Current text\\
1769 \paragraph{LayoutLine} LayoutLine widget (wxBoxSizer)\\
1771 \texttt{Orientation} Orientation (default V), 0=H=HORIZONTAL , 1=V=VERTICAL \\
1772 \texttt{Widget}1 widget 1 \\
1773 \texttt{Widget2} widget 2 \\
1774 \texttt{Widget3} widget 3 \\
1775 \texttt{Widget4} widget 4 \\
1776 \texttt{Widget5} widget 5 \\
1777 \texttt{Widget6} widget 6 \\
1778 \texttt{Widget7} widget 7 \\
1779 \texttt{Widget8} widget 8 \\
1780 \texttt{Widget9} widget 9\\
1783 \paragraph{LayoutSplit} Widget which splits a window in two fixed size parts (wxSplitterWindow)\\
1785 \texttt{Orientation} : Orientation (default H), 0=H=HORIZONTAL , 1=V=VERTICAL\\
1786 \texttt{Proportion} : Proportion (in percent) of the first children in the window\\
1787 \texttt{Widget1} : Upper or left widget\\
1788 \texttt{Widget2} : Lower or right widget\\
1791 \paragraph{LayoutTDown} Creates a 'T like' complex container : Down {UpLeft, UpRight} \\
1793 \texttt{Widget1} : UpLeft container\\
1794 \texttt{Widget2} : UpRight container\\
1795 \texttt{Widget3} : Down container\\
1806 \paragraph{LayoutTLeft} Creates a 'T like' complex container : Left {RigthUp, RightDown}\\
1808 \texttt{input} Widget1 : "UpLeft container"\\
1809 \texttt{input} Widget2 : "UpRight container"\\
1810 \texttt{input} Wigdet3 : "Down container"\\
1821 \paragraph{LayoutTRight} Creates a 'T like' complex container : Right {LeftUp, LeftDown}\\
1823 \texttt{input} Widget1 currentBox.Widget1 "Up container"\\
1824 \texttt{input} Widget2 down.Widget1 "DownLeft container"\\
1825 \texttt{input} Widget3 down.Widget2 "DownRight container"\\
1836 \paragraph{LayoutTUp} Creates a 'T like' complex container : Up {DownLeft, DownRight} as w1{w2,w3}\\
1838 \texttt{ input} Widget1 currentBox.Widget1 "Up"\\
1839 \texttt{input} Widget2 down.Widget1 "DownLeft"\\
1840 \texttt{input} Widget3 down.Widget2 "DownRight"\\
1851 \paragraph{LayoutTab} LayoutTab widget (wxNotebook)\\
1853 \texttt{Orientation} Orientation (default T), 0=T=TOP , 1=R=RIGHT , 2=B=BOTTON , 3=L=LEFT \\
1854 \texttt{Widget1} widget 1 \\
1855 \texttt{Widget2} widget 2 \\
1856 \texttt{Widget3} widget 3 \\
1857 \texttt{Widget4} widget 4 \\
1858 \texttt{Widget5} widget 5 \\
1859 \texttt{Widget6} widget 6 \\
1860 \texttt{Widget7} widget 7 \\
1861 \texttt{Widget8} widget 8 \\
1862 \texttt{Widget9} widget 9 \\
1865 \paragraph{OutputText} Text zone to be inserted into a window (wxStaticText)\\
1868 \texttt{Title} Title prepended to the text\\
1871 \paragraph{RadioButton} RadioButton group widget 0-9 entries\\
1873 \texttt{In} Set initial item \\
1874 \texttt{In0} option 0\\
1875 \texttt{In1} option 1\\
1876 \texttt{In2} option 2\\
1877 \texttt{In3} option 3\\
1878 \texttt{In4} option 4\\
1879 \texttt{In5} option 5 \\
1880 \texttt{In6} option 6 \\
1881 \texttt{In7} option 7 \\
1882 \texttt{In8} option 8 \\
1883 \texttt{In9} option 9 \\
1884 \texttt{Title} Title of the widget (default '')\\
1885 \texttt{Out} Number of the selected Item
1888 \paragraph{Slider} Slider widget (wxSlider)\\
1890 \texttt{ChangeResolution} Enables the user to change the slider resolution (default FALSE) \\
1891 \texttt{In} Initial slider position(default 0) \\
1892 \texttt{Label} Show slider labels ? (default FALSE) \\
1893 \texttt{Max} Maximum value of the slider (default 500)\\
1894 \texttt{Min} Minimum value of the slider (default 0)\\
1895 \texttt{Orientation} Orientation : (default H) 0=H=HORIZONTAL, 1=V=VERTICAL\\
1896 \texttt{ReactiveOnTrack} Slider sends info when track moves (default 0 = no)\\
1897 \texttt{Title} Title shown above the slider (default '')\\
1900 % ==========================================
1901 \subsubsection{Pipeline processing}
1902 \label{bbi-more-on-pipeline-processing}
1903 % ==========================================
1905 \item the ``control'' mechanism in bbi (switch exec commands, e.g. Button)
1906 \item the role of ProcessMode to update widgets.
1908 % ==========================================
1909 \subsubsection{Complex black boxes}
1910 \label{bbi-more-on-complex-black-boxes}
1911 Creation of complex widgets (containers, contained...)
1913 %\subsubsection{Advanced issues}
1914 %\paragraph{Reducing the number of inputs of a box}
1916 % ==========================================
1917 \subsubsection{Errors}
1918 \label{bbi-more-on-errors}
1920 % ==========================================
1921 \subsubsection{\bbtk configuration file and search pathes}
1922 \label{bbi-more-on-configuration}
1924 At start, \bbi tries to open an \texttt{xml}
1925 configuration file named \texttt{bbtk\_config.xml}.
1928 \item The current directory
1929 \item The subdir \texttt{.bbtk} of the user's home directory.
1931 \item On \texttt{Unix}, the home directory is the
1932 one stored by the environnement variable \texttt{HOME},
1933 typically \texttt{/home/username}.
1934 \item On \texttt{Windows}, the home directory is
1935 the user's profile directory stored by the environnement
1936 variable \texttt{USERPROFILE},
1937 typically \texttt{C:\\...}.
1939 \item If none of these two pathes contains the file then it creates
1940 a new one in the \texttt{.bbtk} directory.
1943 Once created, you can edit the \texttt{bbtk\_config.xml} file located
1944 in your \texttt{.bbtk} directory. It contains:
1946 \begin{file}{bbtk\_config.xml}
1948 <?xml version="1.0" encoding="iso-8859-1"?>
1950 <bbtk_url> http://www.creatis.insa-lyon.fr/software/bbtk </bbtk_url>
1951 <bbs_path> </bbs_path>
1952 <package_path> </package_path>
1953 <data_path> </data_path>
1958 You can add pathes to
1960 \item A custom folder in which to search for \texttt{.bbs} scripts (\texttt{include} command of \bbi) by adding an \texttt{xml} tag:
1961 \texttt{<bbs\_path>complete\_path\_to\_folder<\/bbs\_path>}.
1962 \item A custom folder in which to search for packages (\texttt{load} command of \bbi) by adding an \texttt{xml} tag:
1963 \texttt{<package\_path>complete\_path\_to\_folder<\/package\_path>}.
1966 % ==========================================
1967 \subsection{Language reference}
1968 \label{bbi-reference}
1969 % ==========================================
1975 % ==========================================
1977 \caption{\label{bbi-reference-box}
1978 \bbi pipeline creation and execution related commands.}
1980 \begin{tabular}{|lcm{6cm}|}
1982 Command & Parameters & Effect \\ \hline
1984 \texttt{new} & \texttt{<boxtype>} \texttt{<box-name>}&
1985 Creates a box of type \texttt{boxtype} and name
1989 \texttt{delete} & \texttt{<box-name>} &
1990 Destroys the box named \texttt{box-name}.
1993 \texttt{connect} & \texttt{<box1.output>} \texttt{<box2.input>} &
1995 \texttt{output} of the box named \texttt{box1}
1996 to the input \texttt{input} of the box named \texttt{box2} \\ \hline
1998 \texttt{set} & \texttt{<box.input>} \texttt{<value>} &
1999 Sets the input \texttt{input} of
2000 the box named \texttt{box} to the value \texttt{value}.
2001 There must exist an \texttt{adaptor}
2002 in the packages loaded which converts a \texttt{std::string}
2003 to the type of the input \texttt{input}.
2006 \texttt{print} & \texttt{<string>} &
2007 Prints the string after substituting each token of the form \texttt{\$box.output\$} by the adaptation to string of the value of the
2008 output \texttt{output} of the box named \texttt{box}.
2009 There must exist an \texttt{adaptor}
2010 in the packages loaded which converts
2011 the type of the output \texttt{output}
2012 to a \texttt{std::string}.
2015 \texttt{exec} & \texttt{<box-name>} &
2016 Executes the box named \texttt{box-name}.
2018 connected to its inputs
2019 are also processed recursively (pipeline processing).\\ \hline
2020 \texttt{exec} & \texttt{freeze} &
2021 allows to block execution commands while keeping definition commands active.\\ \hline
2022 \texttt{exec} & \texttt{unfreeze} &
2023 turns back to 'normal' mode.\\ \hline
2026 % ==========================================
2030 % ==========================================
2032 \caption{\label{bbi-reference-interpreter}\bbi intepreter related commands.}
2034 \begin{tabular}{|lcm{6cm}|}
2036 Command & Parameters & Effect \\ \hline
2040 Prints help on available commands \\ \hline
2042 & \texttt{<command-name>} &
2043 Prints help on the command \texttt{command-name} \\ \hline
2045 & \texttt{packages} &
2046 Prints help on available packages and their box types
2047 (without description)\\ \hline
2049 & \texttt{<package-name>} &
2050 Prints help on the package \texttt{package-name} and its boxes
2051 (with brief description).
2052 The package must have been previously loaded
2055 & \texttt{<box-type>} &
2056 Prints help (with full description) on the type of box
2058 The box type must belong to a package which has been previously loaded
2061 \texttt{include} & \texttt{<file-name>} &
2062 Includes and executes the content of the file named \texttt{file-name}
2063 exactly like if you were typing its content at the place were the
2064 \texttt{include} command is.
2067 \texttt{load} & \texttt{<package-name>} &
2068 Loads the package \texttt{package-name}\\ \hline
2070 \texttt{include} & \texttt{<package-name>} &
2071 Loads the package \texttt{package-name} and includes all the complex black boxes that comes with it \\ \hline
2073 \texttt{kind} & \texttt{<box kind>} &
2074 Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline
2079 \texttt{unload} & \texttt{<package-name>}&
2080 Unloads the package \texttt{package-name}.
2081 The package must have been previously loaded.
2082 No box of a type defined in this package must still exist.
2085 \texttt{message} & \texttt{<category>} \texttt{<level>} &
2086 Sets the level of verbosity of \bbi for the category of messages
2087 \texttt{category} to \texttt{level}.
2088 %See \ref{verbosity}.
2091 \texttt{config} & - & Displays the Configuration parameters\\ \hline
2093 \texttt{reset} & - & Deletes all boxes and unloads all packages so
2094 that \bbi gets back to its initial state \\ \hline
2096 \texttt{quit} & - & Exits the interpreter\\ \hline
2100 % ==========================================
2106 % ==========================================
2108 \caption{\label{bbi-reference-complex-box}
2109 \bbi complex black box definition related commands.}
2111 \begin{tabular}{|lcm{6cm}|}
2113 Command & Parameters & Effect \\ \hline
2116 \texttt{define} & \texttt{<box-type>} &
2117 Starts the definition of a complex black box of type
2118 \texttt{box-type}\\ \hline
2120 \texttt{endefine} & - &
2121 Ends the definition of a complex black box type\\ \hline
2123 \texttt{author} & \texttt{<string>} &
2124 Sets the author(s) of the complex black box currently being defined \\ \hline
2126 \texttt{description} & \texttt{<string>} &
2127 Sets the description of the complex black box currently being defined
2130 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} &
2131 Defines a new input for the current complex black box,
2132 named \texttt{name}.
2133 It is defined as corresponding to
2134 the input \texttt{input} of the box \texttt{box}.
2136 \texttt{<help>} is the help string for the new input.
2137 The box \texttt{box} must already have been created in the complex box
2138 and of course have an input named \texttt{input}.
2141 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} &
2142 Defines a new output for the current complex black box,
2143 named \texttt{name}.
2144 It is defined as corresponding to
2145 the output \texttt{output} of the box \texttt{box}.
2146 \texttt{<help>} is the help string for the new output.
2147 The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}.
2153 % ==========================================
2158 % ==========================================
2159 \vspace{0.5cm}\hrule
2160 \section{Using black boxes in \CPP programs}
2162 % ==========================================
2171 %\section{Conclusion}