Image sequence I/O

      #include <gandalf/image/io/movie.h>

Gandalf has a module for reading and writing image sequences. These are accessed one image at a time. The Gan_MovieStruct structure defines an image sequence. A movie structure is created using the gan_movie_new() function. An example call is

      Gan_MovieStruct *pMovie;

      pMovie = gan_movie_new ( "/tmp", "movie.", 3, ".png", 1, 20,
                               GAN_PNG_FORMAT );

The arguments to the function define the image sequence attributes, in the following order:

1. The directory in which to find the images;
2. the base name of the image file names;
3. the number of digits in the number part of the image file name;
4. the suffix of each image, usually related to the image file format;
5. the number of the first image in the sequence;
6. the image file format;

The above example defines a sequence of PNG format image files

      /tmp/movie.001.png
      /tmp/movie.002.png
              .
              .
              .
      /tmp/movie.020.png

Other parameters of a movie structure have defaults which can be set using functions before the movie images are accessed. These functions are

      gan_movie_set_step ( pMovie, 2 );

to set the step in numbers between images. The default is one, and the above call would set the frame numbers to 1, 3, 5 etc.

      gan_movie_set_crop_window ( pMovie, 5, 10, 8, 12 );

sets the values of any crop parameters, i.e. the widths of areas at the edge of each image which should be ignored by image processing operations. The widths are give for the left, right, top and bottom edges respectively.

The movie structure is used both for reading and writing images in a sequence. The number of digits indicates the amount of zero-padding of the file number. A value of zero indicates that no padding is done. To read a single image from the sequence, use the function gan_movie_image_read(), for example

      Gan_Image *pImage;

      pImage = gan_movie_image_read ( pMovie, 8, NULL );

The second argument indicates which image in the sequence is to be read, from 0 to 19 in this case. The value 8 indicates the file /tmp/movie.009.png. This reads the image file into a new image. If pImage is already created, you can use

      gan_movie_image_read ( pMovie, 8, pImage );

To write an image in a sequence use

      gan_movie_image_write ( pMovie, 10, pImage );

This will write the file /tmp/movie.011.png.

Sometimes it is desirable to build the full name of a movie image file, for instance when generating error messages to say that a given file cannot be read or written. To write an image file name into a string, use the function

      char acString[300];

      gan_movie_image_name ( pMovie, 0, acString, 300 );

This writes the name of the first image of the sequence into the provided string, up to the 300 character total size of the acString array. For the movie created in the above example this will fill the string acString with the value "/tmp/movie.001.png". The second argument is the number of the image in the sequence, so passing 5 would give the string "/tmp/movie.006.png".

Finally, to free a movie structure use

      gan_movie_free ( pMovie );

Error detection: gan_movie_new() returns a pointer to the allocated movie structure, and NULL is returned in case of error. gan_movie_image_read() and gan_movie_image_name() also return NULL on error.
gan_movie_image_write() returns a boolean value, so GAN_FALSE is returned on error. In all cases the Gandalf error handler is invoked.