OpenCV  3.4.4
Open Source Computer Vision
Enumerations | Functions
Geometric Image Transformations

Enumerations

enum  cv::InterpolationFlags {
  cv::INTER_NEAREST = 0,
  cv::INTER_LINEAR = 1,
  cv::INTER_CUBIC = 2,
  cv::INTER_AREA = 3,
  cv::INTER_LANCZOS4 = 4,
  cv::INTER_LINEAR_EXACT = 5,
  cv::INTER_MAX = 7,
  cv::WARP_FILL_OUTLIERS = 8,
  cv::WARP_INVERSE_MAP = 16
}
 interpolation algorithm More...
 
enum  cv::InterpolationMasks {
  cv::INTER_BITS = 5,
  cv::INTER_BITS2 = INTER_BITS * 2,
  cv::INTER_TAB_SIZE = 1 << INTER_BITS,
  cv::INTER_TAB_SIZE2 = INTER_TAB_SIZE * INTER_TAB_SIZE
}
 
enum  cv::WarpPolarMode {
  cv::WARP_POLAR_LINEAR = 0,
  cv::WARP_POLAR_LOG = 256
}
 Specify the polar mapping mode. More...
 

Functions

void cv::convertMaps (InputArray map1, InputArray map2, OutputArray dstmap1, OutputArray dstmap2, int dstmap1type, bool nninterpolation=false)
 Converts image transformation maps from one representation to another. More...
 
Mat cv::getAffineTransform (const Point2f src[], const Point2f dst[])
 Calculates an affine transform from three pairs of the corresponding points. More...
 
Mat cv::getAffineTransform (InputArray src, InputArray dst)
 
Mat cv::getDefaultNewCameraMatrix (InputArray cameraMatrix, Size imgsize=Size(), bool centerPrincipalPoint=false)
 Returns the default new camera matrix. More...
 
Mat cv::getPerspectiveTransform (const Point2f src[], const Point2f dst[])
 returns 3x3 perspective transformation for the corresponding 4 point pairs. More...
 
Mat cv::getPerspectiveTransform (InputArray src, InputArray dst)
 Calculates a perspective transform from four pairs of the corresponding points. More...
 
void cv::getRectSubPix (InputArray image, Size patchSize, Point2f center, OutputArray patch, int patchType=-1)
 Retrieves a pixel rectangle from an image with sub-pixel accuracy. More...
 
Mat cv::getRotationMatrix2D (Point2f center, double angle, double scale)
 Calculates an affine matrix of 2D rotation. More...
 
void cv::initUndistortRectifyMap (InputArray cameraMatrix, InputArray distCoeffs, InputArray R, InputArray newCameraMatrix, Size size, int m1type, OutputArray map1, OutputArray map2)
 Computes the undistortion and rectification transformation map. More...
 
float cv::initWideAngleProjMap (InputArray cameraMatrix, InputArray distCoeffs, Size imageSize, int destImageWidth, int m1type, OutputArray map1, OutputArray map2, int projType=PROJ_SPHERICAL_EQRECT, double alpha=0)
 initializes maps for remap for wide-angle More...
 
void cv::invertAffineTransform (InputArray M, OutputArray iM)
 Inverts an affine transformation. More...
 
void cv::linearPolar (InputArray src, OutputArray dst, Point2f center, double maxRadius, int flags)
 Remaps an image to polar coordinates space. More...
 
void cv::logPolar (InputArray src, OutputArray dst, Point2f center, double M, int flags)
 Remaps an image to semilog-polar coordinates space. More...
 
void cv::remap (InputArray src, OutputArray dst, InputArray map1, InputArray map2, int interpolation, int borderMode=BORDER_CONSTANT, const Scalar &borderValue=Scalar())
 Applies a generic geometrical transformation to an image. More...
 
void cv::resize (InputArray src, OutputArray dst, Size dsize, double fx=0, double fy=0, int interpolation=INTER_LINEAR)
 Resizes an image. More...
 
void cv::undistort (InputArray src, OutputArray dst, InputArray cameraMatrix, InputArray distCoeffs, InputArray newCameraMatrix=noArray())
 Transforms an image to compensate for lens distortion. More...
 
void cv::undistortPoints (InputArray src, OutputArray dst, InputArray cameraMatrix, InputArray distCoeffs, InputArray R=noArray(), InputArray P=noArray())
 Computes the ideal point coordinates from the observed point coordinates. More...
 
void cv::undistortPoints (InputArray src, OutputArray dst, InputArray cameraMatrix, InputArray distCoeffs, InputArray R, InputArray P, TermCriteria criteria)
 
void cv::warpAffine (InputArray src, OutputArray dst, InputArray M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar &borderValue=Scalar())
 Applies an affine transformation to an image. More...
 
void cv::warpPerspective (InputArray src, OutputArray dst, InputArray M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar &borderValue=Scalar())
 Applies a perspective transformation to an image. More...
 
void cv::warpPolar (InputArray src, OutputArray dst, Size dsize, Point2f center, double maxRadius, int flags)
 Remaps an image to polar or semilog-polar coordinates space. More...
 

Detailed Description

The functions in this section perform various geometrical transformations of 2D images. 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:

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

In case when you specify 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 two main problems with the above formula:

Note
The geometrical transformations do not work with CV_8S or CV_32S images.

Enumeration Type Documentation

§ InterpolationFlags

interpolation algorithm

Enumerator
INTER_NEAREST 
Python: cv.INTER_NEAREST

nearest neighbor interpolation

INTER_LINEAR 
Python: cv.INTER_LINEAR

bilinear interpolation

INTER_CUBIC 
Python: cv.INTER_CUBIC

bicubic interpolation

INTER_AREA 
Python: cv.INTER_AREA

resampling using pixel area relation. It may be a preferred method for image decimation, as it gives moire'-free results. But when the image is zoomed, it is similar to the INTER_NEAREST method.

INTER_LANCZOS4 
Python: cv.INTER_LANCZOS4

Lanczos interpolation over 8x8 neighborhood

INTER_LINEAR_EXACT 
Python: cv.INTER_LINEAR_EXACT

Bit exact bilinear interpolation

INTER_MAX 
Python: cv.INTER_MAX

mask for interpolation codes

WARP_FILL_OUTLIERS 
Python: cv.WARP_FILL_OUTLIERS

flag, fills all of the destination image pixels. If some of them correspond to outliers in the source image, they are set to zero

WARP_INVERSE_MAP 
Python: cv.WARP_INVERSE_MAP

flag, inverse transformation

For example, linearPolar or logPolar transforms:

  • flag is not set: \(dst( \rho , \phi ) = src(x,y)\)
  • flag is set: \(dst(x,y) = src( \rho , \phi )\)

§ InterpolationMasks

Enumerator
INTER_BITS 
Python: cv.INTER_BITS
INTER_BITS2 
Python: cv.INTER_BITS2
INTER_TAB_SIZE 
Python: cv.INTER_TAB_SIZE
INTER_TAB_SIZE2 
Python: cv.INTER_TAB_SIZE2

§ WarpPolarMode

Specify the polar mapping mode.

See also
warpPolar
Enumerator
WARP_POLAR_LINEAR 
Python: cv.WARP_POLAR_LINEAR

Remaps an image to/from polar space.

WARP_POLAR_LOG 
Python: cv.WARP_POLAR_LOG

Remaps an image to/from semilog-polar space.

Function Documentation

§ convertMaps()

void cv::convertMaps ( InputArray  map1,
InputArray  map2,
OutputArray  dstmap1,
OutputArray  dstmap2,
int  dstmap1type,
bool  nninterpolation = false 
)
Python:
dstmap1, dstmap2=cv.convertMaps(map1, map2, dstmap1type[, dstmap1[, dstmap2[, nninterpolation]]])

Converts image transformation maps from one representation to another.

The function converts a pair of maps for remap from one representation to another. The following options ( (map1.type(), map2.type()) \(\rightarrow\) (dstmap1.type(), dstmap2.type()) ) are supported:

  • \(\texttt{(CV_32FC1, CV_32FC1)} \rightarrow \texttt{(CV_16SC2, CV_16UC1)}\). This is the most frequently used conversion operation, in which the original floating-point maps (see remap ) are converted to a more compact and much faster fixed-point representation. The first output array contains the rounded coordinates and the second array (created only when nninterpolation=false ) contains indices in the interpolation tables.
  • \(\texttt{(CV_32FC2)} \rightarrow \texttt{(CV_16SC2, CV_16UC1)}\). The same as above but the original maps are stored in one 2-channel matrix.
  • Reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same as the originals.
Parameters
map1The first input map of type CV_16SC2, CV_32FC1, or CV_32FC2 .
map2The second input map of type CV_16UC1, CV_32FC1, or none (empty matrix), respectively.
dstmap1The first output map that has the type dstmap1type and the same size as src .
dstmap2The second output map.
dstmap1typeType of the first output map that should be CV_16SC2, CV_32FC1, or CV_32FC2 .
nninterpolationFlag indicating whether the fixed-point maps are used for the nearest-neighbor or for a more complex interpolation.
See also
remap, undistort, initUndistortRectifyMap

§ getAffineTransform() [1/2]

Mat cv::getAffineTransform ( const Point2f  src[],
const Point2f  dst[] 
)
Python:
retval=cv.getAffineTransform(src, dst)

Calculates an affine transform from three pairs of the corresponding points.

The function calculates the \(2 \times 3\) matrix of an affine transform so that:

\[\begin{bmatrix} x'_i \\ y'_i \end{bmatrix} = \texttt{map_matrix} \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\]

Parameters
srcCoordinates of triangle vertices in the source image.
dstCoordinates of the corresponding triangle vertices in the destination image.
See also
warpAffine, transform

§ getAffineTransform() [2/2]

Mat cv::getAffineTransform ( InputArray  src,
InputArray  dst 
)
Python:
retval=cv.getAffineTransform(src, dst)

§ getDefaultNewCameraMatrix()

Mat cv::getDefaultNewCameraMatrix ( InputArray  cameraMatrix,
Size  imgsize = Size(),
bool  centerPrincipalPoint = false 
)
Python:
retval=cv.getDefaultNewCameraMatrix(cameraMatrix[, imgsize[, centerPrincipalPoint]])

Returns the default new camera matrix.

The function returns the camera matrix that is either an exact copy of the input cameraMatrix (when centerPrinicipalPoint=false ), or the modified one (when centerPrincipalPoint=true).

In the latter case, the new camera matrix will be:

\[\begin{bmatrix} f_x && 0 && ( \texttt{imgSize.width} -1)*0.5 \\ 0 && f_y && ( \texttt{imgSize.height} -1)*0.5 \\ 0 && 0 && 1 \end{bmatrix} ,\]

where \(f_x\) and \(f_y\) are \((0,0)\) and \((1,1)\) elements of cameraMatrix, respectively.

By default, the undistortion functions in OpenCV (see initUndistortRectifyMap, undistort) do not move the principal point. However, when you work with stereo, it is important to move the principal points in both views to the same y-coordinate (which is required by most of stereo correspondence algorithms), and may be to the same x-coordinate too. So, you can form the new camera matrix for each view where the principal points are located at the center.

Parameters
cameraMatrixInput camera matrix.
imgsizeCamera view image size in pixels.
centerPrincipalPointLocation of the principal point in the new camera matrix. The parameter indicates whether this location should be at the image center or not.

§ getPerspectiveTransform() [1/2]

Mat cv::getPerspectiveTransform ( const Point2f  src[],
const Point2f  dst[] 
)
Python:
retval=cv.getPerspectiveTransform(src, dst)

returns 3x3 perspective transformation for the corresponding 4 point pairs.

§ getPerspectiveTransform() [2/2]

Mat cv::getPerspectiveTransform ( InputArray  src,
InputArray  dst 
)
Python:
retval=cv.getPerspectiveTransform(src, dst)

Calculates a perspective transform from four pairs of the corresponding points.

The function calculates the \(3 \times 3\) matrix of a perspective transform so that:

\[\begin{bmatrix} t_i x'_i \\ t_i y'_i \\ t_i \end{bmatrix} = \texttt{map_matrix} \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\]

Parameters
srcCoordinates of quadrangle vertices in the source image.
dstCoordinates of the corresponding quadrangle vertices in the destination image.
See also
findHomography, warpPerspective, perspectiveTransform

§ getRectSubPix()

void cv::getRectSubPix ( InputArray  image,
Size  patchSize,
Point2f  center,
OutputArray  patch,
int  patchType = -1 
)
Python:
patch=cv.getRectSubPix(image, patchSize, center[, patch[, patchType]])

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

The function getRectSubPix extracts pixels from src:

\[patch(x, y) = src(x + \texttt{center.x} - ( \texttt{dst.cols} -1)*0.5, y + \texttt{center.y} - ( \texttt{dst.rows} -1)*0.5)\]

where the values of the pixels at non-integer coordinates are retrieved using bilinear interpolation. Every channel of multi-channel images is processed independently. Also the image should be a single channel or three channel image. While the center of the rectangle must be inside the image, parts of the rectangle may be outside.

Parameters
imageSource image.
patchSizeSize of the extracted patch.
centerFloating point coordinates of the center of the extracted rectangle within the source image. The center must be inside the image.
patchExtracted patch that has the size patchSize and the same number of channels as src .
patchTypeDepth of the extracted pixels. By default, they have the same depth as src .
See also
warpAffine, warpPerspective

§ getRotationMatrix2D()

Mat cv::getRotationMatrix2D ( Point2f  center,
double  angle,
double  scale 
)
Python:
retval=cv.getRotationMatrix2D(center, angle, scale)

Calculates an affine matrix of 2D rotation.

The function 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

\[\begin{array}{l} \alpha = \texttt{scale} \cdot \cos \texttt{angle} , \\ \beta = \texttt{scale} \cdot \sin \texttt{angle} \end{array}\]

The transformation maps the rotation center to itself. If this is not the target, adjust the shift.

Parameters
centerCenter of the rotation in the source image.
angleRotation angle in degrees. Positive values mean counter-clockwise rotation (the coordinate origin is assumed to be the top-left corner).
scaleIsotropic scale factor.
See also
getAffineTransform, warpAffine, transform

§ initUndistortRectifyMap()

void cv::initUndistortRectifyMap ( InputArray  cameraMatrix,
InputArray  distCoeffs,
InputArray  R,
InputArray  newCameraMatrix,
Size  size,
int  m1type,
OutputArray  map1,
OutputArray  map2 
)
Python:
map1, map2=cv.initUndistortRectifyMap(cameraMatrix, distCoeffs, R, newCameraMatrix, size, m1type[, map1[, map2]])

Computes the undistortion and rectification transformation map.

The function computes the joint undistortion and rectification transformation and represents the result in the form of maps for remap. The undistorted image looks like original, as if it is captured with a camera using the camera matrix =newCameraMatrix and zero distortion. In case of a monocular camera, newCameraMatrix is usually equal to cameraMatrix, or it can be computed by getOptimalNewCameraMatrix for a better control over scaling. In case of a stereo camera, newCameraMatrix is normally set to P1 or P2 computed by stereoRectify .

Also, this new camera is oriented differently in the coordinate space, according to R. That, for example, helps to align two heads of a stereo camera so that the epipolar lines on both images become horizontal and have the same y- coordinate (in case of a horizontally aligned stereo camera).

The function actually builds the maps for the inverse mapping algorithm that is used by remap. That is, for each pixel \((u, v)\) in the destination (corrected and rectified) image, the function computes the corresponding coordinates in the source image (that is, in the original image from camera). The following process is applied:

\[ \begin{array}{l} x \leftarrow (u - {c'}_x)/{f'}_x \\ y \leftarrow (v - {c'}_y)/{f'}_y \\ {[X\,Y\,W]} ^T \leftarrow R^{-1}*[x \, y \, 1]^T \\ x' \leftarrow X/W \\ y' \leftarrow Y/W \\ r^2 \leftarrow x'^2 + y'^2 \\ x'' \leftarrow x' \frac{1 + k_1 r^2 + k_2 r^4 + k_3 r^6}{1 + k_4 r^2 + k_5 r^4 + k_6 r^6} + 2p_1 x' y' + p_2(r^2 + 2 x'^2) + s_1 r^2 + s_2 r^4\\ y'' \leftarrow y' \frac{1 + k_1 r^2 + k_2 r^4 + k_3 r^6}{1 + k_4 r^2 + k_5 r^4 + k_6 r^6} + p_1 (r^2 + 2 y'^2) + 2 p_2 x' y' + s_3 r^2 + s_4 r^4 \\ s\vecthree{x'''}{y'''}{1} = \vecthreethree{R_{33}(\tau_x, \tau_y)}{0}{-R_{13}((\tau_x, \tau_y)} {0}{R_{33}(\tau_x, \tau_y)}{-R_{23}(\tau_x, \tau_y)} {0}{0}{1} R(\tau_x, \tau_y) \vecthree{x''}{y''}{1}\\ map_x(u,v) \leftarrow x''' f_x + c_x \\ map_y(u,v) \leftarrow y''' f_y + c_y \end{array} \]

where \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6[, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\) are the distortion coefficients.

In case of a stereo camera, this function is called twice: once for each camera head, after stereoRectify, which in its turn is called after stereoCalibrate. But if the stereo camera was not calibrated, it is still possible to compute the rectification transformations directly from the fundamental matrix using stereoRectifyUncalibrated. For each camera, the function computes homography H as the rectification transformation in a pixel domain, not a rotation matrix R in 3D space. R can be computed from H as

\[\texttt{R} = \texttt{cameraMatrix} ^{-1} \cdot \texttt{H} \cdot \texttt{cameraMatrix}\]

where cameraMatrix can be chosen arbitrarily.

Parameters
cameraMatrixInput camera matrix \(A=\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\) .
distCoeffsInput vector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6[, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\) of 4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
ROptional rectification transformation in the object space (3x3 matrix). R1 or R2 , computed by stereoRectify can be passed here. If the matrix is empty, the identity transformation is assumed. In cvInitUndistortMap R assumed to be an identity matrix.
newCameraMatrixNew camera matrix \(A'=\vecthreethree{f_x'}{0}{c_x'}{0}{f_y'}{c_y'}{0}{0}{1}\).
sizeUndistorted image size.
m1typeType of the first output map that can be CV_32FC1, CV_32FC2 or CV_16SC2, see convertMaps
map1The first output map.
map2The second output map.

§ initWideAngleProjMap()

float cv::initWideAngleProjMap ( InputArray  cameraMatrix,
InputArray  distCoeffs,
Size  imageSize,
int  destImageWidth,
int  m1type,
OutputArray  map1,
OutputArray  map2,
int  projType = PROJ_SPHERICAL_EQRECT,
double  alpha = 0 
)
Python:
retval, map1, map2=cv.initWideAngleProjMap(cameraMatrix, distCoeffs, imageSize, destImageWidth, m1type[, map1[, map2[, projType[, alpha]]]])

initializes maps for remap for wide-angle

§ invertAffineTransform()

void cv::invertAffineTransform ( InputArray  M,
OutputArray  iM 
)
Python:
iM=cv.invertAffineTransform(M[, iM])

Inverts an affine transformation.

The function computes an inverse affine transformation represented by \(2 \times 3\) matrix M:

\[\begin{bmatrix} a_{11} & a_{12} & b_1 \\ a_{21} & a_{22} & b_2 \end{bmatrix}\]

The result is also a \(2 \times 3\) matrix of the same type as M.

Parameters
MOriginal affine transformation.
iMOutput reverse affine transformation.

§ linearPolar()

void cv::linearPolar ( InputArray  src,
OutputArray  dst,
Point2f  center,
double  maxRadius,
int  flags 
)
Python:
dst=cv.linearPolar(src, center, maxRadius, flags[, dst])

Remaps an image to polar coordinates space.

Deprecated:
This function produces same result as cv::warpPolar(src, dst, src.size(), center, maxRadius, flags)
Examples:
samples/cpp/polar_transforms.cpp.

§ logPolar()

void cv::logPolar ( InputArray  src,
OutputArray  dst,
Point2f  center,
double  M,
int  flags 
)
Python:
dst=cv.logPolar(src, center, M, flags[, dst])

Remaps an image to semilog-polar coordinates space.

Deprecated:
This function produces same result as cv::warpPolar(src, dst, src.size(), center, maxRadius, flags+WARP_POLAR_LOG);
Examples:
samples/cpp/polar_transforms.cpp.

§ remap()

void cv::remap ( InputArray  src,
OutputArray  dst,
InputArray  map1,
InputArray  map2,
int  interpolation,
int  borderMode = BORDER_CONSTANT,
const Scalar borderValue = Scalar() 
)
Python:
dst=cv.remap(src, map1, map2, interpolation[, dst[, borderMode[, borderValue]]])

Applies a generic geometrical transformation to an image.

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

\[\texttt{dst} (x,y) = \texttt{src} (map_x(x,y),map_y(x,y))\]

where values of pixels with non-integer coordinates are computed using one of available interpolation methods. \(map_x\) and \(map_y\) can be encoded as separate floating-point maps in \(map_1\) and \(map_2\) respectively, or interleaved floating-point maps of \((x,y)\) in \(map_1\), or fixed-point maps created by using convertMaps. The reason you might want to convert from floating to fixed-point representations of a map is that they can yield much faster (2x) remapping operations. In the converted case, \(map_1\) contains pairs (cvFloor(x), cvFloor(y)) and \(map_2\) contains indices in a table of interpolation coefficients.

This function cannot operate in-place.

Parameters
srcSource image.
dstDestination image. It has the same size as map1 and the same type as src .
map1The first map of either (x,y) points or just x values having the type CV_16SC2 , CV_32FC1, or CV_32FC2. See convertMaps for details on converting a floating point representation to fixed-point for speed.
map2The second map of y values having the type CV_16UC1, CV_32FC1, or none (empty map if map1 is (x,y) points), respectively.
interpolationInterpolation method (see InterpolationFlags). The method INTER_AREA is not supported by this function.
borderModePixel extrapolation method (see BorderTypes). When borderMode=BORDER_TRANSPARENT, it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function.
borderValueValue used in case of a constant border. By default, it is 0.
Note
Due to current implementation limitations the size of an input and output images should be less than 32767x32767.

§ resize()

void cv::resize ( InputArray  src,
OutputArray  dst,
Size  dsize,
double  fx = 0,
double  fy = 0,
int  interpolation = INTER_LINEAR 
)
Python:
dst=cv.resize(src, dsize[, dst[, fx[, fy[, interpolation]]]])

Resizes an image.

The function resize resizes the image src down to or up to the specified size. Note that the initial dst type or size are not taken into account. Instead, the size and type are derived from the src,dsize,fx, and fy. If you want to resize src so that it fits the pre-created dst, you may call the function as follows:

// explicitly specify dsize=dst.size(); fx and fy will be computed from that.
resize(src, dst, dst.size(), 0, 0, interpolation);

If you want to decimate the image by factor of 2 in each direction, you can call the function this way:

// specify fx and fy and let the function compute the destination image size.
resize(src, dst, Size(), 0.5, 0.5, interpolation);

To shrink an image, it will generally look best with INTER_AREA interpolation, whereas to enlarge an image, it will generally look best with c::INTER_CUBIC (slow) or INTER_LINEAR (faster but still looks OK).

Parameters
srcinput image.
dstoutput image; it has the size dsize (when it is non-zero) or the size computed from src.size(), fx, and fy; the type of dst is the same as of src.
dsizeoutput image size; if it equals zero, it is computed as:

\[\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}\]

Either dsize or both fx and fy must be non-zero.
fxscale factor along the horizontal axis; when it equals 0, it is computed as

\[\texttt{(double)dsize.width/src.cols}\]

fyscale factor along the vertical axis; when it equals 0, it is computed as

\[\texttt{(double)dsize.height/src.rows}\]

interpolationinterpolation method, see InterpolationFlags
See also
warpAffine, warpPerspective, remap
Examples:
samples/cpp/image_alignment.cpp, samples/cpp/train_HOG.cpp, samples/dnn/colorization.cpp, samples/dnn/object_detection.cpp, and samples/dnn/segmentation.cpp.

§ undistort()

void cv::undistort ( InputArray  src,
OutputArray  dst,
InputArray  cameraMatrix,
InputArray  distCoeffs,
InputArray  newCameraMatrix = noArray() 
)
Python:
dst=cv.undistort(src, cameraMatrix, distCoeffs[, dst[, newCameraMatrix]])

Transforms an image to compensate for lens distortion.

The function transforms an image to compensate radial and tangential lens distortion.

The function is simply a combination of initUndistortRectifyMap (with unity R ) and remap (with bilinear interpolation). See the former function for details of the transformation being performed.

Those pixels in the destination image, for which there is no correspondent pixels in the source image, are filled with zeros (black color).

A particular subset of the source image that will be visible in the corrected image can be regulated by newCameraMatrix. You can use getOptimalNewCameraMatrix to compute the appropriate newCameraMatrix depending on your requirements.

The camera matrix and the distortion parameters can be determined using calibrateCamera. If the resolution of images is different from the resolution used at the calibration stage, \(f_x, f_y, c_x\) and \(c_y\) need to be scaled accordingly, while the distortion coefficients remain the same.

Parameters
srcInput (distorted) image.
dstOutput (corrected) image that has the same size and type as src .
cameraMatrixInput camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\) .
distCoeffsInput vector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6[, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\) of 4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
newCameraMatrixCamera matrix of the distorted image. By default, it is the same as cameraMatrix but you may additionally scale and shift the result by using a different matrix.

§ undistortPoints() [1/2]

void cv::undistortPoints ( InputArray  src,
OutputArray  dst,
InputArray  cameraMatrix,
InputArray  distCoeffs,
InputArray  R = noArray(),
InputArray  P = noArray() 
)
Python:
dst=cv.undistortPoints(src, cameraMatrix, distCoeffs[, dst[, R[, P]]])
dst=cv.undistortPointsIter(src, cameraMatrix, distCoeffs, R, P, criteria[, dst])

Computes the ideal point coordinates from the observed point coordinates.

The function is similar to undistort and initUndistortRectifyMap but it operates on a sparse set of points instead of a raster image. Also the function performs a reverse transformation to projectPoints. In case of a 3D object, it does not reconstruct its 3D coordinates, but for a planar object, it does, up to a translation vector, if the proper R is specified.

For each observed point coordinate \((u, v)\) the function computes:

\[ \begin{array}{l} x^{"} \leftarrow (u - c_x)/f_x \\ y^{"} \leftarrow (v - c_y)/f_y \\ (x',y') = undistort(x^{"},y^{"}, \texttt{distCoeffs}) \\ {[X\,Y\,W]} ^T \leftarrow R*[x' \, y' \, 1]^T \\ x \leftarrow X/W \\ y \leftarrow Y/W \\ \text{only performed if P is specified:} \\ u' \leftarrow x {f'}_x + {c'}_x \\ v' \leftarrow y {f'}_y + {c'}_y \end{array} \]

where undistort is an approximate iterative algorithm that estimates the normalized original point coordinates out of the normalized distorted point coordinates ("normalized" means that the coordinates do not depend on the camera matrix).

The function can be used for both a stereo camera head or a monocular camera (when R is empty).

Parameters
srcObserved point coordinates, 1xN or Nx1 2-channel (CV_32FC2 or CV_64FC2).
dstOutput ideal point coordinates after undistortion and reverse perspective transformation. If matrix P is identity or omitted, dst will contain normalized point coordinates.
cameraMatrixCamera matrix \(\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\) .
distCoeffsInput vector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6[, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\) of 4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
RRectification transformation in the object space (3x3 matrix). R1 or R2 computed by stereoRectify can be passed here. If the matrix is empty, the identity transformation is used.
PNew camera matrix (3x3) or new projection matrix (3x4) \(\begin{bmatrix} {f'}_x & 0 & {c'}_x & t_x \\ 0 & {f'}_y & {c'}_y & t_y \\ 0 & 0 & 1 & t_z \end{bmatrix}\). P1 or P2 computed by stereoRectify can be passed here. If the matrix is empty, the identity new camera matrix is used.
Examples:
samples/cpp/tutorial_code/features2D/Homography/pose_from_homography.cpp.

§ undistortPoints() [2/2]

void cv::undistortPoints ( InputArray  src,
OutputArray  dst,
InputArray  cameraMatrix,
InputArray  distCoeffs,
InputArray  R,
InputArray  P,
TermCriteria  criteria 
)
Python:
dst=cv.undistortPoints(src, cameraMatrix, distCoeffs[, dst[, R[, P]]])
dst=cv.undistortPointsIter(src, cameraMatrix, distCoeffs, R, P, criteria[, dst])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Note
Default version of undistortPoints does 5 iterations to compute undistorted points.

§ warpAffine()

void cv::warpAffine ( InputArray  src,
OutputArray  dst,
InputArray  M,
Size  dsize,
int  flags = INTER_LINEAR,
int  borderMode = BORDER_CONSTANT,
const Scalar borderValue = Scalar() 
)
Python:
dst=cv.warpAffine(src, M, dsize[, dst[, flags[, borderMode[, borderValue]]]])

Applies an affine transformation to an image.

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

\[\texttt{dst} (x,y) = \texttt{src} ( \texttt{M} _{11} x + \texttt{M} _{12} y + \texttt{M} _{13}, \texttt{M} _{21} x + \texttt{M} _{22} y + \texttt{M} _{23})\]

when the flag WARP_INVERSE_MAP is set. Otherwise, the transformation is first inverted with invertAffineTransform and then put in the formula above instead of M. The function cannot operate in-place.

Parameters
srcinput image.
dstoutput image that has the size dsize and the same type as src .
M\(2\times 3\) transformation matrix.
dsizesize of the output image.
flagscombination of interpolation methods (see InterpolationFlags) and the optional flag WARP_INVERSE_MAP that means that M is the inverse transformation ( \(\texttt{dst}\rightarrow\texttt{src}\) ).
borderModepixel extrapolation method (see BorderTypes); when borderMode=BORDER_TRANSPARENT, it means that the pixels in the destination image corresponding to the "outliers" in the source image are not modified by the function.
borderValuevalue used in case of a constant border; by default, it is 0.
See also
warpPerspective, resize, remap, getRectSubPix, transform
Examples:
samples/cpp/image_alignment.cpp.

§ warpPerspective()

void cv::warpPerspective ( InputArray  src,
OutputArray  dst,
InputArray  M,
Size  dsize,
int  flags = INTER_LINEAR,
int  borderMode = BORDER_CONSTANT,
const Scalar borderValue = Scalar() 
)
Python:
dst=cv.warpPerspective(src, M, dsize[, dst[, flags[, borderMode[, borderValue]]]])

Applies a perspective transformation to an image.

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

\[\texttt{dst} (x,y) = \texttt{src} \left ( \frac{M_{11} x + M_{12} y + M_{13}}{M_{31} x + M_{32} y + M_{33}} , \frac{M_{21} x + M_{22} y + M_{23}}{M_{31} x + M_{32} y + M_{33}} \right )\]

when the flag WARP_INVERSE_MAP is set. Otherwise, the transformation is first inverted with invert and then put in the formula above instead of M. The function cannot operate in-place.

Parameters
srcinput image.
dstoutput image that has the size dsize and the same type as src .
M\(3\times 3\) transformation matrix.
dsizesize of the output image.
flagscombination of interpolation methods (INTER_LINEAR or INTER_NEAREST) and the optional flag WARP_INVERSE_MAP, that sets M as the inverse transformation ( \(\texttt{dst}\rightarrow\texttt{src}\) ).
borderModepixel extrapolation method (BORDER_CONSTANT or BORDER_REPLICATE).
borderValuevalue used in case of a constant border; by default, it equals 0.
See also
warpAffine, resize, remap, getRectSubPix, perspectiveTransform
Examples:
samples/cpp/image_alignment.cpp, samples/cpp/tutorial_code/features2D/Homography/homography_from_camera_displacement.cpp, and samples/cpp/warpPerspective_demo.cpp.

§ warpPolar()

void cv::warpPolar ( InputArray  src,
OutputArray  dst,
Size  dsize,
Point2f  center,
double  maxRadius,
int  flags 
)
Python:
dst=cv.warpPolar(src, dsize, center, maxRadius, flags[, dst])

Remaps an image to polar or semilog-polar coordinates space.

polar_remap_doc.png
Polar remaps reference

Transform the source image using the following transformation:

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

where

\[ \begin{array}{l} \vec{I} = (x - center.x, \;y - center.y) \\ \phi = Kangle \cdot \texttt{angle} (\vec{I}) \\ \rho = \left\{\begin{matrix} Klin \cdot \texttt{magnitude} (\vec{I}) & default \\ Klog \cdot log_e(\texttt{magnitude} (\vec{I})) & if \; semilog \\ \end{matrix}\right. \end{array} \]

and

\[ \begin{array}{l} Kangle = dsize.height / 2\Pi \\ Klin = dsize.width / maxRadius \\ Klog = dsize.width / log_e(maxRadius) \\ \end{array} \]

Linear vs semilog mapping

Polar mapping can be linear or semi-log. Add one of WarpPolarMode to flags to specify the polar mapping mode.

Linear is the default mode.

The semilog mapping emulates the human "foveal" vision that permit very high acuity on the line of sight (central vision) in contrast to peripheral vision where acuity is minor.

Option on dsize:
  • if both values in dsize <=0 (default), the destination image will have (almost) same area of source bounding circle:

    \[\begin{array}{l} dsize.area \leftarrow (maxRadius^2 \cdot \Pi) \\ dsize.width = \texttt{cvRound}(maxRadius) \\ dsize.height = \texttt{cvRound}(maxRadius \cdot \Pi) \\ \end{array}\]

  • if only dsize.height <= 0, the destination image area will be proportional to the bounding circle area but scaled by Kx * Kx:

    \[\begin{array}{l} dsize.height = \texttt{cvRound}(dsize.width \cdot \Pi) \\ \end{array} \]

  • if both values in dsize > 0, the destination image will have the given size therefore the area of the bounding circle will be scaled to dsize.
Reverse mapping

You can get reverse mapping adding WARP_INVERSE_MAP to flags

// direct transform
warpPolar(src, lin_polar_img, Size(),center, maxRadius, flags); // linear Polar
warpPolar(src, log_polar_img, Size(),center, maxRadius, flags + WARP_POLAR_LOG); // semilog Polar
// inverse transform
warpPolar(lin_polar_img, recovered_lin_polar_img, src.size(), center, maxRadius, flags + WARP_INVERSE_MAP);
warpPolar(log_polar_img, recovered_log_polar, src.size(), center, maxRadius, flags + WARP_POLAR_LOG + WARP_INVERSE_MAP);

In addiction, to calculate the original coordinate from a polar mapped coordinate \((rho, phi)->(x, y)\):

double angleRad, magnitude;
double Kangle = dst.rows / CV_2PI;
angleRad = phi / Kangle;
if (flags & WARP_POLAR_LOG)
{
double Klog = dst.cols / std::log(maxRadius);
magnitude = std::exp(rho / Klog);
}
else
{
double Klin = dst.cols / maxRadius;
magnitude = rho / Klin;
}
int x = cvRound(center.x + magnitude * cos(angleRad));
int y = cvRound(center.y + magnitude * sin(angleRad));
Parameters
srcSource image.
dstDestination image. It will have same type as src.
dsizeThe destination image size (see description for valid options).
centerThe transformation center.
maxRadiusThe radius of the bounding circle to transform. It determines the inverse magnitude scale parameter too.
flagsA combination of interpolation methods, InterpolationFlags + WarpPolarMode.
Note
  • The function can not operate in-place.
  • To calculate magnitude and angle in degrees cartToPolar is used internally thus angles are measured from 0 to 360 with accuracy about 0.3 degrees.
  • This function uses remap. Due to current implementation limitations the size of an input and output images should be less than 32767x32767.
See also
cv::remap
Examples:
samples/cpp/polar_transforms.cpp.