1 % ==========================================
2 \documentclass[11pt,final,a4paper]{article}
16 {\Huge Reference Manual}
19 \bbtk version \bbtkVersion
23 Last modified on : September 20 2008 \\
28 Fr\'ed\'eric Cervenansky, Eduardo D\'avila, Laurent Guigues, Jean-Pierre Roux
31 CREATIS, Centre de Recherche en Imagerie M\'edicale \\ CNRS UMR 5220, INSERM U1044\\
33 Universit\'e Claude-Bernard Lyon 1\\
34 http://www.creatis.insa-lyon.fr/site/en/CreatoolsBBTK
41 % ==========================================
43 % ==========================================
51 % ==========================================
53 % ==========================================
55 % ==========================================
60 ---> Should be moved in a 'Reference Manual' ?\\
61 ---> Any suggestion welcome!
63 --> The following is just the concatenation of various parts, removed from different 'manuals', and wainting for
64 their new affectation.
71 \caption{\label{kinds} \texttt{Black Box} kinds}
75 \texttt{Kind name} & : Meaning \\ \hline \\ \hline
76 \texttt{ADAPTOR} & : Adaptor Box \\ \hline
77 \texttt{DEFAULT\_ADAPTOR} & : \\ \hline
78 \texttt{WIDGET\_ADAPTOR} & : \\ \hline
79 \texttt{DEFAULT\_WIDGET\_ADAPTOR} & : \\ \hline
80 \texttt{GUI} & : \\ \hline
81 \texttt{DEFAULT\_GUI} & : \\ \hline
82 \texttt{ALL} & : If kind='ALL' then sets the level for all kinds \\ \hline
89 \bf\emph{Boxes} : Box retrieving on various criterions :
91 \item {\bf\emph{By name}} (Alphabetical list)
92 \item {\bf\emph{By package}} (see table : \ref{bbi-list_of_packages})
93 \item {\bf\emph{By category}} (see table : \ref{categories})
94 \item {\bf\emph{Adaptors}} Used internaly to perform type conversions (not end user intended)
99 % ==========================================
101 \caption{\label{bbi-list_of_packages} List of bbtk supplied packages.}
103 \begin{tabular}{|lp{10cm}|}
105 Package & What it's used for \\ \hline
106 \texttt{std} & : the 'standard' package including basic useful boxes \\ \hline
107 \texttt{wx} & : basic graphical interface elements (widgets : sliders, buttons, etc.) based on the \texttt{wxWidgets} library \\ \hline
108 \itk & : the basic image processing package, based on the \itk library. (without description)\\ \hline
109 \vtk & : prints help on the package \texttt{package-name} and its boxes (with brief description). The package must have been previously loaded\\ \hline
110 \texttt{wxvtk} & : widget boxes based on the \vtk library.\\ \hline
111 \texttt{itkvtk} & : adaptors to convert \itk structures into \vtk structures and conversally.\\ \hline
112 %\texttt{creaImageIO} & : provides high level widgets to read images including DICOM.\\ \hline
113 \texttt{toolsbbtk} & : Tools for bbtk administration and package development.\\ \hline
117 % ==========================================
121 % ==========================================
123 \caption{\label{categories} \texttt{Black Box} categories}
125 \begin{tabular}{|lp{10cm}|}
127 \texttt{Category name} & : Meaning \\ \hline \\ \hline
128 \texttt{adaptor} & : Adaptor box \\ \hline
129 \texttt{application} & : Final application, end user intended \\ \hline
130 \texttt{atomic box} & : System category.
131 Automatically assigned to Atomic Black Boxes (c++ defined) \\ \hline
132 \texttt{complex box} & : System category.
133 Automatically assigned to Complex Black Boxes (script defined) \\ \hline
134 \texttt{command line} & : Script which defines a command line application \\
135 & :(no embedded GUI, but command line imput parameters) \\ \hline
136 \texttt{demo} & : Demonstration \\ \hline
137 \texttt{devel} & : Developer tool (bbCreatePackage.bbs, ...) \\ \hline
138 \texttt{dicom} & : DICOM aware box \\ \hline
139 \texttt{example} & : Example script showing a box use-case \\ \hline
140 \texttt{filter} & : Image processing box \\ \hline
141 \texttt{image} & : Image processing related box \\ \hline
142 \texttt{interaction} & : \\ \hline
143 \texttt{math} & : Mathematical operations \\ \hline
144 \texttt{mesh} & : Mesh processing related box \\ \hline
145 \texttt{misc} & : Box that cannot be put in any other category ! \\ \hline
146 \texttt{read/write} & : Box that read or write data from or to disk \\ \hline
147 \texttt{viewer} & : Box which displays some data \\ \hline
148 \texttt{widget} & : Piece of graphical interface \\ \hline
149 \texttt{3D object creator} & : Sophisticated 3D widget \\ \hline
150 \texttt{toolsbbtk} & : Component of bbStudio \\ \hline
154 % ==========================================
158 % ==========================================
159 \subsubsection{complex black box definition related commands}
160 \label{bbi-reference-black-box-definition}
161 % ==========================================
163 See table \ref{bbi-reference-complex-box}
164 % ==========================================
166 \caption{\label{bbi-reference-complex-box} \bbi complex black box definition related commands.}
168 \begin{tabular}{|lcm{6cm}|}
170 Command & Parameters & Effect \\ \hline
173 \texttt{define} & \texttt{<box-type>} &
174 Starts the definition of a complex black box of type
175 \texttt{box-type}\\ \hline
177 \texttt{endefine} & - &
178 Ends the definition of a complex black box type\\ \hline
180 \texttt{author} & \texttt{<string>} &
181 Sets the author(s) of the complex black box currently being defined \\ \hline
183 \texttt{description} & \texttt{<string>} &
184 Sets the description of the complex black box currently being defined \\ \hline
186 \texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} &
187 Defines a new input for the current complex black box,
189 It is defined as corresponding to
190 the input \texttt{input} of the box \texttt{box}.
192 \texttt{<help>} is the help string for the new input.
193 The box \texttt{box} must already have been created in the complex box
194 and of course have an input named \texttt{input}.\\ \hline
196 \texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} &
197 Defines a new output for the current complex black box,
199 It is defined as corresponding to
200 the output \texttt{output} of the box \texttt{box}.
201 \texttt{<help>} is the help string for the new output.
202 The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}. \\ \hline
208 % ==========================================
209 \subsubsection{Interpreter related commands}
210 \label{bbi-reference-interpreter}
211 % ==========================================
212 See table \ref{tabbbi-reference-interpreter_1} and \ref{tabbbi-reference-interpreter_2}
213 % ==========================================
215 \caption{\label{tabbbi-reference-interpreter_1}\bbi intepreter related commands (part 1).}
217 \begin{tabular}{|lcm{6cm}|}
219 Command & Parameters & Effect \\ \hline
221 \texttt{author} & \texttt{<author-name>} &
222 Adds the string \texttt{<author-name>} to the author information of the black box being defined \\ \hline
224 \texttt{category} & \texttt{<category-name>} &
225 Adds the string \texttt{<category-name>} to the category information of the black box being defined \\ \hline
228 Prints help on available commands \\ \hline
230 & \texttt{<command-name>} &
231 Prints help on the command \texttt{command-name} \\ \hline
233 & \texttt{packages} &
234 Prints help on available packages and their box types
235 (without description)\\ \hline
237 & \texttt{<package-name>} &
238 Prints help on the package \texttt{package-name} and its boxes
239 (with brief description).
240 The package must have been previously loaded \\ \hline
242 & \texttt{<box-type>} &
243 Prints help (with full description) on the type of box
245 The box type must belong to a package which has been previously loaded \\ \hline
247 & \texttt{<debug-directive>} &
249 Prints debug info on living bbtk objects containing the string \texttt{expr} (default expr='').
250 \texttt{-C} checks the factory integrity.
251 \texttt{-D} turns on objects debug info after main ends\\ \hline
253 \texttt{include} & \texttt{<file-name>} &
254 Includes and executes the content of the file named \texttt{file-name}
255 exactly like if you were typing its content at the place were the
256 \texttt{include} command is. \\ \hline
258 \texttt{load} & \texttt{<package-name>} &
259 Loads the package \texttt{package-name} (use it only if you know that you won't work with complex black boxes) \\ \hline
261 \texttt{include} & \texttt{<package-name>} &
262 Loads the package \texttt{package-name} and includes all the complex black boxes that comes with it \\ \hline
264 \texttt{kind} & \texttt{<box kind>} &
265 Specifies the \texttt{kind} of the complex black boxes you are describing \\ \hline
272 % This arbitrary part1/part2 is to avoid to have all the tables at the end of the docoment ...
276 \caption{\label{tabbbi-reference-interpreter_2}\bbi intepreter related commands (part 2).}
278 \begin{tabular}{|lcm{6cm}|}
280 Command & Parameters & Effect \\ \hline
281 \texttt{unload} & \texttt{<package-name>}&
282 Unloads the package \texttt{package-name}.
283 The package must have been previously loaded.
284 No box of a type defined in this package must still exist.\\ \hline
286 \texttt{message} & \texttt{<category>} \texttt{<level>} &
287 Sets the level of verbosity of \bbi for the category of messages
288 \texttt{category} to \texttt{level}.\\ \hline
289 %See \ref{verbosity}.
291 \texttt{config} & - & Displays the Configuration parameters\\ \hline
293 \texttt{reset} & - & Deletes all boxes and unloads all packages so
294 that \bbi gets back to its initial state \\ \hline
296 \texttt{quit} & - & Exits the interpreter (Don't use it under \bbStudions)\\ \hline
305 ---> Should be moved in a 'Reference Manual' ?\\
306 ---> Any suggestion welcome!
309 % ==========================================
310 \subsubsection{Black box packages}
311 \label{bbi-more-on-packages}
312 % ==========================================
314 There are various others user-intended packages :
317 It contains some vtk based image processing filters :
320 \paragraph{AppendPolyData}
321 Appends one of more polygonal datasets into a single polygonal dataset
323 \paragraph{ConeSource}
326 \paragraph{ImageAnisotropicDiffusion3D}
327 vtk\-Image\-Anisotropic\-Diffusion\-3D dif\-fuses a volume iteratively. \\
328 The neighborhood of the diffusion is determined by the instance flags. \\
329 if 'Faces' is on, the 6 voxels adjoined by faces are included in the neighborhood. \\
330 If 'Edges' is on the 12 edge connected voxels are included, and if 'Corners' is on, the 8 corner connected voxels are included. \\
331 'DiffusionFactor' determines how far a pixel value moves toward its neighbors, and is insensitive to the number of neighbors chosen.\\
332 The diffusion is anisotropic because it only occurs when a gradient measure is below 'GradientThreshold'. \\
333 Two gradient measures exist and are toggled by the 'GradientMagnitudeThreshold' flag. \\
334 When 'GradientMagnitudeThreshold' is on, the magnitude of the gradient, computed by central differences, above 'DiffusionThreshold' a voxel is not
336 The alternative measure examines each neighbor independently.\\
337 The gradient between the voxel and the neighbor must be below the 'DiffusionThreshold' for diffusion to occur with THAT neighbor.\\
339 - In : an image (vtkImageData*)\\
340 - Diffusion : Difference threshold that stops the diffusion\\
342 - Out : the isosurface mesh (vtkPolyData*)
344 \paragraph{ImageCharacteristics}
345 Exports objet sizes, and Spacings
347 \paragraph{ImageDilateErode3D}
349 Dilates one value and erodes another.\\
350 vtkImageDilateErode3D will dilate one value and erode another. \\
351 It uses an elliptical foot print, and only erodes/dilates on the boundary of the two values. \\
352 The filter is restricted to the X, Y, and Z axes for now.\\
353 It can degenerate to a 2 or 1 dimensional filter by setting the kernel size to 1 for a specific axis. \\
354 (bbfication of vtkImageDilateErode3D) \\
356 - In : an image (vtkImageData*)\\
357 - DilateValue : The dilatation value\\
358 - ErodeValue : The erosion value\\
360 - Out : the isosurface mesh (vtkPolyData*)
362 \paragraph{ImageGaussianSmooth}
363 Performs a gaussian convolution of the input image\\
365 - In : an image (vtkImageData*)\\
366 - StdDevX : Standard deviation in X direction\\
367 - StdDevY : Standard deviation in Y direction\\
369 - Out : the isosurface mesh (vtkPolyData*)
371 \paragraph{ImagePlanes}
372 Creates three 3D planes with the input image mapped onto with which the user can interact; \\
373 The output vtkImagePlaneWidget objects are to be inserted into a 3D scene (e.g. a Viewer3D)
375 - In : an image (vtkImageData*)\\
377 - PlaneX : the image plane in X direction (vtkImagePlaneWidget*)\\
378 - PlaneY : the image plane in Y direction (vtkImagePlaneWidget*)\\
379 - PlaneY : the image plane in Z direction (vtkImagePlaneWidget*)\\
382 - Out : the isosurface mesh (vtkPolyData*)
384 \paragraph{IsoSurfaceExtractor}
385 Extracts an iso-surface of a 3D image and creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D)
387 - In : an image (vtkImageData*)\\
388 - Isovalue : the isosurface value (double)\\
389 - Colour : Surface colour (vector of 3 doubles)
391 - Out : the isosurface (vtkProp3D**)
393 \paragraph{MIPCreator}
394 Creates a Maximum Intensity Projection (MIP) view of a 3D image.\\
396 - In : an image (vtkImageData*)\\
397 - Scale : the Gray scale scaling (float) \\
398 - Shift : the Gray scale shift (float) \\
400 - Out : The MIP object (vtkProp3D*) to be plugged into a 3D Viever
402 \paragraph{MarchingCubes}
403 Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes)\\
405 - In : an image (vtkImageData*)\\
406 - Value : the isosurface value (double)\\
408 - Out : the isosurface mesh (vtkPolyData*)
410 \paragraph{MetaImageReader}
411 Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader) \\
413 - In : the name of the file to be read (std::string)
415 - Out : The image (vtkImageData*)
417 \paragraph{SegmentationConnectivity}
418 Segmentation with min max threshold and connectivity \\
420 - In : an image (vtkImageData*)\\
421 - PositionXYZ : initial position (std::vector<int>) \\
422 - ThresholdMinMax : min, max threshold values (std::vector<int>) \\
424 - Out : The image (vtkImageData*)
426 \paragraph{SphereSource}
431 It contains some itk based image processing filters :
433 \paragraph{BinaryThresholdImageFilter}
434 Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter)
437 - In : Input image. Can be any itk::Image<T,D>* \\
438 - InsideValue : Output value for pixels inside thresholds (Double) \\
439 - LowerThreshold : Lower threshold(Double) \\
440 - OutsideValue : Output value for pixels outside thresholds (Double) \\
441 - UpperThreshold : Upper threshold (Double) \\
443 - Out' : Output image. Of the same type and dimension than the input image
445 \paragraph{DICOMSeriesFileNames}
446 Reads a series from a DICOM directory as a 3D itk image
448 \paragraph{ExtractImageFilter}
449 Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)
451 \paragraph{ImageProperties}
452 Outputs different properties of an image (type, dimension, size, spacing, ...)
454 \paragraph{ImageRegion}
455 Creates a generic ImageRegion (bbtk::any) from two vectors providing the index and size of the region.
456 The dimension D of the actual itk::ImageRegion created is the max of the sizes of Index and Size
457 (the smallest vector is padded by zeros)
459 \paragraph{ImageReader}
460 Generic itk image reader
462 \paragraph{ImageWriter}
463 Generic itk image writer
465 \paragraph{ImageSeriesReader}
466 Generic itk image series reader.
468 \paragraph{ResampleImageFilter}
472 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
474 Sorry nothing is done, right now for meshes.
478 It contains two atomic black boxes.
482 - a \textless vtkImageData* \textgreater (In),\\
483 - an Orientation(0:yz / 1:xz / 2:xy),\\
484 - an initial slice number (Slice).\\
486 - a \textless vtkRenderer* \textgreater (Renderer)
490 - up to 5 Input Actors (\textless vtkProp3D* \textgreater),\\
491 - up to 5 Input Observers (\textless vtkInteractorObserver* \textgreater), \\
492 - a boolean 'Stereo' option, to use Red-Blue filter
494 - an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact, \\
495 - a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
497 It contains too some sophisticated complex black boxes :
499 \paragraph{IsoSurfaceWidget}
500 Image iso-surface extractor (vtk::IsoSurfaceExtractor) with associated control panel (isovalue, opacity and colour)\\
502 - an initial isovalue (Isovalue)
503 - an initial opacity (Opacity)
504 - an initial colour (Colour)
506 \textless vtkProp3D* \textgreater (In)\\
508 \paragraph{MIPWidget}
509 Maximum Intensity Projection (MIP) creator (vtk::MIPCreator) with associated control panel (shift and scale) \\
511 - an initial scale (Scale)
512 - an initial shift (Shift)
514 \textless vtkProp3D* \textgreater (In)\\
518 Some boxes are the bbfication of usefull xwWidgets, some other ones are more
521 \paragraph{ColourSelector} Colour Selector dialog (bbfication of wxColourSelector) \\
523 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
526 \paragraph{ColourSelectorButton} A button which displays a colour picker dialog when clicked \\
528 \texttt{In} :Initial colour \\
529 \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
532 \paragraph{CommandButton} Button which executes bbi commands \\
534 \texttt{In} : Commands to be executed separated by commas (;). Each single quote (') is replaced by a double quote ("). \\
535 \texttt{Label} : Label of the button \\
536 \texttt{Widget} : Output widget \\
539 \paragraph{DirectorySelector} Pops up a directory selection dialog (wxDirDialog)\\
541 \texttt{DefaultDir} : The default directory\\
542 \texttt{Message} : Message to show on the dialog \\
543 \texttt{Title} : Title of the dialog \\
544 \texttt{Out} : The directory selected by the user\\
547 \paragraph{FileSelector} Pops up a file selection dialog for reading or saving (wxFileDialog)\\
549 \texttt{DefaultDir} : The default directory \\
550 \texttt{DefaultFile} : The default filename \\
551 \texttt{Message} : Message to show on the dialog \\
552 \texttt{OpenSave} : Open for an open dialog (default) / Save for a save dialog\\
553 \texttt{Title} : Title of the dialog \\
554 \texttt{Wildcard} : A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" \\
555 \texttt{Out} : The file selected by the user \\
558 \paragraph{InputText} A zone in which the user can enter a text (wxTextCtrl)\\
560 \texttt{In} : Initial text (default '')\\
561 \texttt{Title} : Title of the input zone (default '')\\
562 \texttt{WinTitle} : Title of the window (*)\\
563 \texttt{Out} :Current text\\
566 \paragraph{LayoutLine} LayoutLine widget (wxBoxSizer)\\
568 \texttt{Orientation} Orientation (default V), 0=H=HORIZONTAL , 1=V=VERTICAL \\
569 \texttt{Widget}1 widget 1 \\
570 \texttt{Widget2} widget 2 \\
571 \texttt{Widget3} widget 3 \\
572 \texttt{Widget4} widget 4 \\
573 \texttt{Widget5} widget 5 \\
574 \texttt{Widget6} widget 6 \\
575 \texttt{Widget7} widget 7 \\
576 \texttt{Widget8} widget 8 \\
577 \texttt{Widget9} widget 9\\
580 \paragraph{LayoutSplit} Widget which splits a window in two fixed size parts (wxSplitterWindow)\\
582 \texttt{Orientation} : Orientation (default H), 0=H=HORIZONTAL , 1=V=VERTICAL\\
583 \texttt{Proportion} : Proportion (in percent) of the first children in the window\\
584 \texttt{Widget1} : Upper or left widget\\
585 \texttt{Widget2} : Lower or right widget\\
588 \paragraph{LayoutTDown} Creates a 'T like' complex container : Down {UpLeft, UpRight} \\
590 \texttt{Widget1} : UpLeft container\\
591 \texttt{Widget2} : UpRight container\\
592 \texttt{Widget3} : Down container\\
603 \paragraph{LayoutTLeft} Creates a 'T like' complex container : Left {RigthUp, RightDown}\\
605 \texttt{input} Widget1 : "UpLeft container" \\
606 \texttt{input} Widget2 : "UpRight container" \\
607 \texttt{input} Wigdet3 : "Down container" \\
618 \paragraph{LayoutTRight} Creates a 'T like' complex container : Right {LeftUp, LeftDown}\\
620 \texttt{input} Widget1 currentBox.Widget1 "Up container" \\
621 \texttt{input} Widget2 down.Widget1 "DownLeft container" \\
622 \texttt{input} Widget3 down.Widget2 "DownRight container"\\
633 \paragraph{LayoutTUp} Creates a 'T like' complex container : Up {DownLeft, DownRight} as w1{w2,w3}\\
635 \texttt{ input} Widget1 currentBox.Widget1 "Up" \\
636 \texttt{input} Widget2 down.Widget1 "DownLeft" \\
637 \texttt{input} Widget3 down.Widget2 "DownRight"\\
649 \paragraph{LayoutTab} LayoutTab widget (wxNotebook)\\
651 \texttt{Orientation} Orientation (default T), 0=T=TOP , 1=R=RIGHT , 2=B=BOTTON , 3=L=LEFT \\
652 \texttt{Widget1} widget 1 \\
653 \texttt{Widget2} widget 2 \\
654 \texttt{Widget3} widget 3 \\
655 \texttt{Widget4} widget 4 \\
656 \texttt{Widget5} widget 5 \\
657 \texttt{Widget6} widget 6 \\
658 \texttt{Widget7} widget 7 \\
659 \texttt{Widget8} widget 8 \\
660 \texttt{Widget9} widget 9 \\
663 \paragraph{OutputText} Text zone to be inserted into a window (wxStaticText)\\
666 \texttt{Title} Title prepended to the text\\
669 \paragraph{RadioButton} RadioButton group widget 0-9 entries\\
671 \texttt{In} Set initial item \\
672 \texttt{In0} option 0\\
673 \texttt{In1} option 1\\
674 \texttt{In2} option 2\\
675 \texttt{In3} option 3\\
676 \texttt{In4} option 4\\
677 \texttt{In5} option 5 \\
678 \texttt{In6} option 6 \\
679 \texttt{In7} option 7 \\
680 \texttt{In8} option 8 \\
681 \texttt{In9} option 9 \\
682 \texttt{Title} Title of the widget (default '')\\
683 \texttt{Out} Number of the selected Item
686 \paragraph{Slider} Slider widget (wxSlider)\\
688 \texttt{ChangeResolution} Enables the user to change the slider resolution (default FALSE) \\
689 \texttt{In} Initial slider position(default 0) \\
690 \texttt{Label} Show slider labels ? (default FALSE) \\
691 \texttt{Max} Maximum value of the slider (default 500)\\
692 \texttt{Min} Minimum value of the slider (default 0)\\
693 \texttt{Orientation} Orientation : (default H) 0=H=HORIZONTAL, 1=V=VERTICAL\\
694 \texttt{ReactiveOnTrack} Slider sends info when track moves (default 0 = no)\\
695 \texttt{Title} Title shown above the slider (default '')\\
704 %\section{Conclusion}