NVIDIA DRIVE OS Linux SDK API Reference

5.1.15.0 Release
For Test and Development only
Lens Distortion Correction

Detailed Description

The NvMedia Lens Distortion Correction (LDC) API contains NvMedia functions for accessing the LDC hardware engine for geometric transform and temporal noise reduction (TNR3).

Data Structures

struct  NvMediaCamIntriParams
 Holds NvMedia camera intrinsic parameters. More...
 
struct  NvMediaLensDistortion
 Holds distortion coefficients for the lens model. More...
 
struct  NvMediaCameraModel
 Holds NvMedia LDC camera parameter info. More...
 
struct  NvMediaLDCRegionConfig
 Holds the NvMedia LDC region configuration. More...
 
struct  NvMediaLDCBitMaskMap
 Holds the NvMedia mask map surface. More...
 
struct  NvMediaGeoTransParams
 Holds geometric transform initialization paramters. More...
 
struct  NvMediaTNR3Params
 Holds the TNR3 initialization paramters. More...
 
struct  NvMediaTNR2Params
 Holds the TNR2 initialization paramters. More...
 
struct  NvMediaLDCInitParams
 Holds the NvMedia LDC initialization paramters. More...
 
struct  NvMediaLDCSparseWarpMap
 Holds the NvMedia LDC defintion of a sparse warp map. More...
 
struct  NvMediaLDCCtrlParams
 Holds runtime control parameters for NvMediaLDCProcess(). More...
 

Macros

#define NVMEDIA_LDC_VERSION_MAJOR   2
 Major version number. More...
 
#define NVMEDIA_LDC_VERSION_MINOR   1
 Minor version number. More...
 
#define NVMEDIA_LDC_MAX_HOR_REGION   4u
 Maximum number of horizontal regions. More...
 
#define NVMEDIA_LDC_MAX_VER_REGION   4u
 Maximum number of vertical regions. More...
 
#define NVMEDIA_LDC_MIN_REGION_WIDTH   64u
 Minimum width of horizontal and vertical regions. More...
 
#define NVMEDIA_LDC_MIN_REGION_HEIGHT   16u
 Minimum height of horizontal and vertical regions. More...
 

Typedefs

typedef struct NvMediaLDC NvMediaLDC
 Defines the NvMedia LDC handle as an opaque struct. More...
 

Enumerations

enum  NvMediaLDCMode {
  NVMEDIA_LDC_MODE_GEOTRANS,
  NVMEDIA_LDC_MODE_TNR3,
  NVMEDIA_LDC_MODE_GEOTRANS_TNR3,
  NVMEDIA_LDC_MODE_TNR2
}
 Defines the NvMedia LDC operating modes. More...
 
enum  NvMediaGeoTransMode {
  NVMEDIA_GEOTRANS_MODE_GEN_MAPPING = 0,
  NVMEDIA_GEOTRANS_MODE_FEED_MAPPING,
  NVMEDIA_GEOTRANS_MODE_AFFINE_TRANSFORM,
  NVMEDIA_GEOTRANS_MODE_PERSPECTIVE_TRANSFORM
}
 Defines geometric transform operation modes. More...
 
enum  NvMediaLensModel {
  NVMEDIA_LDC_MODEL_POLYNOMIAL_DISTORTION,
  NVMEDIA_LDC_MODEL_FISHEYE_EQUIDISTANT,
  NVMEDIA_LDC_MODEL_FISHEYE_EQUISOLID,
  NVMEDIA_LDC_MODEL_FISHEYE_ORTHOGRAPHIC,
  NVMEDIA_LDC_MODEL_FISHEYE_STEREOGRAPHIC
}
 Defines supported lens models. More...
 
enum  NvMediaLDCDataFormat {
  NVMEDIA_LDC_DATAFORMAT_FLOAT_T,
  NVMEDIA_LDC_DATAFORMAT_FIXEDFLOAT_S15_5
}
 Defines the NvMedia LDC Data Format. More...
 
enum  NvMediaLDCSobelMode {
  NVMEDIA_GEOTRANS_DISABLE_XSOBEL_DISABLE_DS = 0,
  NVMEDIA_GEOTRANS_DISABLE_XSOBEL_ENABLE_DS,
  NVMEDIA_GEOTRANS_ENABLE_XSOBEL_DISABLE_DS,
  NVMEDIA_GEOTRANS_ENABLE_XSOBEL_ENABLE_DS
}
 Defines the xSobel working modes. More...
 

Functions

NvMediaStatus NvMediaLDCGetVersion (NvMediaVersion *version)
 Returns the version information of NvMedia LDC. More...
 
NvMediaStatus NvMediaLDCCreateNew (const NvMediaDevice *device, NvMediaLDC **pldc, const uint16_t srcWidth, const uint16_t srcHeight, const NvMediaRect *srcRect, const uint16_t dstWidth, const uint16_t dstHeight, const NvMediaRect *dstRect, const NvMediaLDCInitParams *initParams)
 Creates an NvMedia LDC handle. More...
 
NvMediaStatus NvMediaLDCDestroy (NvMediaLDC *ldc)
 Destroys an NvMedia LDC handle that was created by a call to NvMediaLDCCreateNew(). More...
 
NvMediaStatus NvMediaLDCFeedSparseWarpMap (NvMediaLDC *ldc, const NvMediaLDCSparseWarpMap *map)
 Feeds a sparse warp map to NvMedia LDC. More...
 
NvMediaStatus NvMediaLDCMappingGen (NvMediaLDC *ldc)
 Generates a sparse warp mapping based on NvMediaCameraModel. More...
 
NvMediaStatus NvMediaLDCUpdateTNR3Params (const NvMediaLDC *ldc, const NvMediaTNR3Params *tnr3Params)
 Updates TNR3 parameters after a call to NvMediaLDCCreateNew(). More...
 
NvMediaStatus NvMediaLDCProcess (const NvMediaLDC *ldc, NvMediaImage *prevSurface, NvMediaImage *curSurface, NvMediaImage *outputSurface, NvMediaImage *xSobel, NvMediaImage *downSample, const NvMediaLDCCtrlParams *ldcCtrlParams)
 Performs a specified LDC operation. More...
 

Macro Definition Documentation

◆ NVMEDIA_LDC_MAX_HOR_REGION

#define NVMEDIA_LDC_MAX_HOR_REGION   4u

Maximum number of horizontal regions.

Definition at line 50 of file nvmedia_ldc.h.

◆ NVMEDIA_LDC_MAX_VER_REGION

#define NVMEDIA_LDC_MAX_VER_REGION   4u

Maximum number of vertical regions.

Definition at line 53 of file nvmedia_ldc.h.

◆ NVMEDIA_LDC_MIN_REGION_HEIGHT

#define NVMEDIA_LDC_MIN_REGION_HEIGHT   16u

Minimum height of horizontal and vertical regions.

Definition at line 59 of file nvmedia_ldc.h.

◆ NVMEDIA_LDC_MIN_REGION_WIDTH

#define NVMEDIA_LDC_MIN_REGION_WIDTH   64u

Minimum width of horizontal and vertical regions.

Definition at line 56 of file nvmedia_ldc.h.

◆ NVMEDIA_LDC_VERSION_MAJOR

#define NVMEDIA_LDC_VERSION_MAJOR   2

Major version number.

Definition at line 40 of file nvmedia_ldc.h.

◆ NVMEDIA_LDC_VERSION_MINOR

#define NVMEDIA_LDC_VERSION_MINOR   1

Minor version number.

Definition at line 42 of file nvmedia_ldc.h.

Typedef Documentation

◆ NvMediaLDC

typedef struct NvMediaLDC NvMediaLDC

Defines the NvMedia LDC handle as an opaque struct.

Definition at line 47 of file nvmedia_ldc.h.

Enumeration Type Documentation

◆ NvMediaGeoTransMode

Defines geometric transform operation modes.

Enumerator
NVMEDIA_GEOTRANS_MODE_GEN_MAPPING 

Specifies generating a sparse warp map for geometric transform.

NVMEDIA_GEOTRANS_MODE_FEED_MAPPING 

Specifies taking a sparse warp map from client via NvMediaLDCFeedSparseWarpMap().

NVMEDIA_GEOTRANS_MODE_AFFINE_TRANSFORM 

Specifies performing an affine transform.

NVMEDIA_GEOTRANS_MODE_PERSPECTIVE_TRANSFORM 

Specifies performing a perspective transform.

Definition at line 82 of file nvmedia_ldc.h.

◆ NvMediaLDCDataFormat

Defines the NvMedia LDC Data Format.

Enumerator
NVMEDIA_LDC_DATAFORMAT_FLOAT_T 

Specifies standard float_t format.

NVMEDIA_LDC_DATAFORMAT_FIXEDFLOAT_S15_5 

Specifies S15.5 fixed floating format.

Data is stored only in the most significant 20 bits of a 32-bit (four-byte) value.

Definition at line 531 of file nvmedia_ldc.h.

◆ NvMediaLDCMode

Defines the NvMedia LDC operating modes.

Enumerator
NVMEDIA_LDC_MODE_GEOTRANS 

Specifies geometric transform mode.

NVMEDIA_LDC_MODE_TNR3 

Specifies temporal noise reduction version 3 mode.

NVMEDIA_LDC_MODE_GEOTRANS_TNR3 

Specifies both geometric transform mode and temporal noise reduction version 3 mode.

NVMEDIA_LDC_MODE_TNR2 

Specifies temporal noise reduction version 2 mode.

Definition at line 64 of file nvmedia_ldc.h.

◆ NvMediaLDCSobelMode

Defines the xSobel working modes.

Enumerator
NVMEDIA_GEOTRANS_DISABLE_XSOBEL_DISABLE_DS 

Specifies disabling both Sobel and downsample output.

NVMEDIA_GEOTRANS_DISABLE_XSOBEL_ENABLE_DS 

Specifies producing luma Sobel and luma downsample output.

NVMEDIA_GEOTRANS_ENABLE_XSOBEL_DISABLE_DS 

Specifies producing gradient Sobel and disable downsample output.

NVMEDIA_GEOTRANS_ENABLE_XSOBEL_ENABLE_DS 

Specifies producing gradient Sobel and gradient downsample output.

Definition at line 576 of file nvmedia_ldc.h.

◆ NvMediaLensModel

Defines supported lens models.

Enumerator
NVMEDIA_LDC_MODEL_POLYNOMIAL_DISTORTION 

Specifies a polynomial distortion model.

NVMEDIA_LDC_MODEL_FISHEYE_EQUIDISTANT 

Specifies a fisheye model: r = 2ftan(theta/2), where theta is the angle from the optical axis, f is the focal length, and r is the distance of a pixel from the image center.

NVMEDIA_LDC_MODEL_FISHEYE_EQUISOLID 

Specifies a fisheye model: r = f*theta, where theta is the angle from the optical axis, f is the focal length, and r is the distance of a pixel from the image center.

NVMEDIA_LDC_MODEL_FISHEYE_ORTHOGRAPHIC 

Specifies a fisheye model: r = 2fsin(theta/2), where theta is the angle from the optical axis, f is the focal length, and r is the distance of a pixel from the image center.

NVMEDIA_LDC_MODEL_FISHEYE_STEREOGRAPHIC 

Specifies a fisheye model: r = fsin(theta), where theta is the angle from the optical axis, f is the focal length, and r is the distance of a pixel from the image center.

Definition at line 100 of file nvmedia_ldc.h.

Function Documentation

◆ NvMediaLDCCreateNew()

NvMediaStatus NvMediaLDCCreateNew ( const NvMediaDevice device,
NvMediaLDC **  pldc,
const uint16_t  srcWidth,
const uint16_t  srcHeight,
const NvMediaRect srcRect,
const uint16_t  dstWidth,
const uint16_t  dstHeight,
const NvMediaRect dstRect,
const NvMediaLDCInitParams initParams 
)

Creates an NvMedia LDC handle.

The function creates and initializes the appropriate internal infrastructure for LDC or TNR3, depending on the input arguments. It returns a valid NvMedia LDC handle if successful.

Parameters
[in]deviceAn NvMediaDevice handle.
[out]pldcA pointer to an LDC handle.
[in]srcWidthWidth of the source image.
[in]srcHeightHeight of the source image.
[in]srcRectA pointer to coordinates of the rectangle in the source image. Set to NULL to specify a rectangle of full source image size.
[in]dstWidthWidth of the destination image.
[in]dstHeightHeight of the destination image.
[in]dstRectA pointer to coordinates of the rectangle in the destination image. Set to NULL to specify a rectangle of full destination image size. DestRect's top and left corner is limited to (0,0).
[in]initParamsA pointer to initialization parameters for creating an instance of LDC. See NvMediaLDCInitParams.
Return values
NVMEDIA_STATUS_OKindicates that the operation was successful. pldc points to a valid LDC handle.
NVMEDIA_STATUS_NOT_INITIALIZEDindicates that the device handle was in an invalid state.
NVMEDIA_STATUS_BAD_PARAMETERindicates that one or more parameters were invalid.
NVMEDIA_STATUS_NOT_SUPPORTEDindicates that the operation is not supported in the current configuration.
NVMEDIA_STATUS_OUT_OF_MEMORYindicates that there was insufficient memory to perform the operation.

◆ NvMediaLDCDestroy()

NvMediaStatus NvMediaLDCDestroy ( NvMediaLDC ldc)

Destroys an NvMedia LDC handle that was created by a call to NvMediaLDCCreateNew().

This function frees internal resources and handles allocated by NvMediaLDCCreateNew().

Parameters
[in]ldcA handle to the current context, returned by NvMediaLDCCreateNew().
Return values
NVMEDIA_STATUS_OKindicates that the operation was successful. The handle ldc was destroyed.
NVMEDIA_STATUS_NOT_INITIALIZEDindicates that the device handle was in an invalid state.
NVMEDIA_STATUS_BAD_PARAMETERindicates that ldc is not a valid LDC handle.
NVMEDIA_STATUS_ERRORindicates that one or more objects were unregistered.

◆ NvMediaLDCFeedSparseWarpMap()

NvMediaStatus NvMediaLDCFeedSparseWarpMap ( NvMediaLDC ldc,
const NvMediaLDCSparseWarpMap map 
)

Feeds a sparse warp map to NvMedia LDC.

NvMediaGeoTransMode must be NVMEDIA_GEOTRANS_MODE_FEED_MAPPING when this function is called. The sparse warp map must match the NvMediaLDCRegionConfig.

Parameters
[in]ldcA handle to the current context, returned by NvMediaLDCCreateNew().
[in]mapA pointer to a client-specified sparse warp map.
Return values
NVMEDIA_STATUS_OKindicates that the operation was successful.
NVMEDIA_STATUS_NOT_INITIALIZEDindicates that the current context was in an invalid state.
NVMEDIA_STATUS_BAD_PARAMETERindicates that one or more parameters were invalid.
NVMEDIA_STATUS_NOT_SUPPORTEDindicates that the operation is not supported in the current configuration.
NVMEDIA_STATUS_OUT_OF_MEMORYindicates that there was insufficient memory to perform the operation.

◆ NvMediaLDCGetVersion()

NvMediaStatus NvMediaLDCGetVersion ( NvMediaVersion version)

Returns the version information of NvMedia LDC.

Parameters
[in]versionA pointer to a structure to be filled by the NvMedia LDC.
Returns
A status code; NVMEDIA_STATUS_OK if successful, or NVMEDIA_STATUS_BAD_PARAMETER if version is invalid.

◆ NvMediaLDCMappingGen()

NvMediaStatus NvMediaLDCMappingGen ( NvMediaLDC ldc)

Generates a sparse warp mapping based on NvMediaCameraModel.

NvMediaGeoTransMode must be NVMEDIA_GEOTRANS_MODE_GEN_MAPPING when this function is called.

This is a CPU-based operation.

Parameters
[in]ldcA handle to the current context, returned by NvMediaLDCCreateNew().
Return values
NVMEDIA_STATUS_OKindicates that the operation was successful.
NVMEDIA_STATUS_NOT_INITIALIZEDindicates that the current context was in an invalid state.
NVMEDIA_STATUS_BAD_PARAMETERindicates that ldc was invalid.
NVMEDIA_STATUS_NOT_SUPPORTEDindicates that the operation is not supported in the current configuration.

◆ NvMediaLDCProcess()

NvMediaStatus NvMediaLDCProcess ( const NvMediaLDC ldc,
NvMediaImage prevSurface,
NvMediaImage curSurface,
NvMediaImage outputSurface,
NvMediaImage xSobel,
NvMediaImage downSample,
const NvMediaLDCCtrlParams ldcCtrlParams 
)

Performs a specified LDC operation.

LDC performs transformations depending on the GEO mode:

  1. LDC performs a geometric transformation if NvMediaLDCInitParams::ldcMode is NVMEDIA_LDC_MODE_GEOTRANS or NVMEDIA_LDC_MODE_GEOTRANS_TNR3. It uses NvMediaLDCInitParams::geoTransParams to fetch the pixel defined by srcRect in the source image and renders onto the destination rectangle of the destination image.

    The source image and the destination image must have the same format.

    LDC bypasses the transform stage if geometric transform is disabled.

    The region of interest in the destination image is defined by:

  2. LDC outputs xSobel if:
  3. LDC outputs 4x4 downsampled xSobel output if:

If NvMediaLDCInitParams::ldcMode is NVMEDIA_LDC_MODE_TNR3 or NVMEDIA_LDC_MODE_GEOTRANS_TNR3, LDC performs temporal noise reduction.

NvMediaLDCProcess() is a non-blocking call.

Use NvMediaImageGetStatus() to check the status of input/output images.

Parameters
[in]ldcAn LDC handle, obtained by a call to NvMediaLDCCreateNew().
[in]prevSurfaceA pointer to the previous image output. Used only when NvMediaLDCInitParams::ldcMode is NVMEDIA_LDC_MODE_GEOTRANS_TNR3 or NVMEDIA_LDC_MODE_TNR3.
[in]curSurfaceA pointer to the source image.
[in,out]outputSurfaceA pointer to the output image. The application must create this surface.
[in,out]xSobelA pointer to the xSobel image output. The application must create this surface.
[in,out]downSampleA pointer to the downsampled image output. The application must create this surface.
[in]ldcCtrlParamsA pointer to run-time control parameters.
Return values
NVMEDIA_STATUS_OKindicates that the operation was successful.
NVMEDIA_STATUS_NOT_INITIALIZEDindicates that the current context was in an invalid state.
NVMEDIA_STATUS_BAD_PARAMETERindicates that one or more parameters were invalid.
NVMEDIA_STATUS_NOT_SUPPORTEDindicates that the operation is not supported in the current configuration.
NVMEDIA_STATUS_OUT_OF_MEMORYindicates that there was insufficient memory to perform the operation.
NVMEDIA_STATUS_ERRORindicates that some other error occurred.

◆ NvMediaLDCUpdateTNR3Params()

NvMediaStatus NvMediaLDCUpdateTNR3Params ( const NvMediaLDC ldc,
const NvMediaTNR3Params tnr3Params 
)

Updates TNR3 parameters after a call to NvMediaLDCCreateNew().

NvMediaLDCCreateNew() initializes NvMediaLDC with TNR3 parameters specified as part of NvMediaLDCInitParams.

This function can be used to update the TNR3 parameters if necessary.

Parameters
[in]ldcA handle to the current context, returned by NvMediaLDCCreateNew().
[in]tnr3ParamsA pointer to an object which holds TNR3 parameters.
Returns
NvMediaStatus. Status indicator.
Return values
NVMEDIA_STATUS_OKindicates that the operation was successful.
NVMEDIA_STATUS_NOT_INITIALIZEDindicates that the current context was in an invalid state.
NVMEDIA_STATUS_BAD_PARAMETERindicates that one or more parameters were invalid.
NVMEDIA_STATUS_NOT_SUPPORTEDindicates that the operation is not supported in the current configuration.