DriveWorks SDK Reference
3.5.78 Release
For Test and Development only

Rectifier Interface

Detailed Description

Defines the Rectifier module.

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

Typedefs

typedef struct dwRectifierObject * dwRectifierHandle_t
 A pointer to the handle representing a rectifier. More...
 

Functions

DW_API_PUBLIC dwStatus dwRectifier_getCUDAStream (cudaStream_t *stream, dwRectifierHandle_t obj)
 Gets the CUDA stream used. More...
 
DW_API_PUBLIC dwStatus dwRectifier_getDistortionMap (dwImageCUDA *distortionMap, dwRectifierHandle_t obj)
 Gets the distortion map as a 2-channel single plane image. More...
 
DW_API_PUBLIC dwStatus dwRectifier_getHomography (dwMatrix3f *homography, dwRectifierHandle_t obj)
 Gets the homography matrix used. More...
 
DW_API_PUBLIC dwStatus dwRectifier_initialize (dwRectifierHandle_t *obj, dwCameraModelHandle_t cameraIn, dwCameraModelHandle_t cameraOut, dwContextHandle_t ctx)
 Initializes a rectifier based on an input and output camera model and a homography. More...
 
DW_API_PUBLIC dwStatus dwRectifier_release (dwRectifierHandle_t obj)
 Releases the rectifier module. More...
 
DW_API_PUBLIC dwStatus dwRectifier_reset (dwRectifierHandle_t obj)
 Resets the rectifier module. More...
 
DW_API_PUBLIC dwStatus dwRectifier_setCUDAStream (cudaStream_t stream, dwRectifierHandle_t obj)
 Sets the CUDA stream used. More...
 
DW_API_PUBLIC dwStatus dwRectifier_setHomography (const dwMatrix3f *homography, dwRectifierHandle_t obj)
 Sets the homography matrix used. More...
 
DW_API_PUBLIC dwStatus dwRectifier_setHomographyFromRotation (float32_t roll, float32_t pitch, float32_t yaw, dwRectifierHandle_t obj)
 Calculates and sets the homography matrix used based on a value for roll, pitch and yaw. More...
 
DW_API_PUBLIC dwStatus dwRectifier_warp (dwImageCUDA *outputImage, const dwImageCUDA *inputImage, bool setOutsidePixelsToBlack, dwRectifierHandle_t obj)
 Warps the image from the input camera model to the model of the output camera using CUDA on the GPU. More...
 
DW_API_PUBLIC dwStatus dwRectifier_warpNvMedia (dwImageNvMedia *outputImage, const dwImageNvMedia *inputImage, dwRectifierHandle_t obj)
 Warps the image from the input camera model to the model of the output camera using the Tegra VIC engine. More...
 
DW_API_PUBLIC dwStatus dwRectifier_warpPointsCPU (dwVector2f *outputPoints, const dwVector2f *inputPoints, uint32_t pointCount, dwRectifierHandle_t obj)
 Warps an array of CPU dwVector2f on a preallocated output CPU buffer. More...
 
DW_API_PUBLIC dwStatus dwRectifier_warpPointsGPU (dwVector2f *outputPoints, const dwVector2f *inputPoints, uint32_t pointCount, dwRectifierHandle_t obj)
 Warps an array of dwVector2f on GPU. More...
 
DW_API_PUBLIC dwStatus dwRectifier_warpPointsInPlaceCPU (dwVector2f *points, uint32_t pointCount, dwRectifierHandle_t obj)
 Warps an array of CPU dwVector2f and writes on the same buffer. More...
 
DW_API_PUBLIC dwStatus dwRectifier_warpPointsInPlaceGPU (dwVector2f *points, uint32_t pointCount, dwRectifierHandle_t obj)
 Warps an array of dwVector2f on the GPU and writes on the same buffer. More...
 
DW_API_PUBLIC dwStatus dwRectifier_warpROI (dwImageCUDA *outputImage, const dwImageCUDA *inputImage, bool setOutsidePixelsToBlack, const dwRect roi, dwRectifierHandle_t obj)
 Warps the image from the input camera model to the model of the output camera limiting the computation to a ROI. More...
 

Typedef Documentation

◆ dwRectifierHandle_t

typedef struct dwRectifierObject* dwRectifierHandle_t

A pointer to the handle representing a rectifier.

This object allows you to rectify an image acquired in one camera model by projecting it into another camera model.

Definition at line 64 of file Rectifier.h.

Function Documentation

◆ dwRectifier_getCUDAStream()

DW_API_PUBLIC dwStatus dwRectifier_getCUDAStream ( cudaStream_t *  stream,
dwRectifierHandle_t  obj 
)

Gets the CUDA stream used.

Parameters
[in]streamUses this CUDA stream.
[in]objA pointer to the rectifier handle that is updated. Initialization must not have changed.
Returns
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_SUCCESS

◆ dwRectifier_getDistortionMap()

DW_API_PUBLIC dwStatus dwRectifier_getDistortionMap ( dwImageCUDA distortionMap,
dwRectifierHandle_t  obj 
)

Gets the distortion map as a 2-channel single plane image.

Parameters
[out]distortionMapThe distortion map.
[in]objA pointer to the rectifier handle that is updated. Initialization must not have changed.
Returns
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_SUCCESS

◆ dwRectifier_getHomography()

DW_API_PUBLIC dwStatus dwRectifier_getHomography ( dwMatrix3f homography,
dwRectifierHandle_t  obj 
)

Gets the homography matrix used.

Parameters
[out]homographyThe homography transformation matrix.
[in]objA pointer to the rectifier handle. Initialization must not have changed.
Returns
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_SUCCESS

◆ dwRectifier_initialize()

DW_API_PUBLIC dwStatus dwRectifier_initialize ( dwRectifierHandle_t obj,
dwCameraModelHandle_t  cameraIn,
dwCameraModelHandle_t  cameraOut,
dwContextHandle_t  ctx 
)

Initializes a rectifier based on an input and output camera model and a homography.

In particular, the rectifier implements Ray2Pixel_cameraOut( H * Pixel2Ray_cameraIn(Image) ). Per default, the homography is set to identity. This also implicitly sets up the VIC engine for rectificaton of dwImageNvMedia (see dwRectifier_warpNvMedia, note the image must have the same resolution of the set camera and it must not be lower that 128x128)

Parameters
[out]objA pointer to the rectifier handle for the created module.
[in]cameraInModel of the input camera.
[in]cameraOutModel of the output camera.
[in]ctxSpecifies the handler to the context to create the rectifier.
Returns
DW_INVALID_ARGUMENT - if the rectifier handle is NULL
DW_INVALID_HANDLE -if the cameraIn model or cameraOut model or context handle is NULL or invalid
DW_SUCCESS

◆ dwRectifier_release()

DW_API_PUBLIC dwStatus dwRectifier_release ( dwRectifierHandle_t  obj)

Releases the rectifier module.

Parameters
[in]objThe object handle to release.
Returns
DW_SUCCESS
DW_INVALID_HANDLE - If the given handle is invalid,i.e. null or of wrong type
DW_BAD_CAST
Note
This method renders the handle unusable.

◆ dwRectifier_reset()

DW_API_PUBLIC dwStatus dwRectifier_reset ( dwRectifierHandle_t  obj)

Resets the rectifier module.

Parameters
[in]objSpecifies the rectifier to reset.
Returns
DW_SUCCESS
DW_INVALID_HANDLE - If the given handle is invalid,i.e. null or of wrong type
DW_BAD_CAST

◆ dwRectifier_setCUDAStream()

DW_API_PUBLIC dwStatus dwRectifier_setCUDAStream ( cudaStream_t  stream,
dwRectifierHandle_t  obj 
)

Sets the CUDA stream used.

Parameters
[in]streamThe CUDA stream to use.
[in]objA pointer to the rectifier handle that is updated. Initialization must not have changed.
Returns
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_SUCCESS

◆ dwRectifier_setHomography()

DW_API_PUBLIC dwStatus dwRectifier_setHomography ( const dwMatrix3f homography,
dwRectifierHandle_t  obj 
)

Sets the homography matrix used.

Parameters
[in]homographyThe new homography transformation matrix.
[in]objA pointer to the rectifier handle that is updated. Initialization must not have changed.
Returns
DW_INVALID_ARGUMENT -if the matrix is NULL
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_SUCCESS

◆ dwRectifier_setHomographyFromRotation()

DW_API_PUBLIC dwStatus dwRectifier_setHomographyFromRotation ( float32_t  roll,
float32_t  pitch,
float32_t  yaw,
dwRectifierHandle_t  obj 
)

Calculates and sets the homography matrix used based on a value for roll, pitch and yaw.

This rotation will be applied during backprojection, so from output to input

Parameters
[in]rollThe camera roll in degrees.
[in]pitchThe camera pitch in degrees.
[in]yawThe camera yaw in degrees.
[in]objA pointer to the rectifier handle that is updated. Initialization must not have changed.
Returns
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_SUCCESS

◆ dwRectifier_warp()

DW_API_PUBLIC dwStatus dwRectifier_warp ( dwImageCUDA outputImage,
const dwImageCUDA inputImage,
bool  setOutsidePixelsToBlack,
dwRectifierHandle_t  obj 
)

Warps the image from the input camera model to the model of the output camera using CUDA on the GPU.

The coordinates are calculated on the spot, unless distortion map has been enabled, in which case they will be read. NOTE: the coordinates of input/output images are implicitly adapted to match the input/output camera if the sizes of the images don't match the cameras. This will result in stretching of the image and possible loss of aspect ratio.

Parameters
[out]outputImagePointer to the output image.
[in]inputImagePointer to the input image.
[in]setOutsidePixelsToBlackif true, the pixels outside the original image are set to black on the undistorted image, otherwise interpolated
[in]objA pointer to the rectifier handle that performs the warping.
Returns
DW_INVALID_ARGUMENT -if the input image or output image pointer is NULL
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_CUDA_ERROR -if underlying CUDA call fails
DW_SUCCESS

◆ dwRectifier_warpNvMedia()

DW_API_PUBLIC dwStatus dwRectifier_warpNvMedia ( dwImageNvMedia outputImage,
const dwImageNvMedia inputImage,
dwRectifierHandle_t  obj 
)

Warps the image from the input camera model to the model of the output camera using the Tegra VIC engine.

External pixels are automatically filled by replicating valid pixels NOTE: the coordinates of input/output images are implicitly adapted to match the input/output camera if the sizes of the images don't match the cameras. This will result in stretching of the image and possible loss of aspect ratio.

Parameters
[out]outputImagePointer to the output image.
[in]inputImagePointer to the input image.
[in]objA pointer to the rectifier handle that performs the warping.
Returns
DW_INVALID_ARGUMENT -if the input image or output image pointer is NULL
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_NVMEDIA_ERROR -if underlying NvMedia call fails
DW_SUCCESS

◆ dwRectifier_warpPointsCPU()

DW_API_PUBLIC dwStatus dwRectifier_warpPointsCPU ( dwVector2f outputPoints,
const dwVector2f inputPoints,
uint32_t  pointCount,
dwRectifierHandle_t  obj 
)

Warps an array of CPU dwVector2f on a preallocated output CPU buffer.

Parameters
[out]outputPointsArray of output points.
[in]inputPointsArray of input points
[in]pointCountnumber of points
[in]objA pointer to the rectifier handle that performs the warping.
Returns
DW_INVALID_ARGUMENT -if the input vector or output vector pointer is NULL
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_SUCCESS

◆ dwRectifier_warpPointsGPU()

DW_API_PUBLIC dwStatus dwRectifier_warpPointsGPU ( dwVector2f outputPoints,
const dwVector2f inputPoints,
uint32_t  pointCount,
dwRectifierHandle_t  obj 
)

Warps an array of dwVector2f on GPU.

Parameters
[out]outputPointsArray of output points.
[in]inputPointsArray of input points
[in]pointCountnumber of points
[in]objA pointer to the rectifier handle that performs the warping.
Returns
DW_INVALID_ARGUMENT -if the input vector or output vector pointer is NULL
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_CUDA_ERROR -if underlying CUDA call fails
DW_SUCCESS

◆ dwRectifier_warpPointsInPlaceCPU()

DW_API_PUBLIC dwStatus dwRectifier_warpPointsInPlaceCPU ( dwVector2f points,
uint32_t  pointCount,
dwRectifierHandle_t  obj 
)

Warps an array of CPU dwVector2f and writes on the same buffer.

Parameters
[in]pointsArray of points to warp in place
[in]pointCountnumber of points
[in]objA pointer to the rectifier handle that performs the warping.
Returns
DW_INVALID_ARGUMENT -if the vector pointer is NULL
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_SUCCESS

◆ dwRectifier_warpPointsInPlaceGPU()

DW_API_PUBLIC dwStatus dwRectifier_warpPointsInPlaceGPU ( dwVector2f points,
uint32_t  pointCount,
dwRectifierHandle_t  obj 
)

Warps an array of dwVector2f on the GPU and writes on the same buffer.

Parameters
[in]pointsArray of points to warp in place
[in]pointCountnumber of points
[in]objA pointer to the rectifier handle that performs the warping.
Returns
DW_INVALID_ARGUMENT -if the input vector or output image vector is NULL
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_CUDA_ERROR -if underlying CUDA call fails
DW_SUCCESS

◆ dwRectifier_warpROI()

DW_API_PUBLIC dwStatus dwRectifier_warpROI ( dwImageCUDA outputImage,
const dwImageCUDA inputImage,
bool  setOutsidePixelsToBlack,
const dwRect  roi,
dwRectifierHandle_t  obj 
)

Warps the image from the input camera model to the model of the output camera limiting the computation to a ROI.

The ROI is defined in output camera coordinates and the resulting image will be translated to the origin of the output image. No further transformation will be performed.

Parameters
[out]outputImagePointer to the output image.
[in]inputImagePointer to the input image. NOTE: the coordinates of this image are implicitly adapted to the input camera
[in]setOutsidePixelsToBlackif true, the pixels outside the original image are set to black on the undistorted image, otherwise interpolated
[in]roiA region of interest of the output rectified area
[in]objA pointer to the rectifier handle that performs the warping.
Returns
DW_INVALID_ARGUMENT -if the input image or output image pointer is NULL, or if roi is invalid
DW_INVALID_HANDLE -if the rectifier handle is invalid or NULL
DW_CUDA_ERROR -if underlying CUDA call fails
DW_SUCCESS