NVIDIA DRIVE OS Linux API Reference

5.1.3.0 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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 Sparse warp map. More...
 
struct  NvMediaLDCCtrlParams
 Holds runtime control parameters for NvMediaLDCProcess(). More...
 

Macros

#define NVMEDIA_LDC_VERSION_MAJOR   1
 Defines the major version number. More...
 
#define NVMEDIA_LDC_VERSION_MINOR   4
 Defines the minor version number. More...
 
#define NVMEDIA_LDC_MAX_HOR_REGION   4u
 Defines the maximum number of horizontal regions. More...
 
#define NVMEDIA_LDC_MAX_VER_REGION   4u
 Defines the aximum number of vertical regions. More...
 
#define NVMEDIA_LDC_MIN_REGION_WIDTH   64u
 Defines the minimum width of horizontal and vertical regions. More...
 
#define NVMEDIA_LDC_MIN_REGION_HEIGHT   16u
 Defines the 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 operate 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 (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 NvMediaLDCCreate (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) NVM_DEPRECATED_MSG("Use NvMediaLDCCreateNew API")
 Creates an NvMedia LDC handle. More...
 
NvMediaStatus NvMediaLDCDestroy (NvMediaLDC *ldc)
 Destroys the NvMedia LDC handle that was created by NvMediaLDCCreate(). More...
 
NvMediaStatus NvMediaLDCFeedSparseWarpMap (NvMediaLDC *ldc, const NvMediaLDCSparseWarpMap *map)
 Feeds sparse warp map to NvMedia LDC. More...
 
NvMediaStatus NvMediaLDCMappingGen (NvMediaLDC *ldc)
 Generates sparse warp mapping based on NvMediaCameraModel. More...
 
NvMediaStatus NvMediaLDCUpdateTNR3Params (NvMediaLDC *ldc, const NvMediaTNR3Params *tnr3Params)
 Updates TNR3 parameters after NvMediaLDCCreate(). More...
 
NvMediaStatus NvMediaLDCProcess (NvMediaLDC *ldc, NvMediaImage *prevSurface, NvMediaImage *curSurface, NvMediaImage *outputSurface, NvMediaImage *xSobel, NvMediaImage *downSample, const NvMediaLDCCtrlParams *ldcCtrlParams)
 Performs the specified LDC operation. More...
 

Macro Definition Documentation

#define NVMEDIA_LDC_MAX_HOR_REGION   4u

Defines the maximum number of horizontal regions.

Definition at line 48 of file nvmedia_ldc.h.

#define NVMEDIA_LDC_MAX_VER_REGION   4u

Defines the aximum number of vertical regions.

Definition at line 51 of file nvmedia_ldc.h.

#define NVMEDIA_LDC_MIN_REGION_HEIGHT   16u

Defines the minimum height of horizontal and vertical regions.

Definition at line 57 of file nvmedia_ldc.h.

#define NVMEDIA_LDC_MIN_REGION_WIDTH   64u

Defines the minimum width of horizontal and vertical regions.

Definition at line 54 of file nvmedia_ldc.h.

#define NVMEDIA_LDC_VERSION_MAJOR   1

Defines the major version number.

Definition at line 38 of file nvmedia_ldc.h.

#define NVMEDIA_LDC_VERSION_MINOR   4

Defines the minor version number.

Definition at line 40 of file nvmedia_ldc.h.

Typedef Documentation

typedef struct NvMediaLDC NvMediaLDC

Defines the NvMedia LDC handle as an opaque struct.

Definition at line 45 of file nvmedia_ldc.h.

Enumeration Type Documentation

Defines geometric transform operate modes.

Enumerator
NVMEDIA_GEOTRANS_MODE_GEN_MAPPING 

Specifies to generate sparse warp map for geometric transform.

NVMEDIA_GEOTRANS_MODE_FEED_MAPPING 

Specifies to take sparse warp map from client via NvMediaLDCFeedSparseWarpMap().

NVMEDIA_GEOTRANS_MODE_AFFINE_TRANSFORM 

Specifies to do affine transform.

NVMEDIA_GEOTRANS_MODE_PERSPECTIVE_TRANSFORM 

Specifies to do perspective transform.

Definition at line 79 of file nvmedia_ldc.h.

Defines the NvMedia LDC Data Format.

Enumerator
NVMEDIA_LDC_DATAFORMAT_FLOAT_T 

standard float_t format

NVMEDIA_LDC_DATAFORMAT_FIXEDFLOAT_S15_5 

S15.5 is the fixed floating format where the data is stored only in the most significant 20 bits of 32bits (4 bytes).

Definition at line 518 of file nvmedia_ldc.h.

Defines the NvMedia LDC operating modes.

Enumerator
NVMEDIA_LDC_MODE_GEOTRANS 

Specifies to do geometric transform.

NVMEDIA_LDC_MODE_TNR3 

Specifies to do temporal noise reduction version 3.

NVMEDIA_LDC_MODE_GEOTRANS_TNR3 

Specifies to do both geometric transform and temporal noise reduction version 3.

NVMEDIA_LDC_MODE_TNR2 

Specifies to do temporal noise reduction version 2.

Definition at line 62 of file nvmedia_ldc.h.

Defines the xSobel working modes.

Enumerator
NVMEDIA_GEOTRANS_DISABLE_XSOBEL_DISABLE_DS 

Specifies to disable both sobel and downsample output.

NVMEDIA_GEOTRANS_DISABLE_XSOBEL_ENABLE_DS 

Specifies to produce luma sobel and luma downsample output.

NVMEDIA_GEOTRANS_ENABLE_XSOBEL_DISABLE_DS 

Specifies to produce gradient sobel and disable downsample output.

NVMEDIA_GEOTRANS_ENABLE_XSOBEL_ENABLE_DS 

Specifies to produce gradient sobel and gradient downsample output.

Definition at line 561 of file nvmedia_ldc.h.

Defines supported lens models.

Enumerator
NVMEDIA_LDC_MODEL_POLYNOMIAL_DISTORTION 

Polynomial distortion model.

NVMEDIA_LDC_MODEL_FISHEYE_EQUIDISTANT 

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 

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 

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 

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 97 of file nvmedia_ldc.h.

Function Documentation

NvMediaStatus NvMediaLDCCreate ( 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/TNR3 depending on the input arguments. A valid NvMedia LDC handle is returned if successful.

Parameters
[out]pldcAn indirect pointer to the NvMediaLDC handle.
[in]srcWidthWidth of the source image.
[in]srcHeightHeight of the source image.
[in]srcRectStructure containing co-ordinates of the rectangle in the source image. Setting srcRect to NULL implies rectangle of full source image size.
[in]dstWidthWidth of the destination image.
[in]dstHeightHeight of the destination image.
[in]dstRectStructure containing co-ordinates of the rectangle in the destination image. Setting dstRect to NULL implies rectangle of full destination image size.
[in]initParamsInitialization parameters of LDC creation. See NvMediaLDCInitParams.
Returns
NvMediaStatus Status indicator. Possible return values are:
NvMediaStatus NvMediaLDCCreateNew ( 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/TNR3 depending on the input arguments. A valid NvMedia LDC handle is returned if successful.

Parameters
[in]devicepointer to the NvMediaDevice handle
[out]pldcAn indirect pointer to the NvMediaLDC handle.
[in]srcWidthWidth of the source image.
[in]srcHeightHeight of the source image.
[in]srcRectStructure containing co-ordinates of the rectangle in the source image. Setting srcRect to NULL implies rectangle of full source image size.
[in]dstWidthWidth of the destination image.
[in]dstHeightHeight of the destination image.
[in]dstRectStructure containing co-ordinates of the rectangle in the destination image. Setting dstRect to NULL implies rectangle of full destination image size.
[in]initParamsInitialization parameters of LDC creation. See NvMediaLDCInitParams.
Returns
NvMediaStatus Status indicator. Possible return values are:
NvMediaStatus NvMediaLDCDestroy ( NvMediaLDC ldc)

Destroys the NvMedia LDC handle that was created by NvMediaLDCCreate().

Frees up the internal resources and handles allocated during NvMediaLDCCreate().

Parameters
[in]ldcHandle to the current context, previously returned by NvMediaLDCCreate().
Returns
NvMediaStatus Status indicator. Possible return values are:
NvMediaStatus NvMediaLDCFeedSparseWarpMap ( NvMediaLDC ldc,
const NvMediaLDCSparseWarpMap map 
)

Feeds sparse warp map to NvMedia LDC.

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

Parameters
[in]ldcHandle to the current context, previously returned by NvMediaLDCCreate().
[in]mapClient-specified sparse warp map, NvMediaLDCSparseWarpMap.
Returns
NvMediaStatus Status indicator. Possible return values are:
NvMediaStatus NvMediaLDCGetVersion ( NvMediaVersion version)

Returns the version information of NvMedia LDC.

Parameters
[in]versionA pointer to a NvMediaVersion structure filled by the NvMedia LDC.
Returns
NvMediaStatus. Return status. Possible values are:
NvMediaStatus NvMediaLDCMappingGen ( NvMediaLDC ldc)

Generates sparse warp mapping based on NvMediaCameraModel.

Must be called when NvMediaGeoTransMode is NVMEDIA_GEOTRANS_MODE_GEN_MAPPING. This is a CPU-based operation.

Parameters
[in]ldcHandle to the current context, previously returned by NvMediaLDCCreate().
Returns
NvMediaStatus Status indicator. Possible return values are:
NvMediaStatus NvMediaLDCProcess ( NvMediaLDC ldc,
NvMediaImage prevSurface,
NvMediaImage curSurface,
NvMediaImage outputSurface,
NvMediaImage xSobel,
NvMediaImage downSample,
const NvMediaLDCCtrlParams ldcCtrlParams 
)

Performs the specified LDC operation.

LDC performs transformations depending onthe GEO mode:

  1. LDC performs 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.

NvMediaImageGetStatus() can be used to check the status of input/output images.

Parameters
[in]ldcNvMediaLDC Handle obtained by call to NvMediaLDCCreate().
[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. Caller must create this surface.
[in,out]xSobelA pointer to the xSobel image output. Caller must create this surface.
[in,out]downSampleA pointer to the downsampled image output. Caller must create this surface.
[in]ldcCtrlParamsA pointer to run-time control parameters.
Returns
A status indicator. Possible values are:
NvMediaStatus NvMediaLDCUpdateTNR3Params ( NvMediaLDC ldc,
const NvMediaTNR3Params tnr3Params 
)

Updates TNR3 parameters after NvMediaLDCCreate().

NvMediaLDCCreate() initializes NvMediaLDC with TNR3 parameters specified as part of NvMediaLDCInitParams. If necessary, this function can be used to update the TNR3 parameters.

Parameters
[in]ldcHandle to the current context, previously returned by NvMediaLDCCreate().
[in]tnr3ParamsPointer to object of type NvMediaTNR3Params.
Returns
NvMediaStatus. Status indicator. Possible values are: