Detailed Description

Calibrated camera model abstraction and functionality.

Typedefs
typedef struct dwCameraModelObject *	dwCameraModelHandle_t
	A pointer to the handle representing a calibrated camera model. More...

typedef struct dwCameraModelObject const *	dwConstCameraModelHandle_t
	A pointer to the handle representing a const calibrated camera. More...

Functions
DW_API_PUBLIC dwStatus	dwCameraModel_applyImageTransform (const dwMatrix3f *transform, dwVector2ui newSize, dwCameraModelHandle_t obj)
	Sets a new origin for the image and adjusts image scales. More...

DW_API_PUBLIC dwStatus	dwCameraModel_getHorizontalFOV (float32_t *hfov, dwConstCameraModelHandle_t obj)
	Gets the horizontal Field of View (FOV) of the calibrated camera, in radians. More...

DW_API_PUBLIC dwStatus	dwCameraModel_getImageSize (uint32_t width, uint32_t height, dwConstCameraModelHandle_t obj)
	Gets the width and height of the calibrated camera, in pixels. More...

DW_API_PUBLIC dwStatus	dwCameraModel_getInversePolynomial (float32_t invPoly, size_t size, dwCameraModelHandle_t obj)
	Returns the inverse polynomial used for the inverse distortion model. More...

DW_API_PUBLIC dwStatus	dwCameraModel_initialize (dwCameraModelHandle_t *camera, uint32_t sensorId, dwConstRigHandle_t obj)
	Creates a calibrated camera model polymorphically for a compatible sensor. More...

DW_API_PUBLIC dwStatus	dwCameraModel_initializeFTheta (dwCameraModelHandle_t obj, const dwFThetaCameraConfig config, dwContextHandle_t context)
	Creates and initializes a calibrated camera for the F-Theta distortion model. More...

DW_API_PUBLIC dwStatus	dwCameraModel_initializeFThetaNew (dwCameraModelHandle_t obj, const dwFThetaCameraConfig config, dwContextHandle_t context)
	Creates and initializes a calibrated camera for the F-Theta distortion model. More...

DW_API_PUBLIC dwStatus	dwCameraModel_initializePinhole (dwCameraModelHandle_t obj, const dwPinholeCameraConfig config, dwContextHandle_t context)
	Creates and initializes a calibrated pinhole camera. More...

DW_API_PUBLIC dwStatus	dwCameraModel_initializeStereographic (dwCameraModelHandle_t obj, const dwStereographicCameraConfig config, dwContextHandle_t context)
	Creates and initializes a calibrated stereographic camera. More...

DW_API_PUBLIC dwStatus	dwCameraModel_isRayInsideFOV (bool *isInsideMaxFOV, float32_t x, float32_t y, float32_t z, dwConstCameraModelHandle_t obj)
	Checks if the angle of a ray with the camera's optical center is below the maximum possible angle of any ray that can be back-projected from valid image domain pixels. More...

DW_API_PUBLIC dwStatus	dwCameraModel_pixel2Ray (float32_t x, float32_t y, float32_t *z, float32_t u, float32_t v, dwConstCameraModelHandle_t obj)
	Back-projects a 2D point in pixel coordinates to a 3D optical ray direction. More...

DW_API_PUBLIC dwStatus	dwCameraModel_ray2Pixel (float32_t u, float32_t v, float32_t x, float32_t y, float32_t z, dwConstCameraModelHandle_t obj)
	Projects a 3D point in camera coordinates to a 2D pixel position. More...

DW_API_PUBLIC dwStatus	dwCameraModel_release (dwCameraModelHandle_t obj)
	Releases the calibrated camera. More...

Typedef Documentation

◆ dwCameraModelHandle_t

typedef struct dwCameraModelObject* dwCameraModelHandle_t

A pointer to the handle representing a calibrated camera model.

This object allows the forward projection of 3D points onto 2D image pixels (ray2Pixel) and the corresponding back-projection (pixel2Ray).

Definition at line 67 of file CameraModel.h.

◆ dwConstCameraModelHandle_t

typedef struct dwCameraModelObject const* dwConstCameraModelHandle_t

A pointer to the handle representing a const calibrated camera.

Definition at line 72 of file CameraModel.h.

Function Documentation

◆ dwCameraModel_applyImageTransform()

DW_API_PUBLIC dwStatus dwCameraModel_applyImageTransform	(	const dwMatrix3f *	transform,
		dwVector2ui	newSize,
		dwCameraModelHandle_t	obj
	)

Sets a new origin for the image and adjusts image scales.

Modifies the camera model so that it applies to a transformed version of the original image The image0 is transformed so that pixel p0= [u0,v0,1]^T becomes pt= [ut,vt,1]^T, i.e., pt = transform * p0.

Currently, transform is limited to an affine matrix containing only scale and translation, i.e., transform =

[s 0 tx]
[0 s ty]
[0 0  1]

Examples:

Cropping: if the original image is cropped by removing the first and last N rows and the first and last M columns.

transform= [1.0, 0.0, N]
           [0.0, 1.0, M]
           [0.0, 0.0, 1.0]
newsize  = `getImageSize()-dwVector2ui{2*N,2*M}`

will produce a camera model that can be used with the cropped image.

Subsampling: if the original image is subsampled by dropping every second pixel:

x0: 0 1 2 3 4 5
xt: 0   1   2
transform= [0.5, 0.0, 0.0]
           [0.0, 0.5, 0.0]
           [0.0, 0.0, 1.0]
newSize  = getImageSize()*0.5f

will produce a camera model that can be used with the subsampled image.

Subsampling with interpolation: if the original image is subsampled by interpolating between the pixels:

x0: 0 1 2 3 4 5
xt: 0   1   2
transform= [0.5, 0.0, 0.5]
           [0.0, 0.5, 0.5]
           [0.0, 0.0, 1.0]
newSize  = getImageSize()*0.5f

will produce a camera model that can be used with the subsampled image.

Parameters

[in]	transform	The scale+shift affine transform, in pixels.
[in]	newSize	The new size of the image after the transformation, in pixels.
[in]	obj	Handle to the calibrated camera model.

Return values

DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_INVALID_HANDLE	if given camera handle is invalid
DW_SUCCESS	no error

◆ dwCameraModel_getHorizontalFOV()

DW_API_PUBLIC dwStatus dwCameraModel_getHorizontalFOV	(	float32_t *	hfov,
		dwConstCameraModelHandle_t	obj
	)

Gets the horizontal Field of View (FOV) of the calibrated camera, in radians.

Parameters

[out]	hfov	A pointer to the camera horizontal FOV in radians.
[in]	obj	Handle to the calibrated camera model.

Return values

DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_INVALID_HANDLE	if given camera handle is invalid
DW_SUCCESS	no error

◆ dwCameraModel_getImageSize()

DW_API_PUBLIC dwStatus dwCameraModel_getImageSize	(	uint32_t *	width,
		uint32_t *	height,
		dwConstCameraModelHandle_t	obj
	)

Gets the width and height of the calibrated camera, in pixels.

Parameters

[out]	width	A pointer to the camera image width, in pixels.
[out]	height	A pointer to the camera image height, in pixels.
[in]	obj	Handle to the calibrated camera model.

Return values

DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_INVALID_HANDLE	if given camera handle is invalid
DW_SUCCESS	no error

◆ dwCameraModel_getInversePolynomial()

DW_API_PUBLIC dwStatus dwCameraModel_getInversePolynomial	(	float32_t *	invPoly,
		size_t *	size,
		dwCameraModelHandle_t	obj
	)

Returns the inverse polynomial used for the inverse distortion model.

The inverse distortion model specifies

the back-projection in Pinhole cameras and in FTheta cameras, and
the forward-projection in OCam cameras.

The back-projection is the mapping of pixel coordinates in the image to optical rays while the forward projection is the mapping of optical rays to pixel coordinates in the image.

Note: If the camera model handle has been instantiated with the inverse polynomial, then the returned polynomial will correspond to this polynomial. Otherwise, the returned polynomial will be a least squares fit to the inverse polynomial within the image domain of the mapping.

Parameters

[out]	invPoly	Array of coefficients, lower degrees first.
[in,out]	size	Input: size of the polynomial buffer. Output: on success, the number of coefficients returned / the effective polynomial degree.
[in]	obj	Camera handle.

Return values

DW_INVALID_HANDLE	if given camera handle is invalid
DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_OUT_OF_BOUNDS	if given array is not large enough to hold the polynomial
DW_SUCCESS	no error

◆ dwCameraModel_initialize()

DW_API_PUBLIC dwStatus dwCameraModel_initialize	(	dwCameraModelHandle_t *	camera,
		uint32_t	sensorId,
		dwConstRigHandle_t	obj
	)

Creates a calibrated camera model polymorphically for a compatible sensor.

Parameters

[out]	camera	A pointer to a handle for the created calibrated camera object. Has to be released by the user with `dwCameraModel_release`.
[in]	sensorId	Specifies the index of the camera sensor to create a calibrated camera for.
[in]	obj	Specifies the rig configuration module handle containing the camera definition.

Note: if camera is of ftheta type and windshield parameters are part of the sensor properties of the respective sensor in the Rig, the windshield will be appended automatically.

Return values

DW_INVALID_ARGUMENT	if no calibrated camera can be constructed given the parameters found in the rig or if the camera pointer is invalid
DW_INVALID_HANDLE	if given context handle is invalid
DW_CANNOT_CREATE_OBJECT	if given `sensorId` is not a camera sensor
DW_OUT_OF_BOUNDS	if the sensorId is larger than the number of sensors in the rig
DW_SUCCESS	no error

◆ dwCameraModel_initializeFTheta()

DW_API_PUBLIC dwStatus dwCameraModel_initializeFTheta	(	dwCameraModelHandle_t *	obj,
		const dwFThetaCameraConfig *	config,
		dwContextHandle_t	context
	)

Creates and initializes a calibrated camera for the F-Theta distortion model.

Parameters

[out]	obj	A pointer to the calibrated camera handle is returned here.
[in]	config	A pointer to the configuration values for the camera.
[in]	context	Specifies the handle to the context under which it is created.

Return values

DW_INVALID_HANDLE	if given context handle is invalid
DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_SUCCESS	no error

◆ dwCameraModel_initializeFThetaNew()

DW_API_PUBLIC dwStatus dwCameraModel_initializeFThetaNew	(	dwCameraModelHandle_t *	obj,
		const dwFThetaCameraConfig *	config,
		dwContextHandle_t	context
	)

Creates and initializes a calibrated camera for the F-Theta distortion model.

Parameters

[out]	obj	A pointer to the calibrated camera handle is returned here.
[in]	config	A pointer to the configuration values for the camera.
[in]	context	Specifies the handle to the context under which it is created.

Return values

DW_INVALID_HANDLE	if given context handle is invalid
DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_SUCCESS	no error

◆ dwCameraModel_initializePinhole()

DW_API_PUBLIC dwStatus dwCameraModel_initializePinhole	(	dwCameraModelHandle_t *	obj,
		const dwPinholeCameraConfig *	config,
		dwContextHandle_t	context
	)

Creates and initializes a calibrated pinhole camera.

Parameters

[out]	obj	A pointer to the calibrated camera handle is returned here.
[in]	config	A pointer to the configuration values for the camera.
[in]	context	Specifies the handle to the context under which it is created.

Return values

DW_INVALID_HANDLE	if given context handle is invalid
DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_SUCCESS	no error

◆ dwCameraModel_initializeStereographic()

DW_API_PUBLIC dwStatus dwCameraModel_initializeStereographic	(	dwCameraModelHandle_t *	obj,
		const dwStereographicCameraConfig *	config,
		dwContextHandle_t	context
	)

Creates and initializes a calibrated stereographic camera.

Parameters

[out]	obj	A pointer to the calibrated camera handle is returned here.
[in]	config	A pointer to the configuration values for the camera.
[in]	context	Specifies the handle to the context under which it is created.

Return values

DW_INVALID_HANDLE	if given context handle is invalid
DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_SUCCESS	no error

◆ dwCameraModel_isRayInsideFOV()

DW_API_PUBLIC dwStatus dwCameraModel_isRayInsideFOV	(	bool *	isInsideMaxFOV,
		float32_t	x,
		float32_t	y,
		float32_t	z,
		dwConstCameraModelHandle_t	obj
	)

Checks if the angle of a ray with the camera's optical center is below the maximum possible angle of any ray that can be back-projected from valid image domain pixels.

Note: This is a fast but approximate check for visibility only, as rays might still be projected outside of the image bounds even if this check passes, because only the maximal possible ray angle is considered for this check. The result of dwCameraModel_ray2Pixel still needs to be considered for accurate inside / outside checks.

Parameters

[out]	isInsideMaxFOV	A pointer to the boolean: `true` if the ray's angle with the optical center is below or equal to the maximum possible angle of any ray back-projected from valid image domain pixel, `false` otherwise.
[in]	x	Specifies the X coordinate of the point.
[in]	y	Specifies the Y coordinate of the point.
[in]	z	Specifies the Z coordinate of the point.
[in]	obj	Specifies the handle to the calibrated camera model.

Return values

DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_INVALID_HANDLE	if given camera handle is invalid
DW_SUCCESS	no error

◆ dwCameraModel_pixel2Ray()

DW_API_PUBLIC dwStatus dwCameraModel_pixel2Ray	(	float32_t *	x,
		float32_t *	y,
		float32_t *	z,
		float32_t	u,
		float32_t	v,
		dwConstCameraModelHandle_t	obj
	)

Back-projects a 2D point in pixel coordinates to a 3D optical ray direction.

The ray is normalized to have a norm of 1.

Parameters

[out]	x	A pointer to the X coordinate of the ray's direction.
[out]	y	A pointer to the Y coordinate of the ray's direction.
[out]	z	A pointer to the Z coordinate of the ray's direction.
[in]	u	Specifies the horizontal coordinate of the pixel.
[in]	v	Specifies the vertical coordinate of the pixel.
[in]	obj	Specifies the handle to the calibrated camera model.

Return values

DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_INVALID_HANDLE	if given camera handle is invalid
DW_SUCCESS	no error

◆ dwCameraModel_ray2Pixel()

DW_API_PUBLIC dwStatus dwCameraModel_ray2Pixel	(	float32_t *	u,
		float32_t *	v,
		float32_t	x,
		float32_t	y,
		float32_t	z,
		dwConstCameraModelHandle_t	obj
	)

Projects a 3D point in camera coordinates to a 2D pixel position.

Parameters

[out]	u	A pointer to the horizontal coordinate of the pixel.
[out]	v	A pointer to the vertical coordinate of the pixel.
[in]	x	Specifies the X coordinate of the point.
[in]	y	Specifies the Y coordinate of the point.
[in]	z	Specifies the Z coordinate of the point.
[in]	obj	Specifies the handle to the calibrated camera model.

Return values

DW_INVALID_ARGUMENT	if one of the given pointers is a nullptr
DW_INVALID_HANDLE	if given camera handle is invalid
DW_SUCCESS	no error

◆ dwCameraModel_release()

DW_API_PUBLIC dwStatus dwCameraModel_release ( dwCameraModelHandle_t obj )

Releases the calibrated camera.

This method releases all resources associated with a calibrated camera.

Note: This method renders the handle unusable.

Parameters

[in] obj The object handle to be released.

Return values

DW_INVALID_HANDLE	if given camera handle is invalid
DW_SUCCESS	no error

Detailed Description

Typedefs

Functions

Typedef Documentation

◆ dwCameraModelHandle_t

◆ dwConstCameraModelHandle_t

Function Documentation

◆ dwCameraModel_applyImageTransform()

◆ dwCameraModel_getHorizontalFOV()

◆ dwCameraModel_getImageSize()

◆ dwCameraModel_getInversePolynomial()

◆ dwCameraModel_initialize()

◆ dwCameraModel_initializeFTheta()

◆ dwCameraModel_initializeFThetaNew()

◆ dwCameraModel_initializePinhole()

◆ dwCameraModel_initializeStereographic()

◆ dwCameraModel_isRayInsideFOV()

◆ dwCameraModel_pixel2Ray()

◆ dwCameraModel_ray2Pixel()

◆ dwCameraModel_release()