impCreateZoom(3)
impCreateZoom, impDestroyZoom, impResetZoom, impZoomRow - zoom image data
As shipped in IRIX 6.5.22. Unchanged since IRIX 6.5.
NAME impCreateZoom, impDestroyZoom, impResetZoom, impZoomRow - zoom image data SYNOPSIS #include <imp.h> IMPZoom* impCreateZoom(ushort_t srcXSize, ushort_t srcYSize, ushort_t dstXSize, ushort_t dstYSize, long min, long max, IMPReadRowFunc readRowFunc, int numChannels, IMPFilterType filterType, float blurFactor); void impDestroyZoom(IMPZoom *zoom); void impResetZoom(IMPZoom *zoom); int impZoomRow(IMPZoom *zoom, short *buffer, ushort_t row, void *clientData); DESCRIPTION The libimp library provides an API for performing image resizing or zooming. Images can be zoomed up or down using any of a number of resampling methods. The resampling methods divide into two categories. The first resampling category is non-filtered zooming (a.k.a. replicative zoom, decimation). The second resampling category is filtered zooming where a filter of a given shape is applied to the data. The image zooming is performed on a row by row basis using a one pass, two dimensional convolution. To zoom one or more rows of an image, first create a zoom operator by calling impCreateZoom. One of the parameters to impCreateZoom is a pointer to a function that will be called during the zoom to read rows of the source image. To obtain zoomed rows call impZoomRow. When all desired zoomed rows have been obtained, call impDestroyZoom to deallocate storage held by the zoom operator. When filtered zooming is performed a number of contiguous rows of image data are cached. Often all rows of a given image channel are zoomed followed by all rows of the next channel. Since rows are cached, the cache should be flushed when switching between image channels. The impResetZoom function performs this row cache flushing operation. The impCreateZoom function has the following parameters: srcXSize, srcYSize Width and height of the source image in pixels. dstXSize, dstYSize Width and height of the destination (i.e. zoomed) image in pixels. min, max Minimum and maximum intensity values to be used for clamping of the zoomed image data. Using certain filters (e.g. Mitchell) it is possible for the zoomed data intensity range to exceed the original data intensity range. Typically these parameters are set to the minimum and maximum possible input data intensities. For example, for 8-bit input data min would be set to 0 and max would be set to 255. readRowFunc Pointer to a function that will be called to read a row from the source image. The prototype for this function is: int (*IMPReadRowFunc)(short *buffer, ushort_t row, void *clientData); The function should read the image row indicated by row and place the data in buffer. The storage for buffer is allocated and deallocated by the zoom operator and should not be manipulated by the read row function. clientData is a pointer to caller specific information. The caller may specify a pointer to client data when calling the impZoomRow function. That pointer is passed to the read row function. At the caller's discretion this pointer may be set to NULL. A common use of the client data is to pass a pointer to a structure containing the image structure pointer and the channel number. The read row function must return -1 if it encountered an error while obtaining the row data and must return a value of 0 or greater if the function succeeds. numChannels Specifies the number of channels of image data that are packed on a single row. For example, if each row contains data for only a single channel, then numChannels should be specified as one. However, if each row contains RGB data packed together as RGBRGBRGB..., numChannels should be specified as three. filterType Specifies the type of filter to be used for resampling the image during zooming. The filter types available are: Filter Type Category __________________________ IMPImpulse Replicative IMPBox Filtered IMPTriangle Filtered IMPQuadratic Filtered IMPMitchell Filtered IMPGaussian Filtered Refer to the section entitled Filter Functions below for detailed information on the available filters. blurFactor Specifies a multiplier for the width of the filter. The default blur factor is 1.0. Higher factors increase the amount of blur present in the image. The impZoomRow function has the following parameters: zoom Pointer to a zoom operator structure obtained from a call to impCreateZoom. buffer Caller allocated buffer that will be filled with the zoomed image row data. The buffer should be allocated to accomodated dstXSize * numChannels * sizeof(short) bytes. row The desired zoomed row. Rows are numbered from 0 through dstYSize - 1. clientData Pointer to client data. This pointer is passed to the readRowFunc. A typical use of this is for passing a pointer to a structure containing the IMPImage pointer and the channel number. FILTER FUNCTIONS The resampling filters available for zooming are summarized below. Note that the span of the filter (i.e. x range) is expressed in terms of the original image not the zoomed image. Filter Type Function Span _______________________________________________________________ IMPImpulse Not Applicable IMPBox f(x) = 0.0 x < -0.5 f(x) = 1.0 -0.5 <= x < 0.5 f(x) = 0.0 x >= 0.5 IMPTriangle f(x) = 0.0 x < -1.0 f(x) = 1.0+x -1.0 <= x < 0.0 f(x) = 1.0-x 0.0 <= x < 1.0 f(x) = 0.0 x >= 1.0 IMPQuadratic f(x) = 0.0 x < -1.5 f(x) = 0.5*(x+1.5)^2 -1.5 <= x < -0.5 f(x) = 0.75-x^2 -0.5 <= x < 0.5 f(x) = 0.5*(x-1.5)^2 0.5 <= x < 1.5 f(x) = 0.0 x >= 1.5 IMPMitchell b = 1.0/3.0 c = 1.0/3.0 p0 = (6.0-2.0*b)/6.0 p2 = (-18.0+12.0*b+6.0*c)/6.0 p3 = (12.0-9.0*b-6.0*c)/6.0 q0 = (8.0*b+24.0*c)/6.0 q1 = (-12.0*b-48.0*c)/6.0 q2 = (6.0*b+30.0*c)/6.0 q3 = (-b-6.0*c)/6.0 f(x) = 0.0 x < -2.0 f(x) = q0-x*(q1-x*(q2-x*q3)) -2.0 <= x < -1.0 f(x) = p0+x*x*(p2-x*p3) -1.0 <= x < 0.0 f(x) = p0+x*x*(p2+x*p3) 0.0 <= x < 1.0 f(x) = q0+x*(q1+x*(q2+x*q3)) 1.0 <= x < 2.0 f(x) = 0.0 x >= 2.0 IMPGaussian a(x) = 1.0/exp((1.5*x)^2) b(x) = 1.0/exp(1.5^4) f(x) = a(x)-b(x) RETURN VALUE impCreateZoom returns a pointer to a zoom operator structure if execution was successful. NULL is returned and IMPerrno is set if an execution error has occurred. impZoomRow returns 0 if execution was successful. -1 is returned and IMPerrno is set if an execution error occurred. EXECUTION ERROR CODES In addition to the system error codes defined in errno.h, the following libimp specific error codes may be returned. impCreateZoom will fail under the following circumstances. IMP_ERR_MEMALLOC Dynamic memory allocation failed. This indicates an out-of-memory condition. impZoomRow will fail under the following circumstances. IMP_ERR_READROW Read row function failed. NOTES 1. The storage for the IMPZoom structure is allocated by the zoom operator creation function. This storage is deallocated by the impDestroyZoom function. The caller should not explicitly reallocate or deallocate any storage related to the image structure. 2. The fields of the IMPZoom structure are private and should not be modified by the caller. SEE ALSO libimp(3)