cv::fisheye Namespace Reference

The methods in this namespace use a so-called fisheye camera model. More...

Functions
double	calibrate (InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints, const Size &image_size, InputOutputArray K, InputOutputArray D, OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, int flags=0, TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 100, DBL_EPSILON))
	Performs camera calibration.
void	distortPoints (InputArray undistorted, OutputArray distorted, InputArray K, InputArray D, double alpha=0)
	Distorts 2D points using fisheye model.
void	distortPoints (InputArray undistorted, OutputArray distorted, InputArray Kundistorted, InputArray K, InputArray D, double alpha=0)
void	estimateNewCameraMatrixForUndistortRectify (InputArray K, InputArray D, const Size &image_size, InputArray R, OutputArray P, double balance=0.0, const Size &new_size=Size(), double fov_scale=1.0)
	Estimates new camera intrinsic matrix for undistortion or rectification.
void	initUndistortRectifyMap (InputArray K, InputArray D, InputArray R, InputArray P, const cv::Size &size, int m1type, OutputArray map1, OutputArray map2)
	Computes undistortion and rectification maps for image transform by cv::remap(). If D is empty zero distortion is used, if R or P is empty identity matrixes are used.
void	projectPoints (InputArray objectPoints, OutputArray imagePoints, const Affine3d &affine, InputArray K, InputArray D, double alpha=0, OutputArray jacobian=noArray())
	Projects points using fisheye model.
void	projectPoints (InputArray objectPoints, OutputArray imagePoints, InputArray rvec, InputArray tvec, InputArray K, InputArray D, double alpha=0, OutputArray jacobian=noArray())
bool	solvePnP (InputArray objectPoints, InputArray imagePoints, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess=false, int flags=SOLVEPNP_ITERATIVE, TermCriteria criteria=TermCriteria(TermCriteria::MAX_ITER+TermCriteria::EPS, 10, 1e-8))
	Finds an object pose from 3D-2D point correspondences for fisheye camera moodel.
double	stereoCalibrate (InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2, InputOutputArray K1, InputOutputArray D1, InputOutputArray K2, InputOutputArray D2, Size imageSize, OutputArray R, OutputArray T, int flags=CALIB_FIX_INTRINSIC, TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 100, DBL_EPSILON))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
double	stereoCalibrate (InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2, InputOutputArray K1, InputOutputArray D1, InputOutputArray K2, InputOutputArray D2, Size imageSize, OutputArray R, OutputArray T, OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, int flags=CALIB_FIX_INTRINSIC, TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 100, DBL_EPSILON))
	Performs stereo calibration.
void	stereoRectify (InputArray K1, InputArray D1, InputArray K2, InputArray D2, const Size &imageSize, InputArray R, InputArray tvec, OutputArray R1, OutputArray R2, OutputArray P1, OutputArray P2, OutputArray Q, int flags, const Size &newImageSize=Size(), double balance=0.0, double fov_scale=1.0)
	Stereo rectification for fisheye camera model.
void	undistortImage (InputArray distorted, OutputArray undistorted, InputArray K, InputArray D, InputArray Knew=cv::noArray(), const Size &new_size=Size())
	Transforms an image to compensate for fisheye lens distortion.
void	undistortPoints (InputArray distorted, OutputArray undistorted, InputArray K, InputArray D, InputArray R=noArray(), InputArray P=noArray(), TermCriteria criteria=TermCriteria(TermCriteria::MAX_ITER+TermCriteria::EPS, 10, 1e-8))
	Undistorts 2D points using fisheye model.

Detailed Description

The methods in this namespace use a so-called fisheye camera model.

Function Documentation

distortPoints() [1/2]

void cv::fisheye::distortPoints	(	InputArray	undistorted,
		OutputArray	distorted,
		InputArray	K,
		InputArray	D,
		double	alpha = 0
	)

Python:
	cv.fisheye.distortPoints(	undistorted, K, D[, distorted[, alpha]]	) ->	distorted
	cv.fisheye.distortPoints(	undistorted, Kundistorted, K, D[, distorted[, alpha]]	) ->	distorted

Distorts 2D points using fisheye model.

Parameters

undistorted	Array of object points, 1xN/Nx1 2-channel (or vector<Point2f> ), where N is the number of points in the view.
K	Camera intrinsic matrix \(cameramatrix{K}\).
D	Input vector of distortion coefficients \(\distcoeffsfisheye\).
alpha	The skew coefficient.
distorted	Output array of image points, 1xN/Nx1 2-channel, or vector<Point2f> .

Note that the function assumes the camera intrinsic matrix of the undistorted points to be identity. This means if you want to distort image points you have to multiply them with \(K^{-1}\) or use another function overload.

distortPoints() [2/2]

void cv::fisheye::distortPoints	(	InputArray	undistorted,
		OutputArray	distorted,
		InputArray	Kundistorted,
		InputArray	K,
		InputArray	D,
		double	alpha = 0
	)

Python:
	cv.fisheye.distortPoints(	undistorted, K, D[, distorted[, alpha]]	) ->	distorted
	cv.fisheye.distortPoints(	undistorted, Kundistorted, K, D[, distorted[, alpha]]	) ->	distorted

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Overload of distortPoints function to handle cases when undistorted points are got with non-identity camera matrix, e.g. output of estimateNewCameraMatrixForUndistortRectify.

Parameters

undistorted	Array of object points, 1xN/Nx1 2-channel (or vector<Point2f> ), where N is the number of points in the view.
Kundistorted	Camera intrinsic matrix used as new camera matrix for undistortion.
K	Camera intrinsic matrix \(cameramatrix{K}\).
D	Input vector of distortion coefficients \(\distcoeffsfisheye\).
alpha	The skew coefficient.
distorted	Output array of image points, 1xN/Nx1 2-channel, or vector<Point2f> .

See also

estimateNewCameraMatrixForUndistortRectify

estimateNewCameraMatrixForUndistortRectify()

void cv::fisheye::estimateNewCameraMatrixForUndistortRectify	(	InputArray	K,
		InputArray	D,
		const Size &	image_size,
		InputArray	R,
		OutputArray	P,
		double	balance = 0.0,
		const Size &	new_size = Size(),
		double	fov_scale = 1.0
	)

Python:
	cv.fisheye.estimateNewCameraMatrixForUndistortRectify(	K, D, image_size, R[, P[, balance[, new_size[, fov_scale]]]]	) ->	P

Estimates new camera intrinsic matrix for undistortion or rectification.

Parameters

K	Camera intrinsic matrix \(cameramatrix{K}\).
image_size	Size of the image
D	Input vector of distortion coefficients \(\distcoeffsfisheye\).
R	Rectification transformation in the object space: 3x3 1-channel, or vector: 3x1/1x3 1-channel or 1x1 3-channel
P	New camera intrinsic matrix (3x3) or new projection matrix (3x4)
balance	Sets the new focal length in range between the min focal length and the max focal length. Balance is in range of [0, 1].
new_size	the new size
fov_scale	Divisor for new focal length.

initUndistortRectifyMap()

void cv::fisheye::initUndistortRectifyMap	(	InputArray	K,
		InputArray	D,
		InputArray	R,
		InputArray	P,
		const cv::Size &	size,
		int	m1type,
		OutputArray	map1,
		OutputArray	map2
	)

Python:
	cv.fisheye.initUndistortRectifyMap(	K, D, R, P, size, m1type[, map1[, map2]]	) ->	map1, map2

Computes undistortion and rectification maps for image transform by cv::remap(). If D is empty zero distortion is used, if R or P is empty identity matrixes are used.

Parameters

K	Camera intrinsic matrix \(cameramatrix{K}\).
D	Input vector of distortion coefficients \(\distcoeffsfisheye\).
R	Rectification transformation in the object space: 3x3 1-channel, or vector: 3x1/1x3 1-channel or 1x1 3-channel
P	New camera intrinsic matrix (3x3) or new projection matrix (3x4)
size	Undistorted image size.
m1type	Type of the first output map that can be CV_32FC1 or CV_16SC2 . See convertMaps() for details.
map1	The first output map.
map2	The second output map.

projectPoints() [1/2]

void cv::fisheye::projectPoints	(	InputArray	objectPoints,
		OutputArray	imagePoints,
		const Affine3d &	affine,
		InputArray	K,
		InputArray	D,
		double	alpha = 0,
		OutputArray	jacobian = noArray()
	)

Python:
	cv.fisheye.projectPoints(	objectPoints, rvec, tvec, K, D[, imagePoints[, alpha[, jacobian]]]	) ->	imagePoints, jacobian

Projects points using fisheye model.

Parameters

objectPoints	Array of object points, 1xN/Nx1 3-channel (or vector<Point3f> ), where N is the number of points in the view.
imagePoints	Output array of image points, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel, or vector<Point2f>.
affine
K	Camera intrinsic matrix \(cameramatrix{K}\).
D	Input vector of distortion coefficients \(\distcoeffsfisheye\).
alpha	The skew coefficient.
jacobian	Optional output 2Nx15 jacobian matrix of derivatives of image points with respect to components of the focal lengths, coordinates of the principal point, distortion coefficients, rotation vector, translation vector, and the skew. In the old interface different components of the jacobian are returned via different output parameters.

The function computes projections of 3D points to the image plane given intrinsic and extrinsic camera parameters. Optionally, the function computes Jacobians - matrices of partial derivatives of image points coordinates (as functions of all the input parameters) with respect to the particular parameters, intrinsic and/or extrinsic.

projectPoints() [2/2]

void cv::fisheye::projectPoints	(	InputArray	objectPoints,
		OutputArray	imagePoints,
		InputArray	rvec,
		InputArray	tvec,
		InputArray	K,
		InputArray	D,
		double	alpha = 0,
		OutputArray	jacobian = noArray()
	)

Python:
	cv.fisheye.projectPoints(	objectPoints, rvec, tvec, K, D[, imagePoints[, alpha[, jacobian]]]	) ->	imagePoints, jacobian

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

solvePnP()

bool cv::fisheye::solvePnP	(	InputArray	objectPoints,
		InputArray	imagePoints,
		InputArray	cameraMatrix,
		InputArray	distCoeffs,
		OutputArray	rvec,
		OutputArray	tvec,
		bool	useExtrinsicGuess = false,
		int	flags = SOLVEPNP_ITERATIVE,
		TermCriteria	criteria = TermCriteria(TermCriteria::MAX_ITER+TermCriteria::EPS, 10, 1e-8)
	)

Python:
	cv.fisheye.solvePnP(	objectPoints, imagePoints, cameraMatrix, distCoeffs[, rvec[, tvec[, useExtrinsicGuess[, flags[, criteria]]]]]	) ->	retval, rvec, tvec

Finds an object pose from 3D-2D point correspondences for fisheye camera moodel.

Parameters

objectPoints	Array of object points in the object coordinate space, Nx3 1-channel or 1xN/Nx1 3-channel, where N is the number of points. vector<Point3d> can be also passed here.
imagePoints	Array of corresponding image points, Nx2 1-channel or 1xN/Nx1 2-channel, where N is the number of points. vector<Point2d> can be also passed here.
cameraMatrix	Input camera intrinsic matrix \(\cameramatrix{A}\) .
distCoeffs	Input vector of distortion coefficients (4x1/1x4).
rvec	Output rotation vector (see Rodrigues ) that, together with tvec, brings points from the model coordinate system to the camera coordinate system.
tvec	Output translation vector.
useExtrinsicGuess	Parameter used for SOLVEPNP_ITERATIVE. If true (1), the function uses the provided rvec and tvec values as initial approximations of the rotation and translation vectors, respectively, and further optimizes them.
flags	Method for solving a PnP problem: see calib3d_solvePnP_flags This function returns the rotation and the translation vectors that transform a 3D point expressed in the object coordinate frame to the camera coordinate frame, using different methods: P3P methods (SOLVEPNP_P3P, SOLVEPNP_AP3P): need 4 input points to return a unique solution. SOLVEPNP_IPPE Input points must be >= 4 and object points must be coplanar. SOLVEPNP_IPPE_SQUARE Special case suitable for marker pose estimation. Number of input points must be 4. Object points must be defined in the following order: point 0: [-squareLength / 2, squareLength / 2, 0] point 1: [ squareLength / 2, squareLength / 2, 0] point 2: [ squareLength / 2, -squareLength / 2, 0] point 3: [-squareLength / 2, -squareLength / 2, 0] for all the other flags, number of input points must be >= 4 and object points can be in any configuration.
criteria	Termination criteria for internal undistortPoints call. The function interally undistorts points with undistortPoints and call cv::solvePnP, thus the input are very similar. Check there and Perspective-n-Points is described in Perspective-n-Point (PnP) pose computation for more information.

undistortImage()

void cv::fisheye::undistortImage	(	InputArray	distorted,
		OutputArray	undistorted,
		InputArray	K,
		InputArray	D,
		InputArray	Knew = cv::noArray(),
		const Size &	new_size = Size()
	)

Python:
	cv.fisheye.undistortImage(	distorted, K, D[, undistorted[, Knew[, new_size]]]	) ->	undistorted

Transforms an image to compensate for fisheye lens distortion.

Parameters

distorted	image with fisheye lens distortion.
undistorted	Output image with compensated fisheye lens distortion.
K	Camera intrinsic matrix \(cameramatrix{K}\).
D	Input vector of distortion coefficients \(\distcoeffsfisheye\).
Knew	Camera intrinsic matrix of the distorted image. By default, it is the identity matrix but you may additionally scale and shift the result by using a different matrix.
new_size	the new size

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

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

See below the results of undistortImage.

• a) result of undistort of perspective camera model (all possible coefficients (k_1, k_2, k_3, k_4, k_5, k_6) of distortion were optimized under calibration)
  • b) result of fisheye::undistortImage of fisheye camera model (all possible coefficients (k_1, k_2, k_3, k_4) of fisheye distortion were optimized under calibration)
  • c) original image was captured with fisheye lens

Pictures a) and b) almost the same. But if we consider points of image located far from the center of image, we can notice that on image a) these points are distorted.

image

undistortPoints()

void cv::fisheye::undistortPoints	(	InputArray	distorted,
		OutputArray	undistorted,
		InputArray	K,
		InputArray	D,
		InputArray	R = noArray(),
		InputArray	P = noArray(),
		TermCriteria	criteria = TermCriteria(TermCriteria::MAX_ITER+TermCriteria::EPS, 10, 1e-8)
	)

Python:
	cv.fisheye.undistortPoints(	distorted, K, D[, undistorted[, R[, P[, criteria]]]]	) ->	undistorted

Undistorts 2D points using fisheye model.

Parameters

distorted	Array of object points, 1xN/Nx1 2-channel (or vector<Point2f> ), where N is the number of points in the view.
K	Camera intrinsic matrix \(cameramatrix{K}\).
D	Input vector of distortion coefficients \(\distcoeffsfisheye\).
R	Rectification transformation in the object space: 3x3 1-channel, or vector: 3x1/1x3 1-channel or 1x1 3-channel
P	New camera intrinsic matrix (3x3) or new projection matrix (3x4)
criteria	Termination criteria
undistorted	Output array of image points, 1xN/Nx1 2-channel, or vector<Point2f> .