~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~ [ freetext search ] ~ [ file search ] ~

Linux Cross Reference
Tina5/tina-libs/README

Version: ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  1 TINA 5 README
  2 =============
  3 
  4 paul.bromiley@manchester.ac.uk 20/4/2005
  5 
  6 
  7 Contents
  8 --------
  9 
 10 
 11 1) What is TINA?
 12         1a) History
 13         1b) Authors
 14         1c) What does TINA stand for?
 15         1d) How do I know it works?
 16 2) Where do I get TINA?
 17 3) How do I compile the libraries?
 18         3a) Compatibility issues
 19                 3a.i) Backup Build System
 20         3b) Widget sets
 21         3c) Compiler warning messages
 22 4) How do I compile the toolkits?
 23         4a) Toolkits with different widget sets
 24 5) How do I write my own TINA code?
 25         5a) Writing new algorithmic functionality
 26         5b) Porting old TINA 4 code to TINA 5
 27 
 28 
 29 1) What is TINA?
 30 ----------------
 31 
 32 
 33 TINA (TINA Is No Acronym) provides a set of libraries for machine vision and
 34 image analysis research.  It is written in C primarily for use on GNU/Linux
 35 platforms, although it can also be compiled on MacOSX, Solaris, and (with some
 36 effort) MS Windows.  The code is split into two areas:
 37 
 38 tina-libs:      back-end code for memory management, image structure handling 
 39                 etc.
 40 
 41 tina-tools:     high-level algorithms, interface etc.
 42 
 43 Each of these areas contains a number of libraries with specific purposes:
 44 
 45 tina-libs:
 46 
 47 file:           input/output file handling
 48 geometry:       basic geometry functions
 49 image:          basic image processing functions
 50 math:           basic mathematical functions
 51 medical:        back-end functions for medical image analysis
 52 sys:            basic memory allocation functions
 53 vision:         back-end functions for machine vision
 54 
 55 tina-tools:
 56 
 57 draw:           basic display drawing
 58 gphx:           low-level interface to widget sets
 59 wdgts:          high-level interface to widget sets
 60 tlbase:         basic tools (image loading etc.)
 61 tlvision:       machine vision tools
 62 tlmedical:      medical tools.
 63 
 64 In order to use TINA, you must download both the tina-libs and tina-tools areas
 65 from our website, and compile both. This will produce a set of libraries in the
 66 libs subdirectories of both tina-libs and tina-tools. 
 67 
 68 The TINA libraries can be used in one of two ways.  They have been designed to
 69 be highly modular, allowing users to strip out parts of the functionality to
 70 use in their own code (under the terms of the licence).  However, they also
 71 include code for interfaces to the algorithms.  This code is in the form of a
 72 set of "tools", each of which appears as a window on the screen, and which
 73 collect together related functionality applicable to a certain task (loading
 74 single images, stereo image pairs, temporal sequences or medical image
 75 volumes; stereo vision; medical image segmentation; registration; blood flow
 76 analysis etc. etc. ).  In order to use this interface, you must build a
 77 "toolkit", a program that includes the tools you want to access.
 78 
 79 TINA is research software, continuously updated by a small group of core
 80 programmers at the University of Manchester, primarily for their own
 81 use. There is no "stable" release as such: the code in both the CVS repository
 82 and the tarballs is the latest version.  However, it is written with numerical
 83 stability and statistical validity in mind, and all new additions are
 84 thoroughly tested.
 85 
 86 
 87 1a) History
 88 -----------
 89 
 90 
 91 Development of the original X11 based versions of TINA started in 1989 at the
 92 Artificial Intelligence & Vision Research Unit (AIVRU) at the University of
 93 Sheffield (www.shef.ac.uk).  It was designed using experience gained in two
 94 previous versions with an aim to minimise the process of software maintenance
 95 and maximise code reuse.  Later versions of TINA were developed there and also
 96 at the Electronic Engineering Department of the University of Sheffield.  TINA
 97 became Open Source whilst being maintained by Electronic Engineering.  Since
 98 1997 TINA maintenance has been switched to Imaging Science and Biomedical
 99 Engineering (ISBE) (www.isbe.man.ac.uk) at the University of Manchester
100 (www.manchester.ac.uk).
101 
102 Until 2002 TINA was never explicitly funded as a project in its own
103 right. Rather it has been developed under numerous research grants and
104 collaborations as a framework to facilitate an ongoing co-ordinated research
105 effort into artificial vision.  TINA was originally conceived by AIVRU
106 researcher Stephen Pollard as a library of functions necessary for
107 stereo-based 3D machine vision.  John Porrill and Neil Thacker where also
108 involved at these early stages.  After this team broke up Neil Thacker
109 continued vision research within TINA at Electronic Engineering, and together
110 with Tony Lacey released TINA as Open Source.  In 1997 both Neil Thacker and
111 Tony Lacey moved to ISBE, from where TINA is now maintained.  Tony left for a
112 career in industry in 2004: today, Neil Thacker is the project leader for
113 TINA, and Paul Bromiley performs most of the day-to-day maintenance of the
114 code and website.
115 
116 
117 1b) Authors
118 -----------
119 
120 
121 Along the way a large number of people have contributed to TINA both at the
122 University of Sheffield and the University of Manchester. Their contributions
123 are never forgotten (and their code never lost). A full list can be found at
124 www.tina-vision.net/people.php.
125 
126 
127 1c) What does TINA stand for?
128 -----------------------------
129 
130 
131 Originally the acronym TINA stood for "there is no alternative", which was
132 true at the time.  Since then, several alternative meanings have been
133 suggested ("Thacker is not acceptable", "TINA is nearly accurate" etc.: most
134 of these were the result of a bad day at work). Today however, in a similar
135 style to acronym GNU, TINA stands for "TINA is no acronym". All previous
136 definitions have now been superseded!
137 
138 
139 1d) How do I know it works?
140 ---------------------------
141 
142 
143 For most software, the question of accuracy is non-existent: your word
144 processor either lets you prepare and print a document, or does not.  However,
145 for scientific software the question becomes more problematic because the
146 requirements are more extensive.  The results of any machine vision algorithm
147 will be dependent on the statistical validity and numerical stability (or what
148 might be called the "theoretical" and "implementation" aspects) of the
149 algorithm, and any failure to meet these two goals might not be obvious to the
150 user without extensive validation work.  Any attempt to justify the algorithms
151 used in TINA here would be largely pointless, since such justification can
152 only be meaningful after a suitable "negotiation of trust".  Therefore, I will
153 commence that process with three simple observations:
154 
155 a) All of the algorithms in TINA have been derived strictly within a context
156 of statistical validity: you won't find any active contour methods with
157 arbitrary image potential terms here! Therefore, the results of any algorithm
158 can be linked directly to the probability theoretic interpretation of the data
159 generation process.  This is not a guarantee that a specific algorithm will
160 work for your data. However, it is a guarantee that, if your data obeys the
161 underlying statistical assumptions relevant to the algorithm (as specified in
162 our published papers: see point b), the interpretation of the data provided by
163 the algorithm will be valid. In theory, your results can be linked directly
164 all the way back to the underlying axioms of mathematics.
165 
166 b) All of the algorithms in TINA have been used in our scientific research,
167 and thus subjected to peer-review in conference and journal publications.  We
168 make preprints of these publications available via our website at
169 www.tina-vision.net/docs/memos.php.  These papers contain details of our
170 in-house validation work.
171 
172 c) All of the algorithms in TINA are available as open-source software.
173 Through a combination of reading the memos, documentation, and code, you can
174 see exactly how a given algorithm works.  This facility is rarely afforded to
175 users of commercial machine vision or medical image analysis software. If you
176 think you have spotted a mistake in our work, get in touch! You will either
177 gain (admittedly limited) fame as an external contributor named on the TINA
178 website, or a very lengthy tutorial on statistics (e.g. if you mention the
179 words "Bayes Theory" within earshot of one of the core programmers).
180 
181 
182 2) Where do I get TINA?
183 -----------------------
184 
185 
186 The tina-libs and tina-tools code can be downloaded from our website
187 (www.tina-vision.net), either in the form of tarballs, or from the CVS
188 repository.  Go to the website and click on the "software" link. Then, either
189 download the two tarballs or use the CVS instructions given there.
190 
191 Tarballs: 
192 
193 Create a directory in /usr/local called "Tina5", and download both tarballs to
194 this directory. Then unzip (using gunzip tarball_name) and untar (using tar
195 -xvf tarball_name) both tarballs: this will create the two directories
196 tina-libs and tina-tools in the /usr/local/Tina5 directory
197 
198 CVS:
199 
200 Create a directory in /usr/local called "Tina5", then from within this
201 directory follow the instructions given on the website for anonymous access to
202 the CVS repository.
203 
204 At the end of this step, you should have two directories, called tina-libs and
205 tina-tools, in the /usr/local/Tina5 directory.
206 
207 
208 3) How do I compile the libraries?
209 ----------------------------------
210 
211 
212 Before you start, you must have
213 
214 autoconf 2.54   (or later)
215 automake 1.6.3  (or later)
216 libtool  1.4.2  (or later)
217 
218 installed on your system in order to build TINA: all reasonably recent Linux
219 distro's should install these by default.
220 
221 The basic approach is to cd into tina-libs, then type
222 
223 ./bootstrap.sh
224 ./configure
225 make
226 make install
227 
228 Then cd into tina-tools, and do the same.  If these steps complete without 
229 errors, you should end up with the compiled libraries in 
230 /usr/local/Tina5/tina-libs/libs and /usr/local/Tina5/tina-tools/libs.
231 
232 The full set of options provided by configure can be seen using;
233 
234 ./configure --help
235 
236 There are currently no specific tina-libs options (as of version 5.0rc0).
237 
238 There are a couple of other concerns though...
239 
240 
241 3a) Compatibility Issues
242 ------------------------
243 
244 
245 If the above instructions fail to work for your system, your first port of
246 call should be the WikiWiki page on our website.  Go to www.tina-vision.net,
247 click on "wiki" in the menu, and then click on "Tina5CompileGuide".  If your
248 system is listed, then it will provide work-arounds or full solutions for
249 known problems.  If not, pipe the outputs of ./configure and make to files and
250 e-mail them to me (paul.bromiley@man.ac.uk) and I will do my best to help you
251 out.  I would appreciate feedback on compilation for systems not listed on the
252 wiki page: it allows us to keep the instructions up-to-date.
253 
254 
255 3a.i) Backup Build System
256 -------------------------
257 
258 
259 As well as the main, automake and autoconf based build system, TINA has a
260 backup system of hand-written Makefiles (a legacy from the TINA4 days).  In
261 extremis, this can be used to work around serious compatibility issues.  It
262 still requires that you run autoconf, since it needs access to config.h, but
263 bypasses the automake-based makefiles entirely.  Read the inline documentation
264 in Tina5/tina-libs/tina-simple-build.sh for further information.
265 
266 
267 3b) Widgets
268 -----------
269 
270 
271 The tina-tools area contains interface code, arranged as a set of "tools" that
272 collect together related functionality for solving particular tasks (loading
273 single images, stereo image pairs, temporal sequences or medical image
274 volumes; stereo vision; medical image segmentation; registration; blood flow
275 analysis etc. etc.).  This interface code is dependent on external widget and
276 graphics libraries.  The tina-tools area contains wrappers for these libraries
277 (in the wdgts and gphx libraries), and is currently capable of using five
278 different widget sets:
279 
280 NULL:   (NULL widgets and NULL graphics) for testing or wrapping TINA code for
281         use in other programs: provides no interface.
282 
283 Tcl/Tk: pronounced "tickle-tk" (Tcl widgets and Tk graphics) for text-based
284         interfaces and client/server operation).
285 
286 XView:  sometimes called openwindows, (Xv widgets and X11 graphics), which is
287         our usual mode of operation. However, the external XView libraries 
288         themselves do not work on 64-bit systems.
289 
290 Motif:  (Xm widgets and X11 graphics): an early replacement for XView, written
291         at a point when it looked like XView would be deprecated. XView was 
292         revived due to popular demand, but it looks like the end of XView has 
293         finally arrived with the jump to 64-bit systems.
294 
295 Gdk/Gtk:stands for "the GIMP (Graphical Image Manipulation Program) toolkit",
296         since it was originally written exclusively for the GIMP, and is the
297         widget set of choice for modern GNU/Linux software. It is anticipated
298         that this will become the default for TINA in the next few years, with
299         the Motif widgets as a backup for older systems, and XView
300         deprecated. Two versions of Gtk (1.2 and 2.0) are currently in use:
301         TINA compiles with 1.2, but there are a few issues with 2.0. We are
302         working on fixing this (by the time you read this, there may be
303         experimental GTK 2 widgets in a directory next to the existing GTK 1.2
304         widgets).
305 
306 At the library compilation stage, you can compile as many of these as you
307 want. NULL widgets and graphics are always compiled.  If you want a graphical
308 interface to TINA, you must compile at least one of XView, Motif or Gtk.
309 
310 In order to compile the TINA widgets and graphics libraries you want to use,
311 you must ensure that the external libraries they depend on are installed.  A
312 complete list of such packages for SuSE 9.2 is:
313 
314 For gtk1.2 and gtk2
315 
316 fontconfig-2.2.96.20040728-9.i586.rpm
317 fontconfig-devel-2.2.96.20040728-9.i586.rpm
318 pkgconfig-0.15.0-199.i586.rpm
319 atk-1.6.0-4.1.i586.rpm
320 atk-devel-1.6.0-4.1.i586.rpm
321 atk-doc-1.6.0-4.1.i586.rpm
322 pango-1.4.1-3.1.i586.rpm
323 pango-devel-1.4.1-3.1.i586.rpm
324 pango-doc-1.4.1-3.1.i586.rpm
325 glib-1.2.10-589.i586.rpm
326 glib-devel-1.2.10-589.i586.rpm
327 glib2-2.4.6-5.1.i586.rpm
328 glib2-devel-2.4.6-5.1.i586.rpm
329 glib2-doc-2.4.6-5.1.i586.rpm
330 gtk-1.2.10-882.1.i586.rpm
331 gtk-devel-1.2.10-882.1.i586.rpm
332 gtk-engines-0.12-960.1.i586.rpm
333 gtk2-2.4.9-10.1.i586.rpm
334 gtk2-devel-2.4.9-10.1.i586.rpm
335 gtk2-doc-2.4.9-10.1.i586.rpm
336 gtk2-engines-2.2.0-400.1.i586.rpm
337 
338 For Motif:
339 
340 openmotif-2.2.3-6.1.i586.rpm
341 openmotif-demo-2.2.3-6.1.i586.rpm
342 openmotif-devel-2.2.3-6.1.i586.rpm
343 openmotif-libs-2.2.3-6.1.i586.rpm
344 openmotif21-libs-2.1.30MLI4-123.1.i586.rpm
345 
346 For XView:
347 
348 xorg-x11-devel-6.8.1-15.4.i586.rpm
349 xview-3.2p1.4-706.1.i586.rpm
350 xview-devel-3.2p1.4-706.1.i586.rpm
351 xview-devel-examples-3.2p1.4-706.1.i586.rpm
352 
353 To get the textsw package (optional for XView):
354 
355 olvwm-4.1-706.1.i586.rpm
356 
357 Version numbers may be different for your own distro.
358 
359 Then, at the stage when you type ./configure in the tina-tools area, the 
360 last part of the output will be a list of which external widget libraries
361 autoconf was able to find.  This search is run by m4 scripts, and targets
362 particular locations, so may not find the external widget libraries.
363 Typical output will look like this:
364 
365 >tinatool configuration complete for i686-pc-linux-gnu.
366 >
367 > Source directory:        .
368 > Installation directory:     /usr/local/Tina5/tina-tools
369 > C compiler:           gcc
370 >
371 > tina-libs headers:       /usr/local/Tina5/tina-tools/../tina-libs
372 > tina-libs libraries:      /usr/local/Tina5/tina-tools/../tina-libs/lib
373 >
374 > X11 headers:          -I/usr/X11R6/include
375 > X11 libraries:         -L/usr/X11R6/lib
376 
377 > GTK flags:          -I/usr/include/gtk-1.2 -I/usr/include/glib-1.2
378 > -I/usr/lib/glib/include -I/usr/X11R6/include
379 > GTK libraries:        -L/usr/lib -L/usr/X11R6/lib -lgtk -lgdk
380 > -rdynamic -lgmodule -lglib -ldl -lXi -lXext -lX11 -lm
381 >
382 > XView headers:         -I/usr/openwin/include
383 > XView libraries:        -L/usr/openwin/lib -lxview -lolgx
384 >
385 > Motif headers:
386 > Motif libraries:        -lXm -lXp -lXext
387 >
388 > Tcl (>= Version 8) NOT FOUND  Warning
389 >
390 > Configuration successful! Now type 'make' to build the libraries and then
391 > 'make install' to install the libraries into the prefix location.
392 
393 In this example, the X11, XView and Gtk libraries and includes are
394 found. The Motif lines show that the libraries are found but not the
395 headers: watch out for this situation, as it means that the Motif widgets
396 will not be compiled. The Tcl libraries and headers are not found at all,
397 and so again will not be compiled.
398 
399 If the external widget libraries you want to use are not found, and you 
400 know that they are installed on your system (this will probably be the case 
401 for 64 bit systems) then you have to specify the location on the ./configure 
402 line. Possible arguments are (these should be typed on one line: they have
403 been split up here for clarity):
404 
405 ./configure
406 --with-gtk-prefix=              (location of the gtk installation)
407 --with-motif-includes=          (location of the Motif headers)
408 --with-motif-libraries=         (location of the Motif libraries)
409 --with-tcl=                     (location of the tcl installation)
410 --with-tk=                      (location of the tk installation)
411 --with-xview-includes=          (location of the xview headers)
412 --with-xview-libraries=         (location of the xview libraries)
413 
414 You can find these by browsing through the inlined documentation in the m4 
415 scripts (in tina-tools/m4). Typical locations on a 64-bit system will be:
416 
417 ./configure
418 --with-xview-libraries=/usr/openwin/lib64
419 --with-xview-includes=/usr/openwin/include
420 --with-gtk-prefix=/opt/gnome
421 --with-tk=/usr/lib64
422 --with-tcl=/usr/lib64
423 --with-motif-libraries=/usr/X11/lib64/Xm
424 --with-motif-includes=/usr/X11/lib64/Xm
425 
426 They may be different on your machine.  The two XView lines are the lib64 and 
427 include directories in the openwin directory (search for openwin). The Motif 
428 paths can be found by searching for Xm.h. The Tcl and Tk paths can be found 
429 by searching for tclconfig.sh and tkconfig.sh. The gtk prefix can be found 
430 by searching for gtkConfig.sh
431 
432 Add these to the configure line, and check the report: as long as full paths
433 are given for both the includes and headers for the widgets and graphics you
434 want to compile, you will be OK. Then "make" and "make install": now you
435 should find that the tina-tools/lib directory contains libraries called e.g.
436 libtinatoolGphxGdk.a and libtinatoolWdgtsGtk.a (for gtk widgets and gdk
437 graphics).
438 
439 
440 3c) Compiler warning messages
441 -----------------------------
442 
443 
444 When you compile TINA you will notice a large number of compiler warnings.
445 They are the legacy of the 20-year development history of TINA: old coding
446 practices that are now considered unacceptable.  One example is the 
447 assumption that a pointer and an integer occupy the same amount of memory:
448 this is true on 32-bit systems, but not in general on 64-bit systems.
449 We are currently fixing these warnings: however, none of them have been 
450 found to affect the algorithmic functionality.
451 
452   
453 4) How do I compile the toolkits?
454 ---------------------------------
455 
456 
457 At the end of step 3 you should have built the TINA libraries in both 
458 tina-libs and tina-tools.  The algorithmic functionality they provide could,
459 in theory, be used in your own code.  However, 99% of users will want to use
460 the interface included with the libraries.  These interfaces are called 
461 "toolkits", and must be built independently of the libraries.  Three examples
462 are included in the Tina5/toolkits area: they are called example, example2, 
463 and mri_analysis.  
464 
465 The toolkit of interest to most users will be example2: this includes all 
466 tools available at the time of writing i.e. all of the TINA functionality.
467 If you don't intend to do any programming, this is the one you should build.
468 Automatic building and installation is not included (yet) for historical 
469 reasons: out scientific users expect to be able to build the libraries 
470 independently, and so toolkit building must be performed after the library 
471 build.  To build this toolkit, follow the instructions below.  You can then 
472 make a link to the example2 executable in /usr/local/bin, allowing you to 
473 run tinaTool from the command line.  An icon is included in the example2 
474 directory, should you wish to set up a desktop icon.
475 
476 To compile one of the example toolkits, cd into example, example2, or
477 mri_analysis, and type make: this will build the tinaTool program, which you
478 can then run.  The example toolkit is very basic, but can be used as a
479 starting point for building your own toolkit.  The example2 toolkit include
480 all available TINA functionality. The mri_analysis toolkit contains the basic
481 medical images analysis functions: download the MRI image sequences from the
482 image library on our website, read the TINA 5 User's Guide (also on the
483 website) to find out how the tools work, and start experimenting with the
484 algorithms!
485 
486 Since TINA is research software, it has been designed to allow users to build
487 their own toolkit for their current project, including only the tools
488 required.  Most users will therefore eventually want to write their own
489 toolkit.  This is relatively simple: you just have to copy one of the example
490 toolkits to a project area (e.g. /home/my_user_name/my_tina_project), open
491 tinaTool.c in an editor, and add a button for the tool you want to main(), and
492 a button procedure function to call the tool.  For example, if you wanted to
493 access the coreg tool, you would add a button to main() using:
494 
495 tw_button("Coreg", coreg_tool_proc, NULL);
496 
497 and then the button procedure coreg_tool_proc anywhere above main
498 
499 static void coreg_tool_proc()
500 {
501     coreg_tool(250, 250);
502 }
503 
504 Finally, you have to add the header files that contain the prototypes for the 
505 tools you want to include. Prototypes for all tool functions are contained in
506 
507 #include <tinatool/tlbase/tlbaseDef.h>
508 #include <tinatool/tlbase/tlbasePro.h>
509 
510 for the basic tools (input/output etc),
511 
512 #include <tinatool/tlbase/tlvisDef.h>
513 #include <tinatool/tlbase/tlvisPro.h>
514 
515 for the machine vision tools, and
516 
517 #include <tinatool/tlbase/tlmedDef.h>
518 #include <tinatool/tlbase/tlmedPro.h>
519 
520 for the medical image analysis tools.  Since the coregistration tool is in the
521 medical tools library, you would add the last two lines to the top of your
522 tinaTool.c file (alongside the other header file include statements), or you
523 could just add all six.  The TINA Users guide on the website
524 (www.tina-vision.net/software.php) contains a complete list of available
525 tools.
526 
527 After building and running tinaTool, you will see a new button in the main
528 tool called "coreg".  Pressing this calls the button procedure, which in turn
529 calls the coreg_tool function from the libraries.
530 
531 
532 4a) Toolkits with different widget sets
533 ---------------------------------------
534 
535 
536 In order to compile toolkits with various widget sets, I recommend that you
537 use a simple Makefile.  The example2 toolkit directory in tina-tools/example
538 contains an example: it allows you to switch simply between the different 
539 available widget sets, although you have to set some paths here by hand.  The
540 Makefile is called Makefile_tina: rename it to Makefile (after backing-up the 
541 existing Makefile) to begin this process.
542 
543 In general, a simple Tina5 makefile should look something like the following
544 (the filename should be "Makefile"):
545 
546 ##
547 # Makefile for Tina5
548 #
549 
550 TINALIBS     = -ltinaMedical -ltinaVision -ltinaImage -ltinaFile -ltinaGeom 
551                -ltinaMath -ltinaSys 
552 TINATOOLLIBS = -ltinatoolTlMed -ltinatoolTlvision -ltinatoolTlBase 
553                -ltinatoolDraw -ltinatoolWdgtsGtk -ltinatoolGphxGdk 
554 XLIBS        = -lgtk -lgdk
555 SYSLIBS      = -lm 
556 CFLAGS       = -g -pipe -DHAVE_CONFIG_H -DOWTOOLKIT_WARNING_DISABLED
557 INCLUDES     = -I./ -I/usr/local/Tina5/tina-tools 
558                -I/usr/local/Tina5/tina-libs -I/usr/openwin/include
559 LDFLAGS      = -L/usr/local/Tina5/tina-libs/lib -L/usr/local/Tina5/tina-tools/lib 
560                $(TINATOOLLIBS) $(TINALIBS) -L/opt/gnome/lib  $(XLIBS) $(SYSLIBS) 
561 OFILES = 
562 
563 .c.o:
564              gcc $(CFLAGS) $(INCLUDES) -c -o $@ $*.c
565 
566 tinaTool: tinaTool.o $(OFILES)
567              gcc -o $@ $(CFLAGS) tinaTool.o $(OFILES) $(LDFLAGS)
568 
569 # ---------
570 # Household
571 # ---------
572 
573 clean : 
574           \rm *.o
575 
576 
577 There are eight lines that set up various locations.  TINALIBS and TINATOOLS
578 list the libraries to be included from the tina-libs and tina-tools lib 
579 directories.  These must be in order, and the only changes you should need
580 to make to the above are to the Wdgts and Gphx libraries: these choose the 
581 widget set you will use, and there are three possible combinations of interest 
582 to the majority of users:
583 
584 -ltinatoolWdgtsXm -ltinatoolGphxX11  :  Motif widgets
585 -ltinatoolWdgtsXv -ltinatoolGphxX11  :  XView widgets
586 -ltinatoolWdgtsGtk -ltinatoolGphxGdk :  Gtk widgets
587 
588 The XLIBS line selects the external widget set libraries used: again there are 
589 three possible selections:
590 
591 XLIBS = -lXm -lX11             : Motif widgets
592 XLIBS = -lxview -lolgx -lX11   : Xview widgets
593 XLIBS = -lgtk -lgdk            : Gtk widgets
594 
595 I always call this line XLIBS, although it should be named for the libraries
596 you want to install. 
597 
598 The CFLAGS line passes arguments to the compiler: for most Linux systems, only
599 the first is of interest: -g adds debugging information, making your
600 executable larger, but providing the information necessary for using GDB or
601 DDD for debugging.  Add -0, -02 or -03 for various levels of optimisation,
602 making the executable run faster, but making debugging more difficult.
603 
604 Finally, the INCLUDES and LDFLAGS lines set paths for the libraries you have 
605 specified above.  These should look something like:
606 
607 INCLUDES = -I./ -I/usr/local/Tina5/tina-tools -I/usr/local/Tina5/tina-libs
608 -I/usr/openwin/include
609 LDFLAGS = -L/usr/local/Tina5/tina-libs/lib -L/usr/local/Tina5/tina-tools/lib
610 $(TINATOOLLIBS) $(TINALIBS) -L/usr/include/gtk-1.2 $(XLIBS) $(SYSLIBS)
611 
612 for gtk, 
613 
614 INCLUDES = -I./ -I/usr/local/Tina5/tina-tools -I/usr/local/Tina5/tina-libs
615 -I/usr/openwin/include
616 LDFLAGS = -L/usr/local/Tina5/tina-libs/lib -L/usr/local/Tina5/tina-tools/lib
617 $(TINATOOLLIBS) $(TINALIBS) -L/usr/openwin/lib -L/usr/X11/lib $(XLIBS)
618 $(SYSLIBS)
619 
620 for XView, and 
621 
622 INCLUDES = -I./ -I/usr/local/Tina5/tina-tools -I/usr/local/Tina5/tina-libs 
623 -I/usr/openwin/include
624 LDFLAGS = -L/usr/local/Tina5/tina-libs/lib -L/usr/local/Tina5/tina-tools/lib 
625 $(TINATOOLLIBS) $(TINALIBS) -L/usr/X11/lib $(XLIBS) $(SYSLIBS) 
626 
627 for Motif.  
628 
629 The library and include locations will have to be set for your machine, but 
630 should be fairly standard. Just two points to be aware of: the locations will 
631 be .../lib64 rather than .../lib on 64-bit systems, and notice that you refer 
632 to libraries in shorthand, so libxview.so becomes lxview (suffix stripped, 
633 and l replacing lib).
634 
635 The OFILES line refers to object files you wish to compile.  If you are 
636 compiling one of the example toolkits i.e. the only .c file in the current
637 directory is tinaTool.c, then leave it empty.  If you start writing or adapting
638 your own Tina code (see below) and have a directory with other c files in it, 
639 add my_c_file.o to this line for every my_c_file.c you want to compile.
640 
641 Finally, type "make" in the directory containing the tinaTool.c file and the 
642 Makefile: if all goes well, you should end up with a "tinaTool" executable that
643 you can run.
644 
645 
646 5) How do I write my own TINA code?
647 -----------------------------------
648 
649 
650 TINA provides the ideal environment for machine vision or medical image
651 analysis researchers to develop their own code.  All of the basic functionality
652 (memory allocation, image representation, basic image processing, geometry, 
653 maths etc. etc.) is already present, allowing for rapid code development.  In
654 addition, the long development history has resulted in highly stable code.
655 
656 
657 5a) Writing new algorithmic functionality
658 -----------------------------------------
659 
660 
661 In order to start developing new algorithmic functionality, set up a project
662 area with a simple Makefile and a tinaTool.c file (you can use the example
663 one provided in the tina-tools area).  Then, there are two possible options:
664 writing new files, or adapting those already present in the libraries.
665 
666 If you are adapting files from the libraries, copy the C files plus their
667 file-level H files to your project area. Then build a copy of the header
668 file directory structure in your project area: put the inctw script
669 in your project area, and run it. The script can be found in the 
670 tina-tools/toolkits/example2 directory. This sets up a copy of the
671 header directory system, and soft-links from the relevant directories to the
672 header files in your project area, ensuring that when you compile TINA it
673 links in the local header files in place of the ones in the libraries. Then
674 you can get on with your coding: remember to add prototypes to your project
675 area header files if you add new functions.
676 
677 Secondly, if you are writing new C files, you can just work in a project area
678 as usual: the libraries won't be linking to your code, so the header file
679 system doesn't affect you. However, if in the future you will be putting
680 your code back into the libraries, you should think about where it would go
681 and divide up your code accordingly.
682 
683 
684 
685 5b) Porting old TINA 4 code to TINA 5
686 -------------------------------------
687 
688 
689 Several major changes were made to the TINA libraries in the move from
690 version 4 to version 5. In particular, we have a new header file system, and 
691 a new version of the sequence tool. The header file structure for TINA4 was 
692 a complete mess (and one of the common criticisms of TINA), so everyone ended 
693 up including tina_all.h and thus completely bypassing the whole point of header
694 files. Therefore, we have put a formal structure in place, which makes the 
695 code much cleaner, easier to write, and easier to understand.
696 
697 The code is divided into three layers: library, group, and file. For example,
698 the function coreg_auto (which performs coregistration) is in the file 
699 tlmedCoreg_auto.c, so the group is tlmedCoreg (the group for coregistration 
700 functions) and the library is tlmed (the library for medical functions).  
701 The tl tells you that it is in the tina-tools area, rather than tina-libs.
702 Every C file has its own H file for prototypes of all non-static functions in 
703 that C file. The file level H file must be in the same directory as its C
704 file. Other C files in the same group should include that "file level" H file 
705 when needed. Every group has its own "group level" header files: in this
706 example tlmed_CoregPro.h and tlmed_coregDef.h. The Pro file includes all of 
707 the file level H files for that group, and the Def file contains all 
708 definitions (structures etc) for that group. C files in other groups should 
709 include the group level header files when needed. Finally, there are library 
710 level header files tlmedPro.h and tlmedDef.h: these include all of the group 
711 level Pro and Def files for that library. C files in other libraries should 
712 include the library-level header files when needed. Finally, the whole of 
713 TINA is split into the tina-tools, which is front end and algorithmic code,
714 and tina-libs, which is lower-level code (memory allocation, handling 
715 structures etc.). It may seem a bit complicated, but when you get used to it 
716 this system allows you to know immediately which H files you should be 
717 including in your own C files, making coding much faster without the need for 
718 a tina-all.h file.
719 
720 The changes in terms of locations of functions are mostly limited to the 
721 sequence tool: some functions (such as get_seq_ptr) have changed their names. 
722 The easiest way to port your code is to put it into a project area, strip out 
723 all include statements, and compile. Then, start the lxr code browser web 
724 page, and search for each function that generates "function not defined" 
725 errors: once you know which C file the function is in, you can work out which 
726 H file to include. These will be only library-level header files if you 
727 never intend to put your code back into the libraries.
728 
729 Finally, if there are any functions whose names have changed, search through 
730 the libraries that correspond to the relevant area in TINA4. For example, if 
731 you are including get_seq_ptr, you know it comes from the sequence tool: 
732 search the sequence tool code (group tlbaseSeq for the tina-tools level stuff 
733 and imgSeq for the tina-libs level stuff) for a function that does the same 
734 job (in this case get_seq_ptr). It seems long-winded at first, but don't 
735 despair: after a couple of hours of this, you can do it from memory without 
736 using the code browser.
737 

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~ [ freetext search ] ~ [ file search ] ~

This page was automatically generated by the LXR engine.
Visit the LXR main site for more information.