DriveWorks SDK Reference
5.14.77 Release
For Test and Development only

RigTypes.h
Go to the documentation of this file.
1
2//
3// Notice
4// ALL NVIDIA DESIGN SPECIFICATIONS AND CODE ("MATERIALS") ARE PROVIDED "AS IS" NVIDIA MAKES
5// NO REPRESENTATIONS, WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO
6// THE MATERIALS, AND EXPRESSLY DISCLAIMS ANY IMPLIED WARRANTIES OF NONINFRINGEMENT,
7// MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
8//
9// NVIDIA CORPORATION & AFFILIATES assumes no responsibility for the consequences of use of such
10// information or for any infringement of patents or other rights of third parties that may
11// result from its use. No license is granted by implication or otherwise under any patent
12// or patent rights of NVIDIA CORPORATION & AFFILIATES. No third party distribution is allowed unless
13// expressly authorized by NVIDIA. Details are subject to change without notice.
14// This code supersedes and replaces all information previously supplied.
15// NVIDIA CORPORATION & AFFILIATES products are not authorized for use as critical
16// components in life support devices or systems without express written approval of
17// NVIDIA CORPORATION & AFFILIATES.
18//
19// SPDX-FileCopyrightText: Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
20// SPDX-License-Identifier: LicenseRef-NvidiaProprietary
21//
22// NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
23// property and proprietary rights in and to this material, related
24// documentation and any modifications thereto. Any use, reproduction,
25// disclosure or distribution of this material and related documentation
26// without an express license agreement from NVIDIA CORPORATION or
27// its affiliates is strictly prohibited.
28//
30
38#ifndef DW_RIG_RIG_TYPES_H_
39#define DW_RIG_RIG_TYPES_H_
40
41#include <dw/core/base/Types.h>
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
48// Calibrated cameras
49
51#define DW_MAX_RIG_SENSOR_COUNT 128U
52
54#define DW_MAX_RIG_CAMERA_COUNT DW_MAX_RIG_SENSOR_COUNT
55
57#define DW_MAX_RIG_SENSOR_NAME_SIZE 64U
58
60#define DW_MAX_EXTRINSIC_PROFILE_NAME_SIZE 64U
61
63#define DW_MAX_EXTRINSIC_PROFILE_COUNT 3U
64
66#define DW_DEFAULT_EXTRINSIC_PROFILE_INDEX 0U
67
72typedef enum dwCameraModel {
73
77
81#define DW_PINHOLE_DISTORTION_LENGTH 3U
82
83/*
84 * Configuration parameters for a calibrated pinhole camera.
85 *
86 * The (forward) projection of a three-dimensional ray to a two-dimensional pixel coordinate
87 * is performed in three steps:
88 *
89 * **Step 1**: Projection of a ray `(x, y, z)` to normalized image coordinates, i.e.,
90 *
91 * (xn, yn) = (x/z, y/z) .
92 *
93 * **Step 2**: Distortion of the normalized image coordinates by a polynomial with coefficients
94 * `[k_1, k_2, k_3]` given in dwPinholeCameraConfig::distortion, i.e.,
95 *
96 * xd = xn * (1 + k_1 * r^2 + k_2 * r^4 + k_3 * r^6),
97 * yd = yn * (1 + k_1 * r^2 + k_2 * r^4 + k_3 * r^6),
98 *
99 * whereas
100 * r^2 = (xn^2 + yn^2) .
101 *
102 * **Step 3**: Mapping of distorted normalized image coordinates `(xd, yd)` to
103 * pixel coordinates `(u, v)`, i.e.,
104 *
105 * [u] = [focalX 0] * [xd] + [u0]
106 * [v] [0 focalY] [yd] [v0] .
107 */
109{
111 uint32_t width;
112
114 uint32_t height;
115
118
121
124
127
134
138#define DW_FTHETA_POLY_LENGTH 6U
139
157
165
175/*
176 * The camera model is defined by three major components
177 *
178 * - the polynomial `polynomial`
179 * - the principal point `(u0, v0)`, and
180 * - the transformation matrix `A`
181 *
182 *
183 * A = [ c d ]
184 * [ e 1 ] .
185 *
186 * The bottom right element of `A` is implicitly set to 1. This is general enough
187 * for relevant linear transformations because any matrix can be brought into this form
188 * by incorporating an absolute scale into the polynomial.
189 *
190 *
191 * The forward projection of a three-dimensional ray to a two-dimensional pixel coordinates
192 * by means of the FTheta camera model can be described in four steps:
193 *
194 * **Step 1**: Projection of a ray `(x, y, z)` to spherical coordinates `(direction, theta)`:
195 *
196 * direction = (x, y) / norm((x, y))
197 * theta = atan2(norm((x, y)), z)
198 *
199 * **Step 2**: Mapping of the angle `theta` to pixel distances according to the polynomial
200 * coefficients `polynomial` and polynomial type `type` :
201 *
202 * distance = map_angle_to_pixeldistance( polynomial, type, theta )
203 *
204 * **Step 3**: Mapping of `distance` and the two-dimensional `direction` to a pixel offset:
205 *
206 * offset = distance * direction
207 *
208 * **Step 4**: Linear transformation of the two-dimensional pixel offset to pixel coordinate `(u, v)`:
209 *
210 * [u] = [c d] * offset^T + [u0]
211 * [v] [e 1] [v0]
212 *
213 * **optional - step 5**: Tangential distortion
214 *
215 * If `hasTangentials == true` tangential distorion of the coefficients t0 and t1 will be applied.
216 * This is only allowed for cameras with fov < Pi, i.e. z > 0.
217 * Note: Forward/backward tangential coefficients differ numerically. The direction of the tangential contribution is
218 * the same as indicated in "polynomialType"
219 *
220 * [u`] = [u] + (2t0 x/z *y/z + t1/(z**2)(y**2 + 3*x**3))
221 * [v`] = [v] + (2t1 x/z *y/z + t0/(z**2)(x**2 + 3*y**3))
222 *
223 * Conversely, the backward projection of a two-dimensional pixel coordinate to
224 * a three-dimensional ray is performed in four steps reversely to the forward projection:
225 *
226 * **Step 1**: Linear transformation of pixel coordinates `(u, v)` to pixel offset:
227 *
228 * offset = inverse(A) * [u - u0]
229 * [v - v0]
230 * **optional - step 2**: Tangential distortion
231 *
232 * If `hasTangentials == true` tangential distorion of the inverse coefficients t0 and t1 will be applied.
233 * Note: Forward/backward tangential coefficients differ numerically. The direction of the tangential contribution is
234 * the same as indicated in "polynomialType".
235 * The contribution is applied by redefining step 1 as:
236 *
237 *
238 * offset = inverse(A) * [u - u0 - (2t0 u * v + t1(v**2 + 3*u**3)]
239 * [v - v0 - (2t1 u * v + t0(u**2 + 3*v**3)]
240 *
241 * **Step 3**: Mapping of the two-dimensional pixel offset to polar coordinates `(direction, distance)`:
242 *
243 * direction = offset / norm(offset)
244 * distance = norm(offset)
245 *
246 * **Step 4**: Mapping of the pixel distance to the sight ray angle `theta` according to the polynomial
247 * coefficients `polynomial` and the polynomial type `type` :
248 *
249 * theta = map_pixel_distance_to_angle( polynomial, type, distance )
250 *
251 * **Step 5**: Computation of the sight ray `(x, y, z)` based on polar coordinates `(direction, angle)`:
252 *
253 * (x, y) = sin(theta) * direction
254 * z = cos(theta)
255 *
256 *
257 * The functions `map_angle_to_pixel_distance(.)` and `map_pixel_distance_to_angle(.)` depend on the
258 * polynomial coefficients `polynomial` and the type of the polynomial, i.e.,
259 *
260 * - whenever the type of polynomial corresponds to the requested direction,
261 * the function corresponds to a simple evaluation of the polynomial:
262 *
263 * map_a_to_b( polynomial, a_to_b, x ) = polynomial[0] + polynomial[1] * x + ... + polynomial[DW_FTHETA_POLY_LENGTH - 1] * x^(DW_FTHETA_POLY_LENGTH - 1)
264 *
265 * - whenever the type of polynomial is the inverse to the requested direction,
266 * the function is equivalent to the inverse of the polynomial:
267 *
268 * map_a_to_b( polynomial, b_to_a, x ) = y
269 *
270 * with `map_b_to_a( polynomial, b_to_a, y ) == x`.
271 * The solution is computed via iterative local inversion. The valid ranges are defined by the
272 * camera's resolution and field of view.
273 *
274 *
275 * In literature, the closest description is found in [Courbon et al, 2007], TABLE II:
276 *
277 * [Courbon et al, 2007]: Courbon, J., Mezouar, Y., Eckt, L., and Martinet, P. (2007, October).
278 * A generic fisheye camera model for robotic applications. In Intelligent Robots and Systems, 2007.
279 * IROS 2007, pp. 1683–1688.
280 */
282{
284 uint32_t width;
285
287 uint32_t height;
288
300
303
311
314
317
326
333
336
347
350
352
360/*
361 * The model is described by three major components:
362 *
363 * - the image size `(width, height)`,
364 * - the principal point `(u0, v0)`, and
365 * - the horizontal field of view `hFOV`.
366 *
367 *
368 * The horizontal field of view determines the radius `r` of the sphere
369 * used in the projection:
370 *
371 * r = 0.5 / tan(hFOV/4)
372 *
373 * The radius determines
374 *
375 * - the distance of the image plane to the origin of the camera coordinate system and
376 * - the distance of the pole of the projection to the origin of the camera coordinate system.
377 *
378 *
379 * The forward projection of a three-dimensional ray to a two-dimensional pixel coordinate
380 * by means of the stereographic camera model can be described in two steps:
381 *
382 * **Step 1**: Projection of a ray `(x, y, z)` of length 1 onto a normalized coordinate `(xn, yn)`
383 * on the image plane at distance r, i.e.,
384 *
385 * (xn, yn) = 2 * r * (x, y) / (1 + z)
386 *
387 * **Step 2**: Scaling and shift to pixel coordinate `(u, v)`, i.e.,
388 *
389 * u = xn * width / 2 + u0
390 * v = yn * height / 2 + v0
391 *
392 *
393 * Conversely, the backward projection of a two-dimensional pixel coordinate to
394 * a three-dimensional ray is performed in two steps reversely to the forward projection:
395 *
396 * **Step 1**: Scaling and shift of pixel coordinate `(u, v)` to normalized image coordinate `(xn, yn)`, i.e.,
397 *
398 * xn = (u - u0) / (width / 2)
399 * yn = (v - v0) / (height / 2)
400 *
401 * **Step 2**: Projection of normalized image coordinates to three-dimensional unit ray `(x, y, z)`, i.e.,
402 *
403 * (x, y, z) = (4 * r * xn, 4 * r * yn, - xn^2 - yn^2 + 4 * r^2)) / (xn^2 + yn^2 + 4 * r^2)
404 */
406{
408 uint32_t width;
409
411 uint32_t height;
412
415
418
422
426#define DW_WINDSHIELD_HORIZONTAL_POLY_LENGTH 6U
430#define DW_WINDSHIELD_VERTICAL_POLY_LENGTH 15U
431
447
453
454 // polynomial type count
456
460
468/*
469 * The windshield model is defined by two major components
470 * - the horizontal polynomial
471 * - the vertical polynomial
472 *
473 *
474 * The forward mapping of a three-dimensional ray(x,y,z) to a distorted three-dimensional ray (x',y',z')
475 * by means of the windshield model can be described as below:
476 *
477 * **Step 1**: conversion of a ray `(x, y, z)` to `(phi, theta)` defined as below:
478 *
479 * phi = asin(x/norm((x, y, z))
480 * theta = asin(y/norm((x, y, z))
481 *
482 * **Step 2**: Mapping of the angle phi to phi', theta to theta' according to the 2D polynomial
483 * coefficients `polynomial` and polynomial type `type` :
484 *
485 * phi' = windshield_horizontal_mapping( polynomial, type, phi )
486 * theta' = windshield_vertical_mapping( polynomial, type, theta )
487 *
488 * **Step 3**: Inverse conversion of the ray from (phi', theta') to a ray (x',y',z'):
489 * x' = sin(phi')
490 * y' = sin(theta')
491 * z' = sqrt(1 - x'^2 -y'^2)
492 */
494{
506
518
526
530#define DW_RADAR_AZIMUTH_CORRECTION_TABLE_MAX_LENGTH 161U
531
546{
549
552
555
558
561
565
566#ifdef __cplusplus
567}
568#endif
569
570#endif // DW_RIG_RIG_TYPES_H_
uint32_t width
Width of the image (in pixels)
Definition: RigTypes.h:284
float32_t u0
U coordinate for the principal point (in pixels)
Definition: RigTypes.h:117
float32_t focalY
Focal length in the Y axis (in pixels)
Definition: RigTypes.h:126
float32_t v0
V coordinate for the principal point (in pixels)
Definition: RigTypes.h:120
dwWindshieldPolynomialType
Type of polynomial stored in Windshield Model.
Definition: RigTypes.h:441
@ DW_WINDSHIELD_POLYNOMIAL_TYPE_BACKWARD
Backward polynomial type, mapping ray distortion by windshield from the camera side to non-camera sid...
Definition: RigTypes.h:452
@ DW_WINDSHIELD_POLYNOMIAL_TYPE_FORWARD
Forward polynomial type, mapping ray distortion by windshield from the non camera side to camera side...
Definition: RigTypes.h:446
@ DW_WINDSHIELD_POLYNOMIAL_TYPE_FORCE_32
Force enum to be 32 bits.
Definition: RigTypes.h:458
@ DW_WINDSHIELD_POLYNOMIAL_TYPE_COUNT
Definition: RigTypes.h:455
float32_t phiMinRad
Minimum azimuth angle of FOV [rad].
Definition: RigTypes.h:548
float32_t stddevRad[DW_RADAR_AZIMUTH_CORRECTION_TABLE_MAX_LENGTH]
Standard deviation of correction function at support i [rad].
Definition: RigTypes.h:563
float32_t e
Linear pixel transformation coefficient e (bottom left element).
Definition: RigTypes.h:316
uint32_t width
Width of the image (in pixels)
Definition: RigTypes.h:111
float32_t distortion[DW_PINHOLE_DISTORTION_LENGTH]
Polynomial coefficients [k_1, k_2, k_3] that allow to map undistored, normalized image coordinates (x...
Definition: RigTypes.h:132
float32_t focalX
Focal length in the X axis (in pixels)
Definition: RigTypes.h:123
float32_t u0
U coordinate for the principal point (in pixels)
Definition: RigTypes.h:414
float32_t correctionsRad[DW_RADAR_AZIMUTH_CORRECTION_TABLE_MAX_LENGTH]
Values of correction function at support i [rad].
Definition: RigTypes.h:560
float32_t phiMaxRad
Maximum azimuth angle of FOV [rad].
Definition: RigTypes.h:551
float32_t v0
V coordinate for the principal point (in pixels)
Definition: RigTypes.h:302
dwCameraModel
Specifies the supported optical camera models.
Definition: RigTypes.h:72
@ DW_CAMERA_MODEL_FTHETA
Definition: RigTypes.h:75
@ DW_CAMERA_MODEL_PINHOLE
Definition: RigTypes.h:74
float32_t c
Linear pixel transformation matrix coefficient c (top left element) If all c, d, and e are set to 0....
Definition: RigTypes.h:310
float32_t u0
Principal point coordinates: indicating the horizontal / vertical image coordinates of the principal ...
Definition: RigTypes.h:299
#define DW_FTHETA_POLY_LENGTH
Defines the number of distortion coefficients for the ftheta camera model.
Definition: RigTypes.h:138
uint32_t height
Height of the image (in pixels)
Definition: RigTypes.h:114
uint32_t width
Width of the image (in pixels)
Definition: RigTypes.h:408
uint32_t height
Height of the image (in pixels)
Definition: RigTypes.h:287
float32_t t1
1st tangential contribution
Definition: RigTypes.h:349
float32_t horizontalPolynomial[DW_WINDSHIELD_HORIZONTAL_POLY_LENGTH]
Windshield polynomial describing the mapping of horizontal angle(phi) from ray-from-object to ray-int...
Definition: RigTypes.h:505
bool hasTangentials
Indicates if the camera has a tangential contribution.
Definition: RigTypes.h:335
float32_t v0
V coordinate for the principal point (in pixels)
Definition: RigTypes.h:417
#define DW_PINHOLE_DISTORTION_LENGTH
Defines the number of distortion coefficients for the pinhole camera model.
Definition: RigTypes.h:81
#define DW_WINDSHIELD_VERTICAL_POLY_LENGTH
Defines the number of coefficients for the windshield parameters in the vertical direction.
Definition: RigTypes.h:430
float32_t verticalPolynomial[DW_WINDSHIELD_VERTICAL_POLY_LENGTH]
Windshield polynomial describing the mapping of vertical angle(theta) from ray-from-object to ray-int...
Definition: RigTypes.h:517
float32_t d
Linear pixel transformation coefficient d (top right element).
Definition: RigTypes.h:313
dwFThetaCameraPolynomialType
Type of polynomial stored in FTheta.
Definition: RigTypes.h:150
@ DW_FTHETA_CAMERA_POLYNOMIAL_TYPE_PIXELDISTANCE_TO_ANGLE
Backward polynomial type, mapping pixel distances (offset from principal point) to angles (angle betw...
Definition: RigTypes.h:156
@ DW_FTHETA_CAMERA_POLYNOMIAL_TYPE_ANGLE_TO_PIXELDISTANCE
Forward polynomial type, mapping angles (angle between ray and forward direction) to pixel distances ...
Definition: RigTypes.h:163
float32_t deltaPhiRad
Equidistant spacing between supports [rad].
Definition: RigTypes.h:554
#define DW_WINDSHIELD_HORIZONTAL_POLY_LENGTH
Defines the number of coefficients for the windshield parameters in the horizontal direction.
Definition: RigTypes.h:426
float32_t t0
Tangential contribution describing an non radial symmetric distortion effect coming from a rotational...
Definition: RigTypes.h:346
float32_t polynomial[DW_FTHETA_POLY_LENGTH]
Polynomial describing either the mapping of angles to pixel-distances or the mapping of pixel-distanc...
Definition: RigTypes.h:325
dwFThetaCameraPolynomialType polynomialType
Defines whether the polynomial parameter either map angles to pixel-distances (called forward directi...
Definition: RigTypes.h:332
float32_t hFOV
Horizontal FOV (in radians)
Definition: RigTypes.h:420
uint32_t numCorrections
Number of correction values/supports.
Definition: RigTypes.h:557
#define DW_RADAR_AZIMUTH_CORRECTION_TABLE_MAX_LENGTH
Defines the maximum number of supports of the radar azimuth angle correction model.
Definition: RigTypes.h:530
dwWindshieldPolynomialType polynomialType
Defines whether the polynomial parameter either map a ray from non-camera side to camera side (called...
Definition: RigTypes.h:524
uint32_t height
Height of the image (in pixels)
Definition: RigTypes.h:411
Configuration parameters for a calibrated FTheta camera.
Definition: RigTypes.h:282
Configuration parameters for a radar azimuth correction model.
Definition: RigTypes.h:546
Configuration parameters for a calibrated stereographic camera.
Definition: RigTypes.h:406
Configuration parameters for a calibrated windshield model.
Definition: RigTypes.h:494
NVIDIA DriveWorks API: Core Types
float float32_t
Specifies POD types.
Definition: BasicTypes.h:59