QccIMGImageSequenceFree.3

NAME

QccIMGImageSequence - data structure QccIMGImageSequence for a sequence of images

int QccIMGImageSequenceInitialize(QccIMGImageSequence *image_sequence);
int QccIMGImageSequenceAlloc(QccIMGImageSequence *image_sequence);
void QccIMGImageSequenceFree(QccIMGImageSequence *image_sequence);
int QccIMGImageSequenceLength(const QccIMGImageSequence *image_sequence);
int QccIMGImageSequenceSetCurrentFilename(QccIMGImageSequence *image_sequence);
int QccIMGImageSequenceIncrementFrameNum(QccIMGImageSequence *image_sequence);
int QccIMGImageSequenceFindFrameNums(QccIMGImageSequence *image_sequence);
int QccIMGImageSequenceReadFrame(QccIMGImageSequence *image_sequence);
int QccIMGImageSequenceWriteFrame(QccIMGImageSequence *image_sequence);
int QccIMGImageSequenceStartRead(QccIMGImageSequence *image_sequence);

DESCRIPTION

QccPack provides data structure QccIMGImageSequence for representing a sequence of images. It is generally assumed that all images of the sequence have the same size and color depth. The frames of the image sequence are indexed by a "frame number" which runs consecutively from some starting frame number to an ending frame number.

The main component of a QccIMGImageSequence structure is a QccIMGImage(3) structure that holds the current frame of the image sequence.

DATA STRUCTURE

The QccIMGImageSequence data structure is defined as:

typedef struct
{
QccString filename;
int start_frame_num;
int end_frame_num;
int current_frame_num;
QccString current_filename;
QccIMGImage current_frame;
} QccIMGImageSequence;

The fields of QccIMGImageSequence are as follows:

filename: The filename template for the image sequence.
start_frame_num, end_frame_num: The numbers of the first and last frames of the image sequence.
current_frame_num: The number of the current frame.
current_filename: The filename for the current frame.
current_frame: The current frame.

FILE ACCESS

A QccIMGImageSequence structure holds only a single frame of the image sequence, and most routines that process image sequences will process a single frame at a time. Consequently, image sequences are normally read and written by specifying a filename template that is "filled in" with the current frame number to access the current frame. The filename field of the QccIMGImageSequence structure is the filename template, and it is a printf(3) format string that contains exactly one numerical descriptor (i.e., %d, %x, etc.). For example, if filename is given as imagefile.%03d.pgm, then the image sequence will be accessed as imagefile.000.pgm, imagefile.001.pgm, imagefile.002.pgm, ..., assuming that the first frame of the sequence is frame number 0. The filenames, as well as the numerical descriptor in the filename template, must use zero padding on the left so that the files are processed in the correct numerical order.

ROUTINES

QccIMGImageSequenceInitialize() should be called before any use of a QccIMGImageSequence structure. QccIMGImageSequenceInitialize() initializes the fields of image_sequence to the following values:

filename: NULL string
start_frame_num: 0
end_frame_num: 0
current_frame_num: 0
current_filename: NULL string

QccIMGImageSequenceAlloc() allocates storage space for image_sequence->current_frame by calling QccIMGImageAlloc(3) . The size of image_sequence->current_frame must be set via a call to QccIMGImageSetSize(3) or QccIMGImageSetSizeYUV(3) prior to calling QccIMGImageSequenceAlloc().

QccIMGImageSequenceFree() frees image_sequence->current_frame via a call to QccIMGImageFree(3) .

QccIMGImageSequenceLength() calculates the number of frames of image_sequence. It is assumed that no frames are skipped between the starting frame and the ending frame, so the number of frames isa image_sequence->end_frame_num - image_sequence->start_frame_num + 1.

QccIMGImageSequenceSetCurrentFilename() updates image_sequence->current_filename by placing the current frame number, image_sequence->current_frame_num, into the filename template, image_sequence->filename. This is done by having image_sequence->current_filename be the output of a call to QccStringSprintf(3) wherein image_sequence->filename is the format string.

QccIMGImageSequenceIncrementFrameNum() increments image_sequence->current_frame_num and then calls QccIMGImageSequenceSetCurrentFilename() to update the current filename.

QccIMGImageSequenceFindFrameNums() determines the starting and ending frame numbers for the specified image sequence. Using the filename template, image_sequence->filename, QccIMGImageSequenceFindFrameNums() scans all the frame numbers matching the template, checking for the existence of a file with that frame number. image_sequence->start_frame_num is set to the first frame number for which a file exists. image_sequence->end_frame_num is set to the last frame number for which a file exists, such that all frame numbers between image_sequence->start_frame_num and image_sequence->end_frame_num correspond to existing files; i.e., the sequence of frames from the starting frame number to the ending frame number is consecutive with no skipped frames.

QccIMGImageSequenceReadFrame() calls QccIMGImageSequenceSetCurrentFilename() to update the current filename, and then QccIMGImageRead(3) to read the current frame, with the current frame being returned in image_sequence->current_frame.

QccIMGImageSequenceWriteFrame() calls QccIMGImageSequenceSetCurrentFilename() to update the current filename, and then QccIMGImageWrite(3) to write image_sequence->current_frame to the current filename.

QccIMGImageSequenceStartRead() calls QccIMGImageSequenceReadFrame() to read the first frame of the sequence, i.e., the one with frame number image_sequence->start_frame_num.

RETURN VALUE

These routines return 0 on success, and 1 on failure, except QccIMGImageSequenceLength(), which returns the length of the image sequence.

AUTHOR

Table of Contents

NAME
SYNOPSIS
DESCRIPTION
DATA STRUCTURE
FILE ACCESS
ROUTINES
RETURN VALUE
SEE ALSO
AUTHOR