]> Creatis software - bbtk.git/blob - kernel/doc/bbtkUsersGuide/bbtkReferenceManual.tex
*** empty log message ***
[bbtk.git] / kernel / doc / bbtkUsersGuide / bbtkReferenceManual.tex
1 % ==========================================
2 \documentclass[11pt,final,a4paper]{article}
3 \input{config.tex}
4
5
6
7
8 \begin{document}
9 \begin{center}
10
11 {\Large \BBTK}
12 \vspace{1cm}
13
14 {\Huge Reference Manual}
15 \vspace{1cm}
16
17 \bbtk version 1.0
18 \vspace{0.5cm}
19
20
21 Last modified on : September 20, 2008 \\
22 Generated on : \today 
23 \vspace{0.5cm}
24
25 Fantomas, Belphegor
26 \end{center}
27
28 % ==========================================
29 \tableofcontents
30 % ==========================================
31
32 \listoftables
33
34 \listoffigures
35
36
37
38 % ==========================================
39 %\section*{Abstract}
40 % ==========================================
41 \newpage
42 % ==========================================
43 \hrule
44
45
46 \begin{verbatim}
47 ---> Should be moved in a 'Reference Manual' ?\\
48 ---> Any suggestion welcome!
49 \end{verbatim}
50
51 \section{aaa}
52 \subsection{bbb}
53
54 \begin{table}[!ht]
55 \caption{\label{kinds} \texttt{Black Box} kinds}
56 \small
57 \begin{tabular}{|ll|}
58 \hline
59 \texttt{Kind name}                & : Meaning                         \\ \hline \\ \hline
60 \texttt{ADAPTOR}                  & : Adaptor Box                     \\ \hline
61 \texttt{DEFAULT\_ADAPTOR}         & :                                  \\ \hline
62 \texttt{WIDGET\_ADAPTOR}          & :                                  \\ \hline
63 \texttt{DEFAULT\_WIDGET\_ADAPTOR} & :                                  \\ \hline
64 \texttt{GUI}                      & :                                  \\ \hline
65 \texttt{DEFAULT\_GUI}             & :                                  \\ \hline
66 \texttt{ALL}                      & : If kind='ALL' then sets the level for all kinds \\ \hline
67 \end{tabular}
68 \end{table}
69
70
71
72         
73    \bf\emph{Boxes} : Box retrieving on various criterions :
74       \begin{itemize}
75         \item {\bf\emph{By name}} (Alphabetical list)
76         \item {\bf\emph{By package}} (see table : \ref{bbi-list_of_packages})
77         \item {\bf\emph{By category}} (see table : \ref{categories})
78         \item {\bf\emph{Adaptors}} Used internaly to perform type conversions (not end user intended)     
79       \end{itemize}
80
81
82
83 % ==========================================
84 \begin{table}[!ht]
85 \caption{\label{bbi-list_of_packages} List of bbtk supplied packages.}
86 \small
87 \begin{tabular}{|lp{10cm}|}
88 \hline
89 Package         & What it's used for \\ \hline
90 \texttt{std}    & : the 'standard' package including basic useful boxes \\ \hline 
91 \texttt{wx}     & : basic graphical interface elements (widgets : sliders, buttons, etc.) based on the \texttt{wxWidgets} library \\ \hline 
92 \itk    & : the basic image processing package, based on the \itk library. (without description)\\ \hline 
93 \vtk    & : prints help on the package \texttt{package-name} and its boxes (with brief description). The package must have been previously loaded\\ \hline 
94 \texttt{wxvtk}  & : widget boxes based on the \vtk library.\\ \hline 
95 \texttt{itkvtk} & : adaptors to convert \itk structures into \vtk structures and conversally.\\ \hline 
96 %\texttt{creaImageIO} & : provides high level widgets to read images including DICOM.\\ \hline 
97 \texttt{toolsbbtk} & : Tools for bbtk administration and package development.\\ \hline 
98
99 \end{tabular}
100 \end{table}
101 % ==========================================
102
103
104
105 % ==========================================
106 \begin{table}[!ht]
107 \caption{\label{categories} \texttt{Black Box} categories}
108 \small
109 \begin{tabular}{|lp{10cm}|}
110 \hline
111  \texttt{Category name}  & : Meaning                                          \\ \hline \\ \hline
112  \texttt{adaptor}        & : Adaptor box                                      \\ \hline
113  \texttt{application}    & : Final application, end user intended             \\ \hline
114  \texttt{atomic box}     & : System category.
115                Automatically assigned to Atomic Black Boxes (c++ defined)     \\ \hline
116  \texttt{complex box}    & : System category.
117                Automatically assigned to Complex Black Boxes (script defined) \\ \hline  
118  \texttt{command line}   & : Script which defines a command line application \\ 
119                          & :(no embedded GUI, but command line imput parameters) \\ \hline
120  \texttt{demo}           & : Demonstration                             \\ \hline
121  \texttt{devel}          & : Developer tool (bbCreatePackage.bbs, ...) \\ \hline
122  \texttt{dicom}          & : DICOM aware box                            \\ \hline 
123  \texttt{example}        & : Example script showing a box use-case      \\ \hline
124  \texttt{filter}         & : Image processing box                       \\ \hline
125  \texttt{image}          & : Image processing related box               \\ \hline
126  \texttt{interaction}    & :                                            \\ \hline
127  \texttt{math}           & : Mathematical operations                    \\ \hline
128  \texttt{mesh}           & : Mesh processing related box                 \\ \hline
129  \texttt{misc}           & : Box that cannot be put in any other category ! \\ \hline
130  \texttt{read/write}     & : Box that read or write data from or to disk  \\ \hline
131  \texttt{viewer}         & : Box which displays some data                \\ \hline
132  \texttt{widget}         & : Piece of graphical interface                \\ \hline  
133  \texttt{3D object creator} & : Sophisticated 3D widget  \\ \hline  
134  \texttt{toolsbbtk}         & : Component of bbStudio    \\ \hline  
135 \end{tabular}
136 \end{table}
137
138 % ==========================================
139
140
141
142
143
144 \subsection{ccc}
145
146 \begin{verbatim}
147 ---> Should be moved in a 'Reference Manual' ?\\
148 ---> Any suggestion welcome!
149 \end{verbatim}
150
151 % ==========================================
152 \subsubsection{Black box packages}
153 \label{bbi-more-on-packages}
154 % ==========================================
155
156 There are various others user-intended packages :
157 \begin{itemize}
158 \item{vtk} \\
159 It contains some vtk based image processing filters :
160 %   \begin{enumerate}
161
162      \paragraph{AppendPolyData}
163      Appends one of more polygonal datasets into a single polygonal dataset 
164
165      \paragraph{ConeSource}
166      Creates a Cone 
167
168      \paragraph{ImageAnisotropicDiffusion3D}
169 vtk\-Image\-Anisotropic\-Diffusion\-3D dif\-fuses a volume iteratively. \\
170 The neighborhood of the diffusion is determined by the instance flags. \\
171 if 'Faces' is on, the 6 voxels adjoined by faces are included in the neighborhood. \\
172 If 'Edges' is on the 12 edge connected voxels are included, and if 'Corners' is on, the 8 corner connected voxels are included. \\
173 'DiffusionFactor' determines how far a pixel value moves toward its neighbors, and is insensitive to the number of neighbors chosen.\\ 
174 The diffusion is anisotropic because it only occurs when a gradient measure is below 'GradientThreshold'. \\
175 Two gradient measures exist and are toggled by the 'GradientMagnitudeThreshold' flag. \\
176 When 'GradientMagnitudeThreshold' is on, the magnitude of the gradient, computed by central differences, above 'DiffusionThreshold' a voxel is not
177 modified. \\
178 The alternative measure examines each neighbor independently.\\ 
179 The gradient between the voxel and the neighbor must be below the 'DiffusionThreshold' for diffusion to occur with THAT neighbor.\\
180      Receives : \\
181      - In : an image (vtkImageData*)\\
182      - Diffusion : Difference threshold that stops the diffusion\\
183      Outputs : \\
184      - Out : the isosurface mesh (vtkPolyData*)
185      
186      \paragraph{ImageCharacteristics}
187      Exports objet sizes, and Spacings
188      
189      \paragraph{ImageDilateErode3D}
190
191      Dilates one value and erodes another.\\ 
192      vtkImageDilateErode3D will dilate one value and erode another. \\
193      It uses an elliptical foot print, and only erodes/dilates on the boundary of the two values. \\
194      The filter is restricted to the X, Y, and Z axes for now.\\ 
195      It can degenerate to a 2 or 1 dimensional filter by setting the kernel size to 1 for a specific axis. \\
196      (bbfication of vtkImageDilateErode3D) \\
197      Receives : \\
198      - In : an image (vtkImageData*)\\
199      - DilateValue : The dilatation value\\
200      - ErodeValue : The erosion value\\
201      Outputs : \\
202      - Out : the isosurface mesh (vtkPolyData*)     
203      
204      \paragraph{ImageGaussianSmooth}
205      Performs a gaussian convolution of the input image\\
206      Receives : \\
207      - In : an image (vtkImageData*)\\
208      - StdDevX : Standard deviation in X direction\\
209      - StdDevY : Standard deviation in Y direction\\
210      Outputs : \\
211      - Out : the isosurface mesh (vtkPolyData*)       
212      
213      \paragraph{ImagePlanes}
214      Creates three 3D planes with the input image mapped onto with which the user can interact; \\ 
215      The output vtkImagePlaneWidget objects are to be inserted into a 3D scene (e.g. a Viewer3D)
216      Receives : \\
217      - In : an image (vtkImageData*)\\
218      Outputs : \\     
219      - PlaneX : the image plane in X direction (vtkImagePlaneWidget*)\\
220      - PlaneY : the image plane in Y direction (vtkImagePlaneWidget*)\\
221      - PlaneY : the image plane in Z direction (vtkImagePlaneWidget*)\\
222      
223           Outputs : \\
224      - Out : the isosurface mesh (vtkPolyData*)  
225            
226      \paragraph{IsoSurfaceExtractor}
227      Extracts an iso-surface of a 3D image and creates a vtkProp3D object to insert into a 3D scene (e.g. a Viewer3D)
228      Receives : \\
229      - In : an image (vtkImageData*)\\
230      - Isovalue : the isosurface value (double)\\
231      - Colour : Surface colour (vector of 3 doubles)
232      Outputs : \\
233      - Out : the isosurface (vtkProp3D**)
234      
235       \paragraph{MIPCreator}     
236      Creates a Maximum Intensity Projection (MIP) view of a 3D image.\\
237      Receives : \\
238      - In : an image (vtkImageData*)\\
239      - Scale : the Gray scale scaling (float) \\
240      - Shift : the Gray scale shift (float) \\    
241      Ouputs : \\
242      - Out : The MIP object (vtkProp3D*) to be plugged into a 3D Viever
243     
244      \paragraph{MarchingCubes}
245      Extracts an iso-surface of an image using the marching cubes algorithm (bbfication of vtkMarchingCubes)\\
246      Receives : \\
247      - In : an image (vtkImageData*)\\
248      - Value : the isosurface value (double)\\
249      Outputs : \\
250      - Out : the isosurface mesh (vtkPolyData*)
251
252      \paragraph{MetaImageReader}
253      Reads .mhd / .mhd image formats (bbfication of vtkMetaImageReader) \\
254      Receives : \\
255      - In : the name of the file to be read (std::string)
256      Outputs :
257      - Out : The image (vtkImageData*)     
258      
259      \paragraph{SegmentationConnectivity}
260      Segmentation with min max threshold and connectivity  \\  
261      Receives : \\
262      - In : an image (vtkImageData*)\\
263      - PositionXYZ : initial position (std::vector<int>) \\
264      - ThresholdMinMax : min, max threshold values (std::vector<int>) \\
265      Outputs : \\
266      - Out : The image (vtkImageData*)       
267           
268      \paragraph{SphereSource}
269      Creates a Sphere      
270 %   \end{enumerate}
271
272 \item{itk} \\
273 It contains some itk based image processing filters :
274  
275      \paragraph{BinaryThresholdImageFilter}
276      Binarizes an image by thresholding (generic bbification of itk::BinaryThresholdImageFilter) 
277      Receives : \\ 
278
279       - In :             Input image. Can be any itk::Image<T,D>*    \\
280       - InsideValue :    Output value for pixels inside thresholds (Double)    \\
281       - LowerThreshold :   Lower threshold(Double)    \\
282       - OutsideValue   :   Output value for pixels outside thresholds (Double)    \\
283       - UpperThreshold :   Upper threshold (Double)    \\
284       Outputs :     \\
285       - Out'        : Output image. Of the same type and dimension than the input image
286      
287      \paragraph{DICOMSeriesFileNames}
288      Reads a series from a DICOM directory as a 3D itk image     
289
290      \paragraph{ExtractImageFilter}
291      Decrease the image size by cropping the image to the selected region bounds (bbification of itk::ExtractImageFilter)     
292
293      \paragraph{ImageProperties}
294      Outputs different properties of an image (type, dimension, size, spacing, ...)      
295
296      \paragraph{ImageRegion}
297 Creates a generic ImageRegion (bbtk::any) from two vectors providing the index and size of the region. 
298 The dimension D of the actual itk::ImageRegion created is the max of the sizes of Index and Size 
299 (the smallest vector is padded by zeros)     
300
301      \paragraph{ImageReader}
302 Generic itk image reader
303
304      \paragraph{ImageWriter}
305 Generic itk image writer
306
307      \paragraph{ImageSeriesReader}
308 Generic itk image series reader.
309
310      \paragraph{ResampleImageFilter}
311 Resamples an image
312
313 \item{itkvtk} \\
314 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 
315
316 Sorry nothing is done, right now for meshes. 
317
318 \item{wxvtk} \\
319
320 It contains two atomic black boxes.
321
322      \paragraph{Viewer2D} 
323      Receives : \\
324      - a \textless vtkImageData* \textgreater (In),\\
325      - an Orientation(0:yz / 1:xz / 2:xy),\\
326      - an initial slice number (Slice).\\
327      Outputs :\\
328      - a \textless vtkRenderer* \textgreater (Renderer)
329      
330      \paragraph{Viewer3D} 
331      Receives :\\
332      - up to 5 Input Actors (\textless vtkProp3D* \textgreater),\\
333      - up to 5 Input Observers (\textless vtkInteractorObserver* \textgreater), \\
334      - a boolean 'Stereo' option, to use Red-Blue filter     
335      Outputs :\\
336      - an Interactor (\textless wxVTKRenderWindowInteractor* \textgreater) with which vtk widgets can interact, \\
337      - a Renderer (\textless vtkRenderer* \textgreater) to which actors can be added.
338
339 It contains too some sophisticated complex black boxes :
340  
341      \paragraph{IsoSurfaceWithControls} 
342      Image iso-surface extractor (vtk::IsoSurfaceExtractor) with associated control panel (isovalue, opacity and colour)\\
343      Receives :\\
344      - an initial isovalue (Isovalue)
345      - an initial opacity  (Opacity)
346      - an initial colour   (Colour)
347      Outputs :\\
348      \textless vtkProp3D* \textgreater (In)\\
349       
350      \paragraph{MIPWithControls}     
351      Maximum Intensity Projection (MIP) creator (vtk::MIPCreator) with associated control panel (shift and scale) \\
352     Receives :\\
353      - an initial scale (Scale)
354      - an initial shift  (Shift) 
355      Outputs :\\
356      \textless vtkProp3D* \textgreater (In)\\
357          
358 \item{wx} \\
359
360 Some boxes are the bbfication of usefull xwWidgets, some other ones are more
361 sophisticated.
362
363     \paragraph{ColourSelector} Colour Selector dialog (bbfication of wxColourSelector) \\
364                         %\begin{verbatim}
365          \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]' 
366                         %\end{verbatim}
367
368     \paragraph{ColourSelectorButton} A button which displays a colour picker dialog when clicked \\
369                         %\begin{verbatim}
370           \texttt{In} :Initial colour \\
371           \texttt{Out} : Colour choosen in format '[0,1] [0,1] [0,1]'
372                         %\end{verbatim} \\
373
374     \paragraph{CommandButton} Button which executes bbi commands \\
375                         %\begin{verbatim}
376           \texttt{In} : Commands to be executed separated by commas (;). Each single quote (') is replaced by a double quote ("). \\
377           \texttt{Label} : Label of the button  \\
378           \texttt{Widget} : Output widget \\
379                         %\end{verbatim}
380
381     \paragraph{DirectorySelector} Pops up a directory selection dialog (wxDirDialog)\\
382                         %\begin{verbatim}
383           \texttt{DefaultDir} : The default directory\\
384           \texttt{Message} : Message to show on the dialog \\
385           \texttt{Title} : Title of the dialog \\
386           \texttt{Out} : The directory selected by the user\\
387                         %\end{verbatim}
388  
389     \paragraph{FileSelector} Pops up a file selection dialog for reading or saving (wxFileDialog)\\
390                         %\begin{verbatim}
391           \texttt{DefaultDir} : The default directory \\
392           \texttt{DefaultFile} : The default filename \\
393           \texttt{Message} : Message to show on the dialog \\
394           \texttt{OpenSave} : Open for an open dialog (default) / Save for a save dialog\\ 
395           \texttt{Title} : Title of the dialog \\
396           \texttt{Wildcard} : A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" \\
397           \texttt{Out} : The file selected by the user \\
398                         %\end{verbatim}
399
400     \paragraph{InputText} A zone in which the user can enter a text (wxTextCtrl)\\
401                         %\begin{verbatim}
402           \texttt{In} : Initial text (default '')\\ 
403           \texttt{Title} : Title of the input zone (default '')\\ 
404           \texttt{WinTitle} : Title of the window (*)\\
405           \texttt{Out} :Current text\\
406                         %\end{verbatim}
407
408     \paragraph{LayoutLine} LayoutLine widget (wxBoxSizer)\\
409                         %\begin{verbatim}
410           \texttt{Orientation} Orientation (default V), 0=H=HORIZONTAL , 1=V=VERTICAL \\
411           \texttt{Widget}1 widget 1 \\
412           \texttt{Widget2} widget 2 \\
413           \texttt{Widget3} widget 3 \\
414           \texttt{Widget4} widget 4 \\
415           \texttt{Widget5} widget 5 \\
416           \texttt{Widget6} widget 6 \\
417           \texttt{Widget7} widget 7 \\
418           \texttt{Widget8} widget 8 \\
419           \texttt{Widget9} widget 9\\
420           %\end{verbatim}    
421     
422     \paragraph{LayoutSplit} Widget which splits a window in two fixed size parts (wxSplitterWindow)\\ 
423                         %\begin{verbatim}
424           \texttt{Orientation} : Orientation (default H), 0=H=HORIZONTAL , 1=V=VERTICAL\\ 
425           \texttt{Proportion} : Proportion (in percent) of the first children in the window\\ 
426           \texttt{Widget1} : Upper or left widget\\ 
427           \texttt{Widget2} : Lower or right widget\\
428                         %\end{verbatim}
429
430     \paragraph{LayoutTDown} Creates a 'T like' complex container : Down {UpLeft, UpRight} \\
431                         %\begin{verbatim}
432           \texttt{Widget1} : UpLeft container\\
433           \texttt{Widget2} : UpRight container\\ 
434           \texttt{Widget3} : Down container\\
435                         \begin{verbatim}
436 //                       ---------------
437 //                       |      |      |
438 //                       |  W1  |  W2  |
439 //                       |-------------|
440 //                       |             |
441 //                       |     W3      |
442 //                       ---------------
443                         \end{verbatim}
444    
445     \paragraph{LayoutTLeft} Creates a 'T like' complex container :  Left {RigthUp, RightDown}\\
446                         %\begin{verbatim}
447            \texttt{input}  Widget1 : "UpLeft container"  \\ 
448            \texttt{input}  Widget2 : "UpRight container" \\  
449            \texttt{input}  Wigdet3 : "Down container"    \\ 
450                         \begin{verbatim} 
451 //                       ---------------
452 //                       |      |  W2  |
453 //                       |  W1  |      |
454 //                       |      |------|
455 //                       |      |  W3  |
456 //                       |      |      |
457 //                       ---------------   
458                         \end{verbatim}
459
460     \paragraph{LayoutTRight} Creates a 'T like' complex container : Right {LeftUp, LeftDown}\\
461                         %\begin{verbatim}
462           \texttt{input} Widget1 currentBox.Widget1 "Up container"       \\
463           \texttt{input} Widget2 down.Widget1       "DownLeft container" \\ 
464           \texttt{input} Widget3 down.Widget2       "DownRight container"\\    
465                         \begin{verbatim}  
466 //                       ---------------
467 //                       |      |      |
468 //                       |  W1  |      |
469 //                       |------|  W2  |
470 //                       |  W3  |      |
471 //                       |      |      |
472 //                       ---------------
473                         \end{verbatim}
474   
475     \paragraph{LayoutTUp} Creates a 'T like' complex container : Up {DownLeft, DownRight} as w1{w2,w3}\\ 
476                         %\begin{verbatim} 
477           \texttt{ input} Widget1 currentBox.Widget1 "Up"       \\
478           \texttt{input} Widget2 down.Widget1        "DownLeft" \\ 
479           \texttt{input} Widget3 down.Widget2        "DownRight"\\
480      
481 //             \begin{verbatim}
482 //                       ----------------
483 //                       |    W1        |
484 //                       |              |
485 //                       |------|-------|
486 //                       | W3   |  W2   |
487 //                       |      |       |
488 //                       ----------------
489                 \end{verbatim}
490                           
491     \paragraph{LayoutTab} LayoutTab widget (wxNotebook)\\
492                         %\begin{verbatim}
493           \texttt{Orientation} Orientation (default T), 0=T=TOP , 1=R=RIGHT , 2=B=BOTTON , 3=L=LEFT \\
494           \texttt{Widget1} widget 1 \\
495           \texttt{Widget2} widget 2 \\
496           \texttt{Widget3} widget 3 \\
497           \texttt{Widget4} widget 4 \\
498           \texttt{Widget5} widget 5 \\
499           \texttt{Widget6} widget 6 \\
500           \texttt{Widget7} widget 7 \\
501           \texttt{Widget8} widget 8 \\
502           \texttt{Widget9} widget 9 \\   
503 %\end{verbatim}
504    
505     \paragraph{OutputText}              Text zone to be inserted into a window (wxStaticText)\\
506                         %\begin{verbatim}
507           \texttt{In} Text \\
508           \texttt{Title} Title prepended to the text\\   
509                         %\end{verbatim}
510                            
511     \paragraph{RadioButton}             RadioButton group widget 0-9 entries\\
512                         %\begin{verbatim}
513           \texttt{In} Set initial item \\
514           \texttt{In0} option 0\\ 
515           \texttt{In1} option 1\\ 
516           \texttt{In2} option 2\\ 
517           \texttt{In3} option 3\\ 
518           \texttt{In4} option 4\\ 
519           \texttt{In5} option 5 \\
520           \texttt{In6} option 6 \\
521           \texttt{In7} option 7 \\
522           \texttt{In8} option 8 \\
523           \texttt{In9} option 9 \\
524           \texttt{Title} Title of the widget (default '')\\ 
525           \texttt{Out} Number of the selected Item 
526                         %\end{verbatim}
527                            
528     \paragraph{Slider}          Slider widget (wxSlider)\\
529                         %\begin{verbatim}
530           \texttt{ChangeResolution} Enables the user to change the slider resolution (default FALSE) \\
531           \texttt{In} Initial slider position(default 0) \\
532           \texttt{Label} Show slider labels ? (default FALSE) \\
533           \texttt{Max} Maximum value of the slider (default 500)\\ 
534           \texttt{Min} Minimum value of the slider (default 0)\\ 
535           \texttt{Orientation} Orientation : (default H) 0=H=HORIZONTAL, 1=V=VERTICAL\\ 
536           \texttt{ReactiveOnTrack} Slider sends info when track moves (default 0 = no)\\ 
537           \texttt{Title} Title shown above the slider (default '')\\     
538                         %\end{verbatim}
539 \end{itemize}
540
541
542 %\bibliography{all}
543
544
545
546 %\section{Conclusion}
547
548
549 \end{document}