The directory /u/nelson/programs/ipp/image/image_proc/lib contains a number of low-level image processing routines operating on images in the ipp core format. These functions are compiled and archived into user libraries for various operating systems, stored under /u/nelson/programs/lib/*/libimage.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 are included in the file image_proc.h (located at /u/nelson/programs/include/image_proc.h), which must be included to use the library. The image data structures used by the functions are defined in utility.h (located at /u/nelson/programs/include/utility.h), so that should be included as well. Some of the routines, as well as any image-file i/o operations the user needs to perform depend on functions in /u/nelson/programs/lib/*/libutility.a hence that library and various system libraries supporting different image file formats must follow libimage.a on the load line. Because the loader searches libraries only once, this ordering is important. See the Readme file for the utility library for descriptions of the data structures, utility file i/o functions, and required external libraries (-lpgm, -ltiff etc.) The functions in the library are a mixture of old-style C and ANSI style declaration, depending on when they were last updated. Most are ANSI at this point but there may be a few holdovers left floating around. BOOL is int, and defined in bool.h (/u/nelson/programs/include/bool.h), Many of the functions work in a sensible way on color and multiband images. The few that don't silently use band 0 of any multi-band image that is provided. The library functions fall into several main groups * Arithmetic functions: Functions for combining images using arithmetic or boolean operation (add, AND etc.); adding, multiplying by, or setting to a constant value; combining bands in various ways; etc. Basically functions whose effect depends only on the pixel value(s) at the current location. * Value remapping functions: Thresholding operations; various other functions for remapping the pixel values in an image to achieve some overall condition on the distribution of values, for instance limiting the range to 8 bits, or creating images that allow negative values to be intuitively displayed. * Geometric functions: These are functions that change the geometry of the image: windowing, shrinking and enlarging, rotation, etc. * Local neighborhood operations: Functions that use values in a local image neighborhood in various ways. Large group with several subgroups. - Smoothing/noise reduction functions: box average, Gaussian, median filters, etc. - Enhancement/sharpening operations: - Image derivative functions (Functions for computing gradient, digital laplacian etc.) - Local feature detectors: (edgels etc.) - Matching operators: General correlation, convolution; ssd, sad, and hamming pattern matching. - Morphological operators: erosion, dilation etc. * Image statistics: Means, variances, histograms etc. ****************************************************************************** *** Arithmetic functions *** ****************************************************************************** Arithmetic operations involving an image and a constant factor. All these functions generalize to multi-band images by applying the same operation to each band. Functions with the suffix _mb take a vector constant whose components provide separate factors for each band. Source is in conop_functions.c ------------------------------------------------------------------------------ BOOL conop_fmultiply( imagetype *inimage, imagetype *outimage, float factor); Multiply image values by floating point factor No rescaling is performed. Negative values may be produced For multi-band images, each band is multiplied by the factor ------------------------------------------------------------------------------ BOOL conop_fmultiply_mb( imagetype *inimage, imagetype *outimage, float *factor); Multiply multi_band image values by floating point vector containing a factor for each band. No rescaling is performed. Negative values may be produced ------------------------------------------------------------------------------ BOOL conop_multiply( imagetype *inimage, imagetype *outimage, int factor); Multiply image values by integer factor. No rescaling is performed. Negative values may be produced For multi-band images, each band is multiplied by the factor WARNING. May be very slow if compiled for a RISC processor due to. implementation of fixed point multiplication. ------------------------------------------------------------------------------ BOOL conop_add( imagetype *inimage, imagetype *outimage, int value); Adds a constant value to every pixel of the image image Negative values may be produced For multi-band images, the same value is added to each band which might or might not be useful... ------------------------------------------------------------------------------ BOOL conop_clip_low( imagetype *inimage, imagetype *outimage, int min_value) Sets every pixel in the image less than min_value to that value. Useful for eliminating negatives, etc. For multi-band images, the same bound is applied to each band ------------------------------------------------------------------------------ BOOL conop_clip_high( imagetype *inimage, imagetype *outimage, int max_value) Sets every pixel in the image greater than max_value to that value. Useful for eliminating overflow values, etc. For multi-band images, the same bound is applied to each band ------------------------------------------------------------------------------ BOOL conop_and( imagetype *inimage, imagetype *outimage, int mask); Performs a bitwise AND of the pixel values with the specified mask. Could be useful for preparing images for display or storage. For multi-band images, the same value is ANDed with each band ------------------------------------------------------------------------------ BOOL conop_or( imagetype *inimage, imagetype *outimage, int mask); Performs a bitwise OR of the pixel values with the specified mask. Don't know what this is useful for. It is here because conop_and is. For multi-band images, the same value is ORed with each band. ------------------------------------------------------------------------------ BOOL conop_shift( imagetype *inimage, imagetype *outimage, int shift); Performs a shift of the bits of each pixel by the specified value Positive values are left shifts (increase value) negative values are right shifts. Could be useful for preparing images for display or file output. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ Arithmetic operations involving the combination of two images All these functions generalize to multi-band images by applying the same operation to each band. (source in binop_functions.c) BOOL binop_add( imagetype *iniamge1, imagetype *inimage2, imagetype *outimage); BOOL binop_subtract( imagetype *iniamge1, imagetype *inimage2, imagetype *outimage); BOOL binop_or( imagetype *iniamge1, imagetype *inimage2, imagetype *outimage); BOOL binop_and( imagetype *iniamge1, imagetype *inimage2, imagetype *outimage); ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ Operations that combine the bands of a multi-band image in various ways (source in com_band_functions.c) ------------------------------------------------------------------------------ BOOL combine_bands_mean( imagetype *inimage, imagetype *outimage); Creates a single-band image whose value is the mean (average) of the bands in the input image. ------------------------------------------------------------------------------ BOOL combine_bands_max( imagetype *inimage, imagetype *outimage); Creates a single-band image whose value is the maximum value of the bands in the input image. ------------------------------------------------------------------------------ BOOL combine_bands_min( imagetype *inimage, imagetype *outimage); Creates a single-band image whose value is the minimum value of the bands in the input image. ------------------------------------------------------------------------------ BOOL combine_bands_mag( imagetype *inimage, imagetype *outimage); Creates a single-band image whose value is the (normalized) Euclidean magnitude of the multi-band value considered as a point in an nbands dimensional space This routine is much slower than the previous ones as it involves both multiplication and a square-root operation at each pixel. ------------------------------------------------------------------------------ BOOL combine_bands_rgb( imagetype *inimage, imagetype *outimage); Creates a single-band monochromatic image from a 3-band rgb image using standard weighting: g = 0.34375r + 0.5g + 0.15265b = 11/32r + 1/2g + 5/32b If image is not 3-band rgb, function returns unweighted average of bands. ****************************************************************************** *** Value remapping functions *** ****************************************************************************** BOOL threshold( imagetype *inimage, imagetype *outimage, int thresh, int above_val, int below_val); Produces a two-valued image assigning one specified value to pixels above a threshold, and a second specified values to pixels equal to or below the threshold. ------------------------------------------------------------------------------ BOOL bimodalize( imagetype *inimage, imagetype *outimage); Produces a binary image from a gray-scale image, attempting to pick the best threshold to segment objects from background. Intended to be used to segment bright objects from a dark background in staged training images. Not intended for general segmentation in natural images. Dark background is set to 0, light foreground to 255. ------------------------------------------------------------------------------ BOOL zero_below_thresh( imagetype *inimage, imagetype *outimage, int thresh); Sets all pixels with value below supplied threshold to zero. Used to eliminate noise in images where non-zero values indicate some sort of feature (e.g. gradient or edgel images). ------------------------------------------------------------------------------ BOOL dejitter( imagetype *inimage, imagetype *outimage, int thresh); Removes jitter noise from an image (e.g. a digital laplacian) by setting any pixel within a given threshold (plus or minus) of zero to zero. Faster than using a median filter for this specialized situation. ------------------------------------------------------------------------------ BOOL mask( imagetype *inimage, imagetype *maskimage, imagetype *outimage); Applies a binary mask image to an image of the same size. All points in the image where the mask is 0 are set to 0. The values of other points are retained. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ ** Now a whole bunch of more or less specialized value scaling functions ** Currently, only scale_for_display(), scale(), scale_and_bound(), and scale_color_disp() handle multi-band images. ------------------------------------------------------------------------------ BOOL scale_for_display( imagetype *inimage, imagetype *outimage, int max_disp_val, int neg_display_mode, int range_control_mode) This first scaling function is intended to provide generic functionality for preparing images that may have been produced by a wide variety of operations for display. Other scaling functions (below) have more limited or specialized application. Remap image so values lie in the range 0 to max_disp_val (usually 255) Negative values are handled by either inverting and displaying the magnitude, or by applying an offset so that 0 takes on the midscale intensity value, negative values appear darker, and positive values appear lighter. The value of the parameter neg_display_mode (IPP_NEGATIVE_INVERT or IPP_NEGATIVE_OFFSET) determines the action Excess range is handled either by rescaling, or by truncation, depending on the value of range_control_mode (IPP_RANGE_TRUNCATE or IPP_RANGE_RESCALE). Range is never expanded to fill the display For multiband images, range is determined by finding min and max over all the bands, and treating each band by the same factors so that ratios are preserved. ------------------------------------------------------------------------------ BOOL scale( imagetype *inimage, imagetype *outimage); Scales the image linearly so that maximum absolute value is 255. Negative values are set to their absolute values. ------------------------------------------------------------------------------ BOOL scale_to_n( imagetype *inimage, imagetype *outimage, int n); Scales image so that maximum absolute gray value is n-1. Slightly more general version of previous scale() function. ------------------------------------------------------------------------------ BOOL scale_float( floatimagetype *inimage, floatimagetype *outimage, float maxmag); Scales a floating point image linearly so that the maximum magnitude is equal to the supplied value. Essentially a floating point version of scale_to_n(). ------------------------------------------------------------------------------ int scale_and_bound( imagetype *inimage, imagetype *outimage, float scl); Multiplies the image by the supplied scale factor and truncates at 255. Useful for visualizing faint structure. ------------------------------------------------------------------------------ BOOL scale_mean_to_n( imagetype *inimage, imagetype *outimage, int n); Scales image so that mean has specified value. Note this could produce values exceeding 255. ------------------------------------------------------------------------------ BOOL scale_top_tenth( imagetype *inimage, imagetype *outimage); Scales image so that the mean value of the top decile is 255, and caps max at 255. Only works with positive images. Used to display images with a few deviant high values. ------------------------------------------------------------------------------ BOOL scale_color_disp( imagetype *inimage, imagetype *outimage) Scale color image for display. Basically scales the image so that the color range is utilized up to a multiplicative factor of 2.0, thus ensuring that really dark images remain dark. Scaling factor is computed from mean of top 5 percent of the image values so that a few really bright points do not throw off the display ****************************************************************************** *** Geometric Functions *** ****************************************************************************** BOOL window( imagetype *inimage, imagetype *outimage, int wrow, int wcol, int nwrows, int nwcols); Extracts a specified window from an image. ------------------------------------------------------------------------------ BOOL embed( imagetype *inimage, imagetype *outimage, int width, int val); Surrounds a given image with a border of specified width and value. ------------------------------------------------------------------------------ BOOL tile( imagetype *inimage, imagetype *outimage, int n_out_rows, int n_out_cols); Tiles the output image with multiple copies of the input image. Useful for producing cool backgrounds or producing Fourier filters from small patches. ------------------------------------------------------------------------------ BOOL double_size( imagetype *inimage, imagetype *outimage) Create an output image twice the size of the imput image by duplicating values. ------------------------------------------------------------------------------ BOOL half_size( imagetype *inimage, imagetype *outimage); Reduces image size by a factor of two using averaging. ------------------------------------------------------------------------------ BOOL expand_nx( imagetype *inimage, imagetype *outimage, int n); Creates an output image n times the size of the imput image by duplicating values. Faster than general expansion operation. ------------------------------------------------------------------------------ BOOL contract_nx( imagetype *inimage, imagetype *outimage, int n); Creates an output image 1/n the size of the imput image using block averaging. Faster than more general contract algorithm that can use non-integral factors. ------------------------------------------------------------------------------ BOOL expand( imagetype *inimage, int wrow1, int wcol1, int nwrows, int nwcols, imagetype *outimage, int nrows, int ncols); Takes a window in a given image (could be the whole image) and expands the window to fit the specified output image size using bilinear interpolation. Cannot be used to shrink images, since direct generalization could produce sampling noise and aliasing. Use contract to shrink images. ------------------------------------------------------------------------------ BOOL contract( imagetype *inimage, int wrow1, int wcol2, int nwrows, int nwcols, imagetype *outimage, int nrows, int ncols); Shrinks the specified window to fit into the specified output image. Uses an averaging algorithm that correctly handles partial pixel boundaries, so performance is good (i.e. minimal aliasing) for rescalings close to 1. Cannot be used to enlarge images. For that, use expand(). ------------------------------------------------------------------------------ BOOL contract_partial( imagetype *inimage, int wrow1, int wcol2, int nwrows, int nwcols, imagetype *outimage, int nrows, int ncols, int dont_care_val); Like the contract() above, only handles don't-care values in special way. (i.e. they don't get averaged, which would destroy their special meaning) Used primarily for producing reduced resolution versions of target templates contaiing dont_care regions. ------------------------------------------------------------------------------ BOOL ipp_rotate( imagetype *inimage, float row_offset, float col_offset, float rot_angle, imagetype *outimage, int nrows, int ncols) Extracts a rotated window/image from the input image */ The origin of the window is specified in input image coordinates */ by row_offset and col_offset. rot_angle specifies the rotation angle */ of the window with respect to the input image coordinate system in */ degrees counterclockwise. nrows and ncols specify the size of the */ output window/image */ Negative and non-integer values are allowed for the offsets and rotation */ angle. Values are determined by bilinear interpolation */ Points that lie outside of the input image are filled with value 0 */ ------------------------------------------------------------------------------ BOOL ipp_rotate_center( imagetype *inimage, float center_row, float center_col, float rot_angle, imagetype *outimage, int nrows, int ncols) Variation of the rotation routine in which the supplied offset represents the center of the rotated window instead of the 0,0 corner. This is sometimes more intutive to use. ****************************************************************************** *** Local Neighborhood operations *** ****************************************************************************** ------------------------------------------------------------------------------ ** Smoothing/noise reduction functions ** ------------------------------------------------------------------------------ BOOL avg3x3( imagetype *inimage, imagetype *outimage); Computes a 3x3 neighborhood average. Takes an integer image, and produces a smoothed image. ------------------------------------------------------------------------------ BOOL avg_nxn( imagetype *inimage, imagetype *outimage); Computes average over a nxn neighborhood Uses efficient block summing technique requiring only a few operations per pixel. For multi-band images, smoothing is done separately on each band. ------------------------------------------------------------------------------ BOOL sum3x3( imagetype *inimage, imagetype *outimage); Computes sum in a 3x3 neighborhood. ------------------------------------------------------------------------------ BOOL gauss_smooth( imagetype *inimage, imagetype *outimage, float halfwidth); Smooths an image with a Gaussian of specified width. ------------------------------------------------------------------------------ BOOL median( imagetype *inimage, imagetype *outimage, int nbhd_size); Produce a median-filtered version of an image in the specified neighborhood. Uses a histogram tracking algorithm which that may be inefficient if many gray-values are used (e.g. greater than 10 bits - 1024 values. Basically intended for use on 8-bit images. Does not currently handle signed images. ------------------------------------------------------------------------------ BOOL snn_smooth( imagetype *inimage, imagetype *outimage); Symmetric nearest neighbor smoothing algorithm. Tends to be edge preserving, and is faster than median filter. 3x3 version. ------------------------------------------------------------------------------ BOOL grad_perp_smooth( imagetype *inimage, imagetype *outimage); Smooths an image only in the direction perpendicular to the gradient. Can help to preserve edge structure. Smoothing neighborhood is 3x3. Similar in effect to snn_smooth(). ------------------------------------------------------------------------------ BOOL max_smooth( imagetype *inimage, imagetype *outimage); Smooths an image by setting each pixel to the maximum value in a Guassian-weighted neighborhood. This is primarily intended to produce nicely broadened lines in a thinned edgel image so as to avoid aliasing problems when running correlations on these images, but the process could be applied to other images as well. ------------------------------------------------------------------------------ ** Enhancement/sharpening operations ** ------------------------------------------------------------------------------ BOOL grad_enhance( imagetype *magimage, imagetype *dirimage, imagetype *outimage, int n_grad_angles); Specialized routine that enhances gradients likely to be associated with image boundaries. Essentially a smoothed version of non-maximum supression. Intended use is to process gradient magnitude images prior to input to a boundary segmentation process to reduce false boundaries found in high-gradient but non-boundary regions such as curved surfaces. More robust than using thresholded laplacian zero crossings. ------------------------------------------------------------------------------ ** Image derivative functions ** ------------------------------------------------------------------------------ BOOL gradient( imagetype *inimage, imagetype *magimage, imagetype *dirimage); Finds the gradient direction and magnitude in an image by finding the maximum absolute value of the 4, 3x3 Prewitt operators. Direction is one of eight values, specified by an integer from 0 to 7. /* */ /* --> increasing column --> */ /* */ /* 3 2 1 */ /* \ | / */ /* 4 -- -- 0 */ /* / | \ */ /* 5 6 7 */ /* . . */ /* /|\ /|\ */ /* | increasing row | */ ------------------------------------------------------------------------------ BOOL gradient2( imagetype *inimage, imagetype *magimage, imagetype *dirimage, int n_directions); Finds the gradient magnitude and direction by taking the square root of the summed squares and the arc tangent of the x and y partial derivatives, computed using 3x3 Prewitt operators. Sends back direction image quantized to the specified number of directions. ------------------------------------------------------------------------------ BOOL gradient2_mag( imagetype *inimage, imagetype *magimage); Like the above, but returns only the magnitude (square root of summed square of x and y partials). Faster, because it does not need to call the arc tangent function to obtain a direction. ------------------------------------------------------------------------------ BOOL ipp_prewitt0( imagetype *inimage, imagetype *outimage); BOOL ipp_prewitt1( imagetype *inimage, imagetype *outimage); BOOL ipp_prewitt2( imagetype *inimage, imagetype *outimage); BOOL ipp_prewitt3( imagetype *inimage, imagetype *outimage); BOOL ipp_sobel0( imagetype *inimage, imagetype *outimage); BOOL ipp_sobel1( imagetype *inimage, imagetype *outimage); BOOL ipp_sobel2( imagetype *inimage, imagetype *outimage); BOOL ipp_sobel3( imagetype *inimage, imagetype *outimage); BOOL edge0( imagetype *inimage, imagetype *outimage); BOOL edge1( imagetype *inimage, imagetype *outimage); BOOL edge2( imagetype *inimage, imagetype *outimage); BOOL edge3( imagetype *inimage, imagetype *outimage); In file edges3x3.c Routines that apply 3x3 Prewitt and Sobel operators to images in 4 principle directions. Used to implement the above gradient functions. The edge*() functions are identical to (and call) the prewitt operators, and are retained for backward compatibility. The following diagram shows the direction of positive mask values of the indices 0-3 with a (iff standard) protocol of numbering image rows bottom to top. With a top to bottom protocol directions 0 to 3 will run clockwise instead of counterclockwise when viewed on a screen, but the notation will remain internally consistant. direction code --> increasing column --> 3 2 1 \ | / (4)-- -- 0 / | \ (5) (6) (7) . . /|\ /|\ | increasing row | For multi-band images, operators are applied to each band independently ------------------------------------------------------------------------------ BOOL laplace3x3( imagetype *inimage, imagetype *outimage); Computes digital laplacian over a 3x3 neighborhood. Divides result by 8, but since negative values can result, an overall doubling of the image dynamic range is possible. ------------------------------------------------------------------------------ BOOL make_8dir_image( imagetype *inimage, imagetype *outimage, int n_directions); Specialized routine that takes a gradient direction image with n directions and converts it to a direction image with 8 directions. Correctly handles transition across zero and does not introduce bias. Used by some higher-level feature detection routines that expect an 8-directional image. ------------------------------------------------------------------------------ ** Local feature detectors ** ------------------------------------------------------------------------------ BOOL grad_mag_max( imagetype *magimage, imagetype *dirimage, imagetype *edgeimage); An edgel finder. Finds edgels by finding local maxima of the gradient magnitude in the direction of the gradient. Produces both a gradient direction image and an edgel image where edge pixels contain a value proportional to the underlying gradient magnitude, and non-edge pixels are set to zero. ------------------------------------------------------------------------------ BOOL zero_crossings( imagetype *inimage, imagetype *outimage); finds the zero crossing of an image (generally the digital laplacian, and sets them to 255. All other pixels are set to 0. Marked pixels are positive or zero adjacent to negative ones. ------------------------------------------------------------------------------ BOOL local_max( imagetype *inimage, imagetype *outimage); Sets all points in image which are not local maxima in a 3x3 neighborhood to 0. Points that are equal to some or all neighbors are retained. Used sometimes in edgel detection. ------------------------------------------------------------------------------ BOOL find_good_feature( imagetype *image, int search_row, int search_col, int search_radius, int template_size, int *target_row, int *target_col, float *target_quality); Takes a starting point and an image and returns the point that is (the center of) the best correlation region nearby. Useful for finding a good tracking feature, or high interest points. ------------------------------------------------------------------------------ ** Matching operators ** ------------------------------------------------------------------------------ BOOL convolve( imagetype *inimage, imagetype *outimage, masktype *mask, int scale); Computes the convolution (actually correlation) of an image with a mask. Takes an image and a mask and produces a (slightly smaller) correlation image. For multi-band image, mask is convolved with each band. ------------------------------------------------------------------------------ BOOL fconvolve( floatimagetype *inimage, floatimagetype *outimage, floatmasktype *mask, float scale); Computes convolution (actually correlation) of a floating point image with a floating point mask. For multi-band image, mask is convolved with each band. ------------------------------------------------------------------------------ BOOL abs_diff_correlate( imagetype *inimage, imagetype *outimage, masktype *mask); Computes a correlation based on the absolute difference. Takes an integer image and a mask, and produces a correlation image. Works only on single band. ------------------------------------------------------------------------------ BOOL abs_diff_partial( imagetype *inimage, imagetype *outimage, masktype *mask, int dont_care_val); Like the previous function, only it ignores image data under dont_care_val regions of the mask. Useful for correlating with shaped targets against a cluttered background. Works only on single band. ------------------------------------------------------------------------------ BOOL match_ssd( imagetype *inimage, imagetype *outimage, masktype *mask); This routine is intended for pattern matching using a mean-normed sum of squared differences metric. Effectively, both the mask and the window have their mean subtracted before the difference is taken. This reduces errors due to bias and illumination changes Low values of metric imply good match Size of image is reduced by size of mask - 1. Works only on single band. ------------------------------------------------------------------------------ BOOL match_sad( imagetype *inimage, imagetype *outimage, masktype *mask); This routine is intended for pattern matching using a mean-normed sum of absolute differences metric. Effectively, both the mask and the window have their mean subtracted before the difference is taken. This reduces errors due to bias and illumination changes Low values of metric imply good match Size of image is reduced by size of mask - 1. Same as old routine abs_diff_correlate Works only on single band. ------------------------------------------------------------------------------ BOOL match_hamming( imagetype *inimage, imagetype *outimage, masktype *mask); Compare mask against each point in an image using an exact match (Hamming) metric. The returned value is a count of the number of location in the window whose value exacly matches the corresponding value in the mask. For binary images result is the Hamming distance. Returned image is smaller than input image by size of mask -1. Works only on single band. ------------------------------------------------------------------------------ ** Morphological operators ** ------------------------------------------------------------------------------ BOOL dilate3x3( imagetype *inimage, imagetype *outimage); Computes dilation of an image using uniform 3x3 structuring element specifically each element is replaced with maximum in a 3x3 neighborhood If image is binary, this is classical dilation, but use of max allows generalization to gray-scale images. Because dilations and erosions are often composed several times in morphological processing, this routine handles pixels at image boundaries as special cases so that the operation does not shrink image. For multi-band image, the dilation operation is performed on each band. Not clear if this is a useful thing to do, but could produce interesting effects with color images, given the implementation as a neighborhood maximum ------------------------------------------------------------------------------ BOOL erode3x3( imagetype *inimage, imagetype *outimage); Computes erosion of an image using uniform 3x3 structuring element Specifically each element is replaced with minimum in a 3x3 neighborhood If image is binary, this is classical erosion, but use of max allows generalization to gray-scale images. Because dilations and erosions are often composed several times in morphological processing, this routine handles pixels at image boundaries as special cases so that the operation does not shrink image. For multi-band image, the dilation operation is performed on each band. Not clear if this is a useful thing to do, but could produce interesting effects with color images, given the implementation as a neighborhood minimum. ****************************************************************************** *** Image Statistics Functions *** ****************************************************************************** BOOL ipp_histogram( imagetype *inimage, ipp_histogram_type *ret_hist, /* structure for returning values */ int nbins, /* number of bins in histogram, e.g. 256 */ int low_bound, /* lowest value in range of interest, e.g. 0 */ int high_bound); /* highest value in range of interest, e.g. 255 */ Computes a histogram for image with specified number of equal sample intervals (bins) evenly partitioning the specified range. the nbins and range parameters give considerable flexibility to gather statistics, but some caution must be excercised, as the algorithm produces aliasing in the bucket counts if the range of interest is not an even multiple of the number of bins. Information is returned in a histogram struct typedef struct { BOOL init; int nbins; /* Number of bins in histogram */ int low_bound; /* Range of interest */ int high_bound; int samples_in_range; int samples_below_range; int samples_above_range; int samples_tested; /* sum of above 3 fields */ int *hist_array; int *min_val_array; /* Bounding indices falling into histgram bins */ int *max_val_array; } ipp_histogram_type; This struct has arrays containing bin counts and bin bounds. It also has fields for total counts in range, below range, and above range. Storage may be allocated for arrays, which should be returned by calling ipp_kill_histogram() before the histogram struct itself goes out of scope. For multi-band images, the values from all the bands are collected and */ treated as a single set rather than, say, histogramming the magnitudes */ There are a couple of associated utility functions: BOOL ipp_init_histogram( ipp_histogram_type *histogram, int nbins) Allocates storage for and initialize histogram structure. BOOL ipp_kill_histogram( ipp_histogram_type *histogram) Returns allocated storage (if any) associated with histogram struct. There is also a simple 256 level histogram function. BOOL histogram256( imagetype *inimage, int *histarray) Computes a raw, 256 gray-level histogram for image which is assumed to be appropriately scaled. Array space for the histogram must be passed in. Out-of-range values go in extremal buckets (0 and 255). For multi-band images, the values from all the bands are collected and treated as a single set rather than, say, histogramming the magnitudes. ------------------------------------------------------------------------------ BOOL ipp_image_stats( imagetype *inimage, ipp_image_stats_type *stats); Loads up a structure with various statistical information about the image. For multi-band images values for individual bands are in the band* arrays, while the scalars hold statistics over all bands. For single band images, values in band*[0] duplicate the scalars. Allocated storage should be returned via ipp_kill_image_stats() before stats structures are deallocated. typedef struct { BOOL init; int n_bands; int samples_per_band; int n_samples; int min; /* values accumulated across all bands */ int max; float mean; float variance; float std; int *band_min; /* allocated arrays for per-band values */ int *band_max; float *band_mean; float *band_variance; float *band_std; } ipp_image_stats_type; Associated utility functions: BOOL ipp_init_image_stats( ipp_image_stats_type *stats, int n_bands) Allocate storage for per-band arrays in stats struct. BOOL ipp_kill_image_stats( ipp_image_stats_type *stats) Free any allocated array storage. ------------------------------------------------------------------------------ int mean( imagetype *inimage); Returns the mean pixel value of the image. ------------------------------------------------------------------------------ int variance( imagetype *inimage); returns the pixel variance of an image. ------------------------------------------------------------------------------ int maxval( imagetype *inimage); Returns the maximum absolute value in an image. ---------------------------------------------------------------------------- BOOL min_val_pos( imagetype *inimage, int *r_min_val, int *r_min_row, int *r_min_col); computes the row and col of the minimum value in an image. ******************************************************************************