Detailed Description

Defines the DataConditioner module for performing common transformations on input images for DNN.

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

Data Structures
struct	dwDataConditionerParams

Typedefs
typedef struct dwDataConditionerObject *	dwDataConditionerHandle_t
	Handle to a DataConditioner. More...

Functions
DW_API_PUBLIC dwStatus	dwDataConditioner_getCUDAStream (cudaStream_t *stream, dwDataConditionerHandle_t obj)
	Gets the CUDA stream used by the data conditioner. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_getOutputSize (dwBlobSize *outputBlobSize, dwDataConditionerHandle_t obj)
	Computes the output size based on the input size and the operations that have been added. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_initialize (dwDataConditionerHandle_t obj, const dwBlobSize networkInputBlobSize, const dwDataConditionerParams *dataConditionerParams, cudaStream_t stream, dwContextHandle_t ctx)
	Initializes a DataConditioner module. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_initializeFromTensorProperties (dwDataConditionerHandle_t obj, const dwDNNTensorProperties outputProperties, uint32_t maxNumImages, const dwDataConditionerParams *dataConditionerParams, cudaStream_t stream, dwContextHandle_t ctx)
	Initializes a DataConditioner module. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_initParams (dwDataConditionerParams *dataConditionerParams)
	Initializes DataConditioner parameters with default values. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_outputPositionToInput (float32_t outputX, float32_t outputY, float32_t inputX, float32_t inputY, const dwRect *roi, dwDataConditionerHandle_t obj)
	Computes the position of a point from the interpreted DNN output on the input image. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_prepareData (dwDNNTensorHandle_t tensorOutput, const dwImageHandle_t inputImages, uint32_t numImages, const dwRect roi, cudaTextureAddressMode addressMode, dwDataConditionerHandle_t obj)
	Runs the configured transformations on an image. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_prepareDataRaw (float32_t d_outputImage, const dwImageCUDA const inputImages, uint32_t numImages, const dwRect roi, cudaTextureAddressMode addressMode, dwDataConditionerHandle_t obj)
	Runs the configured transformations on an image. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_release (dwDataConditionerHandle_t obj)
	Releases the DataConditioner module. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_reset (dwDataConditionerHandle_t obj)
	Resets the DataConditioner module. More...

DW_API_PUBLIC dwStatus	dwDataConditioner_setCUDAStream (cudaStream_t stream, dwDataConditionerHandle_t obj)
	Sets the CUDA stream for CUDA related operations. More...

Data Structure Documentation

◆ dwDataConditionerParams

struct dwDataConditionerParams

Data Fields
bool	doPerPlaneMeanNormalization	Boolean indicating whether to perform per-plane mean normalization. Default false.
bool	ignoreAspectRatio	Boolean indicating whether the aspect ratio of the input image should be kept (false) or the image should be stretched to the roi specified (true). Default false
const dwImageCUDA *	meanImage	Mean image to be subtracted. Default is nullptr. Mean image is expected to be float16 or float32. The pixel format is required to be R or RGBA with interleaved channels. The dimensions of the mean image must meet the dimensions of network input. Pixel range: [0, 255]. Default is nullptr.
float32_t	meanValue[DW_MAX_IMAGE_PLANES]	Mean value to be subtracted. Range [0, 255]. Default is 0.
float32_t	scaleCoefficient	Scale pixel intensities. Default is 1.0.
bool	splitPlanes	Boolean indicating whether planes should be split. Default is true.
float32_t	stdev[DW_MAX_IMAGE_PLANES]	Standard deviation with range [0, 255]. Default is 1.0. The results are computed using the following formula, where R, G and B are from the input image and have range of [0, 255] meanImage is optional and is 0 if it is not set perPlaneMeanX is the mean per plane for that channel and is optional and 0 if it is not set R' = ((R - meanValue[0] - meanImage[pixelIndex] - perPlaneMeanR) / stdev[0]) * scaleCoefficient G' = ((G - meanValue[1] - meanImage[pixelIndex] - perPlaneMeanG) / stdev[1]) * scaleCoefficient B' = ((B - meanValue[2] - meanImage[pixelIndex] - perPlaneMeanB) / stdev[2]) * scaleCoefficient

Typedef Documentation

◆ dwDataConditionerHandle_t

typedef struct dwDataConditionerObject* dwDataConditionerHandle_t

Handle to a DataConditioner.

Definition at line 92 of file DataConditioner.h.

Function Documentation

◆ dwDataConditioner_getCUDAStream()

DW_API_PUBLIC dwStatus dwDataConditioner_getCUDAStream	(	cudaStream_t *	stream,
		dwDataConditionerHandle_t	obj
	)

Gets the CUDA stream used by the data conditioner.

Parameters

[out]	stream	The CUDA stream currently used by the data conditioner.
[in]	obj	A handle to the data conditioner module.

Returns: DW_INVALID_ARGUMENT if the given dataconditioner handle or stream are NUll.
DW_SUCCESS otherwise.

◆ dwDataConditioner_getOutputSize()

DW_API_PUBLIC dwStatus dwDataConditioner_getOutputSize	(	dwBlobSize *	outputBlobSize,
		dwDataConditionerHandle_t	obj
	)

Computes the output size based on the input size and the operations that have been added.

Parameters

[out]	outputBlobSize	Size of the output blob after the transformations have been applied.
[in]	obj	Specifies the DataConditioner handle.

Returns: DW_INVALID_ARGUMENT if outputBlobSize or dataconditioner handle are NULL.
DW_SUCCESS otherwise.

◆ dwDataConditioner_initialize()

DW_API_PUBLIC dwStatus dwDataConditioner_initialize	(	dwDataConditionerHandle_t *	obj,
		const dwBlobSize *	networkInputBlobSize,
		const dwDataConditionerParams *	dataConditionerParams,
		cudaStream_t	stream,
		dwContextHandle_t	ctx
	)

Initializes a DataConditioner module.

Parameters

[out]	obj	A pointer to the DataConditioner handle for the created module.
[in]	networkInputBlobSize	A pointer to the size of the network input as a blob that the DataConditioner expects.
[in]	dataConditionerParams	DataConditioner parameters.
[in]	stream	Specifies the CUDA stream to use for operations.
[in]	ctx	Specifies the handler to the context under which the DataConditioner module is created.

Note: DataConditioner parameters must be initialized using dwDataConditioner_initParams before modifying.

Returns: DW_INVALID_ARGUMENT if dataconditioner handle or network Input Blobsize are NULL or dataConditionerParams is invalid.
DW_INVALID_HANDLE if dwContext handle is NULL.
DW_SUCCESS

◆ dwDataConditioner_initializeFromTensorProperties()

DW_API_PUBLIC dwStatus dwDataConditioner_initializeFromTensorProperties	(	dwDataConditionerHandle_t *	obj,
		const dwDNNTensorProperties *	outputProperties,
		uint32_t	maxNumImages,
		const dwDataConditionerParams *	dataConditionerParams,
		cudaStream_t	stream,
		dwContextHandle_t	ctx
	)

Initializes a DataConditioner module.

Parameters

[out]	obj	A pointer to the DataConditioner handle for the created module.
[in]	outputProperties	Tensor properties of the output. This can be obtained for dwDNN.
[in]	maxNumImages	Maximum number of images to run DataConditioner and combine into one Tensor
[in]	dataConditionerParams	DataConditioner parameters.
[in]	stream	Specifies the CUDA stream to use for operations.
[in]	ctx	Specifies the handler to the context under which the DataConditioner module is created.

Note: DataConditioner parameters must be initialized using dwDataConditioner_initParams before modifying.; Supported output data types are DW_TYPE_FLOAT16 and DW_TYPE_FLOAT32.; Supported output layouts are DW_DNN_TENSOR_LAYOUT_NHWC and DW_DNN_TENSOR_LAYOUT_NCHW. The number of dimensions must be 4.

Returns: DW_INVALID_ARGUMENT if dataconditioner handle or outputProperties are NULL or dataConditionerParams is invalid.
DW_INVALID_HANDLE if dwContext handle is NULL.
DW_SUCCESS

◆ dwDataConditioner_initParams()

DW_API_PUBLIC dwStatus dwDataConditioner_initParams ( dwDataConditionerParams * dataConditionerParams )

Initializes DataConditioner parameters with default values.

Parameters

[out] dataConditionerParams DataConditioner parameters.

Returns: DW_INVALID_ARGUMENT if parameters are NULL.
DW_SUCCESS

◆ dwDataConditioner_outputPositionToInput()

DW_API_PUBLIC dwStatus dwDataConditioner_outputPositionToInput	(	float32_t *	outputX,
		float32_t *	outputY,
		float32_t	inputX,
		float32_t	inputY,
		const dwRect *	roi,
		dwDataConditionerHandle_t	obj
	)

Computes the position of a point from the interpreted DNN output on the input image.

Parameters

[out]	outputX	Pointer to X coordinate on the input image.
[out]	outputY	Pointer to Y coordinate on the input image.
[in]	inputX	X coordinate from DNN output.
[in]	inputY	Y coordinate from DNN output.
[in]	roi	ROI extracted from the input image.
[in]	obj	Specifies the DataConditioner handle.

Returns: DW_INVALID_ARGUMENT if outputX, outputY, roi or dataconditioner handle are NULL.
DW_SUCCESS

◆ dwDataConditioner_prepareData()

DW_API_PUBLIC dwStatus dwDataConditioner_prepareData	(	dwDNNTensorHandle_t	tensorOutput,
		const dwImageHandle_t *	inputImages,
		uint32_t	numImages,
		const dwRect *	roi,
		cudaTextureAddressMode	addressMode,
		dwDataConditionerHandle_t	obj
	)

Runs the configured transformations on an image.

Parameters

[out]	tensorOutput	Tensor CUDA handle to store output.
[in]	inputImages	List of Image CUDA handles as input
[in]	numImages	Number of input images.
[in]	roi	ROI to extract from input images.
[in]	addressMode	cudaTextureAddressMode specifies how to fill the potentially empty part of the ROI.
[in]	obj	Specifies the DataConditioner handle.

Note: Supported image types: R, RGB, RGBA, RCB and RCC.; If the type of inputImage is RGBA, alpha channel is dropped during the operations; therefore, outputImage has three channels instead of four.; If the type of inputImage is RGB, the channels may not be interleaved. Use RGBA if that is intended.; All the images in the list are required to have the same dimensions as the one given during initialization.; The ROI is scaled to match the network input size. If ignoreAspectRatio is false, scaling is performed by maintaining the original ROI aspect ratio. Since after scaling there might be an empty part in the scaled ROI, this will be filled according to addressMode.; numImages cannot exceed the batchsize set at initialization time. If numImages is higher than 1, the resultant output image is batched, and it can then be given to the corresponding DNN.

Returns: DW_INVALID_ARGUMENT if outputImage or dataconditioner handle or roi are NULL, or inputImage is null or invalid.
DW_CUDA_ERROR in case of an underlying cuda failure.
DW_SUCCESS otherwise.

◆ dwDataConditioner_prepareDataRaw()

DW_API_PUBLIC dwStatus dwDataConditioner_prepareDataRaw	(	float32_t *	d_outputImage,
		const dwImageCUDA const	inputImages,
		uint32_t	numImages,
		const dwRect *	roi,
		cudaTextureAddressMode	addressMode,
		dwDataConditionerHandle_t	obj
	)

Runs the configured transformations on an image.

Parameters

[out]	d_outputImage	A pointer to the preallocated output blob in GPU memory.
[in]	inputImages	Pointer to a list of pitched images to batch.
[in]	numImages	Number of pitched images.
[in]	roi	ROI to extract from input images.
[in]	addressMode	cudaTextureAddressMode specifies how to fill the potentially empty part of the ROI.
[in]	obj	Specifies the DataConditioner handle.

Note: Supported image types: R, RGB, RGBA, RCB and RCC.; If the type of inputImage is RGBA, alpha channel is dropped during the operations; therefore, outputImage has three channels instead of four.; If the type of inputImage is RGB, the channels may not be interleaved. Use RGBA if that is intended.; All the images in the list are required to have the same dimensions as the one given during initialization.; The ROI is scaled to match the network input size. If ignoreAspectRatio is false, scaling is performed by maintaining the original ROI aspect ratio. Since after scaling there might be an empty part in the scaled ROI, this will be filled according to addressMode.; numImages cannot exceed the batchsize set at initialization time. If numImages is higher than 1, the resultant output image is batched, and it can then be given to the corresponding DNN.

Returns: DW_INVALID_ARGUMENT if outputImage or dataconditioner handle or roi are NULL, or inputImage is null or invalid.
DW_CUDA_ERROR in case of an underlying cuda failure.
DW_SUCCESS otherwise.

◆ dwDataConditioner_release()

DW_API_PUBLIC dwStatus dwDataConditioner_release ( dwDataConditionerHandle_t obj )

Releases the DataConditioner module.

Parameters

[in] obj The object handle to release.

Returns: DW_INVALID_HANDLE if dataconditioner handle is NULL.
DW_SUCCESS otherwise.

Note: This method renders the handle unusable.

◆ dwDataConditioner_reset()

DW_API_PUBLIC dwStatus dwDataConditioner_reset ( dwDataConditionerHandle_t obj )

Resets the DataConditioner module.

Parameters

[in] obj Specifies the DataConditioner handle to reset.

Returns: DW_INVALID_ARGUMENT if dataconditioner handle is NULL.
DW_SUCCESS otherwise.

◆ dwDataConditioner_setCUDAStream()

DW_API_PUBLIC dwStatus dwDataConditioner_setCUDAStream	(	cudaStream_t	stream,
		dwDataConditionerHandle_t	obj
	)

Sets the CUDA stream for CUDA related operations.

Note: The ownership of the stream remains by the callee.

Parameters

[in]	stream	The CUDA stream to be used. Default is the one passed during dwDataConditioner_initialize.
[in]	obj	A handle to the data conditioner module for which to set CUDA stream.

Returns: DW_INVALID_ARGUMENT if the given dataconditioner handle is NULL.
DW_SUCCESS otherwise.

Detailed Description

Data Structures

Typedefs

Functions

Data Structure Documentation

◆ dwDataConditionerParams

Typedef Documentation

◆ dwDataConditionerHandle_t

Function Documentation

◆ dwDataConditioner_getCUDAStream()

◆ dwDataConditioner_getOutputSize()

◆ dwDataConditioner_initialize()

◆ dwDataConditioner_initializeFromTensorProperties()

◆ dwDataConditioner_initParams()

◆ dwDataConditioner_outputPositionToInput()

◆ dwDataConditioner_prepareData()

◆ dwDataConditioner_prepareDataRaw()

◆ dwDataConditioner_release()

◆ dwDataConditioner_reset()

◆ dwDataConditioner_setCUDAStream()