From: jean-pierre roux Date: Tue, 7 Oct 2008 16:20:22 +0000 (+0000) Subject: Beginning of new version X-Git-Tag: v0.8.0~71 X-Git-Url: https://git.creatis.insa-lyon.fr/pubgit/?a=commitdiff_plain;h=6f1c4c718ea4c6f7f0983b70a87869144e4d6b14;p=bbtk.git Beginning of new version --- diff --git a/kernel/doc/bbtkUsersGuide/LargeGraph.png b/kernel/doc/bbtkUsersGuide/LargeGraph.png new file mode 100644 index 0000000..b8ba51f Binary files /dev/null and b/kernel/doc/bbtkUsersGuide/LargeGraph.png differ diff --git a/kernel/doc/bbtkUsersGuide/SmallGraph.png b/kernel/doc/bbtkUsersGuide/SmallGraph.png new file mode 100644 index 0000000..acd0de5 Binary files /dev/null and b/kernel/doc/bbtkUsersGuide/SmallGraph.png differ diff --git a/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex b/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex index 4d28920..06e156e 100644 --- a/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex +++ b/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex @@ -114,6 +114,9 @@ It's a part of the \texttt{Creatools suite} composed mainly of : creaImageIO creaLib gdcm +\end{verbatim} +which depend on the OpenSource libraries: +\begin{verbatim} itk vtk wxWidgets @@ -187,7 +190,7 @@ which allows to manipulate packages and boxes very easily in symbolic way. \BBTK provides one : \bbi (the Black Box Interpreter). \item {\bf Automatic documentation} of existing packages. \texttt{html} documentation of packages is proposed by -\bbins. +\bbStudions. \end{itemize} Finally, these different components allow {\bf efficient} : @@ -222,19 +225,18 @@ have been written by different persons, using different libraries, etc. \end{itemize} \item A {\bf\emph{Developement environment}}, called \bbStudio, which provides \begin{itemize} - \item An online {\bf\emph{script editor}} - \item A powerfull {\bf\emph{Help environment}}, called \bbPackageBrowser - whith integrated + \item An online {\bf\emph{script editor and interpretor}} + \item A powerfull html {\bf\emph{Help environment}},whith integrated : \begin{itemize} \item Online documentation scaning \item Retreiving boxes on various criterions \item Checking Demo and examples \end{itemize} - - \item An {\bf\emph{interpreter}}, called \bbins, which allows to + \end{itemize} + \item An standalone {\bf\emph{interpreter}}, called \bbins, which allows to load black box packages and to define and execute - processing chains by connecting various black boxes of the already loaded packages. - \item {\bf\emph{Utilities}} : + processing chains by connecting various black boxes. + \item {\bf\emph{Various Development Utilities}} : \begin{itemize} \item \bbfy generates the \CPP code of a black box from a description file written in \texttt{xml}. @@ -243,8 +245,10 @@ have been written by different persons, using different libraries, etc. %author, description, inputs, outputs, and so on). \item \bbCreatePackage allows to create the basic file architecture to start the development of a new black box package. - \end{itemize} - \end{itemize} + \item \texttt{bbs2cpp} translates a \texttt{.bbs} script into a \CPP file. + \item \texttt{bbc} that + \end{itemize} + \item A full {\bf\emph{documentation}} printable (pdf), browsable (html), queryable thru keywords. \end{itemize} The general architecture of \BBTK is shown in figure \ref{bb-architecture}. @@ -259,35 +263,24 @@ is shown in figure \ref{bb-architecture}. \newpage % ========================================== -\subsection{Structure of this guide} +\section{Getting started with bbStudio} % ========================================== -This guide is divided into three parts. - -The first part (\ref{bbStudio}) is a brief presentation of the very intuitive Development -environment, \bbStudions. - -The second part (\ref{bb0}) -is devoted to the use of the \emph{black box interpreter} \bbins. -This is the highest level of use of the toolkit, which -allows to create and execute processing chains by connecting -black boxes of existing packages. - -The third part (\ref{cpp}) explains how to -use the black box toolkit framework in \CPP code, -typically to develop large applications which -involve complex graphical interfaces. - - % ========================================== % ========================================== % ========================================== % ========================================== % ========================================== % ========================================== -\vspace{0.5cm}\hrule -\section{The Development environment (bbStudio)} -\label{bbStudio} + +% ========================================== +\subsection{The interface} +% ========================================== + + +%\vspace{0.5cm}\hrule +%\section{The Development environment (bbStudio)} +%\label{bbStudio} Just run it, typing in a console \bbStudio or clicking on its icon or its menu entry. @@ -305,6 +298,9 @@ You'll get something like in figure \ref{bbi-fig-bbStudio-gui-start} (the exact appearance of \bbStudio is Operating System and \bbtk version dependent) +\newpage + + \begin{figure}[!ht] \caption{\label{bbi-fig-bbStudio-gui-start}The bbStudio Development environment interface at start time} \begin{center} @@ -325,13 +321,7 @@ Let's have a look at the resized window : \end{center} \end{figure} -You can see four parts : -\begin{itemize} - \item {\bf{Files}} - \item {\bf{Messages}} - \item {\bf{Command}} - \item {\bf{Help}} -\end{itemize} +You can see four parts : \texttt{Files}, \texttt{Messages}, \texttt{Command}, \texttt{Help}.\\ The stuff is written using the Advanced User Interface library of wxWidgets, whose 'docking manager' allows windows and toolbars to be floated/docked @@ -339,28 +329,46 @@ onto a frame.\\ Please don't use this feature at learning time (the snapshots of this document wouldn't match with your screen ...) -\subsection{'Files' part} +\subsubsection{'Files' part} \label{bbi-FilesPart} It's the .bbs script editor.\\ If you load a file holding a script, it will be displayed here, and you'll be able to modify it, to save it, to save-as it, to run it, using the -lower toolbar +lower toolbar (see figure : \ref{lowertoolbar}) + +\begin{figure}[!ht] +\caption{\label{lowertoolbar}The lower tool bar} +\begin{center} +\includegraphics[width=0.7\textwidth]{lowertoolbar.png} +\end{center} +\end{figure} -\subsection{'Messages' part} + \begin{itemize} + \item {\bf\emph{New file}} : Create a new file to hold a script + \item {\bf\emph{Open file}} : Open an already existing file holding a script + \item {\bf\emph{Close file}} : Close a file holding a script + \item {\bf\emph{Save file}} : Save he current file (if modified) + \item {\bf\emph{Save file as}} : Save he current file under a different name + \item {\bf\emph{Run file}} : Execute the script you just loaded/modified/written + \item {\bf\emph{cursor position}} : column number : line number + \end{itemize} + + +\subsubsection{'Messages' part} \label{bbi-MessagesPart} Two kinds of messages will be output here:\\ System messages : produced by the kernel, in case of a user mistyping, or an execution error\\ Script messages : produced by the \bbtk equivalent of \texttt{printf} or \texttt{std::cout} in user programs -\subsection{'Command' part} +\subsubsection{'Command' part} \label{bbi-CommandPart} This is where user will type his requirements. -\subsection{'Help Contents' part} +\subsubsection{'Help Contents' part} \label{bbi-HelpContentsPart} The 'Help Contents' part of \bbStudio is used to browse the html help of \BBTK. @@ -387,192 +395,37 @@ All the entries of the starting page are self-explanatory : \end{itemize} \item {\bf\emph{Boxes}} : Box retrieving on various criterions : - \begin{itemize} - \item {\bf\emph{By name}} (Alphabetical list) - \item {\bf\emph{By package}} (see table : \ref{bbi-list_of_packages}) - \item {\bf\emph{By category}} (see table : \ref{categories}) - \item {\bf\emph{Adaptors}} Used internaly to perform type conversions (not end user intended) - \end{itemize} - - \end{itemize} - -% ========================================== -\begin{table}[!ht] -\caption{\label{bbi-list_of_packages} List of bbtk supplied packages.} -\small -\begin{tabular}{|lp{10cm}|} -\hline -Package & What it's used for \\ \hline -\texttt{std} & : the 'standard' package including basic useful boxes \\ \hline -\texttt{wx} & : basic graphical interface elements (widgets : sliders, buttons, etc.) based on the \texttt{wxWidgets} library \\ \hline -\itk & : the basic image processing package, based on the \itk library. (without description)\\ \hline -\vtk & : prints help on the package \texttt{package-name} and its boxes (with brief description). The package must have been previously loaded\\ \hline -\texttt{wxvtk} & : widget boxes based on the \vtk library.\\ \hline -\texttt{itkvtk} & : adaptors to convert \itk structures into \vtk structures and conversally.\\ \hline -%\texttt{creaImageIO} & : provides high level widgets to read images including DICOM.\\ \hline -\texttt{toolsbbtk} & : Tools for bbtk administration and package development.\\ \hline - -\end{tabular} -\end{table} -% ========================================== - + \texttt{By name}} (Alphabetical list), + \texttt{{By package}}, + \texttt{{By category}}.\\ + A special hidden Box category, called \texttt{{Adaptors}} exists. \\ + They are used internaly to perform type conversions. Thought there are not end user intended, an aware user may query them. + + \end{itemize} -% ========================================== -\begin{table}[!ht] -\caption{\label{categories} \texttt{Black Box} categories} -\small -\begin{tabular}{|lp{10cm}|} -\hline - \texttt{Category name} & : Meaning \\ \hline \\ \hline - \texttt{adaptor} & : Adaptor box \\ \hline - \texttt{application} & : Final application, end user intended \\ \hline - \texttt{atomic box} & : System category. - Automatically assigned to Atomic Black Boxes (c++ defined) \\ \hline - \texttt{complex box} & : System category. - Automatically assigned to Complex Black Boxes (script defined) \\ \hline - \texttt{command line} & : Script which defines a command line application \\ - & :(no embedded GUI, but command line imput parameters) \\ \hline - \texttt{demo} & : Demonstration \\ \hline - \texttt{devel} & : Developer tool (bbCreatePackage.bbs, ...) \\ \hline - \texttt{dicom} & : DICOM aware box \\ \hline - \texttt{example} & : Example script showing a box use-case \\ \hline - \texttt{filter} & : Image processing box \\ \hline - \texttt{image} & : Image processing related box \\ \hline - \texttt{interaction} & : \\ \hline - \texttt{math} & : Mathematical operations \\ \hline - \texttt{mesh} & : Mesh processing related box \\ \hline - \texttt{misc} & : A box that cannot be put in other category ! \\ \hline - \texttt{read/write} & : Box that read or write data from or to disk \\ \hline - \texttt{viewer} & : Box which displays some data \\ \hline - \texttt{widget} & : Piece of graphical interface \\ \hline - \texttt{3D object creator} & : Sophisticated 3D widget \\ \hline - \texttt{toolsbbtk} & : Component of bbStudio \\ \hline -\end{tabular} -\end{table} % ========================================== -\begin{table}[!ht] -\caption{\label{kinds} \texttt{Black Box} kinds} -\small -\begin{tabular}{|ll|} -\hline -\texttt{Kind name} & : Meaning \\ \hline \\ \hline -\texttt{ADAPTOR} & : Adaptor Box \\ \hline -\texttt{DEFAULT\_ADAPTOR} & : \\ \hline -\texttt{WIDGET\_ADAPTOR} & : \\ \hline -\texttt{DEFAULT\_WIDGET\_ADAPTOR} & : \\ \hline -\texttt{GUI} & : \\ \hline -\texttt{DEFAULT\_GUI} & : \\ \hline -\texttt{ALL} & : If kind='ALL' then sets the level for all kinds \\ \hline -\end{tabular} -\end{table} -\newpage - .\newline - .\newline - .\newline - .\newline - .\newline - .\newline - . \newline % ========================================== % ========================================== % ========================================== % ========================================== % ========================================== -% ========================================== -\vspace{0.5cm}\hrule -\section{The script manager} -\label{bb0} -% ========================================== - - Atomatically open in the left upper part of bbStudio. - - -\begin{figure}[!ht] -\caption{\label{bbi-fig-bbStudio-file0}The bbStudio script manager} -\begin{center} -\includegraphics[width=0.7\textwidth]{bbFile0.png} -\end{center} -\end{figure} - -Using the lower tool bar (see figure : \ref{lowertoolbar}), you can : - - -\begin{figure}[!ht] -\caption{\label{lowertoolbar}The lower tool bar} -\begin{center} -\includegraphics[width=0.7\textwidth]{lowertoolbar.png} -\end{center} -\end{figure} - \begin{itemize} - \item {\bf\emph{New file}} : Create a new file to hold a script - \item {\bf\emph{Open file}} : Open a already existing file holding a script - \item {\bf\emph{Close file}} : Close a file holding a script - \item {\bf\emph{Save file}} : Save he current file (if modified) - \item {\bf\emph{Save file as}} : Save he current file under a different name - \item {\bf\emph{Run file}} : Execute the script you just loaded/modified/written - \end{itemize} - - -The script language is very simple. -Everything is done with only a very few commands (See table \ref{bbi-reference-box}). -The philosophy of this part is also very simple : -it introduces the \bbi commands using examples, -starting with the most simple commands. -The first section of this part -(\ref{bbi-getting-started}) -is designed like a tutorial, -which progressively introduces all the concepts of the command interpretor. -We suggest you run \bbStudio and follow the examples, -to see how it works in practice. -At the end of this section, -you will be able to use \bbStudio and write -own black box processing scripts. - -After this tutorial, -the section \ref{bbi-more-on} -(called \emph{more on...}) -goes deeper into various issues of the command interpretor. -Read it at your convenience, -either linearly to learn more about \bbStudio, -or in random order to get an answer -to a particular question. - -Finally, the section \ref{bbi-reference} -summarizes all the commands of \bbStudions, -their parameters and effect. -Use it as a reference. - - -\newpage % ========================================== -\subsection{Getting started} -\label{bbi-getting-started} - -% ============================================== -\subsubsection{Installed tree \emph{vs} Built tree} -% ============================================== -If you want to use the 'installed' version (it means you downloaded and run the Windows -installer, or the Fedora package, or you downloaded, compiled and installed the -cvs version), just open a console and type \bbStudions, or double click on the application icon. \\ - -If you want to run your own uninstalled version (say : you downloaded and compiled the -cvs version in order to use a recently commited patch, but you want to be able to still use the standard version), -you have to open a console, cd in the \texttt{bin} directory of the built tree and type \texttt{./bbStudio}. +\newpage % ============================================== -\subsubsection{Using an already existing script} +\subsection{Running Demo and Examples} % ============================================== Run \bbStudio the way you need. \\ @@ -585,6 +438,8 @@ In the part 'Help contents' (See figure \ref{HelpContents}), select \texttt{Exam \end{center} \end{figure} +\newpage + You will be asked to select a Box category (See figure \ref{BoxCategories}); \\ Select \texttt{example}. @@ -630,7 +485,7 @@ in the 'Files' part, within the script editor (See figure \ref{exampleSliderSour Run it, using the lower toolbar (see figure : \ref{lowertoolbar}) -You'll get something like in \ref{execSliderSource}. +You'll get something like in figure \ref{execSliderSource}. \begin{figure}[!ht] \caption{\label{execSliderSource}execution of 'exampleSlider'} @@ -641,37 +496,105 @@ You'll get something like in \ref{execSliderSource}. Feel free to move the slider, to check it actually works... - \newpage -% ========================================== -\subsubsection{Creating and executing black boxes} -% ========================================== +Just a few words on what you saw : +\begin{itemize} +\item{in the File part} \\ +The source code of the script +\begin{verbatim} + new Slider slider + set slider.ReactiveOnTrack 1 +\end{verbatim} +We create a \texttt{Slider} called \emph{slider}\\ +We tell it to inform anybody that's interested in, that the cursor moved, each time it moved. \\ +The standard behaviour is to inform, only when cursor is released. +\begin{verbatim} + new OutputText text +\end{verbatim} +We create a \texttt{OutputText} called \emph{text} +(in which slider value will be displayed) + +\begin{verbatim} +new LayoutLine layout +\end{verbatim} +We create a \texttt{LayoutLine} called \emph{layout}, +a \emph{container} widget, designed to embed other wigets (say, a main window) +\begin{verbatim} +connect slider.Widget layout.Widget1 +connect text.Widget layout.Widget2 +\end{verbatim} +We embed \emph{slider} and \emph{text} into \emph{layout}. +\begin{verbatim} +connect slider.BoxChange text.BoxExecute +connect slider.Out text.In +\end{verbatim} +We tell \emph{slider} to inform \emph{text} every time it's modified.\\ +We tell \emph{slider} to pass its output value (\texttt{Out} to \emph{text} input value (\testtt{In}) +\begin{verbatim} +exec layout +\end{verbatim} +We tell \emph{layout} to process itself (it will do it only if it's warned +that one of its entries was modified since its (own) last processing. -To learn interactivelly the script language features, you can use the black box -interpreter : -open a console and type \bbStudio -or double click on the application icon. -You get a window which looks like the one in figure -\ref{bbi-fig-bbi-gui} -(the exact appearance of \bbStudio is system and \bbtk version dependent) +\item{in the Help part} + +You can see the graphical representation of the script, as in figure \ref{SmallGraph}. -%\footnote{If you compiled \bbtk without \wx then \bbi does not have a -%graphical interface but a simple prompt}. \begin{figure}[!ht] -\caption{\label{bbi-fig-bbi-gui}The black box interpreter interface} +\caption{\label{SmallGraph}Graphical representation of a script} \begin{center} -\includegraphics[width=0.7\textwidth]{bbi-gui0.png} +\includegraphics[width=0.7\textwidth]{SmallGraph.png} \end{center} \end{figure} +Both graphical pipe line (\emph{slider} and \emph{text} are embedded into \emph{layout}) + and processing pipe line (\emph{slider} warns \emph{text} immedialtely when it's modified, \emph{slider} passed \emph{text} its new value).\\ + Yes, we know : all the arrows (pipe line arrows and processing arrows) are blue; we are sorry about that...\\ + + You could get a much more detailled graph, just clicking on the button \\ \texttt{graph (detailled)} in the toolbar of the \texttt{Command} part, like in + figure \ref{LargeGraph}. + +\begin{figure}[!ht] +\caption{\label{LargeGraph}Detailled graphical representation of a script} +\begin{center} +\includegraphics[width=0.75\textwidth]{LargeGraph.png} +\end{center} +\end{figure} + +\end{itemize} +\newpage + +% ============================================== +\subsection{Online Help} +% ============================================== + +TODO + +% ========================================== +\subsubsection{Guides} +% ========================================== +TODO +% ========================================== +\subsubsection{Boxes Help} +% ========================================== +TODO : indexation, categories, etc +% ========================================== +\subsection{Creating and executing black boxes} +% ========================================== +TODO +% ============================================== +\subsection{The Menu} +% ============================================== +TODO + The 'working' area (the left one, as opposed to the 'help' area, on the right side) is composed of : one single line zone (Command), at the bottom in which you can enter your commands and a multiple line zone in which the Command interpreter prints out the result of your commands. The upper part contains the script editor; we shall not use it right now, you may reduce it -Try typing in the input zone (in this manual, +Try typing in the \texttt{Command} area (in this manual, the commands entered by the user will be preceded by a prompt \textgreater) : \begin{verbatim} > help @@ -1219,16 +1142,16 @@ In our example, the \texttt{CastUCharToDouble} adaptor would simply cast the value of the \texttt{char} into a \texttt{double}, however arbitrarily complex type conversion may be done. -\begin{verbatim} -Question (for info-dev): -if two adaptors with the same input and output types exist -in two different packages, currenly loaded, -which one is chosen by the interpreter at connection time? -A feature is missing to specify explicitely which one user wants to choose -(use a namespace notation ?) - --> Role of default adaptors -\end{verbatim} +%\begin{verbatim} +%Question (for info-dev): +%if two adaptors with the same input and output types exist +%in two different packages, currenly loaded, +%which one is chosen by the interpreter at connection time? +%A feature is missing to specify explicitely which one user wants to choose +%(use a namespace notation ?) +% +%-> Role of default adaptors +%\end{verbatim} Note that the \texttt{set} and \texttt{print} commands of interpreter work with adaptors from \texttt{string} to the type of the input to set @@ -1797,11 +1720,11 @@ The label of each 'note book' is the name of the object it contains. \end{itemize} -=====> TODO \\ +%=====> TODO \\ -One word about a special widget in the package \texttt{wx} : -the \texttt{Button}... to be continued. +%One word about a special widget in the package \texttt{wx} : +%the \texttt{Button}... to be continued. % ========================================== \subsubsection{Deeper in the boxes}