DriveWorks SDK Reference
4.0.0 Release
For Test and Development only

Camera Model

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. 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 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 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 66 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 70 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.

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]transformThe scale+shift affine transform, in pixels.
[in]newSizeThe new size of the image after the transformation, in pixels.
[in]objHandle 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]hfovA pointer to the camera horizontal FOV in radians.
[in]objHandle 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]widthA pointer to the camera image width, in pixels.
[out]heightA pointer to the camera image height, in pixels.
[in]objHandle 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]invPolyArray of coefficients, lower degrees first.
[in,out]sizeInput: size of the polynomial buffer. Output: on success, the number of coefficients returned / the effective polynomial degree.
[in]objCamera 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]cameraA pointer to a handle for the created calibrated camera object. Has to be released by the user with dwCameraModel_release.
[in]sensorIdSpecifies the index of the camera sensor to create a calibrated camera for.
[in]objSpecifies 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_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

◆ 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]objA pointer to the calibrated camera handle is returned here.
[in]configA pointer to the configuration values for the camera.
[in]contextSpecifies 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 original 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]objA pointer to the calibrated camera handle is returned here.
[in]configA pointer to the configuration values for the camera.
[in]contextSpecifies 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]objA pointer to the calibrated camera handle is returned here.
[in]configA pointer to the configuration values for the camera.
[in]contextSpecifies 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 stereographic camera.

Parameters
[out]objA pointer to the calibrated camera handle is returned here.
[in]configA pointer to the configuration values for the camera.
[in]contextSpecifies 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 *  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]isInsideMaxFOVA 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]xSpecifies the X coordinate of the point.
[in]ySpecifies the Y coordinate of the point.
[in]zSpecifies the Z coordinate of the point.
[in]objSpecifies 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]xA pointer to the X coordinate of the ray's direction.
[out]yA pointer to the Y coordinate of the ray's direction.
[out]zA pointer to the Z coordinate of the ray's direction.
[in]uSpecifies the horizontal coordinate of the pixel.
[in]vSpecifies the vertical coordinate of the pixel.
[in]objSpecifies 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]uA pointer to the horizontal coordinate of the pixel.
[out]vA pointer to the vertical coordinate of the pixel.
[in]xSpecifies the X coordinate of the point.
[in]ySpecifies the Y coordinate of the point.
[in]zSpecifies the Z coordinate of the point.
[in]objSpecifies 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]objThe object handle to be released.
Returns
DW_INVALID_HANDLE - if given camera handle is invalid
DW_SUCCESS