The directory /u/nelson/programs/ipp/image/utility/lib contains source code for a number of library utility functions, primarily for reading ipp core images to and from various file formats, and converting between core ipp representations. These functions are compiled and archived into user libraries for various operating systems, stored under /u/nelson/programs.d/lib/*/libutility.a, where * is an operating specifier, currently one of * Solaris (all current Suns), * SunOS (old Sun OS, we no longer have any machines running this), * PCLinux (our various Linux PC boxes), and * DigitalUnix (the machines in the DEC alpha cluster) ANSI-style function prototypes, definitions for the ipp core image structures, and macros for specifying various image attributes are defined in the file utility.h (located at /u/nelson/programs/include/utility.h). This file must be included in order to use the library. BOOL is int, defined in bool.h (also located at /u/nelson/programs/include/utility.h), In addition, the file I/O depends on several external libraries, that must be linked in order to use a particular image file format. These libraries are in various places, depending on the operating system. Generally they are either system libraries or in /usr/vision/lib. Since a lot of these are .so shared objects, you need to have the appropriate directories on your LD_LIB_PATH. The tiff libraries have been known to cause trouble because they are present as system libs in Solaris 5.7 and later, but not earlier, and the compiled versions are incompatible. To avoid problems, make sure that /usr/openwin/lib occurs on your LD_LIB_PATH before /usr/vision/lib. Currently supported file formats are * tiff (uncompressed mono and rgb color; link -ltiff, -ljpeg, and -lz) * png (lossless storage for mono and 3-band color; ling -lpng) * jpg (writes at 75% quality level) * pgm (mono images; link -lpgm -lpbm) * ipp (old dept standard, 8-bit mono and 3-band color rgb images; link -liff) * cvl (old UMD standard, 8-bit mono images; no external libs needed) ***************************************************************************** *** Data structures *** ***************************************************************************** The ipp utility library defines core storage data structures for multiband integer images, multiband floating point images. There are corresponding single-band integer and floating point mask (template) structures for convolution and matching operations. These have not yet been generalized to multible bands. There is an obsolete rgb color image structure, retained only for backward compatability with a few programs. There is also a structure for single-band image sequences (which must be short enough to fit in the available memory). The following macros and structure definitions are exerpted from utility.h ----------------------------------------------------------------------------- #define UTIL_BOOL int /* internal to this include file */ /* macros for specifying number of bits */ #define IPP_1_BIT 1 #define IPP_4_BIT 4 #define IPP_8_BIT 8 #define IPP_12_BIT 12 #define IPP_16_BIT 16 #define IPP_24_BIT 24 #define IPP_32_BIT 32 #define IPP_48_BIT 48 #define IPP_64_BIT 64 #define IPP_BINARY IPP_1_BIT /* old nbit macros */ #define BINARY IPP_1_BIT #define GRAY IPP_8_BIT #define COLOR IPP_16_bit /* very old indeed */ /* old data type macros */ #define INT_IMAGE 0 /* code for integer image (default) */ #define FLOAT_IMAGE 1 /* code for floating point image */ #define COLOR_IMAGE 2 /* code for integer 3 band color image */ #define IMAGE_SEQUENCE 8 /* code for integer-valued image sequence */ /* macros specifying different image types */ #define IPP_UNKNOWN 0 #define IPP_MONO 10 /* generic momchromatic (single band) image */ #define IPP_COLOR 20 /* generic color image, assumed rgb */ #define IPP_COLOR_RGB 21 /* color image, specified as rgb */ #define IPP_MULTI_BAND 30 /* generic multi-band image */ /* macros for RGB images */ #define IPP_RGB_NBANDS 3 #define IPP_RGB_RED_BAND 0 #define IPP_RGB_GREEN_BAND 1 #define IPP_RGB_BLUE_BAND 2 ----------------------------------------------------------------------------- typedef struct { UTIL_BOOL prep; /* Set to true if array storage is allocated */ int nrows; int ncols; int bpp; /* number of bits per band in file format of data */ int data_type; /* INT_IMAGE for integer image */ UTIL_BOOL is_signed; /* TRUE if file format is signed */ int lcom; /* Length of comment field in bytes */ char *comments; int **array; /* added 05/2001 to allow general color and multiband images */ int image_class; /* IPP_MONO, IPP_COLOR_RGB etc. */ int nbands; int ***bands; } imagetype; ----------------------------------------------------------------------------- typedef struct { UTIL_BOOL prep; int nrows; int ncols; int bpp; /* Interpret as accuracy of original data */ int data_type; /* FLOAT_IMAGE for floating point image */ UTIL_BOOL is_signed; int lcom; char *comments; float **array; /* added 06/2001 to allow general color and multiband images */ int image_class; /* IPP_MONO, IPP_COLOR_RGB etc. */ int nbands; float ***bands; } floatimagetype; ----------------------------------------------------------------------------- typedef struct { UTIL_BOOL prep; int nframes; int nrows; int ncols; int bpp; int data_type; /* IMAGE_SEQUENCE for image sequence */ UTIL_BOOL is_signed; int lcom; char *comments; int ***frame_store; /* an sequence of image arrays */ } image_sequence_type; ----------------------------------------------------------------------------- typedef struct { UTIL_BOOL prep; int rows; int cols; int **array; } masktype; ----------------------------------------------------------------------------- typedef struct { UTIL_BOOL prep; int rows; int cols; float **array; } floatmasktype; ***************************************************************************** *** Functions *** ***************************************************************************** The functions can be broken into groups by the primary data structure they serve. Here, a brief list of functions in each group is given first (name only, no parameters or description), followed by a more detailed description of the individual functions. * Functions for mono (one-band) and multi-band integer images BOOL prepimage(); BOOL prep_image_mb(); /* for initializing multi-band images */ BOOL killimage(); BOOL input_image(); BOOL output_image(); BOOL makeimage(); BOOL printimage(); BOOL input_tiff_image(); BOOL output_tiff_image(); BOOL input_pgm_image(); BOOL output_pgm_image(); BOOL input_iff_image(); BOOL output_iff_image(); BOOL readimage(); /* same as input_iff_image and output_iff_image */ BOOL writeimage(); /* retained for backwards compatibility */ BOOL input_cvl_image(); BOOL output_cvl_image(); BOOL copyimage(); BOOL extract_band(); BOOL set_band(); BOOL makeconst(); BOOL make_const_mb(); BOOL make_eq_bands(); BOOL flip(); BOOL flip_rl(); BOOL rotate_180(); BOOL rotate_90cw(); BOOL rotate_90ccw(); ----------------------------------------------------------------------------- * Functions for mono (one-band) and multi-band floating point images BOOL prepfloatimage(); BOOL prep_float_image_mb(); BOOL killfloatimage(); BOOL int_to_float(); BOOL float_to_int(); BOOL printfloatimage(); ----------------------------------------------------------------------------- * Functions for (rgb) color integer images These are obsoleted by multi-band capabilities of standard ipp images, and are retained only for backward compatibility BOOL prep_color_image(); BOOL kill_color_image(); BOOL input_color_image(); BOOL output_color_image(); BOOL input_tiff_color_image(); BOOL output_tiff_color_image(); BOOL input_iff_color_image(); BOOL output_iff_color_image(); BOOL int_to_color(); BOOL color_to_int(); BOOL int_3_to_color(); BOOL color_to_int_3(); ----------------------------------------------------------------------------- * Functions for one-band integer masks BOOL prepmask(); BOOL killmask(); BOOL makemask(); BOOL image_to_mask() BOOL printmask(); ----------------------------------------------------------------------------- * Functions for one-band floating point masks BOOL prepfloatmask(); BOOL killfloatmask(); BOOL printfloatmask(); ----------------------------------------------------------------------------- * Functions for (short) 8-bit mono image sequences. Short means the sequence will fit in available core. BOOL prep_sequence(); BOOL kill_sequence(); BOOL input_iff_sequence(); BOOL output_iff_sequence(); ----------------------------------------------------------------------------- * Miscellaneous utility functions void errprnt(); /* local functions, not intended to be called */ void errprnt2(); /* directly by user */ BOOL getnextint(); ****************************************************************************** *** Function Descriptions *** ****************************************************************************** ------------------------------------------------------------------------------ *** Functions for initialization and I/O of integer images *** ------------------------------------------------------------------------------ NAME prepimage SYNOPSIS #include "bool.h" #include "utility.h" BOOL prepimage( imagetype *image int nrows, int ncols, int nbits) DESCRIPTION Initializes and allocates storage for an integer image. Using the macro GRAY for nbits sets it to 8. None of the internal routines look at this value - it is only examined when reading or writing to a file. In fact, current output_iff_image routine may choke for other values, since the UBC iff software was not written very well to begin with. nbits > 32 are not consistent with integer format. ------------------------------------------------------------------------------ NAME prep_image_mb SYNOPSIS #include "bool.h" #include "utility.h" BOOL prep_image_mb( imagetype *image, int nrows, int ncols, int nbits, int nbands) DESCRIPTION Initializes and allocates storage for a multi-band integer image. The "imagetype" data structure was modified (5/2001) to support multiband images, while remaining backward compatible with the old 1-band definition. Other routines will not crash when run with multiband images, but certain ones may just perform 1-band operations using band 0. None of the internal routines look at nbits - it is only examined when reading or writing to a file. In fact, current output_iff_image routine may choke for other values, since the UBC iff software was not written very well to begin with. nbits > 32 are not consistent with integer format. ------------------------------------------------------------------------------ NAME killimage SYNOPSIS #include "bool.h" #include "utility.h" BOOL killimage( imagetype *image) DESCRIPTION Returns the storage associated with an image that is no longer needed. Must be used when temporary images are created in subroutines in order to avoid tying up system memory. ------------------------------------------------------------------------------ NAME input_image SYNOPSIS #include "bool.h" #include "iff.h" #include "utility.h" BOOL input_image( char *file, imagetype *image) DESCRIPTION input_image reads an image file, uses the suffix to determine what the image format is, and reads it into the ipp core image. If the file sufix is unrecognized, the routine defaults attempts to read an image in tiff format. Recognized suffixes are .tif and .tiff (uncompressed mono or rgb only) .pgm, .iff (8-bit mono and 3x8-bit rgb), and .cvl (8 bit mono). This function and output_image() are the primary user functions for input and output of images. There a also specific functions for all the different formats, but the only reason for using them directly would be to defeat the suffix mechanism, which would not ordinarily be desired. ------------------------------------------------------------------------------ NAME output_image SYNOPSIS #include "bool.h" #include "iff.h" #include "utility.h" BOOL output_image( char *file, imagetype *image) DESCRIPTION output_image writes the specified iip core image to an image file using the suffix to determine the format. If the file sufix is unrecognized, the routine defaults attempts to write the image in tiff format. Recognized suffixes are .tif and .tiff (mono or 3-band rgb) .pgm (mono), .iff (8-bit mono or 3-band rgb), and .cvl (8 bit mono). ------------------------------------------------------------------------------ NAME makeimage SYNOPSIS #include "bool.h" #include "utility.h" BOOL makeimage(image, nrows, ncols, infile) imagetype *image; int nrows, ncols; char *infile; DESCRIPTION Produces an image from a file of decimal numerals (integer). Usually used for making (small) test images. File must contain enough data. ------------------------------------------------------------------------------ NAME printimage SYNOPSIS #include "bool.h" #include "utility.h" BOOL printimage( imagetype *image) DESCRIPTION Prints an integer image to standard output. (generally useful only for viewing small images) ------------------------------------------------------------------------------ *** Secondary image I/O functions *** ------------------------------------------------------------------------------ NAME input_tiff_image SYNOPSIS #include "bool.h" #include "utility.h" BOOL input_tiff_image( char *file, imagetype *image) DESCRIPTION Reads an image file in uncompressed mono or rgb tiff format and produces an in core ipp image from it. ------------------------------------------------------------------------------ NAME output_tiff_image SYNOPSIS #include "bool.h" #include "utility.h" BOOL output_tiff_image( char *file, imagetype *image) DESCRIPTION Produces an uncompressed tiff image file corresponding to a mono or three-band rgb ipp core image. ------------------------------------------------------------------------------ NAME input_pgm_image SYNOPSIS #include "bool.h" #include "utility.h" BOOL input_pgm_image( char *file, imagetype *image) DESCRIPTION Reads an image file in (mono) pgm format and produces an in-core ipp image from it. ------------------------------------------------------------------------------ NAME output_pgm_image SYNOPSIS #include "bool.h" #include "utility.h" BOOL output_pgm_image( char *file, imagetype *image) DESCRIPTION Produces a pgm image file from a mono or ipp core image. ------------------------------------------------------------------------------ NAME input_iff_image, readimage SYNOPSIS #include "bool.h" #include "utility.h" BOOL input_iff_image( char *file, imagetype *image) BOOL readimage( char *file, imagetype *image) DESCRIPTION input_iff_image reads an image file in iff format and produces an in-core image from it. readimage: Same as input_iff_image. Retained for backwards compatability. ------------------------------------------------------------------------------ NAME output_iff_image, writeimage SYNOPSIS #include "bool.h" #include "utility.h" BOOL output_iff_image( char *file, imagetype *image) BOOL readimage( char *file, imagetype *image) DESCRIPTION Output_iff_image produces an iff image file corresponding to an image. readimage: same as output_iff_image. Retained for backwards compatibility. ------------------------------------------------------------------------------ NAME input_cvl_image SYNOPSIS #include "bool.h" #include "utility.h" BOOL input_cvl_image( char *file, imagetype *image) DESCRIPTION Reads an image file in cvl (Maryland) format and produces an in core image from it. ------------------------------------------------------------------------------ NAME output_cvl_image SYNOPSIS #include "bool.h" #include "utility.h" BOOL output_cvl_image( char *file, imagetype *image) DESCRIPTION Produces a cvl image file corresponding to an image. ------------------------------------------------------------------------------ *** simple image manipulation functions, useful for I/O *** ------------------------------------------------------------------------------ NAME copyimage SYNOPSIS #include "bool.h" #include "utility.h" BOOL copyimage( imagetype *inimage, imagetype *outimage) DESCRIPTION Makes a duplicate of an image. Unprepped image is passed in. ------------------------------------------------------------------------------ NAME extract_band SYNOPSIS #include "bool.h" #include "utility.h" BOOL extract_band( imagetype *inimage, imagetype *outimage, int band); DESCRIPTION Takes (multiband) input image, and returns a mono (single band) image consisting of specified band. ------------------------------------------------------------------------------ NAME set_band SYNOPSIS #include "bool.h" #include "utility.h" BOOL set_band( imagetype *inimage, imagetype *source_image, int band); DESCRIPTION Sets the specified band of the input image using values from the source image. If source image is smaller than the input image, it is used to tile the band. If it is larger, the (0,0) corners are aligned. ------------------------------------------------------------------------------ NAME makeconst SYNOPSIS #include "bool.h" #include "utility.h" BOOL makeconst( imagetype *inimage, int value); DESCRIPTION Sets an image to a specified constant value. For multi-band images, sets all bands to the same value. ------------------------------------------------------------------------------ NAME make_const_mb SYNOPSIS #include "bool.h" #include "utility.h" BOOL make_const_mb( imagetype *inimage, int *value); DESCRIPTION Multi-band version of makeconst(). Takes a pointer value argument that is assumed to point to a vector of band values. ------------------------------------------------------------------------------ NAME make_eq_bands SYNOPSIS #include "bool.h" #include "utility.h" BOOL make_eq_bands( imagetype *inimage, imagetype *outimage, int nbands); DESCRIPTION Produces a multi-band image from a single-band image consisting of the specified number of identical bands. Useful for producing "color" versions of grayscale images. ------------------------------------------------------------------------------ NAME flip SYNOPSIS #include "bool.h" #include "utility.h" BOOL flip( imagetype *inimage, imagetype *outimage) DESCRIPTION Flips an image vertically. Useful because some formats have row 0 at the top, while others have it at the bottom. ------------------------------------------------------------------------------ NAME flip_rl SYNOPSIS #include "bool.h" #include "utility.h" BOOL flip_rl( imagetype *inimage, imagetype *outimage) DESCRIPTION Flips an image left to right. ------------------------------------------------------------------------------ NAME rotate_180 SYNOPSIS #include "bool.h" #include "utility.h" BOOL rotate_180( imagetype *inimage, imagetype *outimage) DESCRIPTION Rotates an image 180 degrees. ------------------------------------------------------------------------------ NAME rotate_90cw SYNOPSIS #include "bool.h" #include "utility.h" BOOL rotate_90cw( imagetype *inimage, imagetype *outimage) DESCRIPTION Rotates an image 90 degrees clockwise. ------------------------------------------------------------------------------ NAME rotate_90ccw SYNOPSIS #include "bool.h" #include "utility.h" BOOL rotate_90ccw( imagetype *inimage, imagetype *outimage) DESCRIPTION Rotates an image 90 degrees counter-clockwise. ------------------------------------------------------------------------------ *** Functions for floating point images *** ------------------------------------------------------------------------------ NAME prepfloatimage SYNOPSIS #include "bool.h" #include "utility.h" BOOL prepfloatimage( floatimagetype *image, int nrows, int ncols) DESCRIPTION Initializes and allocates storage for a floating point image, of specified size. ------------------------------------------------------------------------------ NAME prep_float_image_mb SYNOPSIS #include "bool.h" #include "utility.h" BOOL prep_float_image_mb( floatimagetype *image, int nrows, int ncols, int nbands) DESCRIPTION Initializes and allocates storage for a multi-band floating point image, of specified size. ------------------------------------------------------------------------------ NAME float_to_int SYNOPSIS #include "bool.h" #include "utility.h" BOOL float_to_int( imagetype *inimage, floatimagetype *outimage) DESCRIPTION Takes a floating point image and makes a corresponding integer image from it. ------------------------------------------------------------------------------ NAME int_to_float SYNOPSIS #include "bool.h" #include "utility.h" BOOL int_to_float( floatimagetype *inimage, imagetype *outimage) DESCRIPTION Takes an integer image and makes a corresponding floating point image from it. ------------------------------------------------------------------------------ NAME BOOL printfloatimage SYNOPSIS #include "bool.h" #include "utility.h" printfloatimage( floatimagetype *image) DESCRIPTION Prints a (single-band) floating point image to standard output. (generally useful only for viewing small images) ------------------------------------------------------------------------------ *** Functions for obsolete color image structure *** ------------------------------------------------------------------------------ ATTENTION: The functionality of the color_image_type structure has been subsumed by adding multi-band capability to the image_type structure, and these functions should not be used. They are retained only for backward compatibility with various legacy code. ------------------------------------------------------------------------------ Initialization and primary I/O functions for obsolete color_image_type structure. BOOL prep_color_image( color_image_type *image, int nrows, int ncols, int nbits); BOOL kill_color_image(color_image_type *image); BOOL input_color_image(char *file, color_image_type *image); BOOL output_color_image(char *file, color_image_type *image); ------------------------------------------------------------------------------ Secondary I/O functions for obsolete color_image_type structure. BOOL input_iff_color_image(char *file, color_image_type *image); BOOL output_iff_color_image(char *file, color_image_type *image); BOOL input_tiff_color_image(char *file, color_image_type *image); BOOL output_tiff_color_image(char *file, color_image_type *image); ------------------------------------------------------------------------------ Conversion routines for obsolete color_image_type structure. BOOL int_to_color(imagetype *inimage, color_image_type *outimage); BOOL color_to_int(color_image_type *inimage, imagetype *outimage); BOOL int_3_to_color( imagetype *red_image, imagetype *green_image, imagetype *blue_image, color_image_type *outimage); BOOL color_to_int_3( color_image_type *inimage, imagetype *red_image, imagetype *greenimage, imagetype *blue_image); ------------------------------------------------------------------------------ *** Functions for integer masks *** ------------------------------------------------------------------------------ NAME prepmask SYNOPSIS #include "bool.h" #include "utility.h" BOOL prepmask( masktype *mask, int nrows, int ncols) DESCRIPTION Initializes and allocates storage for an integer correlation mask. ------------------------------------------------------------------------------ NAME killmask SYNOPSIS #include "bool.h" #include "utility.h" BOOL killmask( masktype *mask) DESCRIPTION Returns storage associated with mask. ------------------------------------------------------------------------------ NAME image_to_mask SYNOPSIS #include "bool.h" #include "utility.h" BOOL image_to_mask( imagetype *inimage, masktype *outmask) DESCRIPTION Converts an integer core image to a mask. Useful for creating templates from image data. ------------------------------------------------------------------------------ NAME makemask SYNOPSIS #include "bool.h" #include "utility.h" BOOL makemask( masktype *image, int nrows, int ncols char *infile) DESCRIPTION Produces a correlation mask from a file of decimal numerals (integer). ------------------------------------------------------------------------------ NAME printmask SYNOPSIS #include "bool.h" #include "utility.h" BOOL printmask( masktype *mask) DESCRIPTION Prints an integer mask to standard output. ------------------------------------------------------------------------------ *** Functions for floating point masks *** ------------------------------------------------------------------------------ NAME prepfloatmask SYNOPSIS #include "bool.h" #include "utility.h" BOOL prepfloatmask( masktype *mask, int nrows, int ncols) DESCRIPTION Initializes and allocates storage for a floating point correlation mask. ------------------------------------------------------------------------------ NAME killfloatmask SYNOPSIS #include "bool.h" #include "utility.h" BOOL killfloatmask( floatmasktype *mask) DESCRIPTION Returns storage associated with mask. ------------------------------------------------------------------------------ NAME printfloatmask SYNOPSIS #include "bool.h" #include "utility.h" BOOL printfloatmask( floatmasktype *mask) DESCRIPTION Prints a floating point mask to standard output. ------------------------------------------------------------------------------ *** Functions for in-core image sequences *** ------------------------------------------------------------------------------ NAME prep_sequence SYNOPSIS #include "bool.h" #include "utility.h" BOOL prep_sequence( image_sequence_type *sequence, int nframes, int nrows, int ncols, int nbits) DESCRIPTION Initializes and allocates storage for an image sequence. Currently limited to mono integer sequences small enough to fit in available core. ------------------------------------------------------------------------------ NAME kill_sequence SYNOPSIS #include "bool.h" #include "utility.h" BOOL kill_sequence( image_sequence_type *sequence) DESCRIPTION Returns storage associated with in-core image sequence, and marks the structures as unused. ------------------------------------------------------------------------------ NAME input_iff_sequence SYNOPSIS #include "bool.h" #include "utility.h" BOOL input_iff_sequence( char *filename, image_sequence_type *sequence) DESCRIPTION Read an image sequence stored as an iff sequence file (basically a a modification of the basic iff image format) into the core representation. Getting an image sequence to begin with requires the use of a program such as ktv_getiff_sequence (currently in /u/nelson/bin/Solaris) which grabs a sequence from the ktv digitizer and stores it as an iff sequence file. The image sequence stuff is not very well developed, and there are not currently many tools for manipulating them. ------------------------------------------------------------------------------ NAME output_iff_sequence SYNOPSIS #include "bool.h" #include "utility.h" BOOL output_iff_sequence( char *filename, image_sequence_type *sequence) DESCRIPTION Writes an ipp core image sequence to the specified file as an iff sequence file. ------------------------------------------------------------------------------ *** Local routines, not intended to be called by user *** ------------------------------------------------------------------------------ void errprnt(char *string) void errprnt2(char *string1, *string2) Local functions for error bomb. ------------------------------------------------------------------------------ BOOL getnextint(FILE *fp, int *val); Local function for reading from files. ------------------------------------------------------------------------------