impZoomRow(3) Impressario impZoomRow(3)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.
Page 1
impZoomRow(3) Impressario impZoomRow(3)
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
Page 2
impZoomRow(3) Impressario impZoomRow(3)
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
Page 3
impZoomRow(3) Impressario impZoomRow(3)
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.
Page 4
impZoomRow(3) Impressario impZoomRow(3)SEE ALSOlibimp(3)
Page 5
