|
Packit |
994f1a |
<HTML>
|
|
Packit |
994f1a |
<HEAD>
|
|
Packit |
994f1a |
<TITLE>
|
|
Packit |
994f1a |
Modifying The TIFF Library
|
|
Packit |
994f1a |
</TITLE>
|
|
Packit |
994f1a |
</HEAD>
|
|
Packit |
994f1a |
<BODY BGCOLOR=white>
|
|
Packit |
994f1a |
<FONT FACE="Arial, Helvetica, Sans">
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Defining New TIFF Tags
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Libtiff has built-in knowledge of all the standard TIFF tags, as
|
|
Packit |
994f1a |
well as extentions. The following describes how to add knowledge of
|
|
Packit |
994f1a |
new tags as builtins to libtiff, or how to application specific tags can
|
|
Packit |
994f1a |
be used by applications without modifying libtiff.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
TIFFFieldInfo
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
How libtiff manages specific tags is primarily controlled by the
|
|
Packit |
994f1a |
definition for that tag value stored internally as a TIFFFieldInfo structure.
|
|
Packit |
994f1a |
This structure looks like this:
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
typedef struct {
|
|
Packit |
994f1a |
ttag_t field_tag; /* field's tag */
|
|
Packit |
994f1a |
short field_readcount; /* read count/TIFF_VARIABLE/TIFF_SPP */
|
|
Packit |
994f1a |
short field_writecount; /* write count/TIFF_VARIABLE */
|
|
Packit |
994f1a |
TIFFDataType field_type; /* type of associated data */
|
|
Packit |
994f1a |
unsigned short field_bit; /* bit in fieldsset bit vector */
|
|
Packit |
994f1a |
unsigned char field_oktochange;/* if true, can change while writing */
|
|
Packit |
994f1a |
unsigned char field_passcount;/* if true, pass dir count on set */
|
|
Packit |
994f1a |
char *field_name; /* ASCII name */
|
|
Packit |
994f1a |
} TIFFFieldInfo;
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
field_tag: the tag number. For instance 277 for the
|
|
Packit |
994f1a |
SamplesPerPixel tag. Builtin tags will generally have a #define in
|
|
Packit |
994f1a |
tiff.h for each known tag.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
field_readcount: The number of values which should be read.
|
|
Packit |
994f1a |
The special value TIFF_VARIABLE (-1) indicates that a variable number of
|
|
Packit |
994f1a |
values may be read. The special value TIFFTAG_SPP (-2) indicates that there
|
|
Packit |
994f1a |
should be one value for each sample as defined by TIFFTAG_SAMPLESPERPIXEL.
|
|
Packit |
994f1a |
The special value TIFF_VARIABLE2 (-3) is presumably similar to TIFF_VARIABLE
|
|
Packit |
994f1a |
though I am not sure what the distinction in behaviour is. This field
|
|
Packit |
994f1a |
is TIFF_VARIABLE for variable length ascii fields.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
field_writecount: The number of values which should be written.
|
|
Packit |
994f1a |
Generally the same as field_readcount. A few built-in exceptions exist, but
|
|
Packit |
994f1a |
I haven't analysed why they differ.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
field_type: Type of the field. One of TIFF_BYTE, TIFF_ASCII,
|
|
Packit |
994f1a |
TIFF_SHORT, TIFF_LONG, TIFF_RATIONAL, TIFF_SBYTE, TIFF_UNDEFINED,
|
|
Packit |
994f1a |
TIFF_SSHORT, TIFF_SLONG, TIFF_SRATIONAL, TIFF_FLOAT, TIFF_DOUBLE or
|
|
Packit |
994f1a |
TIFF_IFD. Note that some fields can support more than one type (for
|
|
Packit |
994f1a |
instance short and long). These fields should have multiple TIFFFieldInfos.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
field_bit: Built-in tags stored in special fields in the
|
|
Packit |
994f1a |
TIFF structure have assigned field numbers to distinguish them (ie.
|
|
Packit |
994f1a |
FIELD_SAMPLESPERPIXEL). New tags should generally just use
|
|
Packit |
994f1a |
FIELD_CUSTOM indicating they are stored in the generic tag list.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
field_oktochange: TRUE if it is OK to change this tag value
|
|
Packit |
994f1a |
while an image is being written. FALSE for stuff that must be set once
|
|
Packit |
994f1a |
and then left unchanged (like ImageWidth, or PhotometricInterpretation for
|
|
Packit |
994f1a |
instance).
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
field_passcount: If TRUE, then the count value must be passed
|
|
Packit |
994f1a |
in TIFFSetField(), and TIFFGetField(), otherwise the count is not required.
|
|
Packit |
994f1a |
This should generally be TRUE for non-ascii variable count tags unless
|
|
Packit |
994f1a |
the count is implicit (such as with the colormap).
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
field_name: A name for the tag. Normally mixed case (studly caps)
|
|
Packit |
994f1a |
like "StripByteCounts" and relatively short.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
A TIFFFieldInfo definition exists for each built-in tag in the tif_dirinfo.c
|
|
Packit |
994f1a |
file. Some tags which support multiple data types have more than one
|
|
Packit |
994f1a |
definition, one per data type supported.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Various functions exist for getting the internal TIFFFieldInfo definitions,
|
|
Packit |
994f1a |
including _TIFFFindFieldInfo(), and _TIFFFindFieldInfoByName(). See
|
|
Packit |
994f1a |
tif_dirinfo.c for details. There must be some mechanism to get the whole
|
|
Packit |
994f1a |
list, though I don't see it off hand.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Default Tag Auto-registration
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
In libtiff 3.6.0 a new mechanism was introduced allowing libtiff to
|
|
Packit |
994f1a |
read unrecognised tags automatically. When an unknown tags is encountered,
|
|
Packit |
994f1a |
it is automatically internally defined with a default name and a type
|
|
Packit |
994f1a |
derived from the tag value in the file. Applications only need to predefine
|
|
Packit |
994f1a |
application specific tags if they need to be able to set them in a file, or
|
|
Packit |
994f1a |
if particular calling conventions are desired for TIFFSetField() and
|
|
Packit |
994f1a |
TIFFGetField().
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
When tags are autodefined like this the field_readcount and
|
|
Packit |
994f1a |
field_writecount values are always TIFF_VARIABLE. The
|
|
Packit |
994f1a |
field_passcount is always TRUE, and the field_bit is
|
|
Packit |
994f1a |
FIELD_CUSTOM. The field name will be "Tag %d" where the %d is the tag
|
|
Packit |
994f1a |
number.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Defining Application Tags
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
For various reasons, it is common for applications to want to define
|
|
Packit |
994f1a |
their own tags to store information outside the core TIFF specification.
|
|
Packit |
994f1a |
This is done by calling TIFFMergeFieldInfo() with one or more TIFFFieldInfos.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
The libgeotiff library provides geospatial information extentions within
|
|
Packit |
994f1a |
a TIFF file. First, a set of TIFFFieldInfo's is prepared with information
|
|
Packit |
994f1a |
on the new tags:
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
static const TIFFFieldInfo xtiffFieldInfo[] = {
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
/* XXX Insert Your tags here */
|
|
Packit |
994f1a |
{ TIFFTAG_GEOPIXELSCALE, -1,-1, TIFF_DOUBLE, FIELD_CUSTOM,
|
|
Packit |
994f1a |
TRUE, TRUE, "GeoPixelScale" },
|
|
Packit |
994f1a |
{ TIFFTAG_GEOTRANSMATRIX, -1,-1, TIFF_DOUBLE, FIELD_CUSTOM,
|
|
Packit |
994f1a |
TRUE, TRUE, "GeoTransformationMatrix" },
|
|
Packit |
994f1a |
{ TIFFTAG_GEOTIEPOINTS, -1,-1, TIFF_DOUBLE, FIELD_CUSTOM,
|
|
Packit |
994f1a |
TRUE, TRUE, "GeoTiePoints" },
|
|
Packit |
994f1a |
{ TIFFTAG_GEOKEYDIRECTORY, -1,-1, TIFF_SHORT, FIELD_CUSTOM,
|
|
Packit |
994f1a |
TRUE, TRUE, "GeoKeyDirectory" },
|
|
Packit |
994f1a |
{ TIFFTAG_GEODOUBLEPARAMS, -1,-1, TIFF_DOUBLE, FIELD_CUSTOM,
|
|
Packit |
994f1a |
TRUE, TRUE, "GeoDoubleParams" },
|
|
Packit |
994f1a |
{ TIFFTAG_GEOASCIIPARAMS, -1,-1, TIFF_ASCII, FIELD_CUSTOM,
|
|
Packit |
994f1a |
TRUE, FALSE, "GeoASCIIParams" }
|
|
Packit |
994f1a |
};
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
In order to define the tags, we call TIFFMergeFieldInfo() on the
|
|
Packit |
994f1a |
desired TIFF handle with the list of TIFFFieldInfos.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
#define N(a) (sizeof (a) / sizeof (a[0]))
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
/* Install the extended Tag field info */
|
|
Packit |
994f1a |
TIFFMergeFieldInfo(tif, xtiffFieldInfo, N(xtiffFieldInfo));
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
The tags need to be defined for each TIFF file opened - and when reading
|
|
Packit |
994f1a |
they should be defined before the tags of the file are read, yet a valid
|
|
Packit |
994f1a |
TIFF * is needed to merge the tags against. In order to get them
|
|
Packit |
994f1a |
registered at the appropriate part of the setup process, it is necessary
|
|
Packit |
994f1a |
to register our merge function as an extender callback with libtiff.
|
|
Packit |
994f1a |
This is done with TIFFSetTagExtender(). We also keep track of the
|
|
Packit |
994f1a |
previous tag extender (if any) so that we can call it from our extender
|
|
Packit |
994f1a |
allowing a chain of customizations to take effect.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
static TIFFExtendProc _ParentExtender = NULL;
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
static
|
|
Packit |
994f1a |
void _XTIFFInitialize(void)
|
|
Packit |
994f1a |
{
|
|
Packit |
994f1a |
static int first_time=1;
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
if (! first_time) return; /* Been there. Done that. */
|
|
Packit |
994f1a |
first_time = 0;
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
/* Grab the inherited method and install */
|
|
Packit |
994f1a |
_ParentExtender = TIFFSetTagExtender(_XTIFFDefaultDirectory);
|
|
Packit |
994f1a |
}
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
The extender callback is looks like this. It merges in our new fields
|
|
Packit |
994f1a |
and then calls the next extender if there is one in effect.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
static void
|
|
Packit |
994f1a |
_XTIFFDefaultDirectory(TIFF *tif)
|
|
Packit |
994f1a |
{
|
|
Packit |
994f1a |
/* Install the extended Tag field info */
|
|
Packit |
994f1a |
TIFFMergeFieldInfo(tif, xtiffFieldInfo, N(xtiffFieldInfo));
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
/* Since an XTIFF client module may have overridden
|
|
Packit |
994f1a |
* the default directory method, we call it now to
|
|
Packit |
994f1a |
* allow it to set up the rest of its own methods.
|
|
Packit |
994f1a |
*/
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
if (_ParentExtender)
|
|
Packit |
994f1a |
(*_ParentExtender)(tif);
|
|
Packit |
994f1a |
}
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
The above approach ensures that our new definitions are used when reading
|
|
Packit |
994f1a |
or writing any TIFF file. However, since on reading we already have
|
|
Packit |
994f1a |
default definitions for tags, it is usually not critical to pre-define them.
|
|
Packit |
994f1a |
If tag definitions are only required for writing custom tags, you can just
|
|
Packit |
994f1a |
call TIFFMergeFieldInfo() before setting new tags. The whole extender
|
|
Packit |
994f1a |
architecture can then be avoided.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Adding New Builtin Tags
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
A similar approach is taken to the above. However, the TIFFFieldInfo
|
|
Packit |
994f1a |
should be added to the tiffFieldInfo[] list in tif_dirinfo.c. Ensure that
|
|
Packit |
994f1a |
new tags are added in sorted order by the tag number.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Normally new built-in tags should be defined with FIELD_CUSTOM; however, if
|
|
Packit |
994f1a |
it is desirable for the tag value to have it's own field in the TIFFDirectory
|
|
Packit |
994f1a |
structure, then you will need to #define a new FIELD_ value for it, and
|
|
Packit |
994f1a |
add appropriate handling as follows:
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Define the tag in tiff.h.
|
|
Packit |
994f1a |
Add a field to the directory structure in tif_dir.h
|
|
Packit |
994f1a |
and define a <TT>FIELD_*</TT> bit (also update the definition of
|
|
Packit |
994f1a |
<TT>FIELD_CODEC</TT> to reflect your addition).
|
|
Packit |
994f1a |
Add an entry in the <TT>TIFFFieldInfo</TT> array defined at the top of
|
|
Packit |
994f1a |
tif_dirinfo.c.
|
|
Packit |
994f1a |
Note that you must keep this array sorted by tag
|
|
Packit |
994f1a |
number and that the widest variant entry for a tag should come
|
|
Packit |
994f1a |
first (e.g. <TT>LONG</TT> before <TT>SHORT</TT>).
|
|
Packit |
994f1a |
Add entries in <TT>_TIFFVSetField()</TT> and <TT>_TIFFVGetField()</TT>
|
|
Packit |
994f1a |
for the new tag.
|
|
Packit |
994f1a |
(optional) If the value associated with the tag is not a scalar value
|
|
Packit |
994f1a |
(e.g. the array for <TT>TransferFunction</TT>) and requires
|
|
Packit |
994f1a |
special processing,
|
|
Packit |
994f1a |
then add the appropriate code to <TT>TIFFReadDirectory()</TT> and
|
|
Packit |
994f1a |
<TT>TIFFWriteDirectory()</TT>. You're best off finding a similar tag and
|
|
Packit |
994f1a |
cribbing code.
|
|
Packit |
994f1a |
Add support to <TT>TIFFPrintDirectory()</TT> in tif_print.c
|
|
Packit |
994f1a |
to print the tag's value.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
If you want to maintain portability, beware of making assumptions
|
|
Packit |
994f1a |
about data types. Use the typedefs (<TT>uint16</TT>, etc. when dealing with
|
|
Packit |
994f1a |
data on disk and <TT>t*_t</TT> when stuff is in memory) and be careful about
|
|
Packit |
994f1a |
passing items through printf or similar vararg interfaces.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Adding New Codec-private Tags
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
To add tags that are meaningful only when a particular compression
|
|
Packit |
994f1a |
algorithm is used follow these steps:
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Define the tag in tiff.h.
|
|
Packit |
994f1a |
Allocate storage for the tag values in the private state block of
|
|
Packit |
994f1a |
the codec.
|
|
Packit |
994f1a |
Insure the state block is created when the codec is initialized.
|
|
Packit |
994f1a |
At <TT>TIFFInitfoo</TT> time override the method pointers in the
|
|
Packit |
994f1a |
TIFF structure
|
|
Packit |
994f1a |
for getting, setting and printing tag values. For example,
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
sp->vgetparent = tif->tif_vgetfield;
|
|
Packit |
994f1a |
tif->tif_vgetfield = fooVGetField; /* hook for codec tags */
|
|
Packit |
994f1a |
sp->vsetparent = tif->tif_vsetfield;
|
|
Packit |
994f1a |
tif->tif_vsetfield = fooVSetField; /* hook for codec tags */
|
|
Packit |
994f1a |
tif->tif_printdir = fooPrintDir; /* hook for codec tags */
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
(Actually you may decide not to override the
|
|
Packit |
994f1a |
<TT>tif_printdir</TT> method, but rather just specify it).
|
|
Packit |
994f1a |
Create a private <TT>TIFFFieldInfo</TT> array for your tags and
|
|
Packit |
994f1a |
merge them into the core tags at initialization time using
|
|
Packit |
994f1a |
<TT>_TIFFMergeFieldInfo</TT>; e.g.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
_TIFFMergeFieldInfo(tif, fooFieldInfo, N(fooFieldInfo));
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
(where <TT>N</TT> is a macro used liberaly throughout the distributed code).
|
|
Packit |
994f1a |
Fill in the get and set routines. Be sure to call the parent method
|
|
Packit |
994f1a |
for tags that you are not handled directly. Also be sure to set the
|
|
Packit |
994f1a |
<TT>FIELD_*</TT> bits for tags that are to be written to the file. Note that
|
|
Packit |
994f1a |
you can create ``pseudo-tags'' by defining tags that are processed
|
|
Packit |
994f1a |
exclusively in the get/set routines and never written to file (see
|
|
Packit |
994f1a |
the handling of <TT>TIFFTAG_FAXMODE</TT> in tif_fax3.c
|
|
Packit |
994f1a |
for an example of this).
|
|
Packit |
994f1a |
Fill in the print routine, if appropriate.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Note that space has been allocated in the <TT>FIELD_*</TT> bit space for
|
|
Packit |
994f1a |
codec-private tags. Define your bits as <TT>FIELD_CODEC+<offset></TT> to
|
|
Packit |
994f1a |
keep them away from the core tags. If you need more tags than there
|
|
Packit |
994f1a |
is room for, just increase <TT>FIELD_SETLONGS</TT> at the top of
|
|
Packit |
994f1a |
tiffiop.h.
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
Last updated: $Date: 2004/09/10 14:43:18 $
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
</BODY>
|
|
Packit |
994f1a |
|
|
Packit |
994f1a |
</HTML>
|