OpenCV AR utilities. More...

Classes
struct	PoseData

Static Public Member Functions
static Matrix4x4	CalculateCameraMatrixValuesFromProjectionMatrix (Matrix4x4 projectionMatrix, float width, float height)
	Calculates OpenCV-style intrinsic camera parameters (camera matrix values) from a Unity-compatible projection matrix.

static float	CalculateDistance (float frustumSize, float fov)
	Calculate distance. https://docs.unity3d.com/Manual/FrustumSizeAtDistance.html.

static float	CalculateFOVAngle (float frustumSize, float distance)
	Calculate FOV angle. https://docs.unity3d.com/Manual/FrustumSizeAtDistance.html.

static float	CalculateFrustumSize (float distance, float fov)
	Calculate frustum size. https://docs.unity3d.com/Manual/FrustumSizeAtDistance.html.

static Matrix4x4	CalculateProjectionMatrixFromCameraMatrixValues (float fx, float fy, float cx, float cy, float width, float height, float near=0.01f, float far=2000f)
	Calculates a projection matrix from OpenCV-style camera intrinsic parameters, suitable for use as Camera.projectionMatrix in Unity.

static void	ComposeMatrix (Vector3 localPosition, Quaternion localRotation, Vector3 localScale, out Matrix4x4 matrix)
	Compose TRS matrix from position, rotation and scale.

static PoseData	ConvertMatrixToPoseData (ref Matrix4x4 matrix)
	Converts transform matrix to PoseData.

static Matrix4x4	ConvertPoseDataToMatrix (ref PoseData poseData, bool toLeftHandCoordinateSystem=false)
	Converts PoseData to transform matrix.

static Quaternion	ConvertRvecToRot (double[] rvec)
	Converts rvec value to rotation transform.

static Quaternion	ConvertRvecToRot (Mat rvec)
	Converts rvec value to rotation transform.

static PoseData	ConvertRvecTvecToPoseData (double[] rvec, double[] tvec)
	Converts rvec and tvec value to PoseData.

static PoseData	ConvertRvecTvecToPoseData (Mat rvec, Mat tvec)
	Converts rvec and tvec value to PoseData.

static Vector3	ConvertTvecToPos (double[] tvec)
	Converts tvec value to position transform.

static Vector3	ConvertTvecToPos (Mat tvec)
	Converts tvec value to position transform.

static Dictionary< int, PoseData >	CreatePoseDataDict (int[] ids, double[] rvecs, double[] tvecs)
	Creates pose data dictionary.

static void	DecomposeMatrix (ref Matrix4x4 matrix, out Vector3 localPosition, out Quaternion localRotation, out Vector3 localScale)
	Extract position, rotation and scale from TRS matrix.

static Quaternion	ExtractRotationFromMatrix (ref Matrix4x4 matrix)
	Extract rotation quaternion from transform matrix.

static Vector3	ExtractScaleFromMatrix (ref Matrix4x4 matrix)
	Extract scale from transform matrix.

static Vector3	ExtractTranslationFromMatrix (ref Matrix4x4 matrix)
	Extract translation from transform matrix.

static void	LowpassPoseData (ref PoseData oldPose, ref PoseData newPose, float posThreshold, float rotThreshold)
	Performs a lowpass check on the position and rotation in newPose, comparing them to oldPose.

static void	LowpassPoseDataDict (Dictionary< int, PoseData > oldDict, Dictionary< int, PoseData > newDict, float posThreshold, float rotThreshold)
	Performs a lowpass check on the position and rotation of each marker in newDict, comparing them to those in oldDict.

static void	SafeDrawFrameAxes (Mat image, Mat cameraMatrix, Mat distCoeffs, Mat rvec, Mat tvec, float length, int thickness=3)
	Safe version of drawFrameAxes that prevents hang or crashes when tvec has zero or near-zero Z component. Draw axes of the world/object coordinate system from pose estimation.

static void	SetTransformFromMatrix (Transform transform, ref Matrix4x4 matrix)
	Set transform component from TRS matrix.

static void	SmoothingFilterPoseData (ref PoseData oldPose, ref PoseData newPose, float positionSmoothingFactor, float rotationSmoothingFactor)
	Performs smoothing filter on the position and rotation in newPose using exponential moving average.

static void	SmoothingFilterPoseDataDict (Dictionary< int, PoseData > oldDict, Dictionary< int, PoseData > newDict, float positionSmoothingFactor, float rotationSmoothingFactor)
	Performs smoothing filter on the position and rotation of each marker in newDict using exponential moving average.

Detailed Description

OpenCV AR utilities.

Member Function Documentation

◆ CalculateCameraMatrixValuesFromProjectionMatrix()

static Matrix4x4 OpenCVForUnity.UnityIntegration.OpenCVARUtils.CalculateCameraMatrixValuesFromProjectionMatrix	(	Matrix4x4	projectionMatrix,
		float	width,
		float	height )

static

Calculates OpenCV-style intrinsic camera parameters (camera matrix values) from a Unity-compatible projection matrix.

Converts from Unity's left-handed camera coordinate system (Z-forward, Y-up) (used by Camera.projectionMatrix) to OpenCV's right-handed camera coordinate system (Z-forward, Y-down).

This effectively reverses the operation performed by CalculateProjectionMatrixFromCameraMatrixValues.

Parameters

projectionMatrix	A Unity camera projection matrix.
width	Image width in pixels.
height	Image height in pixels.

Returns: A 3×3-style camera matrix where:
fx = m00, fy = m11, cx = m02, cy = m12

◆ CalculateDistance()

static float OpenCVForUnity.UnityIntegration.OpenCVARUtils.CalculateDistance	(	float	frustumSize,
		float	fov )

static

Calculate distance. https://docs.unity3d.com/Manual/FrustumSizeAtDistance.html.

Parameters

frustumHeight	One side size of a frustum.
fov	Field of view. (horizontal or vertical direction)

Returns: Distance.

◆ CalculateFOVAngle()

static float OpenCVForUnity.UnityIntegration.OpenCVARUtils.CalculateFOVAngle	(	float	frustumSize,
		float	distance )

static

Calculate FOV angle. https://docs.unity3d.com/Manual/FrustumSizeAtDistance.html.

Parameters

frustumHeight	One side size of a frustum.
distance	Distance.

Returns: FOV angle.

◆ CalculateFrustumSize()

static float OpenCVForUnity.UnityIntegration.OpenCVARUtils.CalculateFrustumSize	(	float	distance,
		float	fov )

static

Calculate frustum size. https://docs.unity3d.com/Manual/FrustumSizeAtDistance.html.

Parameters

distance	Distance.
fov	Field of view. (horizontal or vertical direction)

Returns: Frustum height.

◆ CalculateProjectionMatrixFromCameraMatrixValues()

static Matrix4x4 OpenCVForUnity.UnityIntegration.OpenCVARUtils.CalculateProjectionMatrixFromCameraMatrixValues	(	float	fx,
		float	fy,
		float	cx,
		float	cy,
		float	width,
		float	height,
		float	near = 0::01f,
		float	far = 2000f )

static

Calculates a projection matrix from OpenCV-style camera intrinsic parameters, suitable for use as Camera.projectionMatrix in Unity.

Converts from the right-handed OpenCV camera coordinate system (Z-forward, Y-down) to Unity's left-handed camera coordinate system (Z-forward, Y-up).

The resulting matrix can be directly assigned to Camera.projectionMatrix, regardless of the rendering backend (OpenGL ES, Vulkan, or DirectX).

This effectively reverses the operation performed by CalculateCameraMatrixValuesFromProjectionMatrix.

Parameters

fx	Focal length in pixels along the X axis.
fy	Focal length in pixels along the Y axis.
cx	Principal point (image center) X coordinate in pixels.
cy	Principal point (image center) Y coordinate in pixels.
width	Image width in pixels.
height	Image height in pixels.
near	Near clipping plane distance.
far	Far clipping plane distance.

Returns: A 4×4 projection matrix compatible with Unity’s Camera component.

◆ ComposeMatrix()

static void OpenCVForUnity.UnityIntegration.OpenCVARUtils.ComposeMatrix	(	Vector3	localPosition,
		Quaternion	localRotation,
		Vector3	localScale,
		out Matrix4x4	matrix )

static

Compose TRS matrix from position, rotation and scale.

Parameters

localPosition	Position.
localRotation	Rotation.
localScale	Scale.
matrix	Transform matrix.

◆ ConvertMatrixToPoseData()

static PoseData OpenCVForUnity.UnityIntegration.OpenCVARUtils.ConvertMatrixToPoseData ( ref Matrix4x4 matrix )

static

Converts transform matrix to PoseData.

Parameters

matrix Transform matrix.

Returns: PoseData.

◆ ConvertPoseDataToMatrix()

static Matrix4x4 OpenCVForUnity.UnityIntegration.OpenCVARUtils.ConvertPoseDataToMatrix	(	ref PoseData	poseData,
		bool	toLeftHandCoordinateSystem = false )

static

Converts PoseData to transform matrix.

Parameters

poseData	PoseData.
toLeftHandCoordinateSystem	When true, converts the transformation matrix from OpenCV's right-handed coordinate system to Unity's left-handed coordinate system by inverting the Y-axis. This option must be enabled (set to true) when applying a pose calculated by OpenCV to a Unity object. When false (default), returns the matrix without coordinate system conversion.

Returns: Transform matrix.

◆ ConvertRvecToRot() [1/2]

static Quaternion OpenCVForUnity.UnityIntegration.OpenCVARUtils.ConvertRvecToRot ( double[] rvec )

static

Converts rvec value to rotation transform.

Parameters

tvec Rvec.

Returns: Rotation.

◆ ConvertRvecToRot() [2/2]

static Quaternion OpenCVForUnity.UnityIntegration.OpenCVARUtils.ConvertRvecToRot ( Mat rvec )

static

Converts rvec value to rotation transform.

Parameters

tvec Rvec.

Returns: Rotation.

◆ ConvertRvecTvecToPoseData() [1/2]

static PoseData OpenCVForUnity.UnityIntegration.OpenCVARUtils.ConvertRvecTvecToPoseData	(	double[]	rvec,
		double[]	tvec )

static

Converts rvec and tvec value to PoseData.

Parameters

tvec	Rvec.
tvec	Tvec.

Returns: PoseData.

◆ ConvertRvecTvecToPoseData() [2/2]

static PoseData OpenCVForUnity.UnityIntegration.OpenCVARUtils.ConvertRvecTvecToPoseData	(	Mat	rvec,
		Mat	tvec )

static

Converts rvec and tvec value to PoseData.

Parameters

tvec	Rvec.
tvec	Tvec.

Returns: PoseData.

◆ ConvertTvecToPos() [1/2]

static Vector3 OpenCVForUnity.UnityIntegration.OpenCVARUtils.ConvertTvecToPos ( double[] tvec )

static

Converts tvec value to position transform.

Parameters

tvec Tvec.

Returns: Position.

◆ ConvertTvecToPos() [2/2]

static Vector3 OpenCVForUnity.UnityIntegration.OpenCVARUtils.ConvertTvecToPos ( Mat tvec )

static

Converts tvec value to position transform.

Parameters

tvec Tvec.

Returns: Position.

◆ CreatePoseDataDict()

static Dictionary< int, PoseData > OpenCVForUnity.UnityIntegration.OpenCVARUtils.CreatePoseDataDict	(	int[]	ids,
		double[]	rvecs,
		double[]	tvecs )

static

Creates pose data dictionary.

Parameters

ids	ids.
rvecs	Rvecs.
tvecs	Tvecs.

Returns: PoseData dictionary.

◆ DecomposeMatrix()

static void OpenCVForUnity.UnityIntegration.OpenCVARUtils.DecomposeMatrix	(	ref Matrix4x4	matrix,
		out Vector3	localPosition,
		out Quaternion	localRotation,
		out Vector3	localScale )

static

Extract position, rotation and scale from TRS matrix.

Parameters

matrix	Transform matrix. This parameter is passed by reference to improve performance; no changes will be made to it.
localPosition	Position.
localRotation	Rotation.
localScale	Scale.

◆ ExtractRotationFromMatrix()

static Quaternion OpenCVForUnity.UnityIntegration.OpenCVARUtils.ExtractRotationFromMatrix ( ref Matrix4x4 matrix )

static

Extract rotation quaternion from transform matrix.

Parameters

matrix Transform matrix. This parameter is passed by reference to improve performance; no changes will be made to it.

Returns: Quaternion representation of rotation transform.

◆ ExtractScaleFromMatrix()

static Vector3 OpenCVForUnity.UnityIntegration.OpenCVARUtils.ExtractScaleFromMatrix ( ref Matrix4x4 matrix )

static

Extract scale from transform matrix.

Parameters

matrix Transform matrix. This parameter is passed by reference to improve performance; no changes will be made to it.

Returns: Scale vector.

◆ ExtractTranslationFromMatrix()

static Vector3 OpenCVForUnity.UnityIntegration.OpenCVARUtils.ExtractTranslationFromMatrix ( ref Matrix4x4 matrix )

static

Extract translation from transform matrix.

Parameters

matrix Transform matrix. This parameter is passed by reference to improve performance; no changes will be made to it.

Returns: Translation offset.

◆ LowpassPoseData()

static void OpenCVForUnity.UnityIntegration.OpenCVARUtils.LowpassPoseData	(	ref PoseData	oldPose,
		ref PoseData	newPose,
		float	posThreshold,
		float	rotThreshold )

static

Performs a lowpass check on the position and rotation in newPose, comparing them to oldPose.

Parameters

oldPose	Old PoseData.
newPose	New PoseData.
posThreshold	Position threshold.
rotThreshold	Rotation threshold.

◆ LowpassPoseDataDict()

static void OpenCVForUnity.UnityIntegration.OpenCVARUtils.LowpassPoseDataDict	(	Dictionary< int, PoseData >	oldDict,
		Dictionary< int, PoseData >	newDict,
		float	posThreshold,
		float	rotThreshold )

static

Performs a lowpass check on the position and rotation of each marker in newDict, comparing them to those in oldDict.

Parameters

oldDict	Old dictionary.
newDict	New dictionary.
posThreshold	Position threshold.
rotThreshold	Rotation threshold.

◆ SafeDrawFrameAxes()

static void OpenCVForUnity.UnityIntegration.OpenCVARUtils.SafeDrawFrameAxes	(	Mat	image,
		Mat	cameraMatrix,
		Mat	distCoeffs,
		Mat	rvec,
		Mat	tvec,
		float	length,
		int	thickness = 3 )

static

Safe version of drawFrameAxes that prevents hang or crashes when tvec has zero or near-zero Z component. Draw axes of the world/object coordinate system from pose estimation.

See also: solvePnP

Parameters

image	Input/output image. It must have 1 or 3 channels. The number of channels is not altered.
cameraMatrix	Input 3x3 floating-point matrix of camera intrinsic parameters. \(\cameramatrix{A}\)
distCoeffs	Input vector of distortion coefficients \(\distcoeffs\). If the vector is empty, the zero distortion coefficients are assumed.
rvec	Rotation vector (see Rodrigues ) that, together with tvec, brings points from the model coordinate system to the camera coordinate system.
tvec	Translation vector.
length	Length of the painted axes in the same unit than tvec (usually in meters).
thickness	Line thickness of the painted axes.

OX is drawn in red, OY in green and OZ in blue. It includes safety checks to prevent crashes when tvec has invalid Z values.

◆ SetTransformFromMatrix()

static void OpenCVForUnity.UnityIntegration.OpenCVARUtils.SetTransformFromMatrix	(	Transform	transform,
		ref Matrix4x4	matrix )

static

Set transform component from TRS matrix.

Parameters

transform	Transform component.
matrix	Transform matrix. This parameter is passed by reference to improve performance; no changes will be made to it.

◆ SmoothingFilterPoseData()

static void OpenCVForUnity.UnityIntegration.OpenCVARUtils.SmoothingFilterPoseData	(	ref PoseData	oldPose,
		ref PoseData	newPose,
		float	positionSmoothingFactor,
		float	rotationSmoothingFactor )

static

Performs smoothing filter on the position and rotation in newPose using exponential moving average.

Parameters

oldPose	Old PoseData.
newPose	New PoseData.
positionSmoothingFactor	Position smoothing factor (0.0 = no filtering, 1.0 = maximum filtering).
rotationSmoothingFactor	Rotation smoothing factor (0.0 = no filtering, 1.0 = maximum filtering).

◆ SmoothingFilterPoseDataDict()

static void OpenCVForUnity.UnityIntegration.OpenCVARUtils.SmoothingFilterPoseDataDict	(	Dictionary< int, PoseData >	oldDict,
		Dictionary< int, PoseData >	newDict,
		float	positionSmoothingFactor,
		float	rotationSmoothingFactor )

static

Performs smoothing filter on the position and rotation of each marker in newDict using exponential moving average.

Parameters

oldDict	Old dictionary.
newDict	New dictionary.
positionSmoothingFactor	Position smoothing factor (0.0 = no filtering, 1.0 = maximum filtering).
rotationSmoothingFactor	Rotation smoothing factor (0.0 = no filtering, 1.0 = maximum filtering).

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

OpenCVForUnity/Assets/OpenCVForUnity/org/opencv/unity/OpenCVARUtils.cs

Classes

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ CalculateCameraMatrixValuesFromProjectionMatrix()

◆ CalculateDistance()

◆ CalculateFOVAngle()

◆ CalculateFrustumSize()

◆ CalculateProjectionMatrixFromCameraMatrixValues()

◆ ComposeMatrix()

◆ ConvertMatrixToPoseData()

◆ ConvertPoseDataToMatrix()

◆ ConvertRvecToRot() [1/2]

◆ ConvertRvecToRot() [2/2]

◆ ConvertRvecTvecToPoseData() [1/2]

◆ ConvertRvecTvecToPoseData() [2/2]

◆ ConvertTvecToPos() [1/2]

◆ ConvertTvecToPos() [2/2]

◆ CreatePoseDataDict()

◆ DecomposeMatrix()

◆ ExtractRotationFromMatrix()

◆ ExtractScaleFromMatrix()

◆ ExtractTranslationFromMatrix()

◆ LowpassPoseData()

◆ LowpassPoseDataDict()

◆ SafeDrawFrameAxes()

◆ SetTransformFromMatrix()

◆ SmoothingFilterPoseData()

◆ SmoothingFilterPoseDataDict()