This class implements functions necessary for computations with homographies. More...

Static Public Member Functions
static SquareMatrix3	homographyMatrix (const Quaternion &left_T_right, const AnyCamera &leftCamera, const AnyCamera &rightCamera)
	Calculates the homography between two images transforming the projected planar object points between the two images. More...

static SquareMatrix3	homographyMatrix (const Quaternion &left_T_right, const PinholeCamera &leftCamera, const PinholeCamera &rightCamera)
	Deprecated. More...

static SquareMatrix3	homographyMatrix (const Quaternion &world_R_left, const Quaternion &world_R_right, const PinholeCamera &leftCamera, const PinholeCamera &rightCamera)
	Calculates the homography between two images transforming the projected planar object points between the two images. More...

static SquareMatrix3	homographyMatrix (const HomogenousMatrix4 &world_T_rightCamera, const PinholeCamera &leftCamera, const PinholeCamera &rightCamera, const Plane3 &plane)
	Calculates the homography between two images transforming the projected planar object points between the two images. More...

static SquareMatrix3	homographyMatrix (const HomogenousMatrix4 &poseLeft, const HomogenousMatrix4 &poseRight, const PinholeCamera &leftCamera, const PinholeCamera &rightCamera, const Plane3 &plane)
	Calculates the homography between two images transforming the projected planar object points between the two images. More...

static SquareMatrix3	homographyMatrix (const PinholeCamera &pinholeCamera, const HomogenousMatrix4 &pose, const Vector3 &patternObjectPointTopLeft, const Vector3 &patternObjectPointBottomLeft, const Vector3 &patternObjectPointTopRight, const unsigned int patternWidth, const unsigned int patternHeight)
	Calculates the homography that transforms points defined in a (planar) pattern image to points defined in a camera frame in which the pattern is visible. More...

static bool	homographyMatrix (const Vector2 leftPoints, const Vector2 rightPoints, const size_t correspondences, SquareMatrix3 &right_H_left, const bool useSVD=true)
	Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images. More...

static bool	homographyMatrixSVD (const Vector2 leftPoints, const Vector2 rightPoints, const size_t correspondences, SquareMatrix3 &right_H_left)
	Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images. More...

static bool	homographyMatrixFromPointsAndLinesSVD (const Vector2 leftPoints, const Vector2 rightPoints, const size_t pointCorrespondences, const Line2 leftLines, const Line2 rightLines, const size_t lineCorrespondences, SquareMatrix3 &right_H_left)
	Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points and lines between the two images. More...

static bool	homographyMatrixLinear (const Vector2 leftPoints, const Vector2 rightPoints, const size_t correspondences, SquareMatrix3 &right_H_left, unsigned int optimizationIterations)
	Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images. More...

static bool	homographyMatrixLinearWithOptimizations (const Vector2 leftPoints, const Vector2 rightPoints, const size_t correspondences, SquareMatrix3 &right_H_left)
	Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images. More...

static bool	homographyMatrixLinearWithoutOptimations (const Vector2 leftPoints, const Vector2 rightPoints, const size_t correspondences, SquareMatrix3 &right_H_left)
	Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images. More...

static bool	affineMatrix (const ImagePoint leftPoints, const ImagePoint rightPoints, const size_t correspondences, SquareMatrix3 &right_A_left)
	Calculates the affine transformation (6DOF - translation, rotation, scale, aspect ratio, shear) between two sets of 2D image points. More...

static bool	similarityMatrix (const ImagePoint leftPoints, const ImagePoint rightPoints, const size_t correspondences, SquareMatrix3 &right_S_left)
	Calculates the similarity transformation (4DOF - translation, rotation, scale) between two images transforming the projected planar object points between the two images. More...

static bool	homotheticMatrix (const ImagePoint leftPoints, const ImagePoint rightPoints, const size_t correspondences, SquareMatrix3 &right_H_left)
	Calculates the homothetic transformation (3DOF - translation, scale) between two sets of image points. More...

static SquareMatrix3	factorizeHomographyMatrix (const SquareMatrix3 &homography, const PinholeCamera &leftCamera, const PinholeCamera &rightCamera)
	Factorizes a homography which contains only a rotational part into the corresponding rotation (of the right camera). More...

static bool	factorizeHomographyMatrix (const SquareMatrix3 &right_H_left, const PinholeCamera &leftCamera, const PinholeCamera &rightCamera, const ImagePoint leftImagePoints, const ImagePoint rightImagePoints, const size_t correspondences, HomogenousMatrix4 world_T_rightCameras[2], Vector3 normals[2])
	Factorizes a planar homography into translation and rotation of the camera. More...

static bool	factorizeHomographyMatrix (const SquareMatrix3 &right_H_left, const HomogenousMatrix4 &world_T_leftCamera, const PinholeCamera &leftCamera, const PinholeCamera &rightCamera, const ImagePoint leftImagePoints, const ImagePoint rightImagePoints, const size_t correspondences, HomogenousMatrix4 world_T_rightCameras[2], Vector3 normals[2])
	Factorizes a planar homography into translation and rotation of the camera. More...

static bool	homographyMatrixPlaneXY (const ObjectPoint objectPoints, const ImagePoint imagePoints, const size_t correspondences, SquareMatrix3 &homography)
	Calculates the homography for given 3D object points lying on the Z == 0 plane and corresponding 2D image points. More...

static bool	homographyMatrixPlaneXY (const ImagePoint objectPoints, const ImagePoint imagePoints, const size_t correspondences, SquareMatrix3 &homography)
	Calculates the homography for given 3D object points lying on the Z == 0 plane and 2D image points. More...

template<typename T >
static SquareMatrixT3< T >	normalizedHomography (const SquareMatrixT3< T > &homography)
	Normalizes a given homography forcing a 1 in the lower right matrix corner. More...

template<typename T >
static void	normalizeHomography (SquareMatrixT3< T > &homography)
	Normalizes a given homography forcing a 1 in the lower right matrix corner. More...

template<typename T >
static SquareMatrixT3< T >	scaleHomography (const SquareMatrixT3< T > &homography, const T &scaleLeft, const T &scaleRight)
	Scales a given homography so that it fits to an individually scaled input image and an individually scaled output image. More...

static bool	isHomographyPlausible (const unsigned int leftImageWidth, const unsigned int leftImageHeight, const unsigned int rightImageWidth, const unsigned int rightImageHeight, const SquareMatrix3 &homography)
	Returns whether a given homography represents a plausible transformation. More...

static bool	intrinsicMatrix (const SquareMatrix3 *homographies, const size_t number, SquareMatrix3 &intrinsic)
	Calculates the intrinsic camera matrix for a set of given homographies transforming 3D object points from the z=0 plane to the image plane. More...

static bool	extrinsicMatrix (const SquareMatrix3 &intrinsic, const SquareMatrix3 &homography, HomogenousMatrix4 &world_T_camera)
	Calculates the extrinsic camera matrix for a given intrinsic camera matrix and a corresponding homography transforming 3D object points from the z=0 plane to the image plane. More...

static bool	distortionParameters (const ConstIndexedAccessor< HomogenousMatrix4 > &extrinsics, const SquareMatrix3 &intrinsic, const ConstIndexedAccessor< Vectors3 > &objectPointGroups, const ConstIndexedAccessor< Vectors2 > &imagePointGroups, Scalar &distortion2, Scalar &distortion4)
	Calculates the first two radial distortion parameter. More...

static SquareMatrix3	toFinestHomography (const SquareMatrix3 &coarseHomography, const unsigned int sourceLayer)
	Converts a given homography determined for a coarser pyramid layer to a homography matching with the finest pyramid layer. More...

static SquareMatrix3	toCoarseHomography (const SquareMatrix3 &finestHomography, const unsigned int targetLayer)
	Converts a given homography determined for the finest pyramid layer to a homography matching with a coarser pyramid layer. More...

template<typename T >
static SquareMatrixT3< T >	homographyForLines (const SquareMatrixT3< T > &homographyForPoints)
	Returns the homography transforming lines from one image to another image based on a homography transforming points from one image to another image. More...

Detailed Description

This class implements functions necessary for computations with homographies.

Member Function Documentation

◆ affineMatrix()

static bool Ocean::Geometry::Homography::affineMatrix	(	const ImagePoint *	leftPoints,
		const ImagePoint *	rightPoints,
		const size_t	correspondences,
		SquareMatrix3 &	right_A_left
	)

static

Calculates the affine transformation (6DOF - translation, rotation, scale, aspect ratio, shear) between two sets of 2D image points.

Parameters

leftPoints	The image points in the left image, must be valid
rightPoints	The image points in the right image, one for each point in the left image, must be valid
correspondences	The number of points correspondences, with range [3, infinity)
right_A_left	The resulting affine transformation matrix transforming left to right image points

Returns: True, if succeeded

See also: homographyMatrix(), similarityMatrix().

◆ distortionParameters()

static bool Ocean::Geometry::Homography::distortionParameters	(	const ConstIndexedAccessor< HomogenousMatrix4 > &	extrinsics,
		const SquareMatrix3 &	intrinsic,
		const ConstIndexedAccessor< Vectors3 > &	objectPointGroups,
		const ConstIndexedAccessor< Vectors2 > &	imagePointGroups,
		Scalar &	distortion2,
		Scalar &	distortion4
	)

static

Calculates the first two radial distortion parameter.

The distortion parameters are determined for several different extrinsic camera positions.
The more point correspondences for individual extrinsic camera positions are provided the more accurate the result.

Parameters

extrinsics	Set of extrinsic camera parameters
intrinsic	The intrinsic camera matrix used for all point correspondences
objectPointGroups	The groups of object points, each group corresponds to a group of image points and to one extrinsic camera
imagePointGroups	The groups of image points, each group corresponds to a set of object points
distortion2	Resulting first radial distortion parameter for the square distance (r^2)
distortion4	Resulting second radial distortion parameter for the square of the square distance (r^4)

Returns: True, if succeeded

◆ extrinsicMatrix()

static bool Ocean::Geometry::Homography::extrinsicMatrix	(	const SquareMatrix3 &	intrinsic,
		const SquareMatrix3 &	homography,
		HomogenousMatrix4 &	world_T_camera
	)

static

Calculates the extrinsic camera matrix for a given intrinsic camera matrix and a corresponding homography transforming 3D object points from the z=0 plane to the image plane.

Parameters

intrinsic	The intrinsic camera matrix to return the extrinsic camera matrix for
homography	The homography corresponding to the intrinsic camera matrix
world_T_camera	The resulting extrinsic camera matrix (the camera pose), with default camera pointing towards the negative z-space with y-axis upwards

Returns: True, if succeeded

◆ factorizeHomographyMatrix() [1/3]

static SquareMatrix3 Ocean::Geometry::Homography::factorizeHomographyMatrix	(	const SquareMatrix3 &	homography,
		const PinholeCamera &	leftCamera,
		const PinholeCamera &	rightCamera
	)

static

Factorizes a homography which contains only a rotational part into the corresponding rotation (of the right camera).

The given homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).
Beware: Depending on the accuracy of the given homography (e.g., whether it might contain a tiny translational part) the resulting rotation matrix needs to be adjusted further.

Parameters

homography	the homography which will be factorized
leftCamera	Profile of the left camera object
rightCamera	Profile of the right camera object

Returns: The rotation matrix which transforms points defined in the right camera coordinate system into points defined in the left camera coordinate system

◆ factorizeHomographyMatrix() [2/3]

static bool Ocean::Geometry::Homography::factorizeHomographyMatrix	(	const SquareMatrix3 &	right_H_left,
		const HomogenousMatrix4 &	world_T_leftCamera,
		const PinholeCamera &	leftCamera,
		const PinholeCamera &	rightCamera,
		const ImagePoint *	leftImagePoints,
		const ImagePoint *	rightImagePoints,
		const size_t	correspondences,
		HomogenousMatrix4	world_T_rightCameras[2],
		Vector3	normals[2]
	)

static

Factorizes a planar homography into translation and rotation of the camera.

The resulting factorization provides the camera pose for the right camera.
Further, a plane normal is provided which is defined in relation to the left camera coordinate system.
Two individual camera poses and normals are provided as the factorization cannot be determined uniquely.

Parameters

right_H_left	The homography transforming left points to right points, must be valid
world_T_leftCamera	The camera pose of the left camera, with default camera pointing towards the negative z-space with y-axis upwards, must be valid
leftCamera	The camera profile defining the projection of the left camera, must be valid
rightCamera	The camera profile defining the projection of the right camera, must be valid
leftImagePoints	Image points in the left camera frame (projected 3D plane object points) that have been used to determine the homography
rightImagePoints	Image points in the right camera frame, each point corresponds to one point in the left camera frame
correspondences	The number of image point correspondences, with range [2, infinity)
world_T_rightCameras	Two resulting camera poses for the right cameras, with default camera pointing towards the negative z-space with y-axis upwards
normals	Two resulting plane normals (one for each transformation), the normals are defined in relation to the world coordinate system

Returns: True, if succeeded

◆ factorizeHomographyMatrix() [3/3]

static bool Ocean::Geometry::Homography::factorizeHomographyMatrix	(	const SquareMatrix3 &	right_H_left,
		const PinholeCamera &	leftCamera,
		const PinholeCamera &	rightCamera,
		const ImagePoint *	leftImagePoints,
		const ImagePoint *	rightImagePoints,
		const size_t	correspondences,
		HomogenousMatrix4	world_T_rightCameras[2],
		Vector3	normals[2]
	)

static

Factorizes a planar homography into translation and rotation of the camera.

The resulting factorization provides the camera pose for the right camera while the left camera has the identity camera pose.
Further, a plane normal is provided which is defined in relation to the left camera coordinate system.
Two individual camera poses and normals are provided as the factorization cannot be determined uniquely.

Parameters

right_H_left	The homography transforming left points to right points, must be valid
leftCamera	The camera profile defining the projection of the left camera, must be valid
rightCamera	The camera profile defining the projection of the right camera, must be valid
leftImagePoints	The image points in the left camera frame (projected 3D plane object points) that have been used to determine the homography
rightImagePoints	The image points in the right camera frame, each point corresponds to one point in the left camera frame
correspondences	The number of image point correspondences, with range [2, infinity)
world_T_rightCameras	Two resulting camera poses for the right cameras, with default camera pointing towards the negative z-space with y-axis upwards
normals	Two resulting plane normals (one for each transformation), the normals are defined in relation to the left camera coordinate system

Returns: True, if succeeded

◆ homographyForLines()

template<typename T >

SquareMatrixT3< T > Ocean::Geometry::Homography::homographyForLines ( const SquareMatrixT3< T > & homographyForPoints )

inlinestatic

Returns the homography transforming lines from one image to another image based on a homography transforming points from one image to another image.

This function is mainly returning:

(homographyForPoints^T)^-1

Parameters

homographyForPoints The homography transforming points from one image to another image, must be valid

Returns: The homography allowing to transform lines

Template Parameters

T	The data type of the matrix's scalar type, either 'float' or 'double'

◆ homographyMatrix() [1/7]

static SquareMatrix3 Ocean::Geometry::Homography::homographyMatrix	(	const HomogenousMatrix4 &	poseLeft,
		const HomogenousMatrix4 &	poseRight,
		const PinholeCamera &	leftCamera,
		const PinholeCamera &	rightCamera,
		const Plane3 &	plane
	)

static

Calculates the homography between two images transforming the projected planar object points between the two images.

The given plane must be defined in relation to the left camera coordinate system.
The resulting homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).

Parameters

poseLeft	The camera pose of the left camera in relation to a world coordinate system
poseRight	The camera pose of the right camera in relation to a world coordinate system
leftCamera	Left camera profile
rightCamera	Right camera profile
plane	The plane defined in the coordinate system of the left camera

Returns: Resulting homography

◆ homographyMatrix() [2/7]

static SquareMatrix3 Ocean::Geometry::Homography::homographyMatrix	(	const HomogenousMatrix4 &	world_T_rightCamera,
		const PinholeCamera &	leftCamera,
		const PinholeCamera &	rightCamera,
		const Plane3 &	plane
	)

static

Calculates the homography between two images transforming the projected planar object points between the two images.

The left camera is expected to be in the world origin (an identity camera pose).
Further, the given plane must be defined in relation to the world.

Parameters

world_T_rightCamera	The camera pose of the right camera, with default camera pointing towards the negative z-space with y-axis upwards, must be valid
leftCamera	The camera profile defining the projection of the left camera, must be valid
rightCamera	The camera profile defining the projection of the right camera, must be valid
plane	The plane defined in world, must be valid

Returns: The resulting homography transforming points in the left image to points in the right image (right_H_left)

◆ homographyMatrix() [3/7]

static SquareMatrix3 Ocean::Geometry::Homography::homographyMatrix	(	const PinholeCamera &	pinholeCamera,
		const HomogenousMatrix4 &	pose,
		const Vector3 &	patternObjectPointTopLeft,
		const Vector3 &	patternObjectPointBottomLeft,
		const Vector3 &	patternObjectPointTopRight,
		const unsigned int	patternWidth,
		const unsigned int	patternHeight
	)

static

Calculates the homography that transforms points defined in a (planar) pattern image to points defined in a camera frame in which the pattern is visible.

Thus, the resulting homography can be used to rectify a specific image content of a given live camera frame.
The resolution and aspect ratio of the resulting rectified frame (defined by 'patternWidth' and 'patternHeight') can be arbitrary.
The 3D coordinates of the corners of the planar pattern must be known (in relation to the given camera pose).
The given 6DOF pose is a standard extrinsic camera matrix with default transformation looking into the negative z-space with y-axis as up-vector.
The resulting homography transforms image points defined in the pattern image to image points defined in the camera frame (cameraPoint = H * patternPoint).
Beware: The resulting transformation does not cover the possible distortion of the camera profile.

Parameters

pinholeCamera	The profile of the pinhole camera defining the project, must be valid
pose	The pose of the camera frame in which the pattern is visible, defined in relation to the world coordinate system must be valid
patternObjectPointTopLeft	The 3D location of the upper left corner of the pattern, defined in the world coordinate system, must be located in front of the camera, must be different from all other corners
patternObjectPointBottomLeft	The 3D location of the bottom left corner of the pattern, defined in the world coordinate system, must be located in front of the camera, must be different from all other corners
patternObjectPointTopRight	The 3D location of the upper right corner of the pattern, defined in the world coordinate system, must be located in front of the camera, must be different from all other corners
patternWidth	The width of the pattern frame in pixel space (e.g., the width of a resulting frame that shows the rectified pattern), with range [1, infinity)
patternHeight	The height of the pattern frame in pixel space (e.g., the width of a resulting frame that shows the rectified pattern), with range [1, infinity)

Returns: The resulting homography transforming pattern points to camera points (cameraPoint = H * patternPoint)

See also: CV::Advanced::FrameRectification.

◆ homographyMatrix() [4/7]

static SquareMatrix3 Ocean::Geometry::Homography::homographyMatrix	(	const Quaternion &	left_T_right,
		const AnyCamera &	leftCamera,
		const AnyCamera &	rightCamera
	)

static

Calculates the homography between two images transforming the projected planar object points between the two images.

The left camera is expected to be not rotated (the camera has the default viewing direction).
The default camera viewing direction is defined along the negative z-axis and has the y-axis as up vector.
The resulting homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).

Parameters

left_T_right	The rotation between right camera and left camera, must be valid
leftCamera	The left camera profile, must be valid
rightCamera	The right camera profile, must be valid

Returns: Resulting homography between left and right points (right_H_left)

◆ homographyMatrix() [5/7]

static SquareMatrix3 Ocean::Geometry::Homography::homographyMatrix	(	const Quaternion &	left_T_right,
		const PinholeCamera &	leftCamera,
		const PinholeCamera &	rightCamera
	)

static

Deprecated.

Calculates the homography between two images transforming the projected planar object points between the two images. The left camera is expected to be not rotated (the camera has the default viewing direction).
The default camera viewing direction is defined along the negative z-axis and has the y-axis as up vector.
The resulting homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).

Parameters

left_T_right	The rotation between right camera and left camera, must be valid
leftCamera	The left camera profile, must be valid
rightCamera	The right camera profile, must be valid

Returns: Resulting homography between left and right points (right_H_left)

◆ homographyMatrix() [6/7]

static SquareMatrix3 Ocean::Geometry::Homography::homographyMatrix	(	const Quaternion &	world_R_left,
		const Quaternion &	world_R_right,
		const PinholeCamera &	leftCamera,
		const PinholeCamera &	rightCamera
	)

static

Calculates the homography between two images transforming the projected planar object points between the two images.

The default camera viewing direction is defined along the negative z-axis and has the y-axis as up vector.
The resulting homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).

Parameters

world_R_left	The rotation between left camera and world, must be valid
world_R_right	The rotation between right camera and world, must be valid
leftCamera	The left camera profile, must be valid
rightCamera	The right camera profile, must be valid

Returns: Resulting homography between left and right points (right_H_left)

◆ homographyMatrix() [7/7]

bool Ocean::Geometry::Homography::homographyMatrix	(	const Vector2 *	leftPoints,
		const Vector2 *	rightPoints,
		const size_t	correspondences,
		SquareMatrix3 &	right_H_left,
		const bool	useSVD = `true`
	)

inlinestatic

Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images.

This function either uses a SVD for the determination of a two-step approach which is several times faster.
The resulting homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).
As this function applies the image points in pixel space, the intrinsic camera matrices of both frames are not necessary.

Parameters

leftPoints	Image points in the left camera, each point corresponds to one point in the right image
rightPoints	Image points in the right camera
correspondences	Number of points correspondences, with range [4, infinity)
right_H_left	Resulting homography for the given point correspondences (rightPoint = right_H_left * leftPoint)
useSVD	True, to use the slower SVD approach (i.e., homographyMatrixSVD); False, to use the two-step approach (i.e., homographyMatrixLinearWithOptimizations)

Returns: True, if succeeded

See also: homographyMatrixSVD(), homographyMatrixLinear(), affineMatrix(), similarityMatrix().

◆ homographyMatrixFromPointsAndLinesSVD()

static bool Ocean::Geometry::Homography::homographyMatrixFromPointsAndLinesSVD	(	const Vector2 *	leftPoints,
		const Vector2 *	rightPoints,
		const size_t	pointCorrespondences,
		const Line2 *	leftLines,
		const Line2 *	rightLines,
		const size_t	lineCorrespondences,
		SquareMatrix3 &	right_H_left
	)

static

Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points and lines between the two images.

This function uses a singular value decomposition for the determination of the homography.
The resulting homography transforms image points defined in the left image to image points defined in the right image, and lines defined in the left image to lines defined in the right image, (rightPoint = H * leftPoint).

Parameters

leftPoints	Image points in the left camera, each point corresponds to one point in the right image
rightPoints	Image points in the right camera
pointCorrespondences	Number of provided point correspondences, with range [0, infinity), while pointCorrespondences + lineCorrespondences >= 4
leftLines	Lines in the left camera, each line corresponds to one line in the right image
rightLines	Lines in the right camera, each line
lineCorrespondences	Number of provided line correspondences, with range [0, infinity), while pointCorrespondences + lineCorrespondences >= 4
right_H_left	Resulting homography for the given point correspondences (rightPoint = right_H_left * leftPoint)

Returns: True, if succeeded

See also: homographyMatrixLinear(), affineMatrix(), similarityMatrix().

◆ homographyMatrixLinear()

static bool Ocean::Geometry::Homography::homographyMatrixLinear	(	const Vector2 *	leftPoints,
		const Vector2 *	rightPoints,
		const size_t	correspondences,
		SquareMatrix3 &	right_H_left,
		unsigned int	optimizationIterations
	)

static

Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images.

This function uses a linear equation to determine an initial homography followed by a non-linear optimization.
The initial homography is not as accurate as the homography determined by a SVD; however, the following optimization steps fix the accuracy while being several magnitudes faster.
The resulting homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).
As this function applies the image points in pixel space, the intrinsic camera matrices of both frames are not necessary.

Parameters

leftPoints	Image points in the left camera, each point corresponds to one point in the right image
rightPoints	Image points in the right camera
correspondences	Number of points correspondences, with range [4, infinity)
right_H_left	Resulting homography for the given point correspondences (rightPoint = right_H_left * leftPoint)
optimizationIterations	The number of non-linear-optimization iterations that will be executed after the initial homography has been determined, with range [0, infinity).

Returns: True, if succeeded

See also: homographyMatrixLinearWithOptimizations(), homographyMatrixLinearWithoutOptimations(), homographyMatrixSVD(), affineMatrix(), similarityMatrix().

◆ homographyMatrixLinearWithOptimizations()

bool Ocean::Geometry::Homography::homographyMatrixLinearWithOptimizations	(	const Vector2 *	leftPoints,
		const Vector2 *	rightPoints,
		const size_t	correspondences,
		SquareMatrix3 &	right_H_left
	)

inlinestatic

Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images.

This function uses a linear equation to determine an initial homography followed by a non-linear optimization.
The initial homography is not as accurate as the homography determined by a SVD; however, the following 10 optimization steps fix the accuracy while being several magnitudes faster (at least for a high number of correspondences).
The resulting homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).
As this function applies the image points in pixel space, the intrinsic camera matrices of both frames are not necessary.

Parameters

leftPoints	Image points in the left camera, each point corresponds to one point in the right image
rightPoints	Image points in the right camera
correspondences	Number of points correspondences, with range [4, infinity)
right_H_left	Resulting homography for the given point correspondences (rightPoint = right_H_left * leftPoint)

Returns: True, if succeeded

See also: homographyMatrixSVD(), homographyMatrixLinearWithoutOptimations(), affineMatrix(), similarityMatrix().

◆ homographyMatrixLinearWithoutOptimations()

static bool Ocean::Geometry::Homography::homographyMatrixLinearWithoutOptimations	(	const Vector2 *	leftPoints,
		const Vector2 *	rightPoints,
		const size_t	correspondences,
		SquareMatrix3 &	right_H_left
	)

static

Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images.

This function uses a linear equation to determine an initial homography followed by a non-linear optimization.
The resulting homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).
As this function applies the image points in pixel space, the intrinsic camera matrices of both frames are not necessary.

Parameters

leftPoints	Image points in the left camera, each point corresponds to one point in the right image
rightPoints	Image points in the right camera
correspondences	Number of points correspondences, with range [4, infinity)
right_H_left	Resulting homography for the given point correspondences (rightPoint = right_H_left * leftPoint)

Returns: True, if succeeded

See also: homographyMatrixSVD(), homographyMatrixLinearWithOptimizations(), affineMatrix(), similarityMatrix().

◆ homographyMatrixPlaneXY() [1/2]

static bool Ocean::Geometry::Homography::homographyMatrixPlaneXY	(	const ImagePoint *	objectPoints,
		const ImagePoint *	imagePoints,
		const size_t	correspondences,
		SquareMatrix3 &	homography
	)

static

Calculates the homography for given 3D object points lying on the Z == 0 plane and 2D image points.

Parameters

objectPoints	2D object points with z-axis value equal zero, must be valid
imagePoints	2D image points each corresponding the to an object point, must be valid
correspondences	Number of given correspondences, with range [10, infinity)
homography	The resulting homography

Returns: True, if succeeded

◆ homographyMatrixPlaneXY() [2/2]

static bool Ocean::Geometry::Homography::homographyMatrixPlaneXY	(	const ObjectPoint *	objectPoints,
		const ImagePoint *	imagePoints,
		const size_t	correspondences,
		SquareMatrix3 &	homography
	)

static

Calculates the homography for given 3D object points lying on the Z == 0 plane and corresponding 2D image points.

The resulting homography transforms the object points to the image points (imagePoint = H * objectPoint).
Or more precisely: (imagePointX, imagePointY, 1) = H * (objectPointX, objectPointY, 1)

Parameters

objectPoints	3D object points (with z-axis value equal zero), must be valid
imagePoints	2D image points each corresponding to an object point, must be valid
correspondences	The number of given point correspondences, with range [10, infinity)
homography	The resulting homography

Returns: True, if succeeded

◆ homographyMatrixSVD()

static bool Ocean::Geometry::Homography::homographyMatrixSVD	(	const Vector2 *	leftPoints,
		const Vector2 *	rightPoints,
		const size_t	correspondences,
		SquareMatrix3 &	right_H_left
	)

static

Calculates the homography (8DOF - translation, rotation, scale, aspect ratio, shear, perspective) between two images transforming the projected planar object points between the two images.

This function uses a singular value decomposition for the determination of the homography.
The resulting homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).
As this function applies the image points in pixel space, the intrinsic camera matrices of both frames are not necessary.

Parameters

leftPoints	Image points in the left camera, each point corresponds to one point in the right image
rightPoints	Image points in the right camera
correspondences	Number of provided point correspondences, with range [4, infinity)
right_H_left	Resulting homography for the given point correspondences (rightPoint = right_H_left * leftPoint)

Returns: True, if succeeded

See also: homographyMatrixLinear(), affineMatrix(), similarityMatrix().

◆ homotheticMatrix()

static bool Ocean::Geometry::Homography::homotheticMatrix	(	const ImagePoint *	leftPoints,
		const ImagePoint *	rightPoints,
		const size_t	correspondences,
		SquareMatrix3 &	right_H_left
	)

static

Calculates the homothetic transformation (3DOF - translation, scale) between two sets of image points.

The resulting homothetic matrix transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).
The resulting 3x3 matrix has the following layout:

| s  0  tx |
| 0  s  ty |
| 0  0  1 |

With 's' defining scale and 'tx' and 'ty' defining the translation.

Parameters

leftPoints	Image points in the left image, each point corresponds to one point in the right image
rightPoints	Image points in the right image, each point corresponds to one point in the left image
correspondences	Number of points correspondences, with range [2, infinity)
right_H_left	Resulting homothetic transformation matrix for the given image points (rightPoint = H * leftPoint)

Returns: True, if succeeded

See also: homographyMatrix(), affineMatrix(), similarityMatrix().

◆ intrinsicMatrix()

static bool Ocean::Geometry::Homography::intrinsicMatrix	(	const SquareMatrix3 *	homographies,
		const size_t	number,
		SquareMatrix3 &	intrinsic
	)

static

Calculates the intrinsic camera matrix for a set of given homographies transforming 3D object points from the z=0 plane to the image plane.

Parameters

homographies	Set of given homographies
number	The number of given homographies with range [3, infinity)
intrinsic	Resulting intrinsic camera matrix

Returns: True, if succeeded

◆ isHomographyPlausible()

static bool Ocean::Geometry::Homography::isHomographyPlausible	(	const unsigned int	leftImageWidth,
		const unsigned int	leftImageHeight,
		const unsigned int	rightImageWidth,
		const unsigned int	rightImageHeight,
		const SquareMatrix3 &	homography
	)

static

Returns whether a given homography represents a plausible transformation.

A homography is voted as plausible as long as the transformed frame corners form a convex shape.
The forward transformation as well as the backward transformation (the inverse) is tested.
The homography transforms image points defined in the left image to image points defined in the right image (rightPoint = H * leftPoint).

Parameters

leftImageWidth	The width of the left image in pixel, with range [1, infinity)
leftImageHeight	The height of the left image in pixel, with range [1, infinity)
rightImageWidth	The width of the left image in pixel, with range [1, infinity)
rightImageHeight	The height of the left image in pixel, with range [1, infinity)
homography	The homography transforming points defined in the left image to points defined in the right image, must be valid

Returns: True, if the homography is plausible

◆ normalizedHomography()

template<typename T >

SquareMatrixT3< T > Ocean::Geometry::Homography::normalizedHomography ( const SquareMatrixT3< T > & homography )

inlinestatic

Normalizes a given homography forcing a 1 in the lower right matrix corner.

Parameters

homography The homography to normalize, must be valid

Returns: Normalized homography

Template Parameters

T	The data type of the scalar to be used, either 'float' or 'double'

◆ normalizeHomography()

template<typename T >

void Ocean::Geometry::Homography::normalizeHomography ( SquareMatrixT3< T > & homography )

inlinestatic

Normalizes a given homography forcing a 1 in the lower right matrix corner.

Parameters

homography The homography to be normalized, must be valid

Template Parameters

T	The data type of the scalar to be used, either 'float' or 'double'

◆ scaleHomography()

template<typename T >

SquareMatrixT3< T > Ocean::Geometry::Homography::scaleHomography	(	const SquareMatrixT3< T > &	homography,
		const T &	scaleLeft,
		const T &	scaleRight
	)

inlinestatic

Scales a given homography so that it fits to an individually scaled input image and an individually scaled output image.

Parameters

homography	The homography converting points defined in the left image to points defined in the right image (rightPoint = H * leftPoint)
scaleLeft	The scale which will be applied to the left image, e.g., a scale of 2 means that the image is twice as large, with range (0, infinity)
scaleRight	The scale which will be applied to the right image, e.g., a scale of 2 means that the image is twice as large, with range (0, infinity)

Template Parameters

T	the element type of the homography matrix, e.g., 'float' or 'double'

◆ similarityMatrix()

static bool Ocean::Geometry::Homography::similarityMatrix	(	const ImagePoint *	leftPoints,
		const ImagePoint *	rightPoints,
		const size_t	correspondences,
		SquareMatrix3 &	right_S_left
	)

static

Calculates the similarity transformation (4DOF - translation, rotation, scale) between two images transforming the projected planar object points between the two images.

The resulting similarity matrix transforms image points defined in the left image to image points defined in the right image (rightPoint = S * leftPoint).
The resulting 3x3 matrix has the following layout:

| a  -b  tx |
| b   a  ty |
| 0   0   1 |

With 'a' and 'b' defining scale and rotation and 'tx' and 'ty' defining the translation. As this function applies the image points in pixel space, the intrinsic camera matrices of both frames are not necessary.

Parameters

leftPoints	Image points in the left camera, each point corresponds to one point in the right image
rightPoints	Image points in the right camera
correspondences	Number of points correspondences, with range [2, infinity)
right_S_left	The resulting similarity transformation matrix transforming left points to right points

Returns: True, if succeeded

See also: homographyMatrix(), affineMatrix(), homotheticMatrix().

◆ toCoarseHomography()

static SquareMatrix3 Ocean::Geometry::Homography::toCoarseHomography	(	const SquareMatrix3 &	finestHomography,
		const unsigned int	targetLayer
	)

static

Converts a given homography determined for the finest pyramid layer to a homography matching with a coarser pyramid layer.

The new homography is determined via:

coarseHomography = downsample * finestHomography * upsample

Parameters

finestHomography	The homography determined for the finest pyramid layer, must be valid
targetLayer	The index of the coarser pyramid layer, with range [0, infinity)

Returns: The homography matching with the coarser pyramid layer, 'homography' if 'targetLayer == 0'

◆ toFinestHomography()

static SquareMatrix3 Ocean::Geometry::Homography::toFinestHomography	(	const SquareMatrix3 &	coarseHomography,
		const unsigned int	sourceLayer
	)

static

Converts a given homography determined for a coarser pyramid layer to a homography matching with the finest pyramid layer.

The new homography is determined via:

finestHomography = upsample * coarseHomography * downsample

Parameters

coarseHomography	The homography determined for the coarser pyramid layer, must be valid
sourceLayer	The index of the coarser pyramid layer, with range [0, infinity)

Returns: The homography matching with the finest pyramid layer, 'homography' if 'sourceLayer == 0'

The documentation for this class was generated from the following file:

Homography.h

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ affineMatrix()

◆ distortionParameters()

◆ extrinsicMatrix()

◆ factorizeHomographyMatrix() [1/3]

◆ factorizeHomographyMatrix() [2/3]

◆ factorizeHomographyMatrix() [3/3]

◆ homographyForLines()

◆ homographyMatrix() [1/7]

◆ homographyMatrix() [2/7]

◆ homographyMatrix() [3/7]

◆ homographyMatrix() [4/7]

◆ homographyMatrix() [5/7]

◆ homographyMatrix() [6/7]

◆ homographyMatrix() [7/7]

◆ homographyMatrixFromPointsAndLinesSVD()

◆ homographyMatrixLinear()

◆ homographyMatrixLinearWithOptimizations()

◆ homographyMatrixLinearWithoutOptimations()

◆ homographyMatrixPlaneXY() [1/2]

◆ homographyMatrixPlaneXY() [2/2]

◆ homographyMatrixSVD()

◆ homotheticMatrix()

◆ intrinsicMatrix()

◆ isHomographyPlausible()

◆ normalizedHomography()

◆ normalizeHomography()

◆ scaleHomography()

◆ similarityMatrix()

◆ toCoarseHomography()

◆ toFinestHomography()