]> Creatis software - bbtk.git/blobdiff - kernel/doc/bbtkPackageDevelopersGuide/bbtkPackageDevelopersGuide.tex
git://git.creatis.insa-lyon.fr / bbtk.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
minor modifs
[bbtk.git] / kernel / doc / bbtkPackageDevelopersGuide / bbtkPackageDevelopersGuide.tex
diff --git a/kernel/doc/bbtkPackageDevelopersGuide/bbtkPackageDevelopersGuide.tex b/kernel/doc/bbtkPackageDevelopersGuide/bbtkPackageDevelopersGuide.tex
index 209d5fcabcef0dc9c11fbc5b361dbcde52d31458..8046e8ff0d83eca6bd2452870b7177ca63275edc 100644 (file)
--- a/kernel/doc/bbtkPackageDevelopersGuide/bbtkPackageDevelopersGuide.tex
+++ b/kernel/doc/bbtkPackageDevelopersGuide/bbtkPackageDevelopersGuide.tex
@@ -1,71 +1,39 @@
+
 % ==========================================
 \documentclass[11pt,final,a4paper]{article}
 \input{config.tex}
 
 
 % ==========================================
 \documentclass[11pt,final,a4paper]{article}
 \input{config.tex}
 
 
-\def\todo{\scriptsize\fbox{\bf TODO !!}\normalsize}
-\def\x{\bm{x}}
-\def\BBTK{{\xspace}The {\bf Black Box Toolkit} }
-\def\bbtk{{\xspace}$\texttt{bbtk}$ }
-\def\bbi{{\xspace}$\texttt{bbi}$ }
-\def\bbStudio{{\xspace}$\texttt{bbStudio}$ }
-\def\bbfy{{\xspace}$\texttt{bbfy}$ }
-\def\bbdoc{{\xspace}$\texttt{bbdoc}$ }
-\def\bbCreatePackage{{\xspace}$\texttt{bbCreatePackage}$ }
-
-\def\bb{{\xspace}$\texttt{bb}$ }
-%\def\bbp{{\xspace}$\texttt{bbp}$\xspace}
-
-\def\cmake{{\xspace}$\texttt{cmake}$ }
-
-\def\C{{\xspace}$\texttt{C}$ }
-\def\CPP{{\xspace}$\texttt{C++}$ }
-
-\def\xml{{\xspace}$\texttt{xml}$ }
-
-\def\itk{{\xspace}$\texttt{itk}$ }
-\def\vtk{{\xspace}$\texttt{vtk}$ }
-\def\gdcm{{\xspace}$\texttt{gdcm}$ }
-\def\gsmis{{\xspace}$\texttt{gsmis}$ }
-\def\wx{{\xspace}$\texttt{wxWidgets}$ }
 
 
-\def\lin{{\xspace}\textit{Linux} }
-\def\win{{\xspace}\textit{Windows} }
-
-% the same macros with no space at the end
+\begin{document}
 
 
-\def\BBTKns{{\xspace}The {\bf Black Box Toolkit}}
-\def\bbtkns{{\xspace}$\texttt{bbtk}$}
-\def\bbins{{\xspace}$\texttt{bbi}$}
-\def\bbfyns{{\xspace}$\texttt{bbfy}$}
-\def\bbdocns{{\xspace}$\texttt{bbdoc}$}
-\def\bbCreatePackagens{{\xspace}$\texttt{bbCreatePackage}$}
+\begin{center}
 
 
-\def\bbns{{\xspace}$\texttt{bb}$}
-%\def\bbp{{\xspace}$\texttt{bbp}$\xspace}
+{\Large \BBTK}
+\vspace{1cm}
 
 
-\def\cmakens{{\xspace}$\texttt{cmake}$}
+{\Huge User's Guide}
+\vspace{1cm}
 
 
-\def\Cns{{\xspace}$\texttt{C}$}
-\def\CPPns{{\xspace}$\texttt{C++}$}
+\bbtk version \bbtkVersion
+\vspace{0.5cm}
 
 
-\def\xmlns{{\xspace}$\texttt{xml}$}
 
 
-\def\itkns{{\xspace}$\texttt{itk}$}
-\def\vtkns{{\xspace}$\texttt{vtk}$}
-\def\gdcmns{{\xspace}$\texttt{gdcm}$}
-\def\gsmisns{{\xspace}$\texttt{gsmis}$}
-\def\wxns{{\xspace}$\texttt{wxWidgets}$}
+Last modified on : October 12, 2008 \\
+Generated on : \today 
+\vspace{0.5cm}
+\end{center}
+\begin{center}
+Eduardo Davila, Laurent Guigues, Jean-Pierre Roux 
+\end{center}
+\begin{center}
+CREATIS-LRMN, Centre de Recherche en Imagerie Medicale \\ CNRS UMR 5220, INSERM U620\\
+INSA Lyon\\
+Universit\'e Claude-Bernard Lyon 1
+\end{center}
 
 
-\def\linns{{\xspace}\textit{Linux}}
-\def\winns{{\xspace}\textit{Windows}}
 
 
 
 
-\begin{document}
-\title{The Black Box Toolkit\\Package Developers' Guide}
-\date{\today}
-\author{Laurent Guigues}
-\maketitle
 % ==========================================
 \tableofcontents
 % ==========================================
 % ==========================================
 \tableofcontents
 % ==========================================
@@ -90,14 +58,15 @@
 % ==========================================
 Any black box must be included in a \bbtk package, 
 that is in a particular shared library which can be loaded 
 % ==========================================
 Any black box must be included in a \bbtk package, 
 that is in a particular shared library which can be loaded 
-dynamically by \bbtk (hence applications which use \bbtk, 
-such as the interpreter \bbi). 
+dynamically by \bbtk (hence applications which use \bbtkns, 
+such as the development environment,
+\bbStudions). 
 
 \begin{enumerate}
 \item \textbf{Create a new package. }
 Before defining any black box you  
 have to create a package, or more precisely  
 
 \begin{enumerate}
 \item \textbf{Create a new package. }
 Before defining any black box you  
 have to create a package, or more precisely  
-the files which will allow you to generate the package 
+the source files which will allow you to generate the package 
 (compile and link the shared library) and may be install it. 
  \texttt{bbStudio} does it for you.
  
 (compile and link the shared library) and may be install it. 
  \texttt{bbStudio} does it for you.
  
@@ -116,6 +85,9 @@ that the existing project remain external to the package project.
 You will have to create your new package in a new location and 
 may be include/link against existing libraries. 
 \end{itemize}
 You will have to create your new package in a new location and 
 may be include/link against existing libraries. 
 \end{itemize}
+You'll have to run the standalone application \bbCreatePackagens, that allows 
+to create the basic file architecture 
+to start the development of a new black box package.
 
 \item \textbf{Describe your new box. }
 You can do it either :
 
 \item \textbf{Describe your new box. }
 You can do it either :
@@ -127,6 +99,11 @@ When configuring your project with \cmake,
 the utility \bbfy will then generate the corresponding \CPP code. 
 \end{itemize}
 
 the utility \bbfy will then generate the corresponding \CPP code. 
 \end{itemize}
 
+
+
+You'll have to run the standalone application \bbCreateBlackBox allows to create the basic file architecture 
+ to start the development of a new black box, that will be included in an already existing package.
+
 \end{enumerate}
 
 % ==========================================
 \end{enumerate}
 
 % ==========================================
@@ -135,7 +112,7 @@ the utility \bbfy will then generate the corresponding \CPP code.
 
 Run \texttt{bbStudio}.
 
 
 Run \texttt{bbStudio}.
 
-You''l get something like in fig. \ref{bb-Studio}
+You'll get something like in fig. \ref{bb-Studio}
 
 \begin{figure}[!ht]
 \caption{\label{bb-Studio} bbStudio}
 
 \begin{figure}[!ht]
 \caption{\label{bb-Studio} bbStudio}
@@ -162,7 +139,7 @@ That will creates the directory structure and the \texttt{cmake}
 files necessary to build the project.
 
 You must then decide the name of your new package. 
 files necessary to build the project.
 
 You must then decide the name of your new package. 
-This name will be used to load the package in \texttt{bbi}.
+This name will be used to load the package by \texttt{bbStudio}.
 Fill up the form like in fig. \ref{bbFillUpPackageForm}.
 
 
 Fill up the form like in fig. \ref{bbFillUpPackageForm}.
 
 
@@ -437,7 +414,10 @@ Concretely, a \texttt{bbtk::WxBlackBox} is associated to
 a \texttt{wxWindow} and must be able to return a pointer to it. 
 If your black box is not a widget black box 
 (that is : doesn't returns a pointer to a \emph{Widget}),
 a \texttt{wxWindow} and must be able to return a pointer to it. 
 If your black box is not a widget black box 
 (that is : doesn't returns a pointer to a \emph{Widget}),
- it must inherit from \texttt{bbtk::AtomicBlackBox}.
+ it must inherit from \texttt{bbtk::AtomicBlackBox}.\\
+ It returns a \texttt{wxWidget} which can be embedded into the \texttt{wxWindow}.\\
+ In particular, modal dialogs which are created and destroyed at the end of the process method of the box
+  are NOT \texttt{WxBlackBoxes}/
 
 \subsubsection{Inherit or encapsulate ?}
 
 
 \subsubsection{Inherit or encapsulate ?}
 
@@ -525,10 +505,11 @@ Finally, to create a new black box, you will have to give :
 
  \item Its {\bf type}, either 
    \begin{enumerate} 
 
  \item Its {\bf type}, either 
    \begin{enumerate} 
-     \item  a standard one (\texttt{std-template})
-     \item a VTK Polydata Algorithm based box (\texttt{VTK\_PolydataAlgorithm-template}),    
-     \item  a VTK Image Algorithm based box (\texttt{VTK\_ImageaAlgorithm-template}),
-     \item  if it uses the wxWidget Library (\texttt{widget-template})
+     \item  AtomicBlackBox : a basic one, with no special I/O (\texttt{std-template})
+     \item  WxBackBox : ouputs a \texttt{wxWindow}, 
+     \item a VTK Polydata Algorithm Box descendant,    
+     \item  a VTK Image Algorithm Box descendant
+
    \end{enumerate}
    
   \item The output format of the file, either a C++ file or an XML file.
    \end{enumerate}
    
   \item The output format of the file, either a C++ file or an XML file.
@@ -697,42 +678,45 @@ you must modify the xml file generated in previous step :
 % ==========================================
 
 % ==========================================
 % ==========================================
 
 % ==========================================
-\subsubsection{Specific \texttt{xml} tags for \texttt{vtkImageAlgorithm} classes bbfication}
+\subsubsection{Specific \texttt{xml} tags for \texttt{vtkImageAlgorithm} classes bbfication by inheritance}
 % ==========================================
 \begin{verbatim}
 
 % ==========================================
 \begin{verbatim}
 
-<blackbox name="..." type="VTK\_ImageAlgorithm">
+<blackbox name="..." type="VTK_ImageAlgorithm">
 
 <vtkparent>the vtk ImageAlgorithm class it inherits from</vtkparent>
 <input  name="..."  type="double"        special="vtk parameter" description="..."/>
 
 <vtkparent>the vtk ImageAlgorithm class it inherits from</vtkparent>
 <input  name="..."  type="double"        special="vtk parameter" description="..."/>
-<input name="..."   type="vtkImageData*" special="vtk output"    description="..."/>
+<input name="..."   type="vtkImageData*" special="vtk input"    description="..."/>
 
 <output  name="..." type="double"        special="vtk parameter" description="..."/>
 <output name="..."  type="vtkImageData*" special="vtk output"    description="..."/>
 \end{verbatim}
 % ==========================================
 
 <output  name="..." type="double"        special="vtk parameter" description="..."/>
 <output name="..."  type="vtkImageData*" special="vtk output"    description="..."/>
 \end{verbatim}
 % ==========================================
-\subsubsection{Specific \texttt{xml} tags for \texttt{vtkPolyDataAlgorithm} classes bbfication}
+\subsubsection{Specific \texttt{xml} tags for \texttt{vtkPolyDataAlgorithm} classes bbfication by inheritance}
 % ==========================================
 \begin{verbatim}
 % ==========================================
 \begin{verbatim}
-<blackbox name="..." type="VTK\_PolyDataAlgorithm">
+<blackbox name="..." type="VTK_PolyDataAlgorithm">
 
 <vtkparent>the vtk Polydata class it inherits from</vtkparent>
 <input  name="..."  type="double"       special="vtk parameter" description="..."/>
 
 <vtkparent>the vtk Polydata class it inherits from</vtkparent>
 <input  name="..."  type="double"       special="vtk parameter" description="..."/>
-<input  name="..."  type="vtkPolyData*" special="vtk output"    description="..."/>
+<input  name="..."  type="vtkPolyData*" special="vtk input"    description="..."/>
 
 <output  name="..." type="double"       special="vtk parameter" description="..."/>
 <output name="..."  type="vtkPolyData*" special="vtk output"    description="..."/>
 
 \end{verbatim}
 
 <output  name="..." type="double"       special="vtk parameter" description="..."/>
 <output name="..."  type="vtkPolyData*" special="vtk output"    description="..."/>
 
 \end{verbatim}
+
+\newpage
+
 % ==========================================
 \subsubsection{\bbfy \texttt{xml} tags reference}
 % ==========================================
 
 % ==========================================
 \subsubsection{\bbfy \texttt{xml} tags reference}
 % ==========================================
 
-  
+ See tables \ref{xml_tags}, \ref{xml_tags2}
 % ==========================================
 \begin{table}[!ht]
 \caption{\label{xml_tags}
 % ==========================================
 \begin{table}[!ht]
 \caption{\label{xml_tags}
-\bbfy \texttt{xml} tags reference}
+\bbfy \texttt{xml} tags reference (part 1)}
 \small
 \begin{tabular}{|lcllm{6cm}|}
 \hline
 \small
 \begin{tabular}{|lcllm{6cm}|}
 \hline
@@ -770,22 +754,36 @@ Use \texttt{bbPACKAGE}, where \texttt{PACKAGE} is the name of the package\\\hlin
         & \texttt{special} & - & 0-1 & In: \{\texttt{``itk input'', 
 ``vtk input'', ``itk parameter'', ``vtk parameter''}\} (see below).\\\hline 
         & \texttt{generic\_type} & c) & 0-1 & The ``generic'' type of the input (see text). \\\hline 
         & \texttt{special} & - & 0-1 & In: \{\texttt{``itk input'', 
 ``vtk input'', ``itk parameter'', ``vtk parameter''}\} (see below).\\\hline 
         & \texttt{generic\_type} & c) & 0-1 & The ``generic'' type of the input (see text). \\\hline 
-\texttt{<output>} & \texttt{name} & - & 1 &  The name of the output \\\hline 
+
+
+ \end{tabular}
+ \end{table}
+\begin{table}[!ht]
+\caption{\label{xml_tags2}
+\bbfy \texttt{xml} tags reference (part 2)}
+\small
+\begin{tabular}{|lcllm{6cm}|}
+\hline
+Tag & Attributes & Condition & Multiplicity & Description
+ \\ \hline
+ \texttt{<output>} & \texttt{name} & - & 1 &  The name of the output \\\hline 
         & \texttt{type} & - & 1 &  The type of the output \\\hline 
         & \texttt{special} & - & 0-1 & In: \{\texttt{``itk output'', 
 ``vtk output''}\} (see below).\\\hline
         & \texttt{generic\_type} & c) & 0-1 & The ``generic'' type  of the output (see text).\\\hline  
         & \texttt{nature} & c) & 0-1 & The ``nature'' of the output (used for automatic GUI generation).\\\hline 
         & \texttt{type} & - & 1 &  The type of the output \\\hline 
         & \texttt{special} & - & 0-1 & In: \{\texttt{``itk output'', 
 ``vtk output''}\} (see below).\\\hline
         & \texttt{generic\_type} & c) & 0-1 & The ``generic'' type  of the output (see text).\\\hline  
         & \texttt{nature} & c) & 0-1 & The ``nature'' of the output (used for automatic GUI generation).\\\hline 
-
 \texttt{<process>} & - & - & 0-1 & The code of the processing method of the box. Must be put between clear tags : \texttt{<PRE></PRE>} \\\hline 
 \texttt{<constructor>} & - & - & 0-1 & The code of the user Constructor of the box (may contains default initialisations). Must be put between clear tags : \texttt{<PRE></PRE>} \\\hline 
 \texttt{<copyconstructor>} & - & - & 0-1 & The code of the user Copy Constructor of the box . Must be put between clear tags : \texttt{<PRE></PRE>} \\\hline
 \texttt{<destructor>} & - & - & 0-1 & The code of the user Destructor of the box. Must be put between clear tags : \texttt{<PRE></PRE>} \\\hline
  \end{tabular}
  \end{table}
 \texttt{<process>} & - & - & 0-1 & The code of the processing method of the box. Must be put between clear tags : \texttt{<PRE></PRE>} \\\hline 
 \texttt{<constructor>} & - & - & 0-1 & The code of the user Constructor of the box (may contains default initialisations). Must be put between clear tags : \texttt{<PRE></PRE>} \\\hline 
 \texttt{<copyconstructor>} & - & - & 0-1 & The code of the user Copy Constructor of the box . Must be put between clear tags : \texttt{<PRE></PRE>} \\\hline
 \texttt{<destructor>} & - & - & 0-1 & The code of the user Destructor of the box. Must be put between clear tags : \texttt{<PRE></PRE>} \\\hline
  \end{tabular}
  \end{table}
+ 
+ \newpage
+ 
 % ==========================================
 \begin{table}[!ht]
 % ==========================================
 \begin{table}[!ht]
-\caption{\label{xml_tags}
+\caption{\label{xml_tags-conditions}
 \bbfy \texttt{xml} tags conditions}
 \small
 \begin{tabular}{|ll|}
 \bbfy \texttt{xml} tags conditions}
 \small
 \begin{tabular}{|ll|}
@@ -815,8 +813,7 @@ a \texttt{wxWindow} and is be able to return a pointer to it.... \\ \hline
 
 % ==========================================
 \begin{table}[!ht]
 
 % ==========================================
 \begin{table}[!ht]
-\caption{\label{categories}
-\bbfy \texttt{Black Box} categories}
+\caption{\label{categories} \texttt{bbfy} \texttt{Black Box} categories}
 \small
 \begin{tabular}{|ll|}
 \hline
 \small
 \begin{tabular}{|ll|}
 \hline
@@ -888,6 +885,16 @@ a \texttt{wxWindow} and is be able to return a pointer to it.... \\ \hline
 \end{tabular}
 \end{table}
 
 \end{tabular}
 \end{table}
 
+.\\
+.\\
+.\\
+.\\
+.\\
+
+
+\newpage 
+
+
 % ==========================================
 \subsection{\CPP description of a box}
 % ==========================================
 % ==========================================
 \subsection{\CPP description of a box}
 % ==========================================
@@ -937,7 +944,7 @@ For a quick start, the best you have to do is to run \texttt{bbStudio}, then in
     \item \texttt{BBTK\_NAME} : the name of your box 
     \item \texttt{BBTK\_AUTHOR} : author name (better you put e-mail adress)
     \item \texttt{BBTK\_DESCRIPTION} : brief description of what does the box
     \item \texttt{BBTK\_NAME} : the name of your box 
     \item \texttt{BBTK\_AUTHOR} : author name (better you put e-mail adress)
     \item \texttt{BBTK\_DESCRIPTION} : brief description of what does the box
-    \item \texttt{BBTK\_CATEGORY} :box category  (see table \ref{categories})
+    \item \texttt{BBTK\_CATEGORY} : box category  (see table \ref{categories})
     \item \texttt{BBTK\_INPUT} for each one of the input parameters, you have to supply : 
        \begin{itemize}
          \item The current Blackbox name.
     \item \texttt{BBTK\_INPUT} for each one of the input parameters, you have to supply : 
        \begin{itemize}
          \item The current Blackbox name.
Black Box Tool Kit