1 % ==========================================
2 \documentclass[11pt,final,a4paper]{article}
16 {\Huge Reference Manual}
19 \bbtk version \bbtkVersion
23 Last modified on : September 20 2008 \\
28 Eduardo Davila, Laurent Guigues, Jean-Pierre Roux
31 CREATIS-LRMN, Centre de Recherche en Imagerie Medicale \\ CNRS UMR 5220, INSERM U620\\
33 Universit\'e Claude-Bernard Lyon 1
40 % ==========================================
42 % ==========================================
50 % ==========================================
52 % ==========================================
54 % ==========================================
59 ---> Should be moved in a 'Reference Manual' ?\\
60 ---> Any suggestion welcome!
62 --> The following is just the concatenation of various parts, removed from different 'manuals', and wainting for
63 their new affectation.
70 \caption{\label{kinds} \texttt{Black Box} kinds}
74 \texttt{Kind name} & : Meaning \\ \hline \\ \hline
75 \texttt{ADAPTOR} & : Adaptor Box \\ \hline
76 \texttt{DEFAULT\_ADAPTOR} & : \\ \hline
77 \texttt{WIDGET\_ADAPTOR} & : \\ \hline
78 \texttt{DEFAULT\_WIDGET\_ADAPTOR} & : \\ \hline
79 \texttt{GUI} & : \\ \hline
80 \texttt{DEFAULT\_GUI} & : \\ \hline
81 \texttt{ALL} & : If kind='ALL' then sets the level for all kinds \\ \hline
88 \bf\emph{Boxes} : Box retrieving on various criterions :
90 \item {\bf\emph{By name}} (Alphabetical list)
91 \item {\bf\emph{By package}} (see table : \ref{bbi-list_of_packages})
92 \item {\bf\emph{By category}} (see table : \ref{categories})
93 \item {\bf\emph{Adaptors}} Used internaly to perform type conversions (not end user intended)
98 % ==========================================
100 \caption{\label{bbi-list_of_packages} List of bbtk supplied packages.}
102 \begin{tabular}{|lp{10cm}|}
104 Package & What it's used for \\ \hline
105 \texttt{std} & : the 'standard' package including basic useful boxes \\ \hline
106 \texttt{wx} & : basic graphical interface elements (widgets : sliders, buttons, etc.) based on the \texttt{wxWidgets} library \\ \hline
107 \itk & : the basic image processing package, based on the \itk library. (without description)\\ \hline
108 \vtk & : prints help on the package \texttt{package-name} and its boxes (with brief description). The package must have been previously loaded\\ \hline
109 \texttt{wxvtk} & : widget boxes based on the \vtk library.\\ \hline
110 \texttt{itkvtk} & : adaptors to convert \itk structures into \vtk structures and conversally.\\ \hline
111 %\texttt{creaImageIO} & : provides high level widgets to read images including DICOM.\\ \hline
112 \texttt{toolsbbtk} & : Tools for bbtk administration and package development.\\ \hline
116 % ==========================================
120 % ==========================================
122 \caption{\label{categories} \texttt{Black Box} categories}
124 \begin{tabular}{|lp{10cm}|}
126 \texttt{Category name} & : Meaning \\ \hline \\ \hline
127 \texttt{adaptor} & : Adaptor box \\ \hline
128 \texttt{application} & : Final application, end user intended \\ \hline
129 \texttt{atomic box} & : System category.
130 Automatically assigned to Atomic Black Boxes (c++ defined) \\ \hline
131 \texttt{complex box} & : System category.
132 Automatically assigned to Complex Black Boxes (script defined) \\ \hline
133 \texttt{command line} & : Script which defines a command line application \\
134 & :(no embedded GUI, but command line imput parameters) \\ \hline
135 \texttt{demo} & : Demonstration \\ \hline
136 \texttt{devel} & : Developer tool (bbCreatePackage.bbs, ...) \\ \hline
137 \texttt{dicom} & : DICOM aware box \\ \hline
138 \texttt{example} & : Example script showing a box use-case \\ \hline
139 \texttt{filter} & : Image processing box \\ \hline
140 \texttt{image} & : Image processing related box \\ \hline
141 \texttt{interaction} & : \\ \hline
142 \texttt{math} & : Mathematical operations \\ \hline
143 \texttt{mesh} & : Mesh processing related box \\ \hline
144 \texttt{misc} & : Box that cannot be put in any other category ! \\ \hline
145 \texttt{read/write} & : Box that read or write data from or to disk \\ \hline
146 \texttt{viewer} & : Box which displays some data \\ \hline
147 \texttt{widget} & : Piece of graphical interface \\ \hline
148 \texttt{3D object creator} & : Sophisticated 3D widget \\ \hline
149 \texttt{toolsbbtk} & : Component of bbStudio \\ \hline
153 % ==========================================
157 % ==========================================
158 \subsubsection{complex black box definition related commands}
159 \label{bbi-reference-black-box-definition}
160 % ==========================================
162 See table \ref{bbi-reference-complex-box}
163 % ==========================================
165 \caption{\label{bbi-reference-complex-box} \bbi complex black box definition related commands.}
167 \begin{tabular}{|lcm{6cm}|}
169 Command & Parameters & Effect \\ \hline
172 \texttt{define} & \texttt{<box-type>} &
173 Starts the definition of a complex black box of type
174 \texttt{box-type}\\ \hline
176 \texttt{endefine} & - &
177 Ends the definition of a complex black box type\\ \hline
179 \texttt{author} & \texttt{<string>} &
180 Sets the author(s) of the complex black box currently being defined \\ \hline
182 \texttt{description} & \texttt{<string>} &
183 Sets the description of the complex black box currently being defined \\ \hline
185 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} &
186 Defines a new input for the current complex black box,
188 It is defined as corresponding to
189 the input \texttt{input} of the box \texttt{box}.
191 \texttt{<help>} is the help string for the new input.
192 The box \texttt{box} must already have been created in the complex box
193 and of course have an input named \texttt{input}.\\ \hline
195 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} &
196 Defines a new output for the current complex black box,
198 It is defined as corresponding to
199 the output \texttt{output} of the box \texttt{box}.
200 \texttt{<help>} is the help string for the new output.
201 The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}. \\ \hline
207 % ==========================================
208 \subsubsection{Interpreter related commands}
209 \label{bbi-reference-interpreter}
210 % ==========================================
211 See table \ref{tabbbi-reference-interpreter_1} and \ref{tabbbi-reference-interpreter_2}
212 % ==========================================
214 \caption{\label{tabbbi-reference-interpreter_1}\bbi intepreter related commands (part 1).}
216 \begin{tabular}{|lcm{6cm}|}
218 Command & Parameters & Effect \\ \hline
220 \texttt{author} & \texttt{<author-name>} &
221 Adds the string \texttt{<author-name>} to the author information of the black box being defined \\ \hline
223 \texttt{category} & \texttt{<category-name>} &
224 Adds the string \texttt{<category-name>} to the category information of the black box being defined \\ \hline
227 Prints help on available commands \\ \hline
229 & \texttt{<command-name>} &
230 Prints help on the command \texttt{command-name} \\ \hline
232 & \texttt{packages} &
233 Prints help on available packages and their box types
234 (without description)\\ \hline
236 & \texttt{<package-name>} &
237 Prints help on the package \texttt{package-name} and its boxes
238 (with brief description).
239 The package must have been previously loaded \\ \hline
241 & \texttt{<box-type>} &
242 Prints help (with full description) on the type of box
244 The box type must belong to a package which has been previously loaded \\ \hline
246 & \texttt{<debug-directive>} &
248 Prints debug info on living bbtk objects containing the string \texttt{expr} (default expr='').
249 \texttt{-C} checks the factory integrity.
250 \texttt{-D} turns on objects debug info after main ends\\ \hline
252 \texttt{include} & \texttt{<file-name>} &
253 Includes and executes the content of the file named \texttt{file-name}
254 exactly like if you were typing its content at the place were the
255 \texttt{include} command is. \\ \hline
257 \texttt{load} & \texttt{<package-name>} &
258 Loads the package \texttt{package-name} (use it only if you know that you won't work with complex black boxes) \\ \hline
260 \texttt{include} & \texttt{<package-name>} &
261 Loads the package \texttt{package-name} and includes all the complex black boxes that comes with it \\ \hline
263 \texttt{kind} & \texttt{<box kind>} &
264 Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline
271 % This arbitrary part1/part2 is to avoid to have all the tables at the end of the docoment ...
275 \caption{\label{tabbbi-reference-interpreter_2}\bbi intepreter related commands (part 2).}
277 \begin{tabular}{|lcm{6cm}|}
279 Command & Parameters & Effect \\ \hline
280 \texttt{unload} & \texttt{<package-name>}&
281 Unloads the package \texttt{package-name}.
282 The package must have been previously loaded.
283 No box of a type defined in this package must still exist.\\ \hline
285 \texttt{message} & \texttt{<category>} \texttt{<level>} &
286 Sets the level of verbosity of \bbi for the category of messages
287 \texttt{category} to \texttt{level}.\\ \hline
288 %See \ref{verbosity}.
290 \texttt{config} & - & Displays the Configuration parameters\\ \hline
292 \texttt{reset} & - & Deletes all boxes and unloads all packages so
293 that \bbi gets back to its initial state \\ \hline
295 \texttt{quit} & - & Exits the interpreter (Don't use it under \bbStudions)\\ \hline
304 ---> Should be moved in a 'Reference Manual' ?\\
305 ---> Any suggestion welcome!
308 % ==========================================
309 \subsubsection{Black box packages}
310 \label{bbi-more-on-packages}
311 % ==========================================
313 There are various others user-intended packages :
316 It contains some vtk based image processing filters :
319 \paragraph{AppendPolyData}
320 Appends one of more polygonal datasets into a single polygonal dataset
322 \paragraph{ConeSource}
325 \paragraph{ImageAnisotropicDiffusion3D}
326 vtk\-Image\-Anisotropic\-Diffusion\-3D dif\-fuses a volume iteratively. \\
327 The neighborhood of the diffusion is determined by the instance flags. \\
328 if 'Faces' is on, the 6 voxels adjoined by faces are included in the neighborhood. \\
329 If 'Edges' is on the 12 edge connected voxels are included, and if 'Corners' is on, the 8 corner connected voxels are included. \\
330 'DiffusionFactor' determines how far a pixel value moves toward its neighbors, and is insensitive to the number of neighbors chosen.\\
331 The diffusion is anisotropic because it only occurs when a gradient measure is below 'GradientThreshold'. \\
332 Two gradient measures exist and are toggled by the 'GradientMagnitudeThreshold' flag. \\
333 When 'GradientMagnitudeThreshold' is on, the magnitude of the gradient, computed by central differences, above 'DiffusionThreshold' a voxel is not
335 The alternative measure examines each neighbor independently.\\
336 The gradient between the voxel and the neighbor must be below the 'DiffusionThreshold' for diffusion to occur with THAT neighbor.\\
338 - In : an image (vtkImageData*)\\
339 - Diffusion : Difference threshold that stops the diffusion\\
341 - Out : the isosurface mesh (vtkPolyData*)
343 \paragraph{ImageCharacteristics}
344 Exports objet sizes, and Spacings
346 \paragraph{ImageDilateErode3D}
348 Dilates one value and erodes another.\\
349 vtkImageDilateErode3D will dilate one value and erode another. \\
350 It uses an elliptical foot print, and only erodes/dilates on the boundary of the two values. \\
351 The filter is restricted to the X, Y, and Z axes for now.\\
352 It can degenerate to a 2 or 1 dimensional filter by setting the kernel size to 1 for a specific axis. \\
353 (bbfication of vtkImageDilateErode3D) \\
355 - In : an image (vtkImageData*)\\
356 - DilateValue : The dilatation value\\
357 - ErodeValue : The erosion value\\
359 - Out : the isosurface mesh (vtkPolyData*)
361 \paragraph{ImageGaussianSmooth}
362 Performs a gaussian convolution of the input image\\
364 - In : an image (vtkImageData*)\\
365 - StdDevX : Standard deviation in X direction\\
366 - StdDevY : Standard deviation in Y direction\\
368 - Out : the isosurface mesh (vtkPolyData*)
370 \paragraph{ImagePlanes}
371 Creates three 3D planes with the input image mapped onto with which the user can interact; \\
372 The output vtkImagePlaneWidget objects are to be inserted into a 3D scene (e.g. a Viewer3D)
374 - In : an image (vtkImageData*)\\
376 - PlaneX : the image plane in X direction (vtkImagePlaneWidget*)\\
377 - PlaneY : the image plane in Y direction (vtkImagePlaneWidget*)\\
378 - PlaneY : the image plane in Z direction (vtkImagePlaneWidget*)\\
381 - Out : the isosurface mesh (vtkPolyData*)
383 \paragraph{IsoSurfaceExtractor}
384 Extracts an iso-surface of a 3D image and creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D)
386 - In : an image (vtkImageData*)\\
387 - Isovalue : the isosurface value (double)\\
388 - Colour : Surface colour (vector of 3 doubles)
390 - Out : the isosurface (vtkProp3D**)
392 \paragraph{MIPCreator}
393 Creates a Maximum Intensity Projection (MIP) view of a 3D image.\\
395 - In : an image (vtkImageData*)\\
396 - Scale : the Gray scale scaling (float) \\
397 - Shift : the Gray scale shift (float) \\
399 - Out : The MIP object (vtkProp3D*) to be plugged into a 3D Viever
401 \paragraph{MarchingCubes}
402 Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes)\\
404 - In : an image (vtkImageData*)\\
405 - Value : the isosurface value (double)\\
407 - Out : the isosurface mesh (vtkPolyData*)
409 \paragraph{MetaImageReader}
410 Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader) \\
412 - In : the name of the file to be read (std::string)
414 - Out : The image (vtkImageData*)
416 \paragraph{SegmentationConnectivity}
417 Segmentation with min max threshold and connectivity \\
419 - In : an image (vtkImageData*)\\
420 - PositionXYZ : initial position (std::vector<int>) \\
421 - ThresholdMinMax : min, max threshold values (std::vector<int>) \\
423 - Out : The image (vtkImageData*)
425 \paragraph{SphereSource}
430 It contains some itk based image processing filters :
432 \paragraph{BinaryThresholdImageFilter}
433 Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter)
436 - In : Input image. Can be any itk::Image<T,D>* \\
437 - InsideValue : Output value for pixels inside thresholds (Double) \\
438 - LowerThreshold : Lower threshold(Double) \\
439 - OutsideValue : Output value for pixels outside thresholds (Double) \\
440 - UpperThreshold : Upper threshold (Double) \\
442 - Out' : Output image. Of the same type and dimension than the input image
444 \paragraph{DICOMSeriesFileNames}
445 Reads a series from a DICOM directory as a 3D itk image
447 \paragraph{ExtractImageFilter}
448 Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)
450 \paragraph{ImageProperties}
451 Outputs different properties of an image (type, dimension, size, spacing, ...)
453 \paragraph{ImageRegion}
454 Creates a generic ImageRegion (bbtk::any) from two vectors providing the index and size of the region.
455 The dimension D of the actual itk::ImageRegion created is the max of the sizes of Index and Size
456 (the smallest vector is padded by zeros)
458 \paragraph{ImageReader}
459 Generic itk image reader
461 \paragraph{ImageWriter}
462 Generic itk image writer
464 \paragraph{ImageSeriesReader}
465 Generic itk image series reader.
467 \paragraph{ResampleImageFilter}
471 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
473 Sorry nothing is done, right now for meshes.
477 It contains two atomic black boxes.
481 - a \textless vtkImageData* \textgreater (In),\\
482 - an Orientation(0:yz / 1:xz / 2:xy),\\
483 - an initial slice number (Slice).\\
485 - a \textless vtkRenderer* \textgreater (Renderer)
489 - up to 5 Input Actors (\textless vtkProp3D* \textgreater),\\
490 - up to 5 Input Observers (\textless vtkInteractorObserver* \textgreater), \\
491 - a boolean 'Stereo' option, to use Red-Blue filter
493 - an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact, \\
494 - a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
496 It contains too some sophisticated complex black boxes :
498 \paragraph{IsoSurfaceWithControls}
499 Image iso-surface extractor (vtk::IsoSurfaceExtractor) with associated control panel (isovalue, opacity and colour)\\
501 - an initial isovalue (Isovalue)
502 - an initial opacity (Opacity)
503 - an initial colour (Colour)
505 \textless vtkProp3D* \textgreater (In)\\
507 \paragraph{MIPWithControls}
508 Maximum Intensity Projection (MIP) creator (vtk::MIPCreator) with associated control panel (shift and scale) \\
510 - an initial scale (Scale)
511 - an initial shift (Shift)
513 \textless vtkProp3D* \textgreater (In)\\
517 Some boxes are the bbfication of usefull xwWidgets, some other ones are more
520 \paragraph{ColourSelector} Colour Selector dialog (bbfication of wxColourSelector) \\
522 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
525 \paragraph{ColourSelectorButton} A button which displays a colour picker dialog when clicked \\
527 \texttt{In} :Initial colour \\
528 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
531 \paragraph{CommandButton} Button which executes bbi commands \\
533 \texttt{In} : Commands to be executed separated by commas (;). Each single quote (') is replaced by a double quote ("). \\
534 \texttt{Label} : Label of the button \\
535 \texttt{Widget} : Output widget \\
538 \paragraph{DirectorySelector} Pops up a directory selection dialog (wxDirDialog)\\
540 \texttt{DefaultDir} : The default directory\\
541 \texttt{Message} : Message to show on the dialog \\
542 \texttt{Title} : Title of the dialog \\
543 \texttt{Out} : The directory selected by the user\\
546 \paragraph{FileSelector} Pops up a file selection dialog for reading or saving (wxFileDialog)\\
548 \texttt{DefaultDir} : The default directory \\
549 \texttt{DefaultFile} : The default filename \\
550 \texttt{Message} : Message to show on the dialog \\
551 \texttt{OpenSave} : Open for an open dialog (default) / Save for a save dialog\\
552 \texttt{Title} : Title of the dialog \\
553 \texttt{Wildcard} : A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" \\
554 \texttt{Out} : The file selected by the user \\
557 \paragraph{InputText} A zone in which the user can enter a text (wxTextCtrl)\\
559 \texttt{In} : Initial text (default '')\\
560 \texttt{Title} : Title of the input zone (default '')\\
561 \texttt{WinTitle} : Title of the window (*)\\
562 \texttt{Out} :Current text\\
565 \paragraph{LayoutLine} LayoutLine widget (wxBoxSizer)\\
567 \texttt{Orientation} Orientation (default V), 0=H=HORIZONTAL , 1=V=VERTICAL \\
568 \texttt{Widget}1 widget 1 \\
569 \texttt{Widget2} widget 2 \\
570 \texttt{Widget3} widget 3 \\
571 \texttt{Widget4} widget 4 \\
572 \texttt{Widget5} widget 5 \\
573 \texttt{Widget6} widget 6 \\
574 \texttt{Widget7} widget 7 \\
575 \texttt{Widget8} widget 8 \\
576 \texttt{Widget9} widget 9\\
579 \paragraph{LayoutSplit} Widget which splits a window in two fixed size parts (wxSplitterWindow)\\
581 \texttt{Orientation} : Orientation (default H), 0=H=HORIZONTAL , 1=V=VERTICAL\\
582 \texttt{Proportion} : Proportion (in percent) of the first children in the window\\
583 \texttt{Widget1} : Upper or left widget\\
584 \texttt{Widget2} : Lower or right widget\\
587 \paragraph{LayoutTDown} Creates a 'T like' complex container : Down {UpLeft, UpRight} \\
589 \texttt{Widget1} : UpLeft container\\
590 \texttt{Widget2} : UpRight container\\
591 \texttt{Widget3} : Down container\\
602 \paragraph{LayoutTLeft} Creates a 'T like' complex container : Left {RigthUp, RightDown}\\
604 \texttt{input} Widget1 : "UpLeft container" \\
605 \texttt{input} Widget2 : "UpRight container" \\
606 \texttt{input} Wigdet3 : "Down container" \\
617 \paragraph{LayoutTRight} Creates a 'T like' complex container : Right {LeftUp, LeftDown}\\
619 \texttt{input} Widget1 currentBox.Widget1 "Up container" \\
620 \texttt{input} Widget2 down.Widget1 "DownLeft container" \\
621 \texttt{input} Widget3 down.Widget2 "DownRight container"\\
632 \paragraph{LayoutTUp} Creates a 'T like' complex container : Up {DownLeft, DownRight} as w1{w2,w3}\\
634 \texttt{ input} Widget1 currentBox.Widget1 "Up" \\
635 \texttt{input} Widget2 down.Widget1 "DownLeft" \\
636 \texttt{input} Widget3 down.Widget2 "DownRight"\\
648 \paragraph{LayoutTab} LayoutTab widget (wxNotebook)\\
650 \texttt{Orientation} Orientation (default T), 0=T=TOP , 1=R=RIGHT , 2=B=BOTTON , 3=L=LEFT \\
651 \texttt{Widget1} widget 1 \\
652 \texttt{Widget2} widget 2 \\
653 \texttt{Widget3} widget 3 \\
654 \texttt{Widget4} widget 4 \\
655 \texttt{Widget5} widget 5 \\
656 \texttt{Widget6} widget 6 \\
657 \texttt{Widget7} widget 7 \\
658 \texttt{Widget8} widget 8 \\
659 \texttt{Widget9} widget 9 \\
662 \paragraph{OutputText} Text zone to be inserted into a window (wxStaticText)\\
665 \texttt{Title} Title prepended to the text\\
668 \paragraph{RadioButton} RadioButton group widget 0-9 entries\\
670 \texttt{In} Set initial item \\
671 \texttt{In0} option 0\\
672 \texttt{In1} option 1\\
673 \texttt{In2} option 2\\
674 \texttt{In3} option 3\\
675 \texttt{In4} option 4\\
676 \texttt{In5} option 5 \\
677 \texttt{In6} option 6 \\
678 \texttt{In7} option 7 \\
679 \texttt{In8} option 8 \\
680 \texttt{In9} option 9 \\
681 \texttt{Title} Title of the widget (default '')\\
682 \texttt{Out} Number of the selected Item
685 \paragraph{Slider} Slider widget (wxSlider)\\
687 \texttt{ChangeResolution} Enables the user to change the slider resolution (default FALSE) \\
688 \texttt{In} Initial slider position(default 0) \\
689 \texttt{Label} Show slider labels ? (default FALSE) \\
690 \texttt{Max} Maximum value of the slider (default 500)\\
691 \texttt{Min} Minimum value of the slider (default 0)\\
692 \texttt{Orientation} Orientation : (default H) 0=H=HORIZONTAL, 1=V=VERTICAL\\
693 \texttt{ReactiveOnTrack} Slider sends info when track moves (default 0 = no)\\
694 \texttt{Title} Title shown above the slider (default '')\\
703 %\section{Conclusion}