Vectorized image operations. More...
#include "generic.h"Data Structures | |
| struct | VlImSmoothFilt |
| Image smoothing filter. More... | |
Defines | |
Image convolution flags | |
| #define | VL_PAD_BY_ZERO (0x0 << 0) |
| Pad with zeroes. | |
| #define | VL_PAD_BY_CONTINUITY (0x1 << 0) |
| Pad by continuity. | |
| #define | VL_PAD_MASK (0x3) |
| Padding field selector. | |
| #define | VL_TRANSPOSE (0x1 << 2) |
| Transpose result. | |
Functions | |
Image convolution | |
| void | vl_imconvcol_vf (float *dst, int dst_stride, float const *src, int src_width, int src_height, int src_stride, float const *filt, int filt_begin, int filt_end, int step, unsigned int flags) |
| void | vl_imconvcol_vd (double *dst, int dst_stride, double const *src, int src_width, int src_height, int src_stride, double const *filt, int filt_begin, int filt_end, int step, unsigned int flags) |
| Convolve image along columns. | |
| void | vl_imconvcoltri_f (float *dest, vl_size destStride, float const *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride, vl_size filterSize, vl_size step, int unsigned flags) |
| Convolve an image along the columns with a triangular kernel. | |
| void | vl_imconvcoltri_d (double *dest, vl_size destStride, double const *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride, vl_size filterSize, vl_size step, int unsigned flags) |
| Convolve an image along the columns with a triangular kernel. | |
Integral image | |
| void | vl_imintegral_f (float *integral, vl_size integralStride, float const *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride) |
| Compute integral image. | |
| void | vl_imintegral_d (double *integral, vl_size integralStride, double const *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride) |
| Compute integral image. | |
| void | vl_imintegral_i32 (vl_int32 *integral, vl_size integralStride, vl_int32 const *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride) |
| Compute integral image. | |
| void | vl_imintegral_ui32 (vl_uint32 *integral, vl_size integralStride, vl_uint32 const *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride) |
| Compute integral image. | |
Distance transform | |
| void | vl_image_distance_transform_d (double const *image, vl_size numColumns, vl_size numRows, vl_size columnStride, vl_size rowStride, double *distanceTransform, vl_uindex *indexes, double coeff, double offset) |
| Compute the distance transform of an image. | |
| void | vl_image_distance_transform_f (float const *image, vl_size numColumns, vl_size numRows, vl_size columnStride, vl_size rowStride, float *distanceTransform, vl_uindex *indexes, float coeff, float offset) |
Image smoothing | |
| VlImSmoothFilt * | vl_imsmooth_new (int width, int height) |
| Create a new Gaussian Smooth filter. | |
| void | vl_imsmooth_delete (VlImSmoothFilt *f) |
| Delete Smooth filter. | |
| void | vl_imsmooth_smooth_sub_image (VlImSmoothFilt *self, float *outputImage, vl_size outStride, float const *inputImage, vl_size inWidth, vl_size inHeight, vl_size inStride, double sigma) |
| Smooth a sub-image with a gaussian filter. | |
| void | vl_imsmooth_smooth_image (VlImSmoothFilt *self, float *outputImage, const float *inputImage, vl_size inWidth, vl_size inHeight, double sigma) |
| Smooth an image with a gaussian filter. | |
Image gradients | |
| void | vl_imgradient_polar_f (float *amplitudeGradient, float *angleGradient, vl_size gradWidthStride, vl_size gradHeightStride, float const *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride) |
| Compute gradient amplitudes and directions of an image. | |
| void | vl_imgradient_polar_d (double *amplitudeGradient, double *angleGradient, vl_size gradWidthStride, vl_size gradHeightStride, double const *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride) |
| Compute gradient amplitudes and directions of an image. | |
| void | vl_imgradient_f (float *xGradient, float *yGradient, vl_size gradWidthStride, vl_size gradHeightStride, float *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride) |
| Compute image gradient. | |
| void | vl_imgradient_d (double *xGradient, double *yGradient, vl_size gradWidthStride, vl_size gradHeightStride, double *image, vl_size imageWidth, vl_size imageHeight, vl_size imageStride) |
| Compute image gradient. | |
| void | vl_imgradient_polar_f_callback (float const *sourceImage, int sourceImageWidth, int sourceImageHeight, float *dstImage, int dstWidth, int dstHeight, int octave, int level, void *params) |
Detailed Description
This module provides the following image operations:
- Separable convolution. The function vl_imconvcol_vf() can be used to compute separable convolutions.
- Convolution by a triangular kernel. The function vl_imconvcoltri_vf() is an optimized convolution routine for triangular kernels.
- Distance transform. vl_image_distance_transform_f() is a linear algorithm to compute the distance transform of an image.
- Remarks:
- Some operations are optimized to exploit possible SIMD instructions. This requires image data to be properly aligned (typically to 16 bytes). Similalry, the image stride (the number of bytes to skip to move to the next image row), must be aligned.
Function Documentation
| vl_image_distance_transform_d | ( | double const * | image, |
| vl_size | numColumns, | ||
| vl_size | numRows, | ||
| vl_size | columnStride, | ||
| vl_size | rowStride, | ||
| double * | distanceTransform, | ||
| vl_uindex * | indexes, | ||
| double | coeff, | ||
| double | offset | ||
| ) |
- Parameters:
-
image image. numColumns number of columns of the image. numRows number of rows of the image. columnStride offset from one column to the next. rowStride offset from one row to the next. distanceTransform distance transform (out). indexes nearest neighbor indexes (in/out). coeff quadratic cost coefficient (non-negative). offset quadratic cost offset.
The function computes the distance transform along the first dimension of the image image. Let
be image. Its distance transfrom
is given by:
Notice that coeff must be non negative.
The function fills in the buffer distanceTransform with
. This buffer must have the same size as image.
If indexes is not NULL, it must be a matrix of the same size o the image. The function interprets the value of this matrix as indexes of the pixels, i.e
is the index of pixel
. On output, the matrix indexes contains
. This information can be used to determine for each pixel
its “nearest neighbor&rdquo.
Notice that by swapping numRows and numColumns and columnStride and rowStride, the function can be made to operate along the other image dimension. Specifically, to compute the distance transform along columns and rows, call the functinon twice:
for (i = 0 ; i < numColumns * numRows ; ++i) indexes[i] = i ; vl_image_distance_transform_d(image,numColumns,numRows,1,numColumns, distanceTransform,indexes,u_coeff,u_offset) ; vl_image_distance_transform_d(distanceTransform,numRows,numColumns,numColumns,1, distanceTransform,indexes,u_coeff,u_offset) ;
- Algorithm
The function implements the algorithm described in: P. F. Felzenszwalb and D. P. Huttenlocher, Distance Transforms of Sampled Functions, Technical Report, Cornell University, 2004.
Since the algorithm operates along one dimension per time, consider the 1D version of the problem for simplicity:
Hence the distance transform
is the lower envelope of the family of parabolas
indexed by
. Notice that all parabolas have the same curvature and that their centers are located at
. The algorithm considers one parabola per time, from left to right, and finds the interval for which the parabola belongs to the lower envelope (if any).
Initially, only the leftmost parabola
has been considered, and its validity interval is
. Then the second parabola
is considered. As long as
, the two parabolas
intersect at a unique point
. Then the first parabola belongs to the envelope in the interval
and the second one in the interval
. When the third parabola
is considered, the intersection point
with the previously added parabola
is found. Now two cases may arise:
, in which case all three parabolas belong to the envelope in the intervals
.
, in which case the second parabola
has no point beloning to the envelope, and it is removed. One then remains with the two parabolas
and the algorithm is re-iterated.
The algorithm proceeds in this fashion. Every time a new parabola is considered, its intersection point with the previously added parabola on the left is computed, and that parabola is potentially removed. The cost of an iteration is 1 plus the number of deleted parabolas. Since there are
iterations and at most
parabolas to delete overall, the complexity is linear, i.e.
.
| vl_image_distance_transform_f | ( | float const * | image, |
| vl_size | numColumns, | ||
| vl_size | numRows, | ||
| vl_size | columnStride, | ||
| vl_size | rowStride, | ||
| float * | distanceTransform, | ||
| vl_uindex * | indexes, | ||
| float | coeff, | ||
| float | offset | ||
| ) |
- See also:
- vl_image_distance_transform_d
| vl_imconvcol_vd | ( | double * | dst, |
| int | dst_stride, | ||
| double const * | src, | ||
| int | src_width, | ||
| int | src_height, | ||
| int | src_stride, | ||
| double const * | filt, | ||
| int | filt_begin, | ||
| int | filt_end, | ||
| int | step, | ||
| unsigned int | flags | ||
| ) |
- Parameters:
-
dst destination image. dst_stride width of the destination image including padding. src source image. src_width width of the source image. src_height height of the source image. src_stride width of the source image including padding. filt filter kernel. filt_begin coordinate of the first filter element. filt_end coordinate of the last filter element. step sub-sampling step. flags operation modes.
The function convolves the column of the image src by the filter filt and saves the result to the image dst. The size of dst must be equal to the size of src. Formally, this results in the calculation
The function subsamples the image along the columns according to the parameter step. Setting step to 1 (one) computes the elements
for all pairs (x,0), (x,1), (x,2) and so on. Setting step two 2 (two) computes only (x,0), (x,2) and so on (in this case the height of the destination image is floor(src_height/step)+1).
Calling twice the function can be used to compute 2-D separable convolutions. Use the flag VL_TRANSPOSE to transpose the result (in this case dst has transposed dimension as well).
The function allows the support of the filter to be any range. Usually the support is filt_end = -filt_begin.
The convolution operation may pick up values outside the image boundary. To cope with this edge cases, the function either pads the image by zero (VL_PAD_BY_ZERO) or with the values at the boundary (VL_PAD_BY_CONTINUITY).
| vl_imconvcol_vf | ( | float * | dst, |
| int | dst_stride, | ||
| float const * | src, | ||
| int | src_width, | ||
| int | src_height, | ||
| int | src_stride, | ||
| float const * | filt, | ||
| int | filt_begin, | ||
| int | filt_end, | ||
| int | step, | ||
| unsigned int | flags | ||
| ) |
- See also:
- vl_imconvcol_vf()
| vl_imconvcoltri_d | ( | double * | dest, |
| vl_size | destStride, | ||
| double const * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride, | ||
| vl_size | filterSize, | ||
| vl_size | step, | ||
| int unsigned | flags | ||
| ) |
- Parameters:
-
dest destination image. destStride destination image stride. image image to convolve. imageWidth width of the image. imageHeight height of the image. imageStride width of the image including padding. filterSize size of the triangular filter. step sub-sampling step. flags operation modes.
The function convolves the columns of the image image with the triangular kernel
The paramter
, equal to the function argument filterSize, controls the width of the kernel. Notice that the support of
as a continuous function of
is the open interval
, which has length
. However,
restricted to the ingeter domain
has support
, which counts
elements only. In particular, the discrete kernel is symmetric about the origin for all values of
.
The normalization factor
guaratnees that the filter is normalized to one, i.e.:
- Algorithm
The function exploits the fact that convolution by a triangular kernel can be expressed as the repeated convolution by a rectangular kernel, and that the latter can be performed in time indepenedent on the fiter width by using an integral-image type trick. Overall, the algorithm complexity is independent on the parameter filterSize and linear in the nubmer of image pixels.
- See also:
- vl_imconvcol_vd for details on the meaning of the other parameters.
| vl_imconvcoltri_f | ( | float * | dest, |
| vl_size | destStride, | ||
| float const * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride, | ||
| vl_size | filterSize, | ||
| vl_size | step, | ||
| int unsigned | flags | ||
| ) |
- See also:
- vl_imconvcoltri_d()
| vl_imgradient_d | ( | double * | xGradient, |
| double * | yGradient, | ||
| vl_size | gradWidthStride, | ||
| vl_size | gradHeightStride, | ||
| double * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride | ||
| ) |
This functions computes the amplitudes and angles of input image gradient.
Gradient is computed simple by gradient kernel
,
for border pixels and with sobel filter kernel
,
otherwise on the input image image yielding x-gradient
, stored in xGradient and y-gradient
, stored in yGradient, respectively.
This function also allows to process only part of the input image defining the imageStride as original image width and width as width of the sub-image.
Also it allows to easily align the output data by definition of the gradWidthStride and gradHeightStride .
- Parameters:
-
xGradient Pointer to amplitude gradient plane yGradient Pointer to angle gradient plane gradWidthStride Width of the gradient plane including padding gradHeightStride Height of the gradient plane including padding image Pointer to the source image imageWidth Source image width imageHeight Source image height imageStride Width of the image including padding.
| vl_imgradient_f | ( | float * | xGradient, |
| float * | yGradient, | ||
| vl_size | gradWidthStride, | ||
| vl_size | gradHeightStride, | ||
| float * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride | ||
| ) |
- See also:
- vl_imgradient_d
| vl_imgradient_polar_d | ( | double * | amplitudeGradient, |
| double * | angleGradient, | ||
| vl_size | gradWidthStride, | ||
| vl_size | gradHeightStride, | ||
| double const * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride | ||
| ) |
- Parameters:
-
amplitudeGradient Pointer to amplitude gradient plane angleGradient Pointer to angle gradient plane gradWidthStride Width of the gradient plane including padding gradHeightStride Height of the gradient plane including padding src Pointer to the source image imageWidth Source image width imageHeight Source image height imageStride Width of the source image including padding.
This functions computes the amplitudes and angles of input image gradient.
Gradient is computed simple by gradient kernel
,
for border pixels and with sobel filter kernel
,
otherwise on the input image image yielding x-gradient
, stored in xGradient and y-gradient
, stored in yGradient, respectively.
The amplitude of the gradient, stored in plane amplitudeGradient, is then calculated as
and the angle of the gradient, stored in angleGradient is
normalised into interval 0 and
.
This function also allows to process only part of the input image defining the imageStride as original image width and width as width of the sub-image.
Also it allows to easily align the output data by definition of the gradWidthStride and gradHeightStride .
| vl_imgradient_polar_f | ( | float * | amplitudeGradient, |
| float * | angleGradient, | ||
| vl_size | gradWidthStride, | ||
| vl_size | gradHeightStride, | ||
| float const * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride | ||
| ) |
- See also:
- vl_imgradient_polar_f
| vl_imintegral_d | ( | double * | integral, |
| vl_size | integralStride, | ||
| double const * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride | ||
| ) |
- Parameters:
-
integral integral image. integralStride integral image stride. image source image. imageWidth source image width. imageHeight source image height. imageStride source image stride.
Let
. The function computes the integral image
of
:
The integral image
can be used to compute quickly the integral of of
in a rectangular region
:
Note that the order of operations is important when the integral image has an unsigned data type (e.g. vl_uint32). The formula is easily derived as follows:
| vl_imintegral_f | ( | float * | integral, |
| vl_size | integralStride, | ||
| float const * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride | ||
| ) |
- See also:
- vl_imintegral_d.
| vl_imintegral_i32 | ( | vl_int32 * | integral, |
| vl_size | integralStride, | ||
| vl_int32 const * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride | ||
| ) |
- See also:
- vl_imintegral_d.
| vl_imintegral_ui32 | ( | vl_uint32 * | integral, |
| vl_size | integralStride, | ||
| vl_uint32 const * | image, | ||
| vl_size | imageWidth, | ||
| vl_size | imageHeight, | ||
| vl_size | imageStride | ||
| ) |
- See also:
- vl_imintegral_d.
| vl_imsmooth_delete | ( | VlImSmoothFilt * | f | ) |
- Parameters:
-
f Smooth filter to delete.
The function frees the resources allocated by vl_imsmooth_new().
| vl_imsmooth_new | ( | int | width, |
| int | height | ||
| ) |
- Parameters:
-
width image width. height image height.
The function allocates and returns a new Smooth filter for the specified image size.
- Returns:
- the new Smooth filter.
- See also:
- vl_imsmooth_delete().
| void vl_imsmooth_smooth_image | ( | VlImSmoothFilt * | self, |
| float * | outputImage, | ||
| const float * | inputImage, | ||
| vl_size | inWidth, | ||
| vl_size | inHeight, | ||
| double | sigma | ||
| ) | [inline] |
This functions smoothes inputImage with gaussian filter with standard deviation sigma into outputImage.
Please note that the filter is faster if images are smaller or equal size defined in vl_smooth_new function.
- Parameters:
-
self Smooth filter. outputImage output image buffer. inputImage input image buffer. inWidth input image width. inHeight input image height. sigma smoothing.
| vl_imsmooth_smooth_sub_image | ( | VlImSmoothFilt * | self, |
| float * | outputImage, | ||
| vl_size | outStride, | ||
| float const * | inputImage, | ||
| vl_size | inWidth, | ||
| vl_size | inHeight, | ||
| vl_size | inStride, | ||
| double | sigma | ||
| ) |
- Parameters:
-
self Smooth filter. outputImage output image buffer. outStride width of the output image including padding. inputImage input image buffer. inWidth input image width. inHeight input image height. inStride width of the input image including padding. sigma smoothing.
This functions smoothes inputImage with gaussian filter with standard deviation sigma into outputImage.
This function allows to smooth of sub-images when the strides of input and output images are correct. The strides are usually numbers of collumns.
Please note that the filter is faster if images are smaller or equal size defined in vl_smooth_new function.