iflNITF(3) Image Format Library C++ Reference Manual iflNITF(3)
NAME
iflNITF - NITF file format
HEADER FILE
#include <ifl/iflNITF.h>
DESCRIPTION
The Image Format Library (IFL) provides support for reading and writing
image files with the National Imagery Transmission Format (NITF), Version
2.0. The format has been designed for transmitting the contents of a
briefing boards from one location to another.
As such, it contains support for storing both imagery and its
annotations. The IFL interface is used to directly access the imagery
sections, while the segment interface, described below, is used to access
the remaining objects contained within the file.
The various objects contained within the NITF file are placed into
segments. Each segment is divided into two sections, the header section
and the data section. The header section is a collection fields that
define how to interpret the data section. The IFL NITF file API provides
the ability to create, access or modify each of the various segments
within an NITF file. With the exception of specific header fields, most
all of the remaining fields are modifiable by the application.
A complete listing of all of the available fields within each segment can
be found in /usr/lib/ifl/iflnitfformat. The field and segment names
have been chosen to correspond directly to those found in the NITF
specification.
Access to the imagery segments is affected via the standard IFL calls.
Unlike general NITF file readers, the IFL version requires that the file
contain at least one image. Each of the images in the NITF file is
accessed as a separate sub-image, with the first image segment being
sub-image zero.
The remaining segments in the file and the fields of the image segments
are accessed via the segment interface described below. Using the
iflFile::getTag() method, file segments can be retrieved or created. The
following are the pseudo getTag() declarations that reflect the segment
accessors.
iflStatus getTag(iflNITFTagId tag, iflNITFSegmentType type,
int segNum, iflNITFSegment** seg);
Page 1
iflNITF(3) Image Format Library C++ Reference Manual iflNITF(3)
The following calling sequence is used to retrieve an existing segment.
In this example the retrieved segment is a symbol segment.
iflNITFSegment* seg;
iflStatus sts;
sts = file->getTag(iflNITFTagSegment, iflNITFSegSymbol,
0, &seg);
The following example shows the creation of a new symbol segment. This
sequence is usable for all but image segments, which must be created
using the iflFile::appendImg() or iflFile::create() methods.
sts = file->getTag(iflNITFTagNewSegement, iflNITFSegSymbol,
1, &seg);
With a pointer to an iflNITFSegment, the application can access the
individual fields of the segment header, and read or write the data
section of the segment. The following is a list of the iflNITFSegment
member functions and their descriptions.
getType()
iflNITFSegmentType getType() const
Returns this segment's type.
getNum()
int getNum() const
Returns the index of this segment within the file.
getField()
iflNITFFieldPtr getField(const char* name)
Retrieve the field associated with name. If a matching field cannot
be found then NULL is returned.
Page 2
iflNITF(3) Image Format Library C++ Reference Manual iflNITF(3)
getNextField()
iflNITFFieldPtr getNextField(iflNITFFieldPtr f)
Returns the field that immediately follows the field f. If f is
NULL, then the first field of the segment is returned. If f points
to the last field in the segment, then NULL is returned.
getFieldName()
const char* getFieldName(iflNITFFieldPtr f)
Returns the name of field f.
getFieldType()
iflNITFFieldType getFieldType(iflNITFFieldPtr f)
Returns the field f type.
getFieldWidth()
size_t getFieldWidth(iflNITFFieldPtr f)
Returns the width of the field f in bytes as it appears in the NITF
file.
getFieldValue()
iflStatus getFieldValue(iflNITFFieldPtr f,
int32_t& value)
iflStatus getFieldValue(iflNITFFieldPtr f,
int64_t& value)
iflStatus getFieldValue(iflNITFFieldPtr f,
float& value)
iflStatus getFieldValue(iflNITFFieldPtr f,
const char*& value)
iflStatus getFieldValue(iflNITFFieldPtr f,
const char*& value, size_t& width)
Retrieves the value of the field f into value. If the type of the
field does not match the type of value or cannot be promoted, an
iflBADPARAMS error is returned. The width parameter will contain the
Page 3
iflNITF(3) Image Format Library C++ Reference Manual iflNITF(3)
field width for byte or string fields.
setFieldValue()
iflStatus setFieldValue(iflNITFFieldPtr f,
int32_t value)
iflStatus setFieldValue(iflNITFFieldPtr f,
int64_t value)
iflStatus setFieldValue(iflNITFFieldPtr f,
float value)
iflStatus setFieldValue(iflNITFFieldPtr f,
const char* value)
iflStatus setFieldValue(iflNITFFieldPtr f,
const char* value, size_t width)
Sets the value of the field f to value. If the type of the field
does not match the type of value, or the type of value cannot be
promoted to the field type, then an iflBADPARAMS error is returned.
If the field is read-only, then an iflBADFIELDSET error is returned
to the caller. The width parameter specifies the width of the value
argument for variable byte length fields. There are currently only
two such fields in the format, DESDATA and RESDATA. Attempting to
adjust the width of non-variable length fields will result in an
iflBADFIELDSET error.
getContentLength()
int64_t getContentLength() const
Returns the length of the data section of this segment.
readContent()
iflStatus readContent(void* buf, size_t bufLen,
size_t& rdLen)
This function reads the data section of this segment into buffer
buf. The length of the buffer is given by bufLen. The actual number
of bytes read from the segment is returned in rdLen. Reads of the
data section always start at the beginning of the data section. That
is, the entire data section can only be retrieved via a single read.
writeContent()
Page 4
iflNITF(3) Image Format Library C++ Reference Manual iflNITF(3)
iflStatus writeContent(const void* buf, size_t bufLen,
size_t& wrLen)
This function writes the data section of this segment from the
buffer buf. The amount of data to write from the buffer is given by
bufLen. The actual number of bytes written to the file is returned
in wrLen. In general, the value returned in wrLen should always
match bufLen.
SEE ALSO
iflFile, iflFormat
Page 5