This chapter provides an overview of the information contained in the functional descriptions.
Image library functional descriptions include the following types of information.
Image library function definitions use the following data structures.
|FwiDecodeHuffmanSpec||Huffman decoder specification.|
|FwiDecodeHuffmanState||Huffman decoder state.|
|FwiEncodeHuffmanSpec||Huffman encoder specification.|
|FwiEncodeHuffmanState||Huffman encoder state.|
|FwiLUTSpec||Internal data structure for 3D-LUT table.|
|FwiMorphAdvState||Advanced morphology state.|
|FwiMorphGrayState||Advanced morphology state.|
|FwiPoint||The point represented by (x, y).|
|FwiRect||The position and size of a rectangle represented by (x, y, width, height).|
|FwiSize||The size of a rectangle represented by (width, height).|
Image library function definitions use the following enumerators.
|FwiAlphaType||Type of compositing operation for alpha composition functions.|
|FwiAxis||Image intensity ramp for fwiImageRamp functions or flip axes for fwiMirror functions.|
|FwiBorderType||Border type for filter functions.|
|FwiDitherType||Type of dithering for fwiReduceBits function.|
|FwiMaskSize||Neighborhood area for filter and morphological functions.|
Image library function definitions use the following color channel buffer types.
|AC4||Three-channel color with an additional alpha (transparency) channel|
A channel is a pixel-ordered grayscale representation of a single color. The RGB color model uses three channels, one each for red, green, and blue color data. RGBA adds a fourth channel for transparency.
Image processing functions generally show source and destination buffers in a combined pair, such as C4P4. Use of a single buffer type indicates either that the source and destination buffers are of the same type, or that the function writes data back to the source location.
Image library functions use the following color plane buffer types.
Planes map color spaces. A color space is defined by a color model and a gamut, or range of colors. Many color spaces can be represented by three planes (XYZ coordinated), but there are spaces of greater and lesser dimensions. A single-plane color can be viewed as a slice through a larger color space.
Functions generally show source and destination buffers in a combined pair, such as P4C4. Use of a single buffer type indicates either that the source and destination buffers are of the same type, or that the function writes data back to the source buffer.
Many image library functions use the concept of a Region of Interest (ROI). A programmer can choose to manipulate specific regions of an image buffer rather than the entire image. The following figure shows an ROI for a typical in-place (same source and destination) operation.
The outer rectangle represents an image buffer. The inner grey rectangle represents the ROI inside the buffer.
Four items of information are required to define the ROI:
ROIs for operations that use separate source and destination buffers are defined in the same way.
In an iterative operation that involves image buffers, it may be necessary to skip operating on certain portions of the ROI. This is accomplished by using a mask of the same size as the ROI. When a mask is used, the function writes a result to a destination pixel only when the corresponding pixel value in the mask is non-zero. The function does not write a result to a destination pixel when the corresponding pixel value in the mask is zero.
Many Framewave image processing functions that use the values of adjscent pixels to calculate a destination value require source images with defined border areas. Image processing functions typically assume that referenced adjacent pixels are available, but this is not always the case. The area on which a function operates is defined by ROI position, by kernel or mask size, and by anchor cell position. The following diagram shows a source image with borders, a destination image, and a kernel mask with anchor points.
Anchors position the kernel so that an anchor cell coincides with an input pixel. However, when an input pixel is near the edge of an image, the kernel can include adjacent pixels locations that are outside the source image or ROI. Data for these adjacent locations must be provided in order for the function to work correctly.
The general approach is to first determine whether additional border pixels are required, then define the pixels as needed. When an ROI includes boundary pixels, border extension is required; when an ROI does not include boundary pixels, border extension in not required. To define the border pixels, either use an Framewave function that fills in the border with defined pixel values, or apply a locally-developed extension method.
The following order fill methods are used.
For example, the FilterSharpen function always uses a 3X3 kernel mask with the anchor in the center, location (1,1) in zero-based coordinates, relative to the top left corner of the mask. For the function to operate correctly, the source image must have a complete one-pixel border on both sides, top and bottom.
Consider a Filter32f function with variable-size mask and anchor:
The maximum ROI size that can be safely used with the source image is 16 by 13 pixels, and the minimum destination image size is 16 by 13.
The following formulas calculate the offset from the top left corner of the image to the top left corner of the non-border area of the image.
Offset = StepSizesrc x Yanchor + Xanchor x Channels x ElementSize
Maximum ROI size is:
The destination image size is at least the size of the ROI.
Some Framewave functions assume that the anchor coordinates are relative to the bottom right corner of the mask. In this case, the formulas must be modified accordingly.
It is possible to have a source image with a much larger source step-size value than specified in the formula. This typically occurs when using an Framewave function to process a small part of a source image. In this case, the offset value can also be much larger, pointing somewhere in the middle of the source image data buffer. The developer must make sure there is a safe border area around the image that the function can safely read or modify.
The following interpolation modes are available in functions that use the interpolation parameter.
FWI_INTER_NN: nearest neighbor interpolation
FWI_INTER_LINEAR: linear interpolation
FWI_INTER_CUBIC: cubic interpolation
FWI_INTER_LANCZOS: interpolation with Lanczos window function
Image library function definitions use the following parameters.
|alpha||Alpha (RGBA transparency) constant value.|
|anchor||A pixel locating the kernel (mask) according to source image.|
|angle||Specifies the rotation angle in degrees, counterclockwise.|
|axis||An enumeration that describes the type of gradiation in ImageRamp functions.|
|border||The set of source image boundary pixels.|
|borderType||Specifies a boundary type.|
|borderValue||A constant value assigned to the pixels in a constant border (not used by any other border type).|
|borderValue||A three-channel constant value assigned to the pixels in a constant border (not used by any other border type).|
|bound||Boundary rectangle vertex coordinates for a transformed source ROI.|
|coeffs||Coefficients for Warp Affine transform.|
|coeffs||Coefficients for Warp Affine Bilinear transform.|
|coeffs||Transformation coefficient values.|
|coeffs||Coefficients for Warp Affine Perspective transform.|
|cubeDimensions||dimensions of the 3D-LUT cube in x, y and z directions .(eg. (17,17,17), (33,33,33) etc)|
|cubeMax||The maximum values that can occur in 3D-LUT cube in x, y and z directions.(eg. (1023,1023,1023),4095,4095,4095) for 10 bit and 12 bit outputs respectively)|
|divisor||An integer value by which a result is divided.|
|dst1Step||Destination buffer one step size (width of the buffer in bytes).|
|dst2Step||Destination buffer two step size (width of the buffer in bytes).|
|dstOrder||Specifies destination buffer channel order. For example, dstOrder = 0 indicates that source channel 0 is destination channel 1.|
|dstQuad||Destination quadrangle vertex coordinates.|
|dstRoi||Destination image ROI.|
|dstRoiSize||Destination image ROI size.|
|dstSize||Destination image size.|
|dstStep||Destination buffer step size (width of the buffer in bytes).|
|dstStep||Destination three-channel planar buffer step size (array values define width of each plane in bytes).|
|flip||Image mirror flip mode.|
|fwCmpOp||Specifies a comparison operation to be performed (fwCmpLess, fwCmpGreater, fwCmpLessEq, fwCmpEq, or fwCmpGreaterEq).|
|heightPixels||Height of an image (number of pixels in one column of image).|
|hint||Suggests a level of precision using one of the following values (fwAlgHintNone, fwAlgHintFast, fwAlgHintAccurate).|
|imgSize||Specifies the dimensions of an entire image.|
|interpolation||Specifies the method of interpolation.|
|kernelSize||Specifies the size of the kernel used in calculations.|
|mask||An analysis window (only non-zero mask array values are processed).|
|maskSize||Specifies the size of a mask used in calculations.|
|maskStep||Mask buffer step size in bytes (width of the buffer in bytes).|
|nChannel||Number of channels in the image.|
|offset||A floating-point value that specifies the starting offset for ImageRamp functions.|
|pBuffer||Pointer to the location of a temporary buffer.|
|pBufferSize||Pointer to the size of a temporary buffer.|
|pCube||Pointer to the 3d_LUT cube. The pixel values in the table should be filled along z-axis first, then along y-axis and finally along x-axis|
|pDst||Pointer to a location in a destination buffer.|
|pDst1||Pointer to a location in destination buffer one.|
|pDst2||Pointer to a location in destination buffer two.|
|pDst||Pointer to a location in a three-channel planar destination buffer (array values point to a location in each plane).|
|pDst||Pointer to a location in a four-channel planar destination buffer (array values point to a location in each plane).|
|pKernel||Pointer to the kernel array.|
|pLUTSpec||pointer to the FwiLUTSpec structure|
|pMask||Pointer to a location in a buffer that contains a mask to be used in the operation.|
|pSize||Pointer to the size of an internal structure.|
|pSrc||Pointer to a location in a source buffer.|
|pSrc1||Pointer to a location in source buffer one.|
|pSrc2||Pointer to a location in source buffer two.|
|pSrcDst||Pointer to a location in a buffer that contains both the source and destination.|
|pSrc||Pointer to a location in a three-channel planar source buffer (array values point to a location in each plane).|
|pSrc||Pointer to a location in a four-channel planar source buffer (array values point to a location in each plane).|
|pState||Pointer to the morphology state structure.|
|pStepBytes||Pointer to the step size, in bytes.|
|pSum||Pointer to the sum of values.|
|ppDst||Double pointer to the destination image ROI.|
|ppLUTSpec||pointer to a pointer to FwiLUTSpec structure|
|ppState||Double pointer to the morphology state structure.|
|ptr||Pointer to a buffer.|
|pxMap||Pointer to X axis mapping table array.|
|pyMap||Pointer to Y axis mapping table array.|
|quad||Quadrangle vertex coordinates.|
|roiSize||Specifies the height and width of an ROI.|
|roiWidth||Width of ROI image in pixels.|
|scaleFactor||Specifies the integer scaling factor for the Sfs operation. The returned result is multiplied by 2^(-scaleFactor).|
|slope||A floating-point value that specifies the amount of gradiation in ImageRamp functions.|
|src1Step||Source buffer one step size (width of the buffer in bytes).|
|src2Step||Source buffer two step size (width of the buffer in bytes).|
|srcDstStep||Source and destination buffer step size in bytes (width of both buffers in bytes).|
|srcQuad||Source quadrangle vertex coordinates.|
|srcRoi||Source image ROI.|
|srcSize||Source image size.|
|srcSize1||Specifies the size of source image one.|
|srcSize2||Specifies the size of source image two.|
|srcStep||Source buffer step size (width of the buffer in bytes).|
|srcStep1||Source image one step size (width of the buffer in bytes).|
|srcStep2||Source image two step size (width of the buffer in bytes).|
|srcStep||Source three-channel planar buffer step size (array values define width of each plane in bytes).|
|threshold||Threshold for each pixel.|
|thresholdGT||Three-channel threshold for each pixel in greater-than operation.|
|thresholdGT||Three-channel threshold for each pixel in greater-than operation.|
|thresholdLT||Threshold for each pixel in less-than operation.|
|thresholdLT||Three-channel threshold for each pixel in less-than operation.|
|threshold||Three-channel threshold for each pixel.|
|threshold||Four-channel threshold for each pixel.|
|valueGT||Threshold for each pixel in greater-than operation.|
|valueGT||Three-channel threshold for each pixel in greater-than operation.|
|valueLT||Threshold for each pixel in less-than operation.|
|valueLT||Three-channel threshold for each pixel in less-than operation.|
|value||An array of three specified values.|
|value||An array of four specified values.|
|widthPixels||Width of an image (number of pixels in one row of image).|
|xAnchor||Anchor cell that specifies the horizontal alignment of the kernel with respect to the input pixel.|
|xCenter||X coordinate of center.|
|xFactor||Factor value for X axis direction.|
|xFr||Inverse factor value for X axis direction.|
|xMapStep||X axis mapping table step size (width of the buffer in bytes).|
|xShear||Shear value for X axis in Shear transformation.|
|xShift||Shift value for X axis direction.|
|yAnchor||Anchor cell that specifies the vertical alignment of the kernel with respect to the input pixel.|
|yCenter||Y coordinate of center.|
|yFactor||Factor value for Y axis direction .|
|yFr||Inverse factor value for Y axis direction .|
|yMapStep||Y axis mapping table step size (width of the buffer in bytes).|
|yShear||Shear value for Y axis in Shear transformation.|
|yShift||Shift value for Y axis direction.|