Detailed Description

Calibrated camera model abstraction and functionality.

Note: SW Release Applicability: These APIs are available in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.

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, bool updateMasks, dwCameraModelHandle_t obj)
	Sets a new origin for the image. 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_initializeOCam (dwCameraModelHandle_t obj, const dwOCamCameraConfig config, dwContextHandle_t context)
	Creates and initializes a calibrated omnidirectional camera. 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 camera for the F-Theta distortion model. More...

DW_API_PUBLIC dwStatus	dwCameraModel_isRayInsideFOV (bool *isInside, float32_t x, float32_t y, float32_t z, dwConstCameraModelHandle_t obj)
	Projects a 3D point in pixel coordinates to a 2D pixel position. 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 pixel 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 68 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,
		bool	updateMasks,
		dwCameraModelHandle_t	obj
	)

Sets a new origin for the image.

Adjusts intrinsics.

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 pt = transform*p0

Currently, transform is limited to an affine matrix containing only scale and translation, i.e. [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]	updateMasks	Allow camera to reallocate + resample associated image masks (associated masks will be dropped if false). If enabled and masks are present this incurs a dynamic memory allocation.
[in]	obj	Handle to the calibrated camera model.

Returns: DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_INVALID_HANDLE - if given camera handle is invalid
DW_SUCCESS

◆ 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.

Returns: DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_INVALID_HANDLE - if given camera handle is invalid
DW_SUCCESS

◆ 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.

Returns: DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_INVALID_HANDLE - if given camera handle is invalid
DW_SUCCESS

◆ 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.

Pinhole cameras use this for the back-projection model.
OCam cameras use this for the forward projection model.
FTheta cameras use this for the back-projection model.

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.

Returns: 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

◆ 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.

Returns: 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_CANNOT_CREATE_OBJECT - if given sensorId is not a camera sensor
DW_OUT_OF_BOUNDS - if the sensorId is larger than the numerof sensors in the rig
DW_SUCCESS

◆ 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.

Returns: DW_INVALID_HANDLE - if given context handle is invalid
DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_SUCCESS

◆ dwCameraModel_initializeOCam()

DW_API_PUBLIC dwStatus dwCameraModel_initializeOCam	(	dwCameraModelHandle_t *	obj,
		const dwOCamCameraConfig *	config,
		dwContextHandle_t	context
	)

Creates and initializes a calibrated omnidirectional camera.

See the orignal paper for a description of the model: https://sites.google.com/site/scarabotix/ocamcalib-toolbox Scaramuzza, D. (2008). Omnidirectional Vision: from Calibration to Robot Motion Estimation, ETH Zurich, PhD Thesis no. 17635., February 22, 2008.

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.

Returns: DW_INVALID_HANDLE - if given context handle is invalid
DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_SUCCESS

◆ 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.

Returns: DW_INVALID_HANDLE - if given context handle is invalid
DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_SUCCESS

◆ dwCameraModel_initializeStereographic()

DW_API_PUBLIC dwStatus dwCameraModel_initializeStereographic	(	dwCameraModelHandle_t *	obj,
		const dwStereographicCameraConfig *	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.

Returns: DW_INVALID_HANDLE - if given context handle is invalid
DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_SUCCESS

◆ dwCameraModel_isRayInsideFOV()

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

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

Parameters

[out]	isInside	A pointer to the boolean: true is 3D point is inside the image, 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.

Returns: DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_INVALID_HANDLE - if given camera handle is invalid
DW_SUCCESS

◆ 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.

Returns: DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_INVALID_HANDLE - if given camera handle is invalid
DW_SUCCESS

◆ 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 pixel 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.

Returns: DW_INVALID_ARGUMENT - if one of the given pointers is a nullptr
DW_INVALID_HANDLE - if given camera handle is invalid
DW_SUCCESS

◆ 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.

Returns: DW_INVALID_HANDLE - if given camera handle is invalid
DW_SUCCESS

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_initializeOCam()

◆ dwCameraModel_initializePinhole()

◆ dwCameraModel_initializeStereographic()

◆ dwCameraModel_isRayInsideFOV()

◆ dwCameraModel_pixel2Ray()

◆ dwCameraModel_ray2Pixel()

◆ dwCameraModel_release()