DriveWorks SDK Reference 3.0.4260 Release For Test and Development only
Camera Model

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

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

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

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