1 # Copyright (c) 2018-2019, NVIDIA CORPORATION. All rights reserved.
3 @page dwx_porting_guide_2_2 Porting Guide from SDK 2.0 to SDK 2.2
6 This document will help you port your applications from DriveWorks SDK 2.0 to DriveWorks SDK 2.2.
8 ------------------------------------------------------------------
10 @section pg2_maps Maps
12 Geometry in the dwMaps module is now represented in local coordinates, rather than WGS84. The absGeometry in dwMapsLane, dwMapsLaneDivider and dwMapsFeature will be removed.
13 The local coordinate system is defined by ENU space with origin at dwMapsRoadSegment::origin. For more information about the coordinate systems see @ref maps_usecase6.
15 Depending on the HD Map source, the origin in the road segment might not be precise. However the the relative transformations dwMapsRoadSegmentConnection::connectedToLocal are always precise, such that the connected segments fit nicely together where they physically connect.
17 `dwMapsRoadSegment::lanes` has been marked as deprecated. dwMapsLaneGroup defines a group of lanes neighboring each other. Access of lanes should be done through a road segments lane groups (`dwMapsRoadSegment::laneGroups`).
19 ------------------------------------------------------------------
21 @section pg_laneplanner Lane Planner
23 dwLanePlanActions now has 3 additional parameters:
24 - hasLaneMerge: indicates whether the struct contains a valid lane merge
25 - laneMerge: struct to describe the lane merge in detail
26 - laneMergeDist: distance to point where the lanes merge
28 dwLanePlan_getLanePlanActions() with its signature from the version 2.0 is deprecated. dwLanePlan_getLanePlanActionsNew() contains an additional parameter "laneMergePointIndex" to describe at which point on the lane plan the next merge happens.
30 A new function dwLanePlan_updateCurrentPointWithCurrentRoadSegment() has been added. It does the same as dwLanePlan_updateCurrentPointWithLocalPose(), but the search for the current point is restricted to the reference road segment, for better performance. Use this function if it is known that the current pose is on the reference road segment.
32 ------------------------------------------------------------------
36 This release adds support for finite time waiting when peeking, reading or writing data. This change requires a specific time span (`timeout_us`) during which the thread will block until data is available. Therefore, the following functions' signatures have been updated accordingly:
38 - `dwSocketConnection_peek()` has been renamed to `dwSocketConnection_peekNew()`, and requires an additional argument of type `dwTime_t` indicating during which the thread will block waiting at most. Note that the unit of `timeout_us` is microseconds.
40 - The old `dwSocketConnection_peek()` which performs infinite time waiting until data is available, can be replaced by `dwSocketConnection_peekNew()` with `timeout_us` specified as `DW_TIMEOUT_INFINITE`.
42 - `dwSocketConnection_peekNonBlock()` has been marked as deprecated, and can be replaced by `dwSocketConnection_peekNew()` with `timeout_us` specified as zero.
44 - `dwSocketConnection_send()` has been replaced by `dwSocketConnection_write()`. To achieve equivalent behavior `dwSocketConnection_write()` has to be called with `DW_TIMEOUT_INFINITE` for the `timeout_us` argument.
46 - `dwSocketConnection_recv()` and `dwSocketConnection_recvNonBlock()` have been replaced with `dwSocketConnection_read()` which now accepts a `timeout_us` argument. To achieve same blocking behavior as in `dwSocketConnection_recv()` and non-blocking behavior as in `dwSocketConnection_recvNonBlock()` pass to `dwSocketConnection_read()` as `timeout_us` argument `DW_TIMEOUT_INFINITE` or `0` respectively.
48 @note The old APIs and the `New` suffix for the new APIs will be removed in the next major release.
50 For more information see @ref ipc_mainsection.
52 ------------------------------------------------------------------
54 @section pg_calibration_2_2 Calibration
56 This release has updated the `dwCalibrationState` enum, deprecating the `DW_CALIBRATION_STATE_STOPPED` and `DW_CALIBRATION_STATE_STARTED` values. Please use `dwCalibrationStatus::started` instead.
58 This release has deprecated `dwCalibrationEngine_addLidarPoses` API. The method is extended with a second timestamp and is replaced by `dwCalibrationEngine_addLidarPose`.
60 This release adapts and clarifies the `--use-checkerboard` parameter semantics of the `calibration-intrinsics-constraints` tool to indicate the actual checkerboard pattern *grid dimension* (before, this was the dimension of inner pattern corners).
62 ------------------------------------------------------------------
64 @section pg_egomotion_2_2 Egomotion
66 This release has deprecated the `dwEgomotion_applyRelativeUncertainty` API. Please use the
67 `dwEgomotion_computeRelativeTransformation` API for the computing the uncertainty of a relative
68 motion estimate, and the estimates available in `dwEgomotionUncertainty` for the uncertainty of the
69 corresponding fields in `dwEgomotionResult`.
71 This release has deprecated the `estimationPeriod` parameter in `dwEgomotionParameters`. Use
72 the `automaticUpdate` parameter going forward.
74 This release has deprecated the `dwEgomotionState_getHistoryEntry` API. Use
75 the `dwEgomotionState_getHistoryElement` API going forward. The timestamp is now available as part
76 of `dwEgomotionResult` and `dwEgomotionUncertainty`.
78 This release announces the upcoming deprecation of the GPS-dependent APIs and estimates in `dwEgomotion`,
79 which will be gradually deprecated and removed in future releases. Going forward, please use the
80 `dwGlobalEgomotion` module if global position and orientation estimates are required.
82 This release adds a suspension model used to compensate for vehicle body rotation due to acceleration
83 and resulting rotational suspension effects. See `dwEgomotionSuspensionParameters`.
85 ------------------------------------------------------------------
86 @section pg_mapnet_2_2 dwMapNet
88 This release has deprecated the `dwMapNet_initDefaultParams` API. please use `dwMapNet_initDefaultParamsNew` to initialize parameters for MapNet.
90 ------------------------------------------------------------------
92 @section pg_landmark_perception_2_2 LandmarkPerception
94 Landmark enums are now consolidated under LandmarkTypes.h and `dwLaneMarkType` has been moved to that file. LandmarkDetector and LaneDetector both refer to the new LandmarkTypes.h file.
96 This release changes the struct of `dwLaneDetection`, and extends it with a member `dwTime_t` to indicate the timestamp of frame used for detection.
98 This release has deprecated the `dwLandmarkDetector_initializeDefaultParams` API. Please use `dwLandmarkDetector_initializeDefaultParamsNew` for initializing landmark detector parameters.
100 This release has deprecated the `dwLandmarkDetector_detectLandmarks` API as well as the `dwLandmarkDetectorOutput` struct. Please use `dwLandmarkDetector_detectLandmarksNew` to detect landmarks.
102 This release has deprecated the `dwLandmarkDetector_setDetectionROI` API. Please set ROI with `dwLandmarkDetectorParams`.
103 This release has deprecated the `dwLandmarkDetector_setDetectionThreshold` API. Please set thresholds with `dwLandmarkDetectorParams`.
104 This release has deprecated the `dwLandmarkDetector_setModelParameterFitting` API. Please set model parameter fitting with `dwLandmarkDetectorParams`.
106 This release has deprecated the `dwLandmarkDetector_setTemporalSmoothFactor` API. Note This API currently has no functionality.
107 This release has deprecated the `dwLandmarkDetector_getTemporalSmoothFactor` API. Note This API currently has no functionality.
109 ------------------------------------------------------------------
111 @section pg_freespaceperception_2_2 Freespace Perception
113 In this release, the major change for freespace perception module is to enable per camera setting change for the batched camera frames. Specifically, the static camera parameters can be initialized via `dwFreespaceDetector_initializeFromOpenRoadNet_new`. The runtime per camera parameters such as camera extrinsics, maximum boundary distance, and ROI can be set separately with the camera index in the batch. These are the new initialization struct variables and per camera set/get APIs:
115 - `dwFreespaceDetectorInitParams.cam_new[]`
116 - `dwFreespaceDetectorInitParams.roi[]`
117 - `dwFreespaceDetectorInitParams.maxDistance[]`
118 - `dwFreespaceDetector_setCameraExtrinsics_new`
119 - `dwFreespaceDetector_setMaxFreespaceDistance_new`
120 - `dwFreespaceDetector_setDetectionROI_new`
121 - `dwFreespaceDetector_getDetectionROI_new`
123 The existing struct variables and APIs are deprecated:
125 - `dwFreespaceDetectorInitParams.cam`
126 - `dwFreespaceDetectorInitParams.maxNumImages`
127 - `dwFreespaceDetector_setCameraExtrinsics`
128 - `dwFreespaceDetector_setMaxFreespaceDistance`
129 - `dwFreespaceDetector_setDetectionROI`
130 - `dwFreespaceDetector_getDetectionROI`
133 ------------------------------------------------------------------
135 @section pg_pointcloudprocessing_2_2 Point Cloud Processing
137 This release deprecates KDtree based ICP type (`DW_POINT_CLOUD_ICP_TYPE_KD_TREE`) in `dwPointCloudICPType` struct. There is no replacement for quasi unstructured point clouds available in this release. Please switch to structured `DW_POINT_CLOUD_ICP_TYPE_DEPTH_MAP` depthmap based ICP type.
139 This release has extended `dwPointCloud` structure with a member indicating point format. Currently XYZI and RTHI are supported. `xyzi` pointer is declared deprecated. When creating a buffer it is initialized only if point format is XYZI. Otherwise it is set to nullptr and the user should use `points` instead.
141 Stitcher API has been modified in this release. `dwPointCloudStitcher_setMotionCompensation` is declared deprecated. Instead the following functions added:
143 - `dwPointCloudStitcher_enableMotionCompensation`
144 - `dwPointCloudStitcher_disableMotionCompensation`
145 - `dwPointCloudStitcher_setGlobalTransformation`
147 `dwPointCloudAccumulator` API has been changed in the following way:
148 - `dwPointCloudAccumulator_bindInput` is declared deprecated. It is recommended to use `dwPointCloudAccumulator_addLidarPacket` instead.
149 - `dwPointCloudAccumulator_isReady` is added returning a flag indicating when full spin has been collected.
152 ------------------------------------------------------------------
153 @section pg_lidaraccumulator_2_2 Lidar Accumulator
155 `dwLidarAccumulator` is declared deprecated and corresponding sample has been removed. `dwPointCloudAccumulator` should be used instead.
157 ------------------------------------------------------------------
159 @section pg_softisp_2_2 SoftISP
161 This release changes the struct of SoftISP paramters, and removes the inclusion of `dwCameraProperties` within that struct.
163 ------------------------------------------------------------------
165 @section pg_blindnessdetector_2_2 BlindnessDetector
167 This release deprecates motion based (KLT feature based) blindness detection as a method for the BlindnessDetector module. Going forward, ClearSightNet DNN based blindness detetion will be the only availabe method. As part of this change, the following functions are deprecated:
169 - `dwBlindnessDetector_initMotionBasedDefaultParams()`
170 - `dwBlindnessDetector_detectWithDNN()`
171 - `dwBlindnessDetector_detectWithMotion()`.
173 In addition, the following data elements and structures are deprecated:
175 - `dwBlindnessDetectionType` enum
176 - `maskCPU` and `maskCPUsegmented` variables in `dwBlindnessDetectionOutput` struct
177 - `method`, `imageWidth`, `imageHeight`, `blockX`, `blockY`, `historyCapacity`, `maxFeatureCount`, `useSkyPrior` and `blindnessThreshold` variables in `dwBlindnessDetectorParams` struct
179 In order to remove the use of deprecated API elements in your application that uses ClearSightNet DNN for blindness detection, you need to make the following changes:
181 - change use of `dwBlindnessDetector_detectWithDNN()` to `dwBlindnessDetector_detect()`
182 - remove any instances where `method` member of any object of `dwBlindnessDetectionParams` struct is set to `DW_BLINDNESSDETECTION_CLEARSIGHTNET`
184 For revised details of ClearSightNet based blindness detection, please refer to @ref clearsightnet_usecase1. In addition, please retire any usage of motion based blindness detection from your application. ClearSightNet based blindness detection offers faster performance and much better accuracy.
186 ------------------------------------------------------------------
188 @section pg_sensors_2_2 dwSensorSeekTable
190 This release generalizes the seek table API to all sensors
192 - change use of `dwSensor_getSeekTable()` to `dwSensor_getNumSeekTableEntries()` followed by `dwSensor_getSeekTableEntries`
195 @note Deprecated functions, enums and struct variables will be removed in the next major release.
198 ------------------------------------------------------------------
200 @section pg_objects_2_2 Objects
202 `details` field of `dwObjectCamera`, `dwObjectRadar` and `dwObjectFused` is deprecated. The type `dwObjectGeneric` will be deprecated and removed in the upcoming releases in favor of `dwObstacle`, further use of `dwObjectGeneric` is discouraged.
204 ------------------------------------------------------------------
206 @section pg_drivenet_2_2 dwDriveNet
208 This release add a new enum `dwDriveNetCameraType` to `dwDriveNetParams` specify the type camera with different fields of view. This is essential to make sure depth output for objects from drivenet is properly scaled.
209 - `DW_DRIVENET_CAMERA_60FOV` for 60 degree field of view camera
210 - `DW_DRIVENET_CAMERA_120FOV` for 120 degree field of view camera
211 - `DW_DRIVENET_CAMERA_30FOV` for 30 degree field of view camera
213 The parameter `hasDepth` is deprecated and it is replaced with `hasObjectDepth`.
215 This release adds a new value `hasObjectUrgency` to `dwDriveNetParams`. This value indicates to load a network that outputs urgency for detected objects.
217 This release adds a new value `hasUrgency` to `dwDriveNetClassProperties` to indicate whether a valid urgency is provided for a given object class.
219 This release adds two new temporal models, `DW_STATEFUL_TEMPORAL_DRIVENET_MODEL` and `DW_STATELESS_TEMPORAL_DRIVENET_MODEL`, to enum `dwDriveNetModel`. These two models can predict temporal information such as urgency, which equals to the inverse of time to collision (TTC).
222 ------------------------------------------------------------------
224 @section pg_objectdetector_2_2 dwObjectDetector
226 This release addes a new API, `dwObjectDetector_isObjectUrgencyEnabled`, to indicate whether urgency output is enabled.
228 The API `dwObjectDetector_isDistanceEnabled` is deprecated and it is replaced with `dwObjectDetector_isObjectDepthEnabled`.
230 ------------------------------------------------------------------
232 @section pg_vehicleio_2_2 Vehicle IO
234 This release adds support for AEB signals including a heartbeat as an alive counter, a request to activate automatic emergency braking (AEB), a request to activate a forward collision warning (FCW), and system status/state information for these respective monitoring systems. This change is designed to support external consumption of AEB and FCW requests.
236 Following member variables in `struct dwVehicleIOCommand` were deprecated and scheduled to be removed in the next major version:
242 ------------------------------------------------------------------
244 @section pg_waitconditions_2_2 dwWaitConditions
246 - `dwWaitConditionsDetector_initializeFromWaitNet()` is deprecated. The alternate API is `dwWaitConditionsDetector_initializeFromWaitNetNew()`
247 - `dwWaitConditionsDetector_getDetectedIntersection()` is deprecated. The detected output can be fetched by access input to `dwWaitConditionsDetector_bindOutput()`
248 - `filterMultipleObject` is added to `dwWaitConditionsDetectorTemporalAnalysisParams`. Should turn on when detecting multiple intersections.
249 - `dwTemporalAnalysis_getTrackID()` is added in temporal analysis model. Temporal analysis model now hold a track ID.
250 - `dwTemporalAnalysis_reset()` is added in temporal analysis model. It cleans up all the history.
253 ------------------------------------------------------------------
255 @section pg_dwCANMessage_2_2 dwCANMessage
257 `dwCANMessage` structure has changed size to accommodate large CAN FD message types.
259 This has resulted in a number of log files changing their internal data structure. This update handled automatically in most applications but some old files may need to be updated if the application make assumptions that the file contains structures size `sizeof(dwCANMessages)`.
261 An example of this is in the samples/sensors/plugins directory. These samples will not work on old sensor recording and those recording will need to be updated with @ref virtual_can_file_updater.