1 TINA 6 README
2 =============
3
4 paul.bromiley@manchester.ac.uk 02/07/2010
5
6
7 Contents
8 --------
9
10 1) What is TINA?
11 1a) History
12 1b) Authors
13 1c) What does TINA stand for?
14 1d) How do I know it works?
15 2) Where do I get TINA?
16 3) How do I compile the libraries?
17 3a) Compatibility issues
18 3b) Compiler warning messages
19 3c) For Developers Only
20 4) How do I compile the toolkits?
21 5) How do I write my own TINA code?
22 5b) Porting old TINA 5 code to TINA 6
23
24
25 1) What is TINA?
26 ----------------
27
28 TINA (TINA Is No Acronym) provides a set of libraries for machine vision and
29 image analysis research. It is written in C primarily for use on GNU/Linux
30 platforms, although it can also be compiled on MacOSX, Solaris, and (with some
31 effort) MS Windows. The code is split into two areas:
32
33 tina-libs: back-end code for memory management, image structure handling
34 etc.
35
36 tina-tools: high-level algorithms, interface etc.
37
38 Each of these areas contains a number of libraries with specific purposes:
39
40 tina-libs:
41
42 file: input/output file handling
43 geometry: basic geometry functions
44 image: basic image processing functions
45 math: basic mathematical functions
46 medical: back-end functions for medical image analysis
47 sys: basic memory allocation functions
48 vision: back-end functions for machine vision
49
50 tina-tools:
51
52 draw: basic display drawing
53 gphx: low-level interface to widget sets
54 wdgts: high-level interface to widget sets
55 tlbase: basic tools (image loading etc.)
56 tlvision: machine vision tools
57 tlmedical: medical tools.
58
59 In order to use TINA, you must download both the tina-libs and tina-tools areas
60 from our website, and compile both. This will produce a set of libraries in the
61 libs subdirectories of both tina-libs and tina-tools.
62
63 The TINA libraries can be used in one of two ways. They have been designed to
64 be highly modular, allowing users to strip out parts of the functionality to
65 use in their own code (under the terms of the licence). However, they also
66 include code for interfaces to the algorithms. This code is in the form of a
67 set of "tools", each of which appears as a window on the screen, and which
68 collect together related functionality applicable to a certain task (loading
69 single images, stereo image pairs, temporal sequences or medical image
70 volumes; stereo vision; medical image segmentation; registration; blood flow
71 analysis etc. etc. ). In order to use this interface, you must build a
72 "toolkit", a program that includes the tools you want to access.
73
74 TINA is research software, continuously updated by a small group of core
75 programmers at the University of Manchester, primarily for their own
76 use. There is no "stable" release as such: the code in the tarballs is the
77 latest version. However, it is written with numerical stability and
78 statistical validity in mind, and all new additions are thoroughly tested.
79
80
81 1a) History
82 -----------
83
84 Development of the original X11 based versions of TINA started in 1989 at the
85 Artificial Intelligence & Vision Research Unit (AIVRU) at the University of
86 Sheffield (www.shef.ac.uk). It was designed using experience gained in two
87 previous versions with an aim to minimise the process of software maintenance
88 and maximise code reuse. Later versions of TINA were developed there and also
89 at the Electronic Engineering Department of the University of Sheffield. TINA
90 became Open Source whilst being maintained by Electronic Engineering. Since
91 1997 TINA maintenance has been switched to Imaging Science and Biomedical
92 Engineering (ISBE) (www.isbe.man.ac.uk) at the University of Manchester
93 (www.manchester.ac.uk).
94
95 Until 2002 TINA was never explicitly funded as a project in its own
96 right. Rather it has been developed under numerous research grants and
97 collaborations as a framework to facilitate an ongoing co-ordinated research
98 effort into artificial vision. TINA was originally conceived by AIVRU
99 researcher Stephen Pollard as a library of functions necessary for
100 stereo-based 3D machine vision. John Porrill and Neil Thacker where also
101 involved at these early stages. After this team broke up Neil Thacker
102 continued vision research within TINA at Electronic Engineering, and together
103 with Tony Lacey released TINA as Open Source. In 1997 both Neil Thacker and
104 Tony Lacey moved to ISBE, from where TINA is now maintained. Tony left for a
105 career in industry in 2004: today, Neil Thacker is the project leader for
106 TINA, and Paul Bromiley performs most of the day-to-day maintenance of the
107 code and website.
108
109
110 1b) Authors
111 -----------
112
113 Along the way a large number of people have contributed to TINA both at the
114 University of Sheffield and the University of Manchester. Their contributions
115 are never forgotten (and their code never lost). A full list can be found at
116 www.tina-vision.net/people.php.
117
118
119 1c) What does TINA stand for?
120 -----------------------------
121
122 Originally the acronym TINA stood for "there is no alternative", which was
123 true at the time. Since then, several alternative meanings have been
124 suggested ("Thacker is not acceptable", "TINA is nearly accurate" etc.: most
125 of these were the result of a bad day at work). Today however, in a similar
126 style to acronym GNU, TINA stands for "TINA is no acronym". All previous
127 definitions have now been superseded!
128
129
130 1d) How do I know it works?
131 ---------------------------
132
133 For most software, the question of accuracy is non-existent: your word
134 processor either lets you prepare and print a document, or does not. However,
135 for scientific software the question becomes more problematic because the
136 requirements are more extensive. The results of any machine vision algorithm
137 will be dependent on the statistical validity and numerical stability (or what
138 might be called the "theoretical" and "implementation" aspects) of the
139 algorithm, and any failure to meet these two goals might not be obvious to the
140 user without extensive validation work. Any attempt to justify the algorithms
141 used in TINA here would be largely pointless, since such justification can
142 only be meaningful after a suitable "negotiation of trust". Therefore, I will
143 commence that process with three simple observations:
144
145 a) All of the algorithms in TINA have been derived strictly within a context
146 of statistical validity: you won't find any active contour methods with
147 arbitrary image potential terms here! Therefore, the results of any algorithm
148 can be linked directly to the probability theoretic interpretation of the data
149 generation process. This is not a guarantee that a specific algorithm will
150 work for your data. However, it is a guarantee that, if your data obeys the
151 underlying statistical assumptions relevant to the algorithm (as specified in
152 our published papers: see point b), the interpretation of the data provided by
153 the algorithm will be valid. In theory, your results can be linked directly
154 all the way back to the underlying axioms of mathematics.
155
156 b) All of the algorithms in TINA have been used in our scientific research,
157 and thus subjected to peer-review in conference and journal publications. We
158 make preprints of these publications available via our website at
159 www.tina-vision.net/docs/memos.php. These papers contain details of our
160 in-house validation work.
161
162 c) All of the algorithms in TINA are available as open-source software.
163 Through a combination of reading the memos, documentation, and code, you can
164 see exactly how a given algorithm works. This facility is rarely afforded to
165 users of commercial machine vision or medical image analysis software. If you
166 think you have spotted a mistake in our work, get in touch! You will either
167 gain (admittedly limited) fame as an external contributor named on the TINA
168 website, or a very lengthy tutorial on statistics (e.g. if you mention the
169 words "Bayes Theory" within earshot of one of the core programmers).
170
171
172 2) Where do I get TINA?
173 -----------------------
174
175 Tina tina-libs and tina-tools code can be downloaded from our website
176 (www.tina-vision.net), in the form of tarballs, via the "software" link.
177 Both are required in order to access algorithmic functionality.
178
179
180 3) How do I compile the libraries?
181 ----------------------------------
182
183 Before you start, you must have the GNU autotools (autoconf, automake and
184 libtool) installed. The tina-tools libraries also require pkg-config, and
185 GTK+ 2 and its associated packages (for Suse 9.2, the full list of these
186 is:
187
188 fontconfig
189 fontconfig-devel
190 pkgconfig
191 atk
192 atk-devel
193 pango
194 pango-devel
195 glib2
196 glib2-devel
197 gtk2
198 gtk2-devel).
199
200 The basic approach is to cd into the tina-libs-6.0rcbuildxxx directory,
201 then type:
202
203 ./configure
204 make
205 make install
206
207 Next, cd into the tina-tools-6.0rcbuildxxx directory and type the same
208 commands. The configure command will produce a report on the required
209 packages it has been able to locate, which should look something like:
210
211 > tina-tools configuration complete for i686-suse-linux-gnu.
212 >
213 > Source directory: .
214 > Installation directory: /usr/local/Tina6/tina-tools
215 > C compiler: gcc
216 >
217 > tina-libs headers: /usr/local/Tina6/tina-tools/../tina-libs
218 > tina-libs libraries: /usr/local/Tina6/tina-tools/../tina-libs/lib
219 >
220 > GTK2 flags: -I/usr/include/gtk-2.0 -I/usr/lib/gtk-2.0/include
221 > -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0
222 > -I/usr/lib/glib-2.0/include -I/usr/include/freetype2 -I/usr/include/libpng12
223 > GTK2 libraries: -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lgdk_pixbuf-2.0
224 > -lpangocairo-1.0 -lpango-1.0 -lcairo -lgobject-2.0 -lgmodule-2.0 -ldl -lglib-2.0
225 >
226 > Configuration successful! Now type 'make' to build the libraries and then
227 > 'make install' to install the libraries into the prefix location.
228
229 If the penultimate line contains "The configuration has failed.", then
230 some of the required packages have not been found (as indicated by empty
231 results on the GTK2 or tina-libs lines). Install any missing packages,
232 or use the configure options
233
234 ./configure
235 --with-gtk-prefix= (location of the gtk installation e.g. /opt/gnome)
236 --with-tina-includes= (location of the tina-libs directory)
237 --with-tina-libraries= (location of the tina-libs lib subdirectory)
238
239 to specify locations. The full set of options provided by configure can
240 be seen using;
241
242 ./configure --help
243
244 There are currently no specific tina-libs options (as of version 6.0rc0).
245
246
247 3a) Compatibility Issues
248 ------------------------
249
250 If the above instructions fail to work for your system, your first port of
251 call should be the WikiWiki page on our website. Go to www.tina-vision.net,
252 click on "wiki" in the menu, and then click on "Tina5CompileGuide". If your
253 system is listed, then it will provide work-arounds or full solutions for
254 known problems. If not, pipe the outputs of ./configure and make to files and
255 e-mail them to me (paul.bromiley@man.ac.uk) and I will do my best to help you
256 out. I would appreciate feedback on compilation for systems not listed on the
257 wiki page: it allows us to keep the instructions up-to-date.
258
259
260 3b) Compiler warning messages
261 -----------------------------
262
263 When you compile TINA you will notice a small number of compiler warnings.
264 They are the legacy of the 20-year development history of TINA: old coding
265 practices that are now considered unacceptable. One example is the
266 assumption that a pointer and an integer occupy the same amount of memory:
267 this is true on 32-bit systems, but not in general on 64-bit systems.
268 We are currently fixing these warnings: however, none of them have been
269 found to affect the algorithmic functionality.
270
271
272 3c) For Developers Only
273 -----------------------
274
275 If you are a member of the core TINA developer team, you may be tempted to
276 copy the tina6 directory from server6 directly onto your own machine. This
277 should in general be avoided: use the distribution tarballs instead.
278
279 If you decide to ignore the above advice, you may see warnings from the
280 autotools, an indication that you need to reconfigure the build system.
281 This involves using six different commands in the correct order. See PAB
282 for instructions. The instructions he will give you are: use the distribution
283 tarballs instead.
284
285 Under no account should you copy a tina6 directory from your machine back
286 onto server6. If you wish to modify the source code on server6, this must
287 be done file-by-file. In addition, you will have to diff each file you
288 wish to add with the current version in order to determine whether anyone
289 else has changed the file since you obtained it.
290
291 If you make any changes to the build system (i.e. configure.ac or any
292 Makefile.am), speak to PAB before copying them onto server6.
293
294 At some point in the (hopefully near) future, TINA 6 will be placed under
295 CVS control; this will solve the above issues.
296
297
298 4) How do I compile the toolkits?
299 ---------------------------------
300
301 At the end of step 3 you should have built the TINA libraries in both
302 tina-libs and tina-tools. In order to use them, an interface program
303 called a "toolkit" is required. Three example toolkits are included
304 in the distribution, in the tina-tools/toolkits area: the one of
305 interest to most users will be the example2 toolkit, which includes
306 most of the currently available algorithms. The executable for this
307 toolkit is also installed in tina-tools/bin. If desired, a link to
308 that file can be created in /usr/local/bin, allowing it to be run
309 from the command line. An icon is included in the example2 directory,
310 should you wish to set up a desktop icon.
311
312
313 5) How do I write my own TINA code?
314 -----------------------------------
315
316 TINA provides the ideal environment for machine vision or medical image
317 analysis researchers to develop their own code. All of the basic functionality
318 (memory allocation, image representation, basic image processing, geometry,
319 maths etc. etc.) is already present, allowing for rapid code development. In
320 addition, the long development history has resulted in highly stable code.
321
322 The simplest way to begin writing your own TINA code is to create a project
323 area (e.g. /home/my_user_name/my_tina_project), and copy into it the files
324 from the example2 toolkit in tina-tools/toolkits/example2. These include a
325 simple makefile, called Makefile.tina, which can be used to compile the code
326 without using the GNU autotools. Remove the existing Makefile from the
327 project area and rename Makefile.tina to Makefile.
328
329 The Makefile requires some manual editing, as follows: the EXTWDGTLIBS line
330 should contain the location of your GTK+ 2 library (e.g. /usr/lib), and the
331 INCLUDES and LDFLAGS lines should contain the locations of your tina-libs
332 and tina-tools libraries. The OFILES line of the Makefile refers to object
333 files you wish to compile. If you are compiling one of the example toolkits
334 i.e. the only .c file in the current directory is tinaTool.c, then leave it
335 empty. If you start writing or adapting your own Tina code (see below) and
336 have a directory with other c files in it, add my_c_file.o to this line for
337 every my_c_file.c you want to compile. In order to add new functionality,
338 there are two options: adapt existing files from the libraries, or add new
339 files of your own.
340
341 If you are adapting files from the libraries, copy the C files plus their
342 file-level H files to your project area. Then build a copy of the header
343 file directory structure in your project area: put the inctw script
344 in your project area, and run it. The script can be found in the
345 tina-tools/toolkits/example2 directory. This sets up a copy of the
346 header directory system, and soft-links from the relevant directories to the
347 header files in your project area, ensuring that when you compile TINA it
348 links in the local header files in place of the ones in the libraries. Then
349 you can get on with your coding: remember to add prototypes to your project
350 area header files if you add new functions.
351
352 If you are writing new C files, you can just work in a project area as usual:
353 the libraries won't be linking to your code, so the header file system doesn't
354 affect you. However, if in the future you will be putting your code back into
355 the libraries, you should think about where it would go and divide up your code
356 accordingly.
357
358 Finally, type "make" in the directory containing the tinaTool.c file and the
359 Makefile: if all goes well, you should end up with a "tinaTool" executable that
360 you can run.
361
362
363 5b) Porting old TINA 5 code to TINA 6
364 -------------------------------------
365
366 The only major change between TINA 5 and TINA 6 is the removal of the widget
367 library interfaces for Xview, Motif, Tcl/Tk and Gtk+ 1.2 (as well as the NULL
368 widget interface). Only the Gtk+ 2 interface remains. As a consequence, the
369 build system has been simplified. No changes to toolkit code should be
370 required as a consequence of these changes. However, the local Makefile may
371 have to be modified to remove references to the old widget interface libraries.
372 See the example2 toolkit in tina-tools/toolkits for an example.
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.
