planning/safetyforcefield/docs/usecase1.md

Go to the documentation of this file.

# Copyright (c) 2019-2020, NVIDIA CORPORATION.  All rights reserved.

@page safetyforcefield_usecase1 Safety Force Field Workflow
@tableofcontents

@note SW Release Applicability: This tutorial is applicable to modules in **NVIDIA DRIVE Software** releases.

@section safetyforcefield_initialization Initialization

#### To initialize the Safety Force Field default parameters

```{.cpp}
dwStatus dwSafetyForceField_initDefaultParams(dwSafetyForceFieldParams* params);
```

An actor's claimed set is the likely trajectory in space-time of the actor executing its safety procedure.
For example, the green set in the following figure is a claimed set if the safety procedure is driving straight and braking:

![](safetyforcefield/claimedSet.png)


The underlying space of the green claimed set is space-time where the space is the xy-plane. Its projection on xy-plane is a long rectangle, showing the obstacle is moving along a fixed direction. Its projection on the plane spanned by the obstacle direction and time axis is a parabola opening downwards. This indicates the obstacle is slowing down over time.

The following attributes for the `dwSafetyForceFieldParams` struct configure the shape for each actor's claimed set:
- `forceStraight`.
- `useRoadStructure`.
- `expandClaimedSets`.

The default value for these attributes is `false`, so the default claimed set comes from holding the steering wheel and braking.

The following figures are examples of claimed sets when each of these attributes are enabled:
- `forceStraight = true`, and other attributes are default.
The claimed set is continued straight in the actor's current heading throughout the safety procedure.

![](safetyforcefield/forceStraight.png)


- `useRoadStructure = true`, and other attributes are default. The claimed sets align with the ego-vehicle's current path.

![](safetyforcefield/useRoad.png)


- `expandClaimedSets = true`, and other attributes are default.
The claimed sets expand laterally and longitudinally to take account of control uncertainties and reaction time. In the following figure, the quadrilateral time slices of the green claimed set grow over time.

![](safetyforcefield/expandClaimedSets.png)


About combining the attributes, you can set `useRoadStructure = true` and `expandClaimedSets = true` together.
However, the setting `forceStraight = true` ignores what `useRoadStructure` and `expandClaimedSets` are set, so that road structure is not used and claimed sets are not expanded.

#### To initialize a pointer to a Safety Force Field handle

```{.cpp}
dwStatus dwSafetyForceField_initialize(dwSafetyForceFieldHandle_t* handle,
                                       const dwSafetyForceFieldParams* params,
                                       dwContextHandle_t context);
```

@section safetyforcefield_binding_inputs Binding Inputs

The inputs for a Safety Force Field module must be bound before you run the process function.
These include obstacles, egomotion, the vehicleIO state, and a lane graph.

#### To bind an objects pointer

```{.cpp}
dwStatus dwSafetyForceField_bindInputObjects(const uint32_t* slotId,
                                             dwObjectArray* objects,
                                             dwSafetyForceFieldHandle_t handle);

```
The Safety Force Field module consumes obstacles on the ground within 120 meters of the ego-vehicle.
The `maxNumActors` attribute for the `dwSafetyForceFieldParams` struct determines the upper bound of the number of these obstacles to be processed.

The egomotion and vehicleIO state decide the ego-vehicle's state (including speed and front wheel steering angle).
This is used as input to generate the ego-vehicle's claimed set.

#### To bind an egomotion handle

```{.cpp}
dwStatus dwSafetyForceField_setEgomotion(dwEgomotionConstHandle_t egomotion,
                                         dwSafetyForceFieldHandle_t handle);
```

#### To bind the vehicleIO state

```{.cpp}
dwStatus dwSafetyForceField_bindInputVehicleIOState(const dwVehicleIOState* vioState,
                                                    dwSafetyForceFieldHandle_t handle);
```


#### To bind a lane graph pointer

```{.cpp}
dwStatus dwSafetyForceField_bindInputLaneGraph(const dwLaneGraph* lg,
                                               dwSafetyForceFieldHandle_t handle);
```

@section safetyforcefield_process_function Process Function

The process function computes the claimed set for each actor, checks for collisions between the ego-vehicle and an actor, and computes
a Safety Force Field for each collision point.

```{.cpp}
dwStatus dwSafetyForceField_process(dwSafetyForceFieldHandle_t handle);
```

Each Safety Force Field generates one control constraint.

#### To obtain the control constraints from a Safety Force Field module for actuation

```{.cpp}
dwStatus dwSafetyForceField_getControlConstraints(dwSafetyForceFieldControlConstraints* constraints,
                                                  dwSafetyForceFieldHandle_t handle);
```

@section safetyforcefield_release Release

#### To release a Safety Force Field module

```{.cpp}
dwStatus dwSafetyForceField_release(dwSafetyForceFieldHandle_t handle);
```

For a more detailed workflow, please refer to the @ref dwx_safetyforcefield_sample.