Rig.h

Go to the documentation of this file.

 
//
// Notice
// ALL NVIDIA DESIGN SPECIFICATIONS AND CODE ("MATERIALS") ARE PROVIDED "AS IS" NVIDIA MAKES
// NO REPRESENTATIONS, WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO
// THE MATERIALS, AND EXPRESSLY DISCLAIMS ANY IMPLIED WARRANTIES OF NONINFRINGEMENT,
// MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
//
// NVIDIA CORPORATION & AFFILIATES assumes no responsibility for the consequences of use of such
// information or for any infringement of patents or other rights of third parties that may
// result from its use. No license is granted by implication or otherwise under any patent
// or patent rights of NVIDIA CORPORATION & AFFILIATES. No third party distribution is allowed unless
// expressly authorized by NVIDIA. Details are subject to change without notice.
// This code supersedes and replaces all information previously supplied.
// NVIDIA CORPORATION & AFFILIATES products are not authorized for use as critical
// components in life support devices or systems without express written approval of
// NVIDIA CORPORATION & AFFILIATES.
//
// SPDX-FileCopyrightText: Copyright (c) 2015-2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: LicenseRef-NvidiaProprietary
//
// NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
// property and proprietary rights in and to this material, related
// documentation and any modifications thereto. Any use, reproduction,
// disclosure or distribution of this material and related documentation
// without an express license agreement from NVIDIA CORPORATION or
// its affiliates is strictly prohibited.
//
 
#ifndef DW_RIG_RIG_H_
#define DW_RIG_RIG_H_
 
#include <dw/core/base/Config.h>
#include <dw/core/base/Exports.h>
#include <dw/core/context/Context.h>
#include <dw/core/base/Types.h>
#include <dw/sensors/Sensors.h>
#include <dw/rig/Vehicle.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef struct dwRigObject* dwRigHandle_t;
typedef struct dwRigObject const* dwConstRigHandle_t;
 
// Calibrated cameras
 
#define DW_MAX_RIG_SENSOR_COUNT 128U
 
#define DW_MAX_RIG_CAMERA_COUNT DW_MAX_RIG_SENSOR_COUNT
 
#define DW_MAX_RIG_SENSOR_NAME_SIZE 64U
 
#define DW_MAX_EXTRINSIC_PROFILE_NAME_SIZE 64U
 
#define MAX_EXTRINSIC_PROFILE_COUNT 3U
 
typedef enum dwCameraModel {
 
    DW_CAMERA_MODEL_PINHOLE = 1,
    DW_CAMERA_MODEL_FTHETA  = 2
} dwCameraModel;
 
#define DW_PINHOLE_DISTORTION_LENGTH 3U
 
/*
 * Configuration parameters for a calibrated pinhole camera.
 *
 * The (forward) projection of a three-dimensional ray to a two-dimensional pixel coordinate
 * is performed in three steps:
 *
 * **Step 1**: Projection of a ray `(x, y, z)` to normalized image coordinates, i.e.,
 *
 *     (xn, yn) = (x/z, y/z) .
 *
 * **Step 2**: Distortion of the normalized image coordinates by a polynomial with coefficients
 * `[k_1, k_2, k_3]` given in dwPinholeCameraConfig::distortion, i.e.,
 *
 *     xd = xn * (1 + k_1 * r^2 + k_2 * r^4 + k_3 * r^6),
 *     yd = yn * (1 + k_1 * r^2 + k_2 * r^4 + k_3 * r^6),
 *
 * whereas
 *     r^2 = (xn^2 + yn^2) .
 *
 * **Step 3**: Mapping of distorted normalized image coordinates `(xd, yd)` to
 * pixel coordinates `(u, v)`, i.e.,
 *
 *     [u] =  [focalX   0] * [xd] + [u0]
 *     [v]    [0   focalY]   [yd]   [v0] .
 */
typedef struct dwPinholeCameraConfig
{
    uint32_t width;
 
    uint32_t height;
 
    float32_t u0;
 
    float32_t v0;
 
    float32_t focalX;
 
    float32_t focalY;
 
    float32_t distortion[DW_PINHOLE_DISTORTION_LENGTH];
} dwPinholeCameraConfig;
 
#define DW_FTHETA_POLY_LENGTH 6U
 
typedef struct dwFThetaCameraConfig
{
    uint32_t width;
 
    uint32_t height;
 
    float32_t u0;
 
    float32_t v0;
 
    float32_t backwardsPoly[DW_FTHETA_POLY_LENGTH];
} dwFThetaCameraConfig;
 
typedef enum dwFThetaCameraPolynomialType {
    DW_FTHETA_CAMERA_POLYNOMIAL_TYPE_PIXELDISTANCE_TO_ANGLE = 0,
 
    DW_FTHETA_CAMERA_POLYNOMIAL_TYPE_ANGLE_TO_PIXELDISTANCE,
} dwFThetaCameraPolynomialType;
 
/*
 * The camera model is defined by three major components
 *
 *  - the polynomial `polynomial`
 *  - the principal point `(u0, v0)`, and
 *  - the transformation matrix `A`
 *
 *
 *     A  =  [ c  d ]
 *           [ e  1 ] .
 *
 * The bottom right element of `A` is implicitly set to 1. This is general enough
 * for relevant linear transformations because any matrix can be brought into this form
 * by incorporating an absolute scale into the polynomial.
 *
 *
 * The forward projection of a three-dimensional ray to a two-dimensional pixel coordinates
 * by means of the FTheta camera model can be described in four steps:
 *
 * **Step 1**: Projection of a ray `(x, y, z)` to spherical coordinates `(direction, theta)`:
 *
 *     direction = (x, y) / norm((x, y))
 *     theta = atan2(norm((x, y)), z)
 *
 * **Step 2**: Mapping of the angle `theta` to pixel distances according to the polynomial
 * coefficients `polynomial` and polynomial type `type` :
 *
 *     distance = map_angle_to_pixeldistance( polynomial, type, theta )
 *
 * **Step 3**: Mapping of `distance` and the two-dimensional `direction` to a pixel offset:
 *
 *     offset = distance * direction
 *
 * **Step 4**: Linear transformation of the two-dimensional pixel offset to pixel coordinate `(u, v)`:
 *
 *     [u] =  [c  d] * offset^T + [u0]
 *     [v]    [e  1]              [v0]
 *
 *
 * Conversely, the backward projection of a two-dimensional pixel coordinate to
 * a three-dimensional ray is performed in four steps reversely to the forward projection:
 *
 * **Step 1**: Linear transformation of pixel coordinates `(u, v)` to pixel offset:
 *
 *     offset = inverse(A) * [u - u0]
 *                           [v - v0]
 *
 * **Step 2**: Mapping of the two-dimensional pixel offset to polar coordinates `(direction, distance)`:
 *
 *     direction = offset / norm(offset)
 *     distance = norm(offset)
 *
 * **Step 3**: Mapping of the pixel distance to the sight ray angle `theta` according to the polynomial
 * coefficients `polynomial` and the polynomial type `type` :
 *
 *     theta = map_pixel_distance_to_angle( polynomial, type, distance )
 *
 * **Step 4**: Computation of the sight ray `(x, y, z)` based on polar coordinates `(direction, angle)`:
 *
 *     (x, y) = sin(theta) * direction
 *     z = cos(theta)
 *
 *
 * The functions `map_angle_to_pixel_distance(.)` and `map_pixel_distance_to_angle(.)` depend on the
 * polynomial coefficients `polynomial` and the type of the polynomial, i.e.,
 *
 * - whenever the type of polynomial corresponds to the requested direction,
 *   the function corresponds to a simple evaluation of the polynomial:
 *
 *        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)
 *
 * - whenever the type of polynomial is the inverse to the requested direction,
 *   the function is equivalent to the inverse of the polynomial:
 *
 *        map_a_to_b( polynomial, b_to_a, x ) = y
 *
 *   with `map_b_to_a( polynomial, b_to_a, y ) == x`.
 *   The solution is computed via iterative local inversion. The valid ranges are defined by the
 *   camera's resolution and field of view.
 *
 *
 * In literature, the closest description is found in [Courbon et al, 2007], TABLE II:
 *
 *   [Courbon et al, 2007]: Courbon, J., Mezouar, Y., Eckt, L., and Martinet, P. (2007, October).
 *   A generic fisheye camera model for robotic applications. In Intelligent Robots and Systems, 2007.
 *   IROS 2007, pp. 1683–1688.
 */
typedef struct dwFThetaCameraConfigNew
{
    uint32_t width;
 
    uint32_t height;
 
    float32_t u0;
 
    float32_t v0;
 
    float32_t c;
 
    float32_t d;
 
    float32_t e;
 
    float32_t polynomial[DW_FTHETA_POLY_LENGTH];
 
    dwFThetaCameraPolynomialType polynomialType;
} dwFThetaCameraConfigNew;
 
/*
 * The model is described by three major components:
 *
 *  - the image size `(width, height)`,
 *  - the principal point `(u0, v0)`, and
 *  - the horizontal field of view `hFOV`.
 *
 *
 * The horizontal field of view determines the radius `r` of the sphere
 * used in the projection:
 *
 *     r = 0.5 / tan(hFOV/4)
 *
 * The radius determines
 *
 *  - the distance of the image plane to the origin of the camera coordinate system and
 *  - the distance of the pole of the projection to the origin of the camera coordinate system.
 *
 *
 * The forward projection of a three-dimensional ray to a two-dimensional pixel coordinate
 * by means of the stereographic camera model can be described in two steps:
 *
 * **Step 1**: Projection of a ray `(x, y, z)` of length 1 onto a normalized coordinate `(xn, yn)`
 * on the image plane at distance r, i.e.,
 *
 *     (xn, yn) = 2 * r * (x, y) / (1 + z)
 *
 * **Step 2**: Scaling and shift to pixel coordinate `(u, v)`, i.e.,
 *
 *     u = xn * width / 2 + u0
 *     v = yn * height / 2 + v0
 *
 *
 * Conversely, the backward projection of a two-dimensional pixel coordinate to
 * a three-dimensional ray is performed in two steps reversely to the forward projection:
 *
 * **Step 1**: Scaling and shift of pixel coordinate `(u, v)` to normalized image coordinate `(xn, yn)`, i.e.,
 *
 *     xn = (u - u0) / (width / 2)
 *     yn = (v - v0) / (height / 2)
 *
 * **Step 2**: Projection of normalized image coordinates to three-dimensional unit ray `(x, y, z)`, i.e.,
 *
 *     (x, y, z) = (4 * r * xn, 4 * r * yn, - xn^2 - yn^2 + 4 * r^2)) / (xn^2 + yn^2 + 4 * r^2)
 */
typedef struct dwStereographicCameraConfig
{
    uint32_t width;
 
    uint32_t height;
 
    float32_t u0;
 
    float32_t v0;
 
    float32_t hFOV;
} dwStereographicCameraConfig;
 
DW_API_PUBLIC
dwStatus dwRig_initializeFromFile(dwRigHandle_t* const obj,
                                  dwContextHandle_t const ctx,
                                  char8_t const* const configurationFile);
 
DW_API_PUBLIC
dwStatus dwRig_initializeFromString(dwRigHandle_t* const obj,
                                    dwContextHandle_t const ctx,
                                    char8_t const* const configurationString,
                                    char8_t const* const relativeBasePath);
 
DW_API_PUBLIC
dwStatus dwRig_reset(dwRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_release(dwRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getVehicle(dwVehicle const** const vehicle, dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getGenericVehicle(dwGenericVehicle* const vehicle, dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_setVehicle(dwVehicle const* const vehicle, dwRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_setGenericVehicle(dwGenericVehicle const* const vehicle, dwRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getVehicleIOConfigCount(uint32_t* const vioConfigCount,
                                       dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorCount(uint32_t* const sensorCount,
                              dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorCountOfType(uint32_t* const sensorCount,
                                    dwSensorType const sensorType,
                                    dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorProtocol(char8_t const** const sensorProtocol,
                                 uint32_t const sensorId,
                                 dwConstRigHandle_t const obj);
 
DW_API_PUBLIC dwStatus dwRig_getSensorParameter(char8_t const** const sensorParameter,
                                                uint32_t const sensorId,
                                                dwConstRigHandle_t const obj);
 
DW_API_PUBLIC dwStatus dwRig_setSensorParameter(char8_t const* const sensorParameter,
                                                uint32_t const sensorId,
                                                dwRigHandle_t const obj);
 
DW_API_PUBLIC dwStatus dwRig_getSensorParameterUpdatedPath(char8_t const** const sensorParameter,
                                                           uint32_t const sensorId,
                                                           dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorToRigTransformation(dwTransformation3f* const transformation,
                                            uint32_t const sensorId,
                                            dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorFLUToRigTransformation(dwTransformation3f* const transformation,
                                               uint32_t const sensorId,
                                               dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getNominalSensorToRigTransformation(dwTransformation3f* const transformation,
                                                   uint32_t const sensorId,
                                                   dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorToSensorTransformation(dwTransformation3f* const transformation,
                                               uint32_t const sensorIdFrom,
                                               uint32_t const sensorIdTo,
                                               dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getNominalSensorToSensorTransformation(dwTransformation3f* const transformation,
                                                      uint32_t const sensorIdFrom,
                                                      uint32_t const sensorIdTo,
                                                      dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_setSensorToRigTransformation(dwTransformation3f const* const transformation,
                                            uint32_t const sensorId,
                                            dwRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorName(char8_t const** const sensorName,
                             uint32_t const sensorId,
                             dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorDataPath(char8_t const** const dataPath,
                                 uint32_t const sensorId,
                                 dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getCameraTimestampPath(char8_t const** const timestampPath,
                                      uint32_t const sensorId,
                                      dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorPropertyByName(char8_t const** const propertyValue,
                                       char8_t const* const propertyName,
                                       uint32_t const sensorId,
                                       dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_addOrSetSensorPropertyByName(char8_t const* const propertyValue,
                                            char8_t const* const propertyName,
                                            uint32_t const sensorId,
                                            dwRigHandle_t const obj);
DW_API_PUBLIC
dwStatus dwRig_getPropertyByName(char8_t const** const propertyValue,
                                 char8_t const* const propertyName,
                                 dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_addOrSetPropertyByName(char8_t const* const propertyValue,
                                      char8_t const* const propertyName,
                                      dwRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_findSensorByName(uint32_t* const sensorId,
                                char8_t const* const sensorName,
                                dwConstRigHandle_t const obj);
DW_API_PUBLIC
dwStatus dwRig_findSensorIdFromVehicleIOId(uint32_t* const sensorId,
                                           uint32_t const vehicleIOId,
                                           dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_findSensorByTypeIndex(uint32_t* const sensorId,
                                     dwSensorType const sensorType,
                                     uint32_t const sensorTypeIndex,
                                     dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getSensorType(dwSensorType* const sensorType,
                             uint32_t const sensorId,
                             dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getCameraModel(dwCameraModel* const cameraModel,
                              uint32_t const sensorId,
                              dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getPinholeCameraConfig(dwPinholeCameraConfig* const config,
                                      uint32_t const sensorId,
                                      dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
DW_DEPRECATED("dwRig_getFThetaCameraConfig is replaced by dwRig_getFThetaCameraConfigNew.")
dwStatus dwRig_getFThetaCameraConfig(dwFThetaCameraConfig* const config,
                                     uint32_t const sensorId,
                                     dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_getFThetaCameraConfigNew(dwFThetaCameraConfigNew* const config,
                                        uint32_t const sensorId,
                                        dwConstRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_setPinholeCameraConfig(dwPinholeCameraConfig const* const config,
                                      uint32_t const sensorId,
                                      dwRigHandle_t const obj);
 
DW_API_PUBLIC
DW_DEPRECATED("dwRig_setFThetaCameraConfig is replaced by dwRig_setFThetaCameraConfigNew.")
dwStatus dwRig_setFThetaCameraConfig(dwFThetaCameraConfig const* const config,
                                     uint32_t const sensorId,
                                     dwRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_setFThetaCameraConfigNew(dwFThetaCameraConfigNew const* const config,
                                        uint32_t const sensorId,
                                        dwRigHandle_t const obj);
 
DW_API_PUBLIC
dwStatus dwRig_serializeToFile(char8_t const* const configurationFile,
                               dwConstRigHandle_t const obj);
 
#ifdef __cplusplus
}
#endif
 
#endif // DW_RIG_RIG_H_