Geometric Image Transformations

The functions in this section perform various geometrical transformations of 2D images. That is, they do not change the image content, but deform the pixel grid, and map this deformed grid to the destination image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order, from destination to the source. That is, for each pixel (x, y) of the destination image, the functions compute coordinates of the corresponding “donor” pixel in the source image and copy the pixel value, that is:

\texttt{dst} (x,y)= \texttt{src} (f_x(x,y), f_y(x,y))

In the case when the user specifies the forward mapping: \left<g_x, g_y\right>: \texttt{src} \rightarrow \texttt{dst} , the OpenCV functions first compute the corresponding inverse mapping: \left<f_x, f_y\right>: \texttt{dst} \rightarrow \texttt{src} and then use the above formula.

The actual implementations of the geometrical transformations, from the most generic Remap and to the simplest and the fastest Resize , need to solve the 2 main problems with the above formula:

  1. extrapolation of non-existing pixels. Similarly to the filtering functions, described in the previous section, for some (x,y) one of f_x(x,y) or f_y(x,y) , or they both, may fall outside of the image, in which case some extrapolation method needs to be used. OpenCV provides the same selection of the extrapolation methods as in the filtering functions, but also an additional method BORDER_TRANSPARENT , which means that the corresponding pixels in the destination image will not be modified at all.
  2. interpolation of pixel values. Usually f_x(x,y) and f_y(x,y) are floating-point numbers (i.e. \left<f_x, f_y\right> can be an affine or perspective transformation, or radial lens distortion correction etc.), so a pixel values at fractional coordinates needs to be retrieved. In the simplest case the coordinates can be just rounded to the nearest integer coordinates and the corresponding pixel used, which is called nearest-neighbor interpolation. However, a better result can be achieved by using more sophisticated interpolation methods , where a polynomial function is fit into some neighborhood of the computed pixel (f_x(x,y), f_y(x,y)) and then the value of the polynomial at (f_x(x,y), f_y(x,y)) is taken as the interpolated pixel value. In OpenCV you can choose between several interpolation methods, see Resize .

GetRotationMatrix2D

Comments from the Wiki

GetRotationMatrix2D(center, angle, scale, mapMatrix) → None

Calculates the affine matrix of 2d rotation.

Parameters:
  • center (CvPoint2D32f) – Center of the rotation in the source image
  • angle (float) – The rotation angle in degrees. Positive values mean counter-clockwise rotation (the coordinate origin is assumed to be the top-left corner)
  • scale (float) – Isotropic scale factor
  • mapMatrix (CvMat) – Pointer to the destination 2\times 3 matrix

The function cv2DRotationMatrix calculates the following matrix:

\begin{bmatrix} \alpha &  \beta & (1- \alpha )  \cdot \texttt{center.x} -  \beta \cdot \texttt{center.y} \\ - \beta &  \alpha &  \beta \cdot \texttt{center.x} - (1- \alpha )  \cdot \texttt{center.y} \end{bmatrix}

where

\alpha =  \texttt{scale} \cdot cos( \texttt{angle} ),  \beta =  \texttt{scale} \cdot sin( \texttt{angle} )

The transformation maps the rotation center to itself. If this is not the purpose, the shift should be adjusted.

GetAffineTransform

Comments from the Wiki

GetAffineTransform(src, dst, mapMatrix) → None

Calculates the affine transform from 3 corresponding points.

Parameters:
  • src (CvPoint2D32f) – Coordinates of 3 triangle vertices in the source image
  • dst (CvPoint2D32f) – Coordinates of the 3 corresponding triangle vertices in the destination image
  • mapMatrix (CvMat) – Pointer to the destination 2 \times 3 matrix

The function cvGetAffineTransform calculates the matrix of an affine transform such that:

\begin{bmatrix} x'_i \\ y'_i \end{bmatrix} = \texttt{mapMatrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}

where

dst(i)=(x'_i,y'_i),
src(i)=(x_i, y_i),
i=0,1,2

GetPerspectiveTransform

Comments from the Wiki

GetPerspectiveTransform(src, dst, mapMatrix) → None

Calculates the perspective transform from 4 corresponding points.

Parameters:
  • src (CvPoint2D32f) – Coordinates of 4 quadrangle vertices in the source image
  • dst (CvPoint2D32f) – Coordinates of the 4 corresponding quadrangle vertices in the destination image
  • mapMatrix (CvMat) – Pointer to the destination 3\times 3 matrix

The function cvGetPerspectiveTransform calculates a matrix of perspective transforms such that:

\begin{bmatrix} x'_i \\ y'_i \end{bmatrix} = \texttt{mapMatrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}

where

dst(i)=(x'_i,y'_i),
src(i)=(x_i, y_i),
i=0,1,2,3

GetQuadrangleSubPix

Comments from the Wiki

GetQuadrangleSubPix(src, dst, mapMatrix) → None

Retrieves the pixel quadrangle from an image with sub-pixel accuracy.

Parameters:
  • src (CvArr) – Source image
  • dst (CvArr) – Extracted quadrangle
  • mapMatrix (CvMat) – The transformation 2 \times 3 matrix [A|b] (see the discussion)

The function cvGetQuadrangleSubPix extracts pixels from src at sub-pixel accuracy and stores them to dst as follows:

dst(x, y)= src( A_{11} x' + A_{12} y' + b_1, A_{21} x' + A_{22} y' + b_2)

where

x'=x- \frac{(width(dst)-1)}{2} ,
y'=y- \frac{(height(dst)-1)}{2}

and

\texttt{mapMatrix} =  \begin{bmatrix} A_{11} & A_{12} & b_1 \\ A_{21} & A_{22} & b_2 \end{bmatrix}

The values of pixels at non-integer coordinates are retrieved using bilinear interpolation. When the function needs pixels outside of the image, it uses replication border mode to reconstruct the values. Every channel of multiple-channel images is processed independently.

GetRectSubPix

Comments from the Wiki

GetRectSubPix(src, dst, center) → None

Retrieves the pixel rectangle from an image with sub-pixel accuracy.

Parameters:
  • src (CvArr) – Source image
  • dst (CvArr) – Extracted rectangle
  • center (CvPoint2D32f) – Floating point coordinates of the extracted rectangle center within the source image. The center must be inside the image

The function cvGetRectSubPix extracts pixels from src :

dst(x, y) = src(x +  \texttt{center.x} - (width( \texttt{dst} )-1)*0.5, y +  \texttt{center.y} - (height( \texttt{dst} )-1)*0.5)

where the values of the pixels at non-integer coordinates are retrieved using bilinear interpolation. Every channel of multiple-channel images is processed independently. While the rectangle center must be inside the image, parts of the rectangle may be outside. In this case, the replication border mode is used to get pixel values beyond the image boundaries.

LogPolar

Comments from the Wiki

LogPolar(src, dst, center, M, flags=CV_INNER_LINEAR+CV_WARP_FILL_OUTLIERS) → None

Remaps an image to log-polar space.

Parameters:
  • src (CvArr) – Source image
  • dst (CvArr) – Destination image
  • center (CvPoint2D32f) – The transformation center; where the output precision is maximal
  • M (float) – Magnitude scale parameter. See below
  • flags (int) –

    A combination of interpolation methods and the following optional flags:

    • CV_WARP_FILL_OUTLIERS fills all of the destination image pixels. If some of them correspond to outliers in the source image, they are set to zero
    • CV_WARP_INVERSE_MAP See below

The function cvLogPolar transforms the source image using the following transformation:

Forward transformation ( CV_WARP_INVERSE_MAP is not set):

dst( \phi , \rho ) = src(x,y)

Inverse transformation ( CV_WARP_INVERSE_MAP is set):

dst(x,y) = src( \phi , \rho )

where

\rho = M  \cdot \log{\sqrt{x^2 + y^2}} , \phi =atan(y/x)

The function emulates the human “foveal” vision and can be used for fast scale and rotation-invariant template matching, for object tracking and so forth. The function can not operate in-place.

Remap

Comments from the Wiki

Remap(src, dst, mapx, mapy, flags=CV_INNER_LINEAR+CV_WARP_FILL_OUTLIERS, fillval=(0, 0, 0, 0)) → None

Applies a generic geometrical transformation to the image.

Parameters:
  • src (CvArr) – Source image
  • dst (CvArr) – Destination image
  • mapx (CvArr) – The map of x-coordinates (CV _ 32FC1 image)
  • mapy (CvArr) – The map of y-coordinates (CV _ 32FC1 image)
  • flags (int) –

    A combination of interpolation method and the following optional flag(s):

    • CV_WARP_FILL_OUTLIERS fills all of the destination image pixels. If some of them correspond to outliers in the source image, they are set to fillval
  • fillval (CvScalar) – A value used to fill outliers

The function cvRemap transforms the source image using the specified map:

\texttt{dst} (x,y) =  \texttt{src} ( \texttt{mapx} (x,y), \texttt{mapy} (x,y))

Similar to other geometrical transformations, some interpolation method (specified by user) is used to extract pixels with non-integer coordinates. Note that the function can not operate in-place.

Resize

Comments from the Wiki

Resize(src, dst, interpolation=CV_INTER_LINEAR) → None

Resizes an image.

Parameters:
  • src (CvArr) – Source image
  • dst (CvArr) – Destination image
  • interpolation (int) –

    Interpolation method:

    • CV_INTER_NN nearest-neigbor interpolation
    • CV_INTER_LINEAR bilinear interpolation (used by default)
    • CV_INTER_AREA resampling using pixel area relation. It is the preferred method for image decimation that gives moire-free results. In terms of zooming it is similar to the CV_INTER_NN method
    • CV_INTER_CUBIC bicubic interpolation

The function cvResize resizes an image src so that it fits exactly into dst . If ROI is set, the function considers the ROI as supported.

WarpAffine

Comments from the Wiki

WarpAffine(src, dst, mapMatrix, flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS, fillval=(0, 0, 0, 0)) → None

Applies an affine transformation to an image.

Parameters:
  • src (CvArr) – Source image
  • dst (CvArr) – Destination image
  • mapMatrix (CvMat) – 2\times 3 transformation matrix
  • flags

    A combination of interpolation methods and the following optional flags:

    • CV_WARP_FILL_OUTLIERS fills all of the destination image pixels; if some of them correspond to outliers in the source image, they are set to fillval
    • CV_WARP_INVERSE_MAP indicates that matrix is inversely
      transformed from the destination image to the source and, thus, can be used directly for pixel interpolation. Otherwise, the function finds the inverse transform from mapMatrix
    type flags:int
  • fillval (CvScalar) – A value used to fill outliers

The function cvWarpAffine transforms the source image using the specified matrix:

dst(x',y') = src(x,y)

where

\begin{matrix} \begin{bmatrix} x' \\ y' \end{bmatrix} =  \texttt{mapMatrix} \cdot \begin{bmatrix} x \\ y \\ 1 \end{bmatrix} &  \mbox{if CV\_WARP\_INVERSE\_MAP is not set} \\ \begin{bmatrix} x \\ y \end{bmatrix} =  \texttt{mapMatrix} \cdot \begin{bmatrix} x' \\ y' \\ 1 \end{bmatrix} &  \mbox{otherwise} \end{matrix}

The function is similar to GetQuadrangleSubPix but they are not exactly the same. WarpAffine requires input and output image have the same data type, has larger overhead (so it is not quite suitable for small images) and can leave part of destination image unchanged. While GetQuadrangleSubPix may extract quadrangles from 8-bit images into floating-point buffer, has smaller overhead and always changes the whole destination image content. Note that the function can not operate in-place.

To transform a sparse set of points, use the Transform function from cxcore.

WarpPerspective

Comments from the Wiki

WarpPerspective(src, dst, mapMatrix, flags=CV_INNER_LINEAR+CV_WARP_FILL_OUTLIERS, fillval=(0, 0, 0, 0)) → None

Applies a perspective transformation to an image.

Parameters:
  • src (CvArr) – Source image
  • dst (CvArr) – Destination image
  • mapMatrix (CvMat) – 3\times 3 transformation matrix
  • flags (int) –

    A combination of interpolation methods and the following optional flags:

    • CV_WARP_FILL_OUTLIERS fills all of the destination image pixels; if some of them correspond to outliers in the source image, they are set to fillval
    • CV_WARP_INVERSE_MAP indicates that matrix is inversely transformed from the destination image to the source and, thus, can be used directly for pixel interpolation. Otherwise, the function finds the inverse transform from mapMatrix
  • fillval (CvScalar) – A value used to fill outliers

The function cvWarpPerspective transforms the source image using the specified matrix:

\begin{matrix} \begin{bmatrix} x' \\ y' \end{bmatrix} =  \texttt{mapMatrix} \cdot \begin{bmatrix} x \\ y \\ 1 \end{bmatrix} &  \mbox{if CV\_WARP\_INVERSE\_MAP is not set} \\ \begin{bmatrix} x \\ y \end{bmatrix} =  \texttt{mapMatrix} \cdot \begin{bmatrix} x' \\ y' \\ 1 \end{bmatrix} &  \mbox{otherwise} \end{matrix}

Note that the function can not operate in-place. For a sparse set of points use the PerspectiveTransform function from CxCore.