Thumbcat

Image Catalogue Application

9 Developer Notes

This chapter contains information about how Thumbcat works and can be tuned to suit the user. The section on Book styles describes the necessary sprite files and the use of each icon inside the file. The section on tag files describes the lists that Thumbcat uses to decode the EXIF data embedded in digital camera exif files. These files can be modified by the user to add new camera maker notes if necessary. However, it is recommended that the description of the maker notes is passed back to the author who can test them and make sure that the new maker is available in a future release of Thumbcat for all users.

9.1 Book Styles

A book style is made up of a number of icons all of which are 24 x 24 pixels in size.

Binding

This is the spine of the book and consists of a single sprite called "bindingv". The name of the sprite file is the name of the binding and all are located in !Thumbcat.Resources.Book.Binding.

Finish

These icons define the "covers" of the book. The sprite file is the name of the finish and all are located in the directory !Thumbcat.Resources.Book.Finish. The various sprite names and positions are as follows :

tlc	tlcr	te	te	tm	te	te	trcl	trcf
tlcd	bg	bg	bg	bg	bg	bg	bg	trcd
le	bg	bg	bg	bg	bg	bg	bg	re
le	bg	bg	bg	bg	bg	bg	bg	re
blcu	bg	bg	bg	bg	bg	bg	bg	brcu
blc	blcr	be	be	bm	be	be	brcl	brc

The top right corner can be either "trcf" or "trcb" which are for a window at the front of the stack or behind other windows respectively. An example of these icons is show below for the above array.

In the above example the sprites "re" and "brcu" are identical but they don't have to be. The background and edge sprites are not all plotted 24x24 pixels in size. When the the book is loaded Thumbcat creates an additional sprite for each edge (te, be , re, le) and the background (bg) that is 4 times the size i.e. 4 sprites joined together. This significantly reduces the number of icons in a window and improves the redraw time.

9.2 Tag Files

These files define the contents and format of the EXIF data tags.

9.2.1 Makers

This file defines the camera makers and has 6 columns

The internal maker id which links to the "Taglist" file.
A short name to match maker names, this is shorter than normal so that truncated names in EXIF files will still match
Camera model id or blank for default maker. Also a shortened name to ensure matched values.
The offset within the maker note to the start of the IFD records
The type of ifd
- 0 - normal 2 byte tag count followed by 12 byte tag records
- 1 - single byte tag count followed by 12 byte tag records
- +100 - Offset data is with respect to the start of the maker note
The data format of the maker note
- 0 - little endian
- 1 - big endian
- 2 - inherit from IFD containing the makernote tag. This is the normal value

9.2.2 Itemlist

This defines all the data items that Thumbcat recognises and is an amalgamation of all the standard EXIF tags and each makers own tag. Wherever possible the original EXIF tagname has been used. The table is in case insensitive alphabetic order of the tag name. It has 4 columns :

The group name. Not currently used but it is the EXIF grouped name...almost.
The tag name
The descriptive title, if blank then the tag name is used
Bits defining the applicability of the tag
- bit 0 - the tag applies to a still image
- bit 1 - the tag applies to a vector image
- bit 2 - the tag applies to a video image
- bit 3 - Thumbcat determines the value from other tags i.e. those with bit 4 set
- bit 4 - the tag is not stored in the Thumbcat catalogue but referenced by others during interpretation
- bit 5 - the tag value is displayed in the detail window
- bit 6 - the value is stored but never displayed
The datatype for validation of changes performed by the user
- 0 - any
- 2 - string
- 4 - unsigned integer
- 5 - unsigned real
- 9 - signed integer
- 10 - signed real
- 19 - real represented as a fraction. If the value is less than 1 then it is represented in the form 1/x where x = 1/value. If greater than 1 then shown as is.
- 20 - date-time
- 21 - list of reals (not currently handled)
- 22 - list of integers (not currently handled)
- 23 - pointer i.e. internal use, included here for clarity only
- 24 - mixed table (not currently handled)
- +256 - Limited set of values as listed in Fixedval
The units

There are some tags that only have bit 4 set. In these cases Thumbcat will handle multiple tags with the same interpretation and assign the most appropriate value to the applied tag. Examples are :

   Applied Tag    Reference Tags

   Xsize    ImageWidth , PixelXDimension , the image itself.

   Ysize    ImageHeight , PixelYDimension , the image itself.

   Shutter    ShutterSpeedValue , ExposureTime

   Aperture    FNumber , ApertureValue

   Title    ImageDescription , other databases.

   Date    DateTime , the files datestamp.

The tags in this file, with the appropriate flags, are the ones in the !ThumbcatC database files. Thus adding new tags to this file expands the Thumbcat database.

9.2.3 Taglist

This table defines all the standard EXIF tags and all the maker note tags. The link between the contents of this file and the "Itemlist" file is the tag name. the link to the "Maker" file is the maker id. This has 5 columns

The internal maker id
The decimal code number
The internal sub tag number. this is 1 in most cases but allows for each element within a tag to have a different meaning.
The tag name
The translation of the value
- 0 - ignored ,don't know, unknown
- 1 - the tag value as is, i.e. an integer number
- 2 - the tag value is a subcode to be translated by referencing TVXlate.
- 3 - the tag value needs to be interpreted internally by Thumbcat.
- 4 - the tag value is a 4 byte string
- 5 - the tag is made up of sub tags. These are exactly the same format as multiple subcodes except that each subcode is interpreted differently.

9.2.4 TVxlate

This table is used to translate coded tags and has 5 columns

The internal maker id i.e. as listed in the Maker file
The element. Almost always 1.
If the translation type is 2 then each element defines a different translated list where each translated element is concatenated to form the overall tag value.
If the translation type is 4 then each element is a different tag value. the internal sub tag value from the Taglist file will define each tags meaning.
The decimal tag code number
The subcode number
The translated value

9.2.5 Fixedval

This specifies the limited set of values that an item can have.

The tag name which links to the name in the file Itemlist
A value

9.2.6 Reading from an Exif File

The file contents are interpreted and values will be assigned against the tags from the "Taglist" file. These are then matched against the list tags in the "Itemlist" file. Since the maker notes are at the end of the "taglist" file then if there any duplicate tag values the maker note version will be the last one matched to the "Itemlist" file.

When storing tags in the thumbcat database the "Itemlist" values are searched and any missing values whose bit 3 is set are then interpreted from other values. For example FNnumber and ApertureValue will be read from the Exif file. The thumbcat internal tag "Aperture" will be blank and so its value will be populated with either FNnumber or ApertureValue. Only "Aperture" will be stored in the thumbcat database.

9.2.7 Reading from the Thumbcat Database

When reading tags from the database (!ThumbcatC file) they are all matched against the "Itemlist" list and handled within thumbcat as if a complete list was read. However, only non blank values are stored in !ThumbcatC.

9.3 View Files

There is one view file per view and they are all stored in the directory <Choices$Write>.Thumbcat.Views. The name of the file is the name of the view. Each file has a header line and an entry for each image in the view. The entries have four comma seperated values :

The catalogue name
The album name
The image name
The RISCOS filespec for the options file of the source catalogue

9.4 Search Files

Search files are stored in the directory <Choices$Write>.Thumbcat.Searches. The file name is the search name. Each file contains lines of tag-name : tag-value pairs of data. The tags are :

Tag Name	Tag Description
Title	A short description of the use of the search
Context	How the search is applied. It can have one of 3 values:
	Album	search is confined to the current album
	Catalogue	search is confined to the current catalogue
	All	search is applied to all albums of all known catalogues
Match	Defines how multiple criteria results are interpreted, There are two values :
	All	All the criteria must match for a success (Logical AND)
	Any	At least one of the criteria must match for a success (Logical OR)
Criteria	Start of a criteria expression block. There can be up to 4 criteria blocks
Tag	The name of a tag. Part of a criteria block
Condition	The condition of the expression. Part of a criteria block. It can be one of :
	=	Number or string
	<	Number or string
	<=	Number or string
	>	Number or string
	>=	Number or string
	<>	Number or string
	contains	String only
	begins with	String only
	ends with	String only
Value	The comparison value for the expression. Part of a criteria block.
Case	If Y then string comparisons are case sensitive. Part of a criteria block.
End	End of a criteria block

9.5 Database Files

This section describes the internal organisation of the three database files.

9.5.1 !ThumbcatO

This describes the options that have been selected for the catalogue. It is made up of a list of tag-name:tag-value pairs. The tag names are case insensitive but must be seperated from the tag value by a colon. Any whitespace is ignored.

Tag Name	Value interpretation
Calendar_Order	If 1 then Albums will be ordered by their equivelent calendar month number e.g. January before April.
Image_Location	The location of the top of the image tree. For a linked catalogue this will be a relative reference. For an unlinked catalogue with will be an absolute reference
Calendars_First	If 1 then Albums with a name that matches a calendar month precede non calendar Albums in the catalogue display
Catalogue_Location	The RISCOS filespec for the location of this catalogue. It will be a relative or absolute reference like Image_Location
Title	The title for the catalogue
Read_Only	Either a 1 or a 0. If 1 then the catalogue is for read-only images e.g. CDROM

9.5.2 !ThumbcatI

This describes all the albums in the catalogue. There is one line per album and each line consists of 5 comma seperated values:

The RISCOS directory spec relative to the top of the image tree. The concatenation of the value stored in !ThumbcatO tag Image_Location and this value gives the absolute RISCOS directory name.
The level of the Album. All Albums (directories) in the same parent directory have the same level number. This may seem superfluous for a catalogue where there is a one to one link between Albums and directories. However, the same strucutre is used to organise arbitrary collections of images. Thus in a arbitrary collection images in totally different locations, even different media, can be grouped in the same Album. Levels allow nested structures even for arbitrary collections.
The number of images in the album.
The total size of all the images in the Album
The Album title.

9.5.3 !ThumbcatC

This contains the EXIF like data for each image. The file is organised as a pair of tag-name:tag-value pairs of data. The tag-name is case insensitive. There is one entry for every non blank value. There are some special tags that are not data related :

Tag Name	Value interpretation
Image	The image name. This must be the first tag for an image
Location	The full RISCOS filespec for the location of the image. This is either in relative notation (<2003$dir>.apicture) or absolute notation (ADFS::$.2003.apicture) depending on whether the catalogue is linked or unlinked.
End	There is no value but the tag must be present to indicate the end of the tag data for the image

	Applied Tag		Reference Tags
	Xsize		ImageWidth , PixelXDimension , the image itself.
	Ysize		ImageHeight , PixelYDimension , the image itself.
	Shutter		ShutterSpeedValue , ExposureTime
	Aperture		FNumber , ApertureValue
	Title		ImageDescription , other databases.
	Date		DateTime , the files datestamp.