Basic Concepts

This chapter provides an overview of the information contained in the functional descriptions.

Image library functional descriptions include the following types of information.

Data Structures

Image library function definitions use the following data structures.

Enumerators

Image library function definitions use the following enumerators.

Color Channel Buffers

Image library function definitions use the following color channel buffer types.

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.

Color Plane Buffers

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.

Regions of Interest

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:

A pointer to the starting pixel of the ROI (pSrcDst).

The number of bytes from the starting pixel of the ROI to the end of that image row (srcDstStep).

The number of pixels in one row of the ROI (roiSize.width).

The number of pixels in one column of the ROI (roiSize.height).

ROIs for operations that use separate source and destination buffers are defined in the same way.

Image Masking

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.

Borders In Image Functions

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.

Zero fill - the border area is extended with zeros.

Constant fill - the border area is extended with a specified constant value.

Extension - the border area is created by copying the edge and corner pixels.

Reflection - the border area is created by reflection of the outer edge of the source image.

Wrap - the border area is created by toroidal wrapping of the image plane, effectively joining opposite edges of the image.

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:

Let the source image be 19 by 17 pixels.

Let the mask size be 4 by 5 pixels.

Let the anchor coordinates be (2,1) relative to the top left corner.

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.

Assume that:

W_src and H_src are the width and height of the source image in pixels.

W_mask and H_mask are the width and height of the mask in pixels.

X_anchor and Y_anchor are the zero-based coordinates of the anchor point, relative to the top left corner of the mask.

Channels is the number of channels in the image (in non-planar format).

ElementSize is the size of a single value in the source image, for example, four (bytes) for single precision floating point.

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 = StepSize_src x Y_anchor + X_anchor x Channels x ElementSize

Where:

StepSize_src = W_src x Channels x ElementSize

Maximum ROI size is:

W_ROI = W_src - W_mask + 1

H_ROI = H_src - H_mask + 1

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.

Interpolation Modes

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_SUPER: supersampling

FWI_INTER_LANCZOS: interpolation with Lanczos window function

Parameter Glossary

Image library function definitions use the following parameters.