]> Creatis software - bbtk.git/blob - kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex
*** empty log message ***
[bbtk.git] / kernel / doc / bbtkUsersGuide / bbtkUsersGuide.tex
1 % ==========================================
2 \documentclass[11pt,final,a4paper]{article}
3 \input{config.tex}
4 \begin{document}
5 \title{The Black Box Toolkit\\User's Guide}
6 \date{\today}
7 \author{Laurent Guigues}
8 \maketitle
9 % ==========================================
10 \tableofcontents
11 % ==========================================
12
13 \listoftables
14
15 \listoffigures
16
17 % ==========================================
18 %\section*{Abstract}
19 % ==========================================
20 \newpage
21 % ==========================================
22 \hrule
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. 
31
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 
39 or structure''}. 
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}.
48
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 
53
54 \begin{itemize}
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.
66 \end{itemize}
67
68 (in fact, genericity is achieved because the interface is symbolic. 
69 I let you think about this\dots)
70
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. 
75
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. 
86
87 These two mechanisms (black boxes and packages) 
88 then gives the way to:
89
90 \begin{itemize}
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 
96 \bbi.
97 \end{itemize}
98
99 Finally, these different components allow {\bf efficient}:
100
101 \begin{itemize}
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. 
107 \end{itemize}
108
109 % ==========================================
110 \subsection{\bbtk components}
111 % ==========================================
112 \BBTK includes:
113 \begin{itemize}
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}}:
118     \begin{itemize}
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. 
125     \end{itemize}
126   \item A {\bf\emph{Developement environment}}, called bbStudio, which provides
127     \begin{itemize}
128       \item An online {\bf\emph{script editor}}, called bbed
129       \item A powerfull {\bf\emph{Help environment}}, called bbhelp
130         whith integrated
131         \begin{itemize}
132           \item Online documentation scaning
133           \item Retreiving boxes on various criterions
134           \item Checking Demo and examples
135         \end{itemize}
136
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}}:
141          \begin{itemize}
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.
149          \end{itemize} 
150     \end{itemize}
151 \end{itemize}
152 The general architecture of \BBTK 
153 is shown in figure \ref{bb-architecture}.
154
155 \begin{figure}[!ht]
156 \caption{\label{bb-architecture}\BBTK architecture}
157 \begin{center}
158 \includegraphics[width=0.6\textwidth]{bb-architecture.png}
159 \end{center}
160 \end{figure}
161
162 % ==========================================
163 \subsection{Structure of this guide}
164 % ==========================================
165
166 This guide is divided into three parts. 
167
168 The first part (\ref{bbStudio}) is a brief presentation of the very intuitive Development
169 environment, \bbStudio.
170
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. 
176
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.
181
182
183 % ==========================================
184 % ==========================================
185 % ==========================================
186 % ==========================================
187 % ==========================================
188 % ==========================================
189 \vspace{0.5cm}\hrule
190 \section{The Development environment (bbStudio)}
191 \label{bbStudio}
192
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)
199
200 \begin{figure}[!ht]
201 \caption{\label{bbi-fig-bbStudio-gui}The bbStudio Development environment interface}
202 \begin{center}
203 \includegraphics[width=0.7\textwidth]{bbStudioMainPage.png}
204 \end{center}
205 \end{figure}
206
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 :
209
210  \begin{itemize}
211    \item {\bf\emph{Wiki}}: Direct link to the bbtk Wiki (intranet only, right now, www
212    later).
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
217    black boxes.
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 :
222       \begin{itemize}
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)     
227       \end{itemize}
228  \end{itemize}
229
230
231 % ==========================================
232 \begin{table}[!ht]
233 \caption{\label{bbi-list_of_packages} List of bbtk supplied packages.}
234 \small
235 \begin{tabular}{|lp{10cm}|}
236 \hline
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 
244
245 \end{tabular}
246 \end{table}
247 % ==========================================
248
249
250
251
252 % ==========================================
253 \begin{table}[!ht]
254 \caption{\label{categories} \texttt{Black Box} categories}
255 \small
256 \begin{tabular}{|lp{10cm}|}
257 \hline
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 
280  
281  \texttt{3D object creator} & : Sophisticated 3D widget  \\ \hline  
282  \texttt{toolsbbtk}         & : Component of bbStudio    \\ \hline  
283 \end{tabular}
284 \end{table}
285
286 % ==========================================
287
288 \begin{table}[!ht]
289 \caption{\label{kinds} \texttt{Black Box} kinds}
290 \small
291 \begin{tabular}{|ll|}
292 \hline
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
301 \end{tabular}
302 \end{table}
303
304
305
306 % ==========================================
307 % ==========================================
308 % ==========================================
309 % ==========================================
310 % ==========================================
311 % ==========================================
312 \vspace{0.5cm}\hrule
313 \section{The script manager}
314 \label{bb0}
315 % ==========================================
316
317  Call it with the bookmark \emph{File}.
318  
319
320 \begin{figure}[!ht]
321 \caption{\label{bbi-fig-bbStudio-file0}The bbStudio script manager}
322 \begin{center}
323 \includegraphics[width=0.7\textwidth]{bbFile0.png}
324 \end{center}
325 \end{figure}
326
327 Using the lower tool bar, you can :
328
329 \begin{figure}[!ht]
330 \caption{\label{lowertoolbar}The lower tool bar}
331 \begin{center}
332 \includegraphics[width=0.7\textwidth]{lowertoolbar.png}
333 \end{center}
334 \end{figure}
335
336
337  \begin{itemize}
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
344  \end{itemize}
345
346
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. 
361
362 After this tutorial, 
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. 
370
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.
375
376 % ==========================================
377 \subsection{Getting started}
378 \label{bbi-getting-started}
379 % ==========================================
380 \subsubsection{Creating and executing black boxes}
381 % ==========================================
382
383 To learn interactivelly the script language features, you can use the black box
384 interpreter : 
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}.
392
393 \begin{figure}[!ht]
394 \caption{\label{bbi-fig-bbi-gui}The black box interpreter interface}
395 \begin{center}
396 \includegraphics[width=0.7\textwidth]{bbi-gui0.png}
397 \end{center}
398 \end{figure}
399
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.
404
405 Try typing in the input zone (in this manual, 
406 the commands entered by the user will be preceded by a prompt \textgreater) :
407 \begin{verbatim}
408 > help 
409 \end{verbatim}
410
411 you get the list of the commands of the interpreter:
412 \begin{verbatim}
413 Available commands:
414  author
415  category
416  config
417  connect
418  debug
419  define
420  delete
421  description
422  endefine
423  endpackage
424  exec
425  graph
426  help
427  include
428  index
429  input
430  kind
431  load
432  message
433  new
434  newgui
435  output
436  package
437  print
438  quit
439  reset
440  set
441  unload
442 \end{verbatim}
443
444 To get help on a particular command type \texttt{help <command-name>},
445 for example:
446 \begin{verbatim}
447 > help quit
448 \end{verbatim}
449
450 gives:
451 \begin{verbatim}
452  quit: 
453    usage: quit
454     Quits the program (during script execution it stops the complete execution)
455 \end{verbatim}
456
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:
460 \begin{verbatim}
461 > help help
462  usage: 
463          (1) help 
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>
469   Effect:
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.
478 \end{verbatim}
479
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:
483 \begin{verbatim}
484 > help packages
485 user
486   workspace
487 \end{verbatim}
488
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}). 
504
505 If you type \texttt{'help workspace'}, you get:
506 \begin{verbatim}
507 > help workspace
508 Complex Black Box <user::workspace>
509  User's workspace
510  By: bbi (internal)
511  Category(s) : complex box;
512  * No inputs
513  * No outputs
514  * No boxes
515 \end{verbatim}
516
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.
524
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. 
529
530 To load it, type:
531 \begin{verbatim}
532 > include std
533 \end{verbatim}
534
535 Then if you type:
536 \begin{verbatim}
537 > help packages
538 \end{verbatim}
539
540 you get something like:
541 \begin{verbatim}
542 std
543   Add 
544   ConcatStrings          
545   Configuration          
546   Div   
547   ...
548   StringRelay            
549   StringSelect    
550 user
551   workspace
552
553 \end{verbatim}
554
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. 
559 If you type:  
560 \begin{verbatim}
561 > help Add
562 \end{verbatim}
563
564 You get:
565 \begin{verbatim}
566 Black Box <std::Add>
567   Adds its inputs
568   By : laurent.guigues@creatis.insa-lyon.fr
569   Categories : atomic box;math;
570   * Inputs : 
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
575   * Outputs : 
576      'BoxChange'      <bbtk::Void> [signal] : Signals modifications of the box
577      'Out'            <Double>     []       : Result
578 \end{verbatim}
579
580 Like previously, 
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>})
592 and a description.    
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.
596
597 You can create an \emph{instance} of an \texttt{Add} box by 
598 the command \texttt{new}:
599 \begin{verbatim}
600 > new Add a
601 \end{verbatim}
602
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 
612 name is \texttt{i}. 
613 Of course, like in \texttt{C} Language, you can declare multiple boxes of the 
614 same type in \bbi. 
615
616 After the creation of the box \texttt{a}, type:
617 \begin{verbatim}
618 > help workspace
619 \end{verbatim}
620
621 you get:
622 \begin{verbatim}
623 Complex Black Box <user::workspace>
624  User's workspace
625  By: bbi (internal)
626  Category(s) : complex box;
627  * No inputs
628  * No outputs
629  * Boxes: 
630     'a' <std::Add>
631 \end{verbatim}
632
633 which means that \bbi workspace now contains a black box named \texttt{a},
634 of type \texttt{std::Add}.
635
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}.
640
641 You can set the input \texttt{In1} 
642 of the \texttt{Add} box \texttt{a} to the value $1$ 
643 by the command:
644 \begin{verbatim}
645 > set a.In1 1 
646 \end{verbatim}
647
648 Similarly, setting the input \texttt{In2} of \texttt{a} to the value $2$
649 is done with:
650 \begin{verbatim}
651 > set a.In2 2
652 \end{verbatim}
653  
654 And you print the output \texttt{Out} of the box \texttt{a} with:
655 \begin{verbatim}
656 > print "result=$a.Out$"
657 result=3
658 \end{verbatim}
659
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:
664 \begin{enumerate}
665 \item Processes the box if needed (see below)
666 \item Converts the output of the box to a string if possible 
667 (see below)
668 \item Substitutes the result in the string to print
669 \item postpone an implicit 'new line' character to the string
670 \end{enumerate}
671
672 \paragraph
673 Box processing is needed if:
674 \begin{itemize}
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. 
678 \end{itemize}
679
680 Note that all boxes have the input \texttt{'BoxProcessMode'}. 
681
682 Another way to process the box \texttt{a} is to issue the command:
683 \begin{verbatim}
684 > exec a
685 \end{verbatim}
686
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. 
693
694 To exit \bbi, type:
695 \begin{verbatim}
696 > quit
697 Good bye !
698 \end{verbatim}
699
700 % ==========================================
701 \hrule
702 \paragraph{Summary}
703 %\hrule
704 \begin{itemize}
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:
707 \begin{itemize} 
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}).
713 \end{itemize}
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.
724 \end{itemize}
725 \hrule
726
727 \paragraph{Note :}
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} :
730
731 \begin{figure}[!ht]
732 \caption{\label{bbCommandPlusHelp}
733 An other way to run the command interpreter}
734 \begin{center}
735 \includegraphics[width=0.5\textwidth]{bbCommandPlusHelp.png}
736 \end{center}
737 \end{figure}
738 % ==========================================
739
740 % ==========================================
741 \subsubsection{Connecting black boxes}
742 \label{bbi-connecting-black-boxes}
743 % ==========================================
744
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.
752
753 First start \bbi and load the package \texttt{std}:
754 \begin{verbatim}
755 > include std
756 \end{verbatim}
757
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}. 
761
762 \begin{figure}[!ht]
763 \caption{\label{bbi-fig-connecting-black-boxes-1}
764 A simple pipeline which adds 3 numbers}
765 \begin{center}
766 \includegraphics[width=0.5\textwidth]{1plus2plus3.png}
767 \end{center}
768 \end{figure}
769
770
771 The \bbi instructions to create and execute this pipeline are:
772 \begin{verbatim}
773 > new Add a
774 > new Add b
775 > connect a.Out b.In1
776 > set a.In1 1
777 > set a.In2 2
778 > set b.In2 3
779 > print $b.Out$
780 \end{verbatim}
781
782 You will see the (very expected) result :
783 \begin{verbatim}
784 6
785 \end{verbatim}
786
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.
791  
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 
794 box \texttt{b}. 
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} 
800 for details).
801
802
803 Lets' consider an other, more image oriented, example :
804
805 \begin{verbatim}
806 > include vtk
807 > include wx
808 > include itk
809 > include wxvtk
810
811 > new FileSelector fileDialog
812 > new ImageReader  reader 
813 > new Slider       slider
814 > new Viewer2D     viewer
815
816 > connect fileDialog.Out   reader.In 
817 > connect reader.Out       viewer.In
818 > connect slider.Out       viewer.Slice
819 > connect slider.BoxChange viewer.BoxExecute
820
821 > exec viewer
822 \end{verbatim}
823
824 Some explainations : the \texttt{include} instructions load the necessary packages. \\
825
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.\\
830 \\
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.\\
835 \\
836 \texttt{exec viewer} processes the viewer.
837
838
839 This would correspond to the graph in figure \ref{bbi-simplegraph}
840
841
842 \begin{figure}[!ht]
843 \caption{\label{bbi-simplegraph}(Very) simple Graph of a (very) simple pipeline}
844 \begin{center}
845 \includegraphics[width=0.8\textwidth]{bbi-simplegraph.png}
846 \end{center}
847 \end{figure}
848    
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}.
853
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).
859
860 In \bbi, if you type:
861 \begin{verbatim}
862 > load std
863 > help std all
864 \end{verbatim}
865 you get:
866 \begin{verbatim}
867  Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
868  Basic useful black boxes
869  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
873     ... 
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...
877 >
878 \end{verbatim}
879
880 The \texttt{Cast<?,?>} and \texttt{Convert<?,?>} boxes are \emph{default adaptors}, which is signaled by the tag \texttt{[DA]} before their descriptions.
881
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.
899
900 Question: 
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
905
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.
911  
912 % ==========================================
913 \hrule
914 \paragraph{Summary}
915 %\hrule
916 \begin{itemize}
917 \item The \texttt{connect} command allows to connect two black boxes
918 \item You can connect two black boxes if (and only if): 
919 \begin{itemize}
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
923 \end{itemize}
924 \item \texttt{help <package name>} does not display the adaptors of the package. To see them use: \texttt{help <package name> all}.
925 including adaptors
926 \end{itemize}
927 \hrule
928 % ==========================================
929
930 % ==========================================
931 \subsubsection{Creating complex black boxes}
932 \label{bbi-complex-black-boxes}
933 % ==========================================
934
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}.
942
943 \begin{figure}[!ht]
944 \caption{\label{bbi-fig-complex-black-box-1}
945 Creating the complex black box \texttt{Add3}}
946 \begin{center}
947 \includegraphics[width=0.5\textwidth]{Add3.png}
948 \end{center}
949 \end{figure}
950
951 The \bbi commands to define this complex black box are 
952 the following:
953
954 \begin{verbatim}
955 > load std
956 >
957 > define Add3
958 >
959 > new Add a
960 > new Add b
961 > connect a.Out b.In1
962 >
963 > author "myself"
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"
969 >
970 > endefine
971 \end{verbatim}
972
973 Explainations:
974
975 As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
976
977 The command \texttt{define} then starts the definition 
978 of the complex box type, which will be called \texttt{Add3}. 
979
980 The next three lines define the pipeline, 
981 exactly in the same way than outside a complex box definition. 
982
983 The commands \texttt{author}, \texttt{description}, \texttt{input} 
984 and \texttt{output} are commands specific to complex boxes definition:
985
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.
990
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.
1008
1009 Finally, the \texttt{endefine} command ends the definition of the 
1010 new box type.
1011
1012 After this definition, if you ask for help 
1013 on packages, you get:
1014 \begin{verbatim}
1015 > help packages
1016 std
1017   Add
1018   ...
1019 user
1020   Add3
1021   workspace
1022 \end{verbatim}
1023
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:
1026 \begin{verbatim}
1027 > help Add3
1028 Complex Black Box <user::Add3>
1029  adds 3 doubles
1030  By: myself
1031  * Inputs: 
1032     'x'      <double>: first double to add
1033     'y'      <double>: second double to add
1034     'z'      <double>: third double to add
1035  * Outputs: 
1036     'result' <double>: output
1037  * Boxes: 
1038     'a' <std::Add>
1039     'b' <std::Add>
1040 \end{verbatim}
1041
1042 and you can use it like any other box, for example type:
1043
1044 \begin{verbatim}
1045 > new Add3 a
1046 > set a.x 1
1047 > set a.y 2
1048 > set a.z 3
1049 > print $a.result$
1050 6
1051 \end{verbatim}
1052
1053
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
1057 entry'.
1058
1059 % ==========================================
1060 \hrule
1061 \paragraph{Summary}
1062 %\hrule
1063 \begin{itemize}
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:
1066 \begin{itemize}
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.  
1070 \end{itemize}
1071 \end{itemize}
1072 \hrule
1073 % ==========================================
1074
1075 % ==========================================
1076 \subsubsection{Writing scripts}
1077 \label{bbi-writing-scripts}
1078 % ==========================================
1079
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} 
1086 (black box script).
1087 For consistency reasons, you are requested to prepend \texttt{bb} to the name.
1088
1089 For example, the \texttt{Add3} complex box we previously worked on 
1090 can be defined in the \texttt{bbAdd3.bbs} file:
1091
1092 \begin{file}{bbAdd3.bbs}
1093 \begin{verbatim}
1094 # Defines the Add3 black box which adds 3 doubles 
1095 load std
1096
1097 define Add3
1098   # I am the author 
1099   author "myself"
1100   description "adds 3 doubles"
1101   # Pipeline creation
1102   new Add a
1103   new Add b
1104   connect a.Out b.In1
1105   # Inputs definition
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"
1109   # Output definition
1110   output result b.Out "output"
1111 endefine
1112 \end{verbatim}
1113 \end{file}
1114
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:
1118
1119 \begin{verbatim}
1120 > include bbAdd3.bbs
1121 > help Add3
1122 Complex Black Box <user::Add3>
1123  adds 3 doubles
1124  By: myself
1125  * Inputs: 
1126     'x'      <double>: first double to add
1127     'y'      <double>: second double to add
1128     'z'      <double>: third double to add
1129  * Outputs: 
1130     'result' <double>: output
1131  * Boxes: 
1132     'a' <std::Add>
1133     'b' <std::Add>
1134 >
1135 and so on ...
1136 \end{verbatim}
1137
1138 If the file has the \texttt{bbs} extension, you can ommit it and just type:
1139 \begin{verbatim}
1140 > include Add3
1141 \end{verbatim}
1142
1143 Of course, you can include script files in other script files, 
1144 like in the following example:
1145
1146 \begin{file}{bbAdd4.bbs}
1147 \begin{verbatim}
1148 # Defines the Add4 black box which adds 4 doubles 
1149 include Add3
1150
1151 define Add4
1152   author "myself"
1153   description "adds 4 doubles"
1154   new Add3 a
1155   new Add b
1156   connect a.Out b.In1
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"
1162 endefine
1163 \end{verbatim}
1164 \end{file}
1165
1166 % ==========================================
1167 \hrule
1168 \paragraph{Naming Conventions}
1169 %\hrule
1170
1171 \hrule
1172 % ==========================================
1173 \begin{itemize}
1174 \item
1175 File names: 
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.
1178
1179 For example, the \texttt{Add3} complex box we previously worked on 
1180 can be defined in the \texttt{bbAdd3.bbs} file.
1181 \item
1182 Search Paths 
1183 \end{itemize}
1184 % ==========================================
1185 \hrule
1186
1187 \paragraph{Summary}
1188 %\hrule
1189 \begin{itemize}
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.
1193 \end{itemize}
1194
1195 \hrule
1196 % ==========================================
1197
1198 % ==========================================
1199 \subsubsection{Creating command line applications}
1200 \label{bbi-command-line-app}
1201 % ==========================================
1202
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} 
1211 complex black box.
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 
1215 \texttt{workspace}.
1216
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.
1225
1226 For example, consider the script: 
1227
1228 \begin{file}{add.bbs}
1229 \begin{verbatim}
1230 load std
1231 new Add a
1232 input x a.In1 "first number to add"
1233 input y a.In2 "second number to add"
1234 print "x+y=$a.Out$"
1235 \end{verbatim}
1236 \end{file}
1237
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, 
1241 like this:
1242
1243 \begin{verbatim}
1244 > bbi add x=1 y=1
1245 x+y=2
1246 \end{verbatim}
1247
1248 You can also invoke \bbi the option \texttt{-h}, 
1249 which gives help on the \texttt{workspace} box:
1250
1251 \begin{verbatim}
1252 > bbi add -h
1253  User's workspace
1254  By: bbi (internal)
1255  * Inputs: 
1256     'x' <double>: first number to add
1257     'y' <double>: second number to add
1258 \end{verbatim}
1259
1260 To get a better help, use the \texttt{description} 
1261 and \texttt{author} commands:
1262
1263 \begin{file}{add.bbs}
1264 \begin{verbatim}
1265 description "Adds two numbers"
1266 author "foo@bar.com"
1267 load std
1268 new Add a
1269 input x a.In1 "first number to add"
1270 input y a.In2 "second number to add"
1271 print "x+y=$a.Out$"
1272 \end{verbatim}
1273 \end{file}
1274
1275 Now if you ask for help on the \texttt{add} script, you get:
1276
1277 \begin{verbatim}
1278 > bbi add -h
1279  Adds two numbers
1280  By: foo@bar.com
1281  * Inputs: 
1282     'x' <double>: first number to add
1283     'y' <double>: second number to add
1284 \end{verbatim}
1285
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}
1289 commutator:
1290
1291 \begin{verbatim}
1292 > bbi add -t
1293 x=[the program waits for user answer]2
1294 y=[the program waits for user answer]5
1295 x+y=7
1296 \end{verbatim}
1297
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}.
1303
1304 \begin{figure}[!ht]
1305 \caption{\label{bb-input-dialog-box}Input dialog box}
1306 \begin{center}
1307 \includegraphics[width=0.6\textwidth]{enter-the-value-of-x.png}
1308 \end{center}
1309 \end{figure}
1310
1311 % ==========================================
1312 \hrule
1313 \paragraph{Summary}
1314 %\hrule
1315 \begin{itemize}
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.
1327 \end{itemize}
1328 \hrule
1329 % ==========================================
1330
1331 % ==========================================
1332 \subsubsection{Using graphical interface boxes (widget boxes)}
1333 \label{bbi-widget}
1334 % ==========================================
1335
1336 % ==========================================
1337 \subsubsection{Overwiew}
1338 \label{bbi-overview}
1339 % ==========================================
1340
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.
1347
1348 As first example, type the following commands in \bbi:
1349 \begin{verbatim}
1350 > load wx 
1351 > new InputText t
1352 > print $t.Out$\n
1353 \end{verbatim}
1354
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.
1359
1360 Type \texttt{help wx}, you get something like:
1361 \begin{verbatim}
1362  Package wx v1.0.0- info-dev@creatis.insa-lyon.fr
1363  Basic graphical interface elements (sliders, buttons ...) based on wxWidgets
1364  Black boxes : 
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)
1377 \end{verbatim}
1378
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.
1382
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 
1392 to a ``handle''.
1393
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:
1399
1400 \begin{file}{scripts/test/testSplit.bbs}
1401 \begin{verbatim}
1402 load std
1403 load wx
1404
1405 new Slider s1
1406 new Slider s2
1407
1408 new LayoutSplit s
1409 connect  s1.Widget s.Widget1
1410 connect  s2.Widget s.Widget2
1411
1412 print s1=$s1.Out$\\n
1413 print s2=$s2.Out$\\n
1414 \end{verbatim}
1415 \end{file}
1416
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} 
1424 widgets 
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).
1438
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}
1441 widget. 
1442
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.
1452
1453 The \texttt{LayoutTab}  widget is based on the \texttt{wxNotebook.}
1454
1455 One word about a special widget in the package \texttt{wx}: 
1456 the \texttt{Button}... to be continued.
1457
1458 % ==========================================
1459 \subsubsection{Deeper in the boxes}
1460 \label{bbi-deep-box}
1461 % ==========================================
1462
1463 Any widget box has two mandatory Outputs :
1464
1465 \begin{itemize}
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.
1470 \end{itemize}    
1471
1472 Any widget box has two mandatory Inputs :
1473 \begin{itemize}
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 :
1476   \begin{itemize}
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()    
1480   \end{itemize}   
1481 \end{itemize}
1482
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} :  
1484 \begin{itemize}
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})   
1491 \end{itemize}
1492
1493
1494 Any \emph{Layout box} (i.e. \emph{LayoutLine}, \emph{LayoutSplit} or \emph{LayoutTab}) has at one or more mandatory Inputs :
1495 \begin{itemize}
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.
1498 \end{itemize} 
1499
1500
1501 % ==========================================
1502 \subsection{More on ...}
1503 \label{bbi-more-on}
1504 % ==========================================
1505
1506 % ==========================================
1507 \subsubsection{Black box packages}
1508 \label{bbi-more-on-packages}
1509 % ==========================================
1510
1511 There are various others user-intended packages :
1512 \begin{itemize}
1513 \item{vtk} \\
1514 It contains some vtk based image processing filters :
1515 %   \begin{enumerate}
1516
1517      \paragraph{AppendPolyData}
1518      Appends one of more polygonal datasets into a single polygonal dataset 
1519
1520      \paragraph{ConeSource}
1521      Creates a Cone 
1522
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
1532 modified. \\
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.\\
1535      Receives : \\
1536      - In : an image (vtkImageData*)\\
1537      - Diffusion : Difference threshold that stops the diffusion\\
1538      Outputs : \\
1539      - Out : the isosurface mesh (vtkPolyData*)
1540      
1541      \paragraph{ImageCharacteristics}
1542      Exports objet sizes, and Spacings
1543      
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) \\
1551      Receives : \\
1552      - In : an image (vtkImageData*)\\
1553      - DilateValue : The dilatation value\\
1554      - ErodeValue : The erosion value\\
1555      Outputs : \\
1556      - Out : the isosurface mesh (vtkPolyData*)     
1557      
1558      \paragraph{ImageGaussianSmooth}
1559      Performs a gaussian convolution of the input image\\
1560      Receives : \\
1561      - In : an image (vtkImageData*)\\
1562      - StdDevX : Standard deviation in X direction\\
1563      - StdDevY : Standard deviation in Y direction\\
1564      Outputs : \\
1565      - Out : the isosurface mesh (vtkPolyData*)       
1566      
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)
1570      Receives : \\
1571      - In : an image (vtkImageData*)\\
1572      Outputs : \\     
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*)\\
1576      
1577           Outputs : \\
1578      - Out : the isosurface mesh (vtkPolyData*)  
1579            
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)
1582      Receives : \\
1583      - In : an image (vtkImageData*)\\
1584      - Isovalue : the isosurface value (double)\\
1585      - Colour : Surface colour (vector of 3 doubles)
1586      Outputs : \\
1587      - Out : the isosurface (vtkProp3D**)
1588      
1589      \paragraph{MarchingCubes}
1590      Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes)\\
1591      Receives : \\
1592      - In : an image (vtkImageData*)\\
1593      - Value : the isosurface value (double)\\
1594      Outputs : \\
1595      - Out : the isosurface mesh (vtkPolyData*)
1596      
1597      \paragraph{MIPCreator}     
1598      Creates a Maximum Intensity Projection (MIP) view of a 3D image.\\
1599      Receives : \\
1600      - In : an image (vtkImageData*)\\
1601      - Scale : the Gray scale scaling (float) \\
1602      - Shift : the Gray scale shift (float) \\    
1603      Ouputs : \\
1604      - Out : The MIP object (vtkProp3D*) to be plugged into a 3D Viever
1605
1606      \paragraph{MetaImageReader}
1607      Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader) \\
1608      Receives : \\
1609      - In : the name of the file to be read (std::string)
1610      Outputs :
1611      - Out : The image (vtkImageData*)     
1612      
1613      \paragraph{SegmentationConnectivity}
1614      Segmentation with min max threshold and connectivity  \\  
1615      Receives : \\
1616      - In : an image (vtkImageData*)\\
1617      - PositionXYZ : initial position (std::vector<int>) \\
1618      - ThresholdMinMax : min, max threshold values (std::vector<int>) \\
1619      Outputs : \\
1620      - Out : The image (vtkImageData*)       
1621           
1622      \paragraph{SphereSource}
1623      Creates a Sphere      
1624 %   \end{enumerate}
1625
1626 \item{itk} \\
1627 It contains some itk based image processing filters :
1628  
1629      \paragraph{BinaryThresholdImageFilter}
1630      Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter) 
1631
1632      \paragraph{DICOMSeriesFileNames}
1633      Reads a series from a DICOM directory as a 3D itk image     
1634
1635      \paragraph{ExtractImageFilter}
1636      Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)     
1637
1638      \paragraph{ImageProperties}
1639      Outputs different properties of an image (type, dimension, size, spacing, ...)      
1640
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)     
1645
1646      \paragraph{ImageReader}
1647 Generic itk image reader
1648
1649      \paragraph{ImageWriter}
1650 Generic itk image writer
1651
1652      \paragraph{ImageSeriesReader}
1653 Generic itk image series reader.
1654
1655      \paragraph{ResampleImageFilter}
1656 Resamples an image
1657
1658 \item{itkvtk} \\
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 
1660
1661 Sorry nothing is done, right now for meshes. 
1662
1663 \item{wxvtk} \\
1664
1665 It contains two atomic black boxes.
1666
1667      \paragraph{Viewer2D} 
1668      Receives : \\
1669      - a \textless vtkImageData* \textgreater (In),\\
1670      - an Orientation(0:yz / 1:xz / 2:xy),\\
1671      - an initial slice number (Slice).\\
1672      Outputs :\\
1673      - a \textless vtkRenderer* \textgreater (Renderer)
1674      
1675      \paragraph{Viewer3D} 
1676      Receives :\\
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     
1680      Outputs :\\
1681      - an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact, \\
1682      - a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
1683
1684 It contains too some sophisticated complex black boxes :
1685  
1686      \paragraph{IsoSurfaceWithControls} 
1687      Image iso-surface extractor (vtk::IsoSurfaceExtractor) with associated control panel (isovalue, opacity and colour)\\
1688      Receives :\\
1689      - an initial isovalue (Isovalue)
1690      - an initial opacity  (Opacity)
1691      - an initial colour   (Colour)
1692      Outputs :\\
1693      \textless vtkProp3D* \textgreater (In)\\
1694       
1695      \paragraph{MIPWithControls}     
1696      Maximum Intensity Projection (MIP) creator (vtk::MIPCreator) with associated control panel (shift and scale) \\
1697     Receives :\\
1698      - an initial scale (Scale)
1699      - an initial shift  (Shift) 
1700      Outputs :\\
1701      \textless vtkProp3D* \textgreater (In)\\
1702          
1703 \item{wx} \\
1704
1705 Some boxes are the bbfication of usefull xwWidgets, some other ones are more
1706 sophisticated.
1707
1708     \paragraph{ColourSelector} Colour Selector dialog (bbfication of wxColourSelector) \\
1709                         %\begin{verbatim}
1710          \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]' 
1711                         %\end{verbatim}
1712
1713     \paragraph{ColourSelectorButton} A button which displays a colour picker dialog when clicked \\
1714                         %\begin{verbatim}
1715           \texttt{In} :Initial colour \\
1716           \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
1717                         %\end{verbatim} \\
1718
1719     \paragraph{CommandButton} Button which executes bbi commands \\
1720                         %\begin{verbatim}
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 \\
1724                         %\end{verbatim}
1725
1726     \paragraph{DirectorySelector} Pops up a directory selection dialog (wxDirDialog)\\
1727                         %\begin{verbatim}
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\\
1732                         %\end{verbatim}
1733  
1734     \paragraph{FileSelector} Pops up a file selection dialog for reading or saving (wxFileDialog)\\
1735                         %\begin{verbatim}
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 \\
1743                         %\end{verbatim}
1744
1745     \paragraph{InputText} A zone in which the user can enter a text (wxTextCtrl)\\
1746                         %\begin{verbatim}
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\\
1751                         %\end{verbatim}
1752
1753     \paragraph{LayoutLine} LayoutLine widget (wxBoxSizer)\\
1754                         %\begin{verbatim}
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\\
1765           %\end{verbatim}    
1766     
1767     \paragraph{LayoutSplit} Widget which splits a window in two fixed size parts (wxSplitterWindow)\\ 
1768                         %\begin{verbatim}
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\\
1773                         %\end{verbatim}
1774
1775     \paragraph{LayoutTDown} Creates a 'T like' complex container : Down {UpLeft, UpRight} \\
1776                         %\begin{verbatim}
1777           \texttt{Widget1} : UpLeft container\\
1778           \texttt{Widget2} : UpRight container\\ 
1779           \texttt{Widget3} : Down container\\
1780                         \begin{verbatim}
1781 //                       ---------------
1782 //                       |      |      |
1783 //                       |  W1  |  W2  |
1784 //                       |-------------|
1785 //                       |             |
1786 //                       |     W3      |
1787 //                       ---------------
1788                         \end{verbatim}
1789    
1790     \paragraph{LayoutTLeft} Creates a 'T like' complex container :  Left {RigthUp, RightDown}\\
1791                         %\begin{verbatim}
1792            \texttt{input}  Widget1 : "UpLeft container"\\ 
1793            \texttt{input}  Widget2 : "UpRight container"\\  
1794            \texttt{input}  Wigdet3 : "Down container"\\ 
1795                         \begin{verbatim} 
1796 //                       ---------------
1797 //                       |      |  W2  |
1798 //                       |  W1  |      |
1799 //                       |      |------|
1800 //                       |      |  W3  |
1801 //                       |      |      |
1802 //                       ---------------   
1803                         \end{verbatim}
1804
1805     \paragraph{LayoutTRight} Creates a 'T like' complex container : Right {LeftUp, LeftDown}\\
1806                         %\begin{verbatim}
1807           \texttt{input} Widget1 currentBox.Widget1 "Up container"\\
1808           \texttt{input} Widget2 down.Widget1       "DownLeft container"\\ 
1809           \texttt{input} Widget3 down.Widget2       "DownRight container"\\    
1810                         \begin{verbatim}  
1811 //                       ---------------
1812 //                       |      |      |
1813 //                       |  W1  |      |
1814 //                       |------|  W2  |
1815 //                       |  W3  |      |
1816 //                       |      |      |
1817 //                       ---------------
1818                         \end{verbatim}
1819   
1820     \paragraph{LayoutTUp} Creates a 'T like' complex container : Up {DownLeft, DownRight} as w1{w2,w3}\\ 
1821                         \begin{verbatim} 
1822          \texttt{ input} Widget1 currentBox.Widget1 "Up"\\
1823           \texttt{input} Widget2 down.Widget1       "DownLeft"\\ 
1824           \texttt{input} Widget3 down.Widget2       "DownRight"\\
1825      
1826 //                       ----------------
1827 //                       |    W1        |
1828 //                       |              |
1829 //                       |------|-------|
1830 //                       | W3   |  W2   |
1831 //                       |      |       |
1832 //                       ----------------
1833                 \end{verbatim}
1834                           
1835     \paragraph{LayoutTab} LayoutTab widget (wxNotebook)\\
1836                         %\begin{verbatim}
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 \\   
1847 %\end{verbatim}
1848    
1849     \paragraph{OutputText}              Text zone to be inserted into a window (wxStaticText)\\
1850                         %\begin{verbatim}
1851           \texttt{In} Text \\
1852           \texttt{Title} Title prepended to the text\\   
1853                         %\end{verbatim}
1854                            
1855     \paragraph{RadioButton}             RadioButton group widget 0-9 entries\\
1856                         %\begin{verbatim}
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 
1870                         %\end{verbatim}
1871                            
1872     \paragraph{Slider}          Slider widget (wxSlider)\\
1873                         %\begin{verbatim}
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 '')\\     
1882                         %\end{verbatim}
1883 \end{itemize}
1884 % ==========================================
1885 \subsubsection{Pipeline processing}
1886 \label{bbi-more-on-pipeline-processing}
1887 % ==========================================
1888 \begin{itemize}
1889 \item the ``control'' mechanism in bbi (switch exec commands, e.g. Button)
1890 \item the role of ProcessMode to update widgets.
1891 \end{itemize}
1892 % ==========================================
1893 \subsubsection{Complex black boxes}
1894 \label{bbi-more-on-complex-black-boxes}
1895 Creation of complex widgets (containers, contained...)
1896
1897 %\subsubsection{Advanced issues}
1898 %\paragraph{Reducing the number of inputs of a box}
1899
1900 % ==========================================
1901 \subsubsection{Errors}
1902 \label{bbi-more-on-errors}
1903
1904 % ==========================================
1905 \subsubsection{\bbtk configuration file and search pathes}
1906 \label{bbi-more-on-configuration}
1907
1908 At start, \bbi tries to open an \texttt{xml} 
1909 configuration file named \texttt{bbtk\_config.xml}. 
1910 The search order is 
1911 \begin{enumerate}
1912 \item The current directory
1913 \item The subdir \texttt{.bbtk} of the user's home directory. 
1914 \begin{itemize} 
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:\\...}.
1922 \end{itemize}
1923 \item If none of these two pathes contains the file then it creates 
1924 a new one in the \texttt{.bbtk} directory. 
1925 \end{enumerate}
1926
1927 Once created, you can edit the \texttt{bbtk\_config.xml} file located 
1928 in your \texttt{.bbtk} directory. It contains:
1929
1930 \begin{file}{bbtk\_config.xml}
1931 \begin{verbatim}
1932 <?xml version="1.0" encoding="iso-8859-1"?>
1933 <config>
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>
1938 </config>
1939 \end{verbatim}
1940 \end{file}
1941
1942 You can add pathes to 
1943 \begin{itemize}
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>}.
1948 \end{itemize}
1949
1950 % ==========================================
1951 \subsection{Language reference}
1952 \label{bbi-reference}
1953 % ==========================================
1954
1955
1956
1957
1958
1959 % ==========================================
1960 \begin{table}[!ht]
1961 \caption{\label{bbi-reference-box}
1962 \bbi pipeline creation and execution related commands.}
1963 \small
1964 \begin{tabular}{|lcm{6cm}|}
1965 \hline
1966 Command & Parameters & Effect \\ \hline
1967
1968 \texttt{new} & \texttt{<boxtype>} \texttt{<box-name>}& 
1969 Creates a box of type \texttt{boxtype} and name  
1970 \texttt{box-name}.
1971 \\ \hline
1972
1973 \texttt{delete} & \texttt{<box-name>} & 
1974 Destroys the box named \texttt{box-name}.
1975 \\ \hline 
1976
1977 \texttt{connect} & \texttt{<box1.output>} \texttt{<box2.input>} & 
1978 Connects the output 
1979 \texttt{output} of the box named \texttt{box1} 
1980 to the input \texttt{input} of the box named \texttt{box2} \\ \hline 
1981
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}.
1988  \\ \hline 
1989
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}.
1997 \\ \hline 
1998
1999 \texttt{exec} & \texttt{<box-name>} & 
2000 Executes the box named \texttt{box-name}.
2001 If needed the boxes 
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 
2008 \end{tabular}
2009 \end{table}
2010 % ==========================================
2011
2012
2013
2014 % ==========================================
2015 \begin{table}[!ht]
2016 \caption{\label{bbi-reference-interpreter}\bbi intepreter related commands.}
2017 \small
2018 \begin{tabular}{|lcm{6cm}|}
2019 \hline
2020 Command & Parameters & Effect \\ \hline
2021
2022
2023 \texttt{help} & - & 
2024 Prints help on available commands \\ \hline 
2025
2026 & \texttt{<command-name>} & 
2027 Prints help on the command \texttt{command-name} \\ \hline 
2028
2029 & \texttt{packages} & 
2030 Prints help on available packages and their box types 
2031 (without description)\\ \hline 
2032
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
2037 \\ \hline 
2038
2039 & \texttt{<box-type>} & 
2040 Prints help (with full description) on the type of box 
2041 \texttt{box-type}. 
2042 The box type must belong to a package which has been previously loaded
2043 \\ \hline 
2044
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.
2049 \\ \hline 
2050
2051 \texttt{load} & \texttt{<package-name>} & 
2052 Loads the package \texttt{package-name}\\ \hline 
2053
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 
2056
2057 \texttt{kind} & \texttt{<box kind>} & 
2058 Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline 
2059
2060
2061
2062
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.
2067 \\ \hline 
2068
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}.
2073 \\ \hline 
2074
2075 \texttt{config} & - & Displays the Configuration parameters\\ \hline 
2076
2077 \texttt{reset} & - & Deletes all boxes and unloads all packages so 
2078 that \bbi gets back to its initial state \\ \hline 
2079
2080 \texttt{quit} & - & Exits the interpreter\\ \hline 
2081
2082 \end{tabular}
2083 \end{table}
2084 % ==========================================
2085
2086
2087
2088
2089
2090 % ==========================================
2091 \begin{table}[!ht]
2092 \caption{\label{bbi-reference-complex-box}
2093 \bbi complex black box definition related commands.}
2094 \small
2095 \begin{tabular}{|lcm{6cm}|}
2096 \hline
2097 Command & Parameters & Effect \\ \hline
2098
2099
2100 \texttt{define} & \texttt{<box-type>} & 
2101 Starts the definition of a complex black box of type  
2102 \texttt{box-type}\\ \hline 
2103
2104 \texttt{endefine} & - & 
2105 Ends the definition of a complex black box type\\ \hline 
2106
2107 \texttt{author} & \texttt{<string>} & 
2108 Sets the author(s) of the complex black box currently being defined \\ \hline 
2109
2110 \texttt{description} & \texttt{<string>} & 
2111 Sets the description of the complex black box currently being defined 
2112 \\ \hline 
2113
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}.
2119  
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}.
2123 \\ \hline 
2124
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}. 
2132 \\ \hline 
2133
2134
2135 \end{tabular}
2136 \end{table}
2137 % ==========================================
2138
2139
2140
2141
2142 % ==========================================
2143 \vspace{0.5cm}\hrule
2144 \section{Using black boxes in \CPP programs}
2145 \label{cpp}
2146 % ==========================================
2147
2148
2149
2150
2151 %\bibliography{all}
2152
2153
2154
2155 %\section{Conclusion}
2156 \end{document}
2157