Provides a safety layer purely based on obstacle avoidance.
- Note
- SW Release Applicability: These APIs are available in NVIDIA DRIVE Software releases.
The safety force field uses perceived static and moving obstacles from any sensor(s) and egomotion or vehicle io state of the ego car to predict whether a collision is likely when all involved actors are assumed to execute a safety procedure.
The following choices of safety procedures exist:
- Freeze the current steering angle and come to a stop (default)
- Continue straight in the current direction and come to a stop (forceStraight = true)
- Line up the car to go parallel to a given road structure and come to a stop (useRoadStructure = true, forceStraight = false)
- Option 1 and 3 can additionally select (expandClaimedSets = true) and will have the claimed sets get bigger over time to take into account uncertainty and reaction time.
The actors are simulated to execute their safety procedures and collisions are checked between their 3-d space-time claimed sets. When collisions are found, the collision point undergoes a differential analysis to determine which actions improve the safety potential (i.e. a numeric measure of how unsafe the situation is).
The safety force field uses perceived static and moving obstacles from any sensor(s) and egomotion or vehicle io state of the ego car to predict whether a collision is likely when all involved actors are assumed to execute a safety procedure.
The following choices of safety procedures exist:
- Freeze the current steering angle and come to a stop (default)
- Continue straight in the current direction and come to a stop (forceStraight = true)
- Line up the car to go parallel to a given road structure and come to a stop (useRoadStructure = true, forceStraight = false)
- Option 1 and 3 can additionally select (expandClaimedSets = true) and will have the claimed sets get bigger over time to take into account uncertainty and reaction time.
The actors are simulated to execute their safety procedures and collisions are checked between their 3-d space-time claimed sets. When collisions are found, the collision point undergoes a differential analysis to determine which actions improve the safety potential (i.e. a numeric measure of how unsafe the situation is).
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_bindInputLaneGraph (const dwLaneGraph *lg, dwSafetyForceFieldHandle_t handle) |
| Bind a lane graph which represents road geometries. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_bindInputObjects (dwObjectArray *objects, dwBindSlot slot, dwSafetyForceFieldHandle_t handle) |
| Bind input perceived objects. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_bindInputVehicleIOState (const dwVehicleIOState *vioState, dwSafetyForceFieldHandle_t handle) |
| Bind input vehicle IO state. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_combineControlConstraints (dwSafetyForceFieldMultiControlConstraints *out, const dwSafetyForceFieldControlConstraints *ins, uint32_t inCount, dwSafetyForceFieldCombinationType type, uint32_t constraintBits) |
| Helper function to combine control constraints. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_getControlConstraints (dwSafetyForceFieldControlConstraints *constraints, dwSafetyForceFieldHandle_t handle) |
| Getter of the SFF control constraints for actuation for safety. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_getControlImage (dwImageHandle_t *img, const dwSafetyForceFieldControl *beforeActuation, const dwSafetyForceFieldControl *afterActuation, float32_t steeringLimit, float32_t minAccel, float32_t maxAccel, float32_t steerRange, float32_t accelRange, dwSafetyForceFieldHandle_t handle) |
| Control image getter. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_getCUDAStream (cudaStream_t *stream, dwSafetyForceFieldHandle_t handle) |
| Get the cuda stream to be used. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_getMetrics (dwSafetyForceFieldMetrics *metrics, dwSafetyForceFieldHandle_t handle) |
| Getter of statistics of safety force field collisions. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_getState (dwSafetyForceFieldState *state, const dwSafetyForceFieldControl *beforeActuation, const dwSafetyForceFieldControl *afterActuation, bool relative, dwSafetyForceFieldHandle_t handle) |
| Getter of SFF state for roadcast. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_initDefaultParams (dwSafetyForceFieldParams *params) |
| Initialize module parameters with default values. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_initialize (dwSafetyForceFieldHandle_t *handle, const dwSafetyForceFieldParams *params, dwContextHandle_t context) |
| Initialize a safety force field module. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_initializeControlConstraints (dwSafetyForceFieldControlConstraints *c) |
| Helper function to initialize control constraints. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_initializeMultiControlConstraints (dwSafetyForceFieldMultiControlConstraints *c) |
| Helper function to initialize multi control constraints. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_process (dwObjectArray **objectsList, uint32_t numObjectArrays, const dwVehicleIOState *vioState, const dwLaneGraph *lg, dwSafetyForceFieldHandle_t handle) |
| Main process. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_processStage (dwSafetyForceFieldStage stage, dwSafetyForceFieldHandle_t handle) |
| Perform safety force field processing stages. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_release (dwSafetyForceFieldHandle_t handle) |
| Release the safety force field module. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_reset (dwSafetyForceFieldHandle_t handle) |
| Reset the safety force field module. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_setCUDAStream (cudaStream_t stream, dwSafetyForceFieldHandle_t handle) |
| Set the cuda stream to be used. More...
|
|
DW_API_PUBLIC dwStatus | dwSafetyForceField_setEgomotion (dwEgomotionConstHandle_t egomotion, dwSafetyForceFieldHandle_t handle) |
| Bind egomotion model handle. More...
|
|
◆ dwSafetyForceFieldMetrics
struct dwSafetyForceFieldMetrics |
Data Fields |
float32_t |
actuationEMA |
exponential moving average of actuation number to visualize the average false positives and focus more on the current changes |
uint32_t |
actuationSequenceLength |
length of ongoing continuous sequence of frames with altered controls |
uint64_t |
collidingObjectIds[DW_SAFETY_FORCE_FIELD_METRICS_MAX_NUM_COLLIDING_OBJECTS] |
object ids of objects in current frame that ego has predicted collision with |
uint32_t |
collidingObjectSensorIds[DW_SAFETY_FORCE_FIELD_METRICS_MAX_NUM_COLLIDING_OBJECTS] |
sensor ids of objects in current frame that ego has predicted collision with |
float32_t |
collisionEMA |
exponential moving average of collision number to visualize the average false positives and focus more on the current changes |
uint32_t |
collisionSequenceLength |
length of ongoing continuous sequence of frames with predicted collisions |
uint32_t |
numCollidingObjects |
number of objects in current frame that ego has predicted collision with |
uint32_t |
totalNumFrames |
number of frames processed |
uint32_t |
totalNumFramesWithActuation |
number of frames that altered the controls checked |
uint32_t |
totalNumFramesWithCollision |
number of frames that had predicted collisions |
uint32_t |
totalNumSequencesWithActuation |
number of continuous sequences of frames with altered controls |
uint32_t |
totalNumSequencesWithCollision |
number of continuous sequences of frames with predicted collisions |
◆ dwSafetyForceFieldParams
struct dwSafetyForceFieldParams |
Data Fields |
bool |
expandClaimedSets |
true to inflate claimed sets that represent reaction time, uncertainties, etc. |
bool |
filterActors |
true to filter actors by keeping the ones that are close to ego-vehicle and have high velocity confidence |
bool |
forceStraight |
true to use straight claimed sets, i.e. the safety procedure has no lateral movement |
float32_t |
margin |
distance margin in [m] |
float32_t |
maxClearance |
always filter objects with absolute clearance above this threshold [m] |
uint32_t |
maxNumActors |
max number of input objects |
float32_t |
minConfidence |
object velocity confidence threshold. |
bool |
restrictToMoving |
true to ignore obstacles that are not moving (requires valid obstacleState) |
bool |
useGPU |
use true if cuda optimization should be used |
bool |
useRoadStructure |
true if structured safety procedures should be used |
dwVehicle |
vehicleProps |
ego vehicle properties |
◆ dwSafetyForceFieldPerActor
struct dwSafetyForceFieldPerActor |
Data Fields |
dwVector2f |
collisionPoint |
2D collision point in rig; only valid if collisionTime is positive |
float32_t |
collisionTime |
time of collision of actor with ego, -1.0 if there is no collision |
float32_t |
headings[DW_SAFETY_FORCE_FIELD_NUM_SLICES] |
heading in radians of the actor at discrete time steps (in rig coords) |
float32_t |
lateralSafetyForce |
lateral force from this collision point; only valid if collisionTime is positive |
float32_t |
longitudinalSafetyForce |
longitudinal force from this collision point; only valid if collisionTime is positive |
uint64_t |
objectId |
object IDs of the actor |
uint32_t |
objectSensorId |
sensor IDs of the actor |
dwVector2f |
positions[DW_SAFETY_FORCE_FIELD_NUM_SLICES] |
positions of the actor at discrete time steps (in rig coords) |
◆ dwSafetyForceFieldRequest
struct dwSafetyForceFieldRequest |
Data Fields |
bool |
activationRequest |
Activation request. |
dwTime_t |
timeStamp |
Timestamp for request. |
◆ dwSafetyForceFieldState
struct dwSafetyForceFieldState |
◆ DW_SAFETY_FORCE_FIELD_MAX_NUM_ACTORS_LIMIT
#define DW_SAFETY_FORCE_FIELD_MAX_NUM_ACTORS_LIMIT 150 |
◆ DW_SAFETY_FORCE_FIELD_MAX_NUM_CLOSE_ACTORS
#define DW_SAFETY_FORCE_FIELD_MAX_NUM_CLOSE_ACTORS 10 |
◆ DW_SAFETY_FORCE_FIELD_METRICS_MAX_NUM_COLLIDING_OBJECTS
#define DW_SAFETY_FORCE_FIELD_METRICS_MAX_NUM_COLLIDING_OBJECTS 200 |
◆ DW_SAFETY_FORCE_FIELD_NUM_SLICES
#define DW_SAFETY_FORCE_FIELD_NUM_SLICES 16 |
◆ DW_SAFETY_FORCE_FIELD_NUM_VERTICES_EXPANDING_CLAIMED_SETS
#define DW_SAFETY_FORCE_FIELD_NUM_VERTICES_EXPANDING_CLAIMED_SETS 6 |
◆ dwConstSafetyForceFieldHandle_t
◆ dwSafetyForceFieldHandle_t
◆ dwSafetyForceFieldStage
The process stages of the SafetyForceField.
Enumerator |
---|
DW_SAFETY_FORCE_FIELD_STAGE_CPU_PRE_PROCESSING | |
DW_SAFETY_FORCE_FIELD_STAGE_GPU_PROCESS | |
DW_SAFETY_FORCE_FIELD_STAGE_CPU_SYNC_PROCESS | |
Definition at line 78 of file SafetyForceField_processpipeline.h.
◆ dwSafetyForceField_bindInputLaneGraph()
Bind a lane graph which represents road geometries.
- Parameters
-
[in] | lg | a lane graph |
[in] | handle | The object to be updated |
- Returns
- DW_SUCCESS Bind successfully.
DW_INVALID_ARGUMENT lg or handle is nullptr.
◆ dwSafetyForceField_bindInputObjects()
Bind input perceived objects.
- Parameters
-
[in] | slot | to bind some particular input data to an internal slot |
[in] | objects | Memory location that stores perceived objects, nullptr if the slot is to be unbound |
[in] | handle | The object to be updated |
- Returns
- DW_SUCCESS Set successfully.
DW_INVALID_ARGUMENT objects or handle is nullptr.
◆ dwSafetyForceField_bindInputVehicleIOState()
Bind input vehicle IO state.
- Parameters
-
[in] | vioState | the vehicle IO state, which is owned by the application |
[in] | handle | The object to be updated |
- Returns
- DW_SUCCESS Bind successfully.
DW_INVALID_ARGUMENT vioState or handle is nullptr.
◆ dwSafetyForceField_combineControlConstraints()
Helper function to combine control constraints.
- Parameters
-
[out] | out | combined constraints |
[in] | ins | address of the input constraints array |
[in] | inCount | size of the input constraints array |
[in] | type | type of control constraint combination |
[in] | constraintBits | bits that define which constraints are used for combination. The k-th bit is 1 if the constraint ins[k] is used for combination, 0 otherwise. |
- Returns
- DW_SUCCESS Process successfully.
DW_INVALID_ARGUMENT Either out or ins is nullptr.
- Note
- If the input combination type
type
is DW_SAFETY_FORCE_FIELD_COMBINATION_TYPE_UNION
, union of the considered constraints will be taken and the result is stored in out->constraints[0]
. Also out->constraintsCount
is 1. In particular, it is possible to take the union of a proper subset of control constraints in the input ins
, by specifying constraintBits
correctly. For example, if inCount
is 5, constraintBits
is the binary number 10011, then the union of ins[0]
, ins[1]
and ins[4]
will be taken to generate the output out
.
-
If the input combination type
type
is DW_SAFETY_FORCE_FIELD_COMBINATION_TYPE_VOTING
, then constraintBits
should have at least three 1's. If k0
, k1
and k2
are the three smallest indices such that their bits in constraintBits
are 1's, then out->constraints[i]
stores ins[ki]for i = 0,1,2, and
out->constraintsCountis 3. For example, if
inCountis 7,
constraintBitsis the binary number 1100110, then only
ins[1],
ins[2]and
ins[5]will be considered for generating the output
out`.
◆ dwSafetyForceField_getControlConstraints()
Getter of the SFF control constraints for actuation for safety.
- Parameters
-
[out] | constraints | SFF control constraints for actuation |
[in] | handle | sff instance handle to get from |
- Returns
- DW_SUCCESS SFF control constraints were gotten.
DW_INVALID_ARGUMENT Either constraints or handle is nullptr.
◆ dwSafetyForceField_getControlImage()
Control image getter.
- Parameters
-
[out] | img | Handle of the control image |
[in] | beforeActuation | Ego's control that was queried (for rendering) |
[in] | afterActuation | The control ego's control was corrected to (for rendering) |
[in] | steeringLimit | The maximum allowed front wheel angle in radians (for rendering) |
[in] | minAccel | Maximum allowed vehicle deceleration (for rendering) |
[in] | maxAccel | Maximum allowed vehicle acceleration (for rendering) |
[in] | steerRange | Maximum positive front wheel steering angle rendered in control image in degree (range of steering angle in control image is [-steerRange, steerRange]) |
[in] | accelRange | Maximum positive acceleration rendered in control image in m/s^2 (range of acceleration in control image is [-accelRange, accelRange]) |
[in] | handle | The object to be updated |
- Returns
- DW_SUCCESS Process successfully.
DW_INVALID_ARGUMENT handle is nullptr.
◆ dwSafetyForceField_getCUDAStream()
Get the cuda stream to be used.
- Parameters
-
[out] | stream | Cuda stream to be retrieved |
[in] | handle | sff instance handle to set |
- Returns
- DW_SUCCESS stream was retrieved.
DW_INVALID_ARGUMENT handle or stream is nullptr.
◆ dwSafetyForceField_getMetrics()
Getter of statistics of safety force field collisions.
- Parameters
-
[out] | metrics | a pointer to the current metrics of SFF |
[in] | handle | sff instance handle to get from |
- Returns
- DW_SUCCESS metrics were retrieved.
DW_INVALID_ARGUMENT handle or metrics is nullptr.
◆ dwSafetyForceField_getState()
Getter of SFF state for roadcast.
- Parameters
-
[out] | state | a pointer to the current state of SFF |
[in] | beforeActuation | Control of ego that was checked |
[in] | afterActuation | Control it was corrected to |
[in] | relative | true if claimed sets should be relative to ego |
[in] | handle | sff instance handle to get from |
- Returns
- DW_SUCCESS state was retrieved.
DW_INVALID_ARGUMENT handle or state is nullptr.
◆ dwSafetyForceField_initDefaultParams()
Initialize module parameters with default values.
- Parameters
-
[out] | params | The module parameters |
- Returns
- DW_SUCCESS When parameter initialization is successful.
DW_FAILURE When parameter initialization is unsuccessful.
DW_INVALID_ARGUMENT When params is nullptr.
◆ dwSafetyForceField_initialize()
Initialize a safety force field module.
- Parameters
-
[out] | handle | A pointer to the safety force field object to be initialized. |
[in] | params | Module parameters |
[in] | context | Specifies a handle to the context under which it is created. |
- Returns
- DW_SUCCESS module initialized successfully.
DW_INVALID_ARGUMENT handle, params or context is nullptr.
◆ dwSafetyForceField_initializeControlConstraints()
Helper function to initialize control constraints.
- Parameters
-
[in,out] | c | constraints obj to be initialized |
- Returns
- DW_SUCCESS Initialize successfully.
DW_INVALID_ARGUMENT c is nullptr.
◆ dwSafetyForceField_initializeMultiControlConstraints()
Helper function to initialize multi control constraints.
- Parameters
-
[in,out] | c | constraints obj to be initialized |
- Returns
- DW_SUCCESS Initialize successfully.
DW_INVALID_ARGUMENT c is nullptr.
◆ dwSafetyForceField_process()
Main process.
- Parameters
-
[in] | objectsList | List of memory locations that store perceived objects. The objects are assigned to the first numObjectArrays bind slots |
[in] | numObjectArrays | The number of input object arrays |
[in] | vioState | the vehicle IO state, which is owned by the application |
[in] | lg | a lane graph |
[in] | handle | The object to be updated |
- Returns
- DW_SUCCESS Process successfully.
DW_INVALID_ARGUMENT handle is nullptr.
◆ dwSafetyForceField_processStage()
Perform safety force field processing stages.
Inputs must be bound before this call.
- Parameters
-
[in] | stage | Processing stage to run. |
[in] | handle | The object to be updated. |
- Returns
- DW_SUCCESS Processed successfully.
DW_INVALID_ARGUMENT handle is nullptr.
◆ dwSafetyForceField_release()
Release the safety force field module.
The handle points to NULL on success.
- Parameters
-
[in] | handle | The object to be released |
- Returns
- DW_SUCCESS module released successfully.
DW_INVALID_ARGUMENT handle is nullptr.
◆ dwSafetyForceField_reset()
Reset the safety force field module.
- Parameters
-
[in] | handle | The object to be reset. |
- Returns
- DW_SUCCESS module reset successfully.
DW_INVALID_ARGUMENT handle is nullptr.
◆ dwSafetyForceField_setCUDAStream()
Set the cuda stream to be used.
- Parameters
-
[in] | stream | Cuda stream to be used |
[in] | handle | sff instance handle to set |
- Returns
- DW_SUCCESS stream was successfully set.
DW_INVALID_ARGUMENT handle is nullptr.
◆ dwSafetyForceField_setEgomotion()
Bind egomotion model handle.
- Parameters
-
[in] | egomotion | model handle |
[in] | handle | The object to be updated |
- Returns
- DW_SUCCESS Bind successfully.
DW_INVALID_ARGUMENT egomotion or handle is nullptr.