NVIDIA Tegra
NVIDIA DRIVE OS 5.1 Linux SDK

Developer Guide
5.1.12.0 Release

 
Image LDC (nvmimg_ldc)
 
Architecture
Running the Sample Application
Configuration File Parameters
General configuration parameters
Geometric Transformation Parameters
Feed Sparse Warp Map Parameters
TNR3 Parameters
Runtime Parameters
Command Line Options
Required Options
Other Options
Examples
The NvMedia Image LDC sample application, nvmimg_ldc, demonstrates how to use the NvMedia Lens Distortion Correction (LDC) APIs to perform Geometric Transformation (GEOTRANS) and Temporal Noise Reduction (TNR). The sample uses the NVIDIA® VIC hardware engine.
The application can read YUV files and perform GEOTRANS and/or TNR on input YUV files. It uses a configuration file that specifies various settings. It can also write the output surfaces as YUV files.
Architecture
The application architecture is as follows.
Running the Sample Application
This topic describes how to run the sample application.
To run the sample application
1. Create a configuration file. You can use the sample.conf files packaged in the platform as references.
2. Follow the steps in Building and Running the NvMedia Samples.
3. Launch the application:
$ nvmimg_ldc -cf /path/to/config/file.conf -v 3
Configuration File Parameters
Sample configuration files (.conf files) are available in platform install directory under:
samples/nvmedia/img_ldc/
A configuration file contains parameters with values, groups or sections of parameters, and comments.
General configuration parameters
This table describes the general configuration parameters:
Parameter
Description
Type and Range
numFrames
Number of frames to be processed.
uint: [1,f] where f is the number of frames in the input file]
InputFile
Name of input YUV file.
string: maximum 1024 characters
subSampling
YUV subsampling type of input file. Supported formats are:
• 1: 420
• 2: 422
• 3: 444
• 4: 422R
• 0: NONE
uint: [0,4]
outputFile
Name of output YUV file.
string: maximum 1024 characters
xSobelFile
Outputs an xSobel file.
string: maximum 1024 characters
downSampleFile
Outputs a 4×4 downsampled xSobel file.
string: maximum 1024 characters
bitsPerComponent
Number of bits per component in input/output surfaces.
Supported formats are:
• 1: 8 bits
• 2: 10 bits
• 3: 12 bits
• 4: 14 bits
• 5: 16 bits
• 6: 32 bits
uint: [1,6]
UV order
Order of U and V planes in YUV file.
Supported formats are:
• 0: YVU
• 1: YUV
uint: [0,1]
srcWidth
Width of source surface.
ushort: [64, 16384]
srcHeight
Height of source surface.
ushort: [16, 16384]
srcRectx0
Left X coordinate of source rectangle.
ushort: [0, srcWidth)
srcRecty0
Top Y coordinate of source rectangle.
ushort: [0, srcHeight)
srcRectx1
Right X coordinate of source rectangle.
ushort: [0, srcWidth)
srcRecty1
Bottom Y coordinate of source rectangle.
ushort: [0, srcHeight)
dstWidth
Width of destination surface.
ushort: [64, 16384]
dstHeight
Height of destination surface.
ushort: [16, 16384]
dstRectx0
Left X coordinate of destination rectangle.
ushort: [0, dstWidth)
dstRecty0
Top Y coordinate of destination rectangle.
ushort: [0, dstHeight)
dstRectx1
Right X coordinate of destination rectangle.
ushort: [0, dstWidth)
dstRecty1
Bottom Y coordinate of destination rectangle.
ushort: [0, dstHeight)
ldcMode
LDC Mode. Supported modes are:
• 0: GEOTRANS
• 1: TNR3
• 2: GEOTRANS+TNR3
• 3: TNR2
ushort: [0,3]
 
Geometric Transformation Parameters
This table describes the Geometric Transformation Parameters:
Parameter
Description
Range
geoTransMode
Geometric Transformation mode. Supported values are:
• 0: GEN_MAPPING
• 1: FEED_MAPPING
• 2: AFFINE_TRANSFORM
• 3: PERSPECTIVE_TRANSFORM
uint: [0, 3]
filter
Filter quality. Supported values are:
0: LOW
1: MEDIUM
2: HIGH
uint: [0, 2]
model
Lens Model. Supported values are:
• 0: POLYNOMIAL
• 1: FISHEYE_EQUIDISTANT
• 2: FISHEYE_EQISOLID
• 3: FISHEYE_ORTHOGRAPHIC
• 4: FISHEYE_STEREOGRAPHIC
uint: [0, 4]
k1
k2
k3
k4
k5
k6
Radial distortion coefficients.
float
p1
p2
Tangential distortion coefficients.
float
fx
Fy
Camera focal length in X and Y-axis, measured in pixel units.
float
Cx
Cy
Camera optical center in X and Y-axis, measured in pixel units.
float
R00
R01
R02
R10
R11
R12
R20
R21
R22
Rotation matrix elements.
float
T0
T1
T2
Translation vector elements.
float
targetKfx
targetKfy
Target camera focal length in X and Y-axis, measured in pixel units.
float
targetKcx
targetKcy
Target camera optical center in X and Y-axis, measured in pixel units.
float
ptMatrix00
ptMatrix01
ptMatrix02
ptMatrix10
ptMatrix11
ptMatrix12
ptMatrix20
ptMatrix21
ptMatrix22
Perspective matrix elements.
float
numHorRegion
Number of horizontal regions.
uint: [1, 4]
numVerRegion
Number of vertical regions.
uint: [1, 4]
horRegionWidth0
horRegionWidth1
horRegionWidth2
horRegionWidth3
Widths of regions.
uint
verRegionHeight0
verRegionHeight1
Heights of regions.
uint
log2horSpace0
log2horSpace1
log2horSpace2
log2horSpace3
Horizontal interval between the control points in regions in log2 space.
uint
log2verSpace0
log2verSpace1
log2verSpace2
log2verSpace3
Vertical interval between the control points in regions in log2 space.
uint
bitMaskEnable
Indicates whether to enable the bit mask map.
boolean
bitMaskwidth
Width of the bit mask surface.
uint
bitMaskHeight
Height of the bit mask surface.
uint
bitMaskSurfaceFile
Pathname of a file containing a bit mask map.
string: maximum 1024 characters
maskedPixelFillColor
Indicates whether to fill the masked pixels with specified color.
boolean
maskY
Y channel value of the default color.
float: [0.0,1.0]
maskU
U channel value of the default color.
float: [0.0,1.0]
maskV
V channel value of the default color.
float: [0.0,1.0]
Feed Sparse Warp Map Parameters
This table describes the parameters that specify a user-provided sparse warp map, used for geometric transformation.
Parameter
Description
Range
numHorPoints
Number of control points in each row.
uint
numVerPoints
Number of control points in each column.
uint
mapStride
Number of control points in each stride.
unit
sparseMapFile
Path to the .map file containing the mapping value of each control point.
The size of the file in bytes must be
numVerPoints * numHorPoints * sizeof(float_t) * 2.
string: maximum 1024 characters
dataFormat
Data format of the control points.
Value may be:
• 0: FLOAT
• 1: FIXED_FLOAT_S15_5
uint: [0,1]
TNR3 Parameters
This table describes the geometric transformation parameters. The TNR3 feature is supported only on the Xavier chip.
Parameter
Description
Range
bUpdateTNR3Params
Indicates whether to update the TNR3 parameters for each frame.
boolean
spatialSigmaLuma
-
uint
spatialSigmaChroma
-
uint
rangeSigmaLuma
-
uint
rangeSigmaChroma
-
uint
sadMultiplier
-
float: [0.0,1.0]
sadWeightLuma
-
float: [0.0,1.0]
alphaSmoothEnable
-
boolean
alphaIncreaseCap
-
float: [0.0,1.0]
alphaScaleIIR
-
float: [0.0,1.0]
alphaMaxLuma
-
float: [0.0,1.0]
alphaMinLuma
-
float: [0.0,1.0]
alphaMaxChroma
-
float: [0.0,1.0]
alphaMinChroma
-
float: [0.0,1.0]
betaX1
-
float: [0.0,1.0]
betaX2
-
float: [0.0,1.0]
minBeta
-
float: [0.0,1.0]
maxBeta
-
float: [0.0,1.0]
Runtime Parameters
This table describes the runtime control parameters:
Parameter
Description
Range
bUpdateTNR3Params
Indicates whether to update the TNR3 Parameters for each frame.
boolean
xSobelMode
xSobel Mode. Value may be:
• 0: DISABLE_XSOB_DISABLE_DS
• 1: DISABLE_XSOB_ENABLE_DS
• 2: ENABLE_XSOB_DISABLE_DS
• 3: ENABLE_XSOB_ENABLE_DS
uint: [0,3]
Command Line Options
This is the application’s command syntax:
$ nvmimg_ldc [-h] [-v] [-cf config.conf]
Required Options
This table describes required command line options:
Option
Description
Default
-cf
Specifies the configuration file including its full path.
N/A
Other Options
This table describes optional command line options:
Option
Description
Default
-h
Displays the application’s help text.
N/A
-v <level>
Logging level. Value may be:
• 0: Errors
• 1: Warnings
• 2: Info
• 3: Debug
0
Examples
These examples demonstrate how to call nvimg_ldc to perform various operations.
To correct fisheye distortion using parameterized cameral model
• Enter the command:
$ nvmimg_ldc -cf ldc_GeoTrans.conf -v 3
Geometric transformation is done according to the parameters specified in the configuration file.
To correct fisheye distortion using a user-provided sparse warp map
• Enter the command:
$ nvmimg_ldc -cf ldc_GeoTransFeedMap.conf -v 3
Geometric transformation is done according to the parameters specified in the configuration file.
To perform an inverse perspective transformation (IPT)
• Enter the command:
$ nvmimg_ldc -cf ldc_GeoTransIPT.conf -v 3
Geometric transformation is done according to the parameters specified in the configuration file.
To perform temporal noise reduction (TNR3)
• Enter the command:
$ nvmimg_ldc -cf ldc_TNR3MultiFrame.conf -v 3
TNR3 is done according to the parameters specified in the configuration file.
To perform geometric transformation and TNR
• Enter the command:
$ nvmimg_ldc -cf ldc_GeoTrans_TNR3.conf -v 3
Geometric transformation and TNR are done according to the parameters specified in the configuration file.
To perform temporal noise reduction (TNR2)
• Enter the command:
$ nvmimg_ldc -cf ldc_TNR2MultiFrame.conf -v 3
TNR2 is done according to the parameters specified in the configuration file.