# controllerVFH

Avoid obstacles using vector field histogram

Since R2019b

## Description

The `controllerVFH` System object™ enables your vehicle to avoid obstacles based on range sensor data using vector field histograms (VFH) . Given laser scan readings and a target direction to drive toward, the object computes an obstacle-free steering direction.

`controllerVFH` specifically uses the VFH+ algorithm to compute an obstacle-free direction. First, the algorithm takes the ranges and angles from laser scan data and builds a polar histogram for obstacle locations. Then, the input histogram thresholds are used to calculate a binary histogram that indicates occupied and free directions. Finally, the algorithm computes a masked histogram, which is computed from the binary histogram based on the minimum turning radius of the vehicle.

The algorithm selects multiple steering directions based on the open space and possible driving directions. A cost function, with weights corresponding to the previous, current, and target directions, calculates the cost of different possible directions. The object then returns an obstacle-free direction with minimal cost. Using the obstacle-free direction, you can input commands to move your vehicle in that direction.

To use this object for your own application and environment, you must tune the properties of the algorithm. Property values depend on the type of vehicle, the range sensor, and the hardware you use.

To find an obstacle-free steering direction:

1. Create the `controllerVFH` object and set its properties.

2. Call the object with arguments, as if it were a function.

## Creation

### Syntax

``VFH = controllerVFH``
``VFH = controllerVFH(Name,Value)``

### Description

example

````VFH = controllerVFH` returns a vector field histogram object that computes the obstacle-free steering direction using the `VFH+` algorithm.```
````VFH = controllerVFH(Name,Value)` returns a vector field histogram object with additional options specified by one or more `Name,Value` pairs. Name is the property name and Value is the corresponding value. Name must appear inside single quotes (`' '`). You can specify several name-value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`. Properties not specified retain their default values.```

## Properties

expand all

Number of angular sectors in the vector field histogram, specified as a scalar. This property defines the number of bins used to create the histograms. This property is non-tunable. You can only set this when the object is initialized.

Limits for range readings, specified as a 2-element vector with elements measured in meters. The range readings specified when calling the object are considered only if they fall within the distance limits. Use the lower distance limit to ignore false positives from poor sensor performance at lower ranges. Use the upper limit to ignore obstacles that are too far from the vehicle.

Radius of the vehicle in meters, specified as a scalar. This dimension defines the smallest circle that can circumscribe your vehicle. The vehicle radius is used to account for vehicle size when computing the obstacle-free direction.

Safety distance around the vehicle, specified as a scalar in meters. This is a safety distance to leave around the vehicle position in addition to the value of the `RobotRadius` parameter. The sum of the vehicle radius and the safety distance is used to compute the obstacle-free direction.

Minimum turning radius in meters for the vehicle moving at its current speed, specified as a scalar.

Cost function weight for moving toward the target direction, specified as a scalar. To follow a target direction, set this weight to be higher than the sum of the `CurrentDirectionWeight` and `PreviousDirectionWeight` properties. To ignore the target direction cost, set this weight to zero.

Cost function weight for moving the robot in the current heading direction, specified as a scalar. Higher values of this weight produce efficient paths. To ignore the current direction cost, set this weight to zero.

Cost function weight for moving in the previously selected steering direction, specified as a scalar. Higher values of this weight produces smoother paths. To ignore the previous direction cost, set this weight to zero.

Thresholds for binary histogram computation, specified as a 2-element vector. The algorithm uses these thresholds to compute the binary histogram from the polar obstacle density. Polar obstacle density values higher than the upper threshold are represented as occupied space (1) in the binary histogram. Values smaller than the lower threshold are represented as free space (0). Values that fall between the limits are set to the values in the previous binary histogram, with the default being free space (0).

Use `lidarScan` object as scan input, specified as either `true` or `false`.

## Usage

### Syntax

``steeringDir = vfh(scan,targetDir)``
``steeringDir = vfh(ranges,angles,targetDir)``

### Description

example

````steeringDir = vfh(scan,targetDir)` finds an obstacle-free steering direction using the VFH+ algorithm for the input `lidarScan` object, `scan`. A target direction is given based on the target location.To enable this syntax, you must set the `UseLidarScan` property to `true`. For example: mcl = monteCarloLocalization('UseLidarScan',true); ... [isUpdated,pose,covariance] = mcl(odomPose,scan); ```
````steeringDir = vfh(ranges,angles,targetDir)` defines the lidar scan with two vectors: `ranges` and `angles`.```

### Input Arguments

expand all

Lidar scan readings, specified as a `lidarScan` object.

#### Dependencies

To use this argument, you must set the `UseLidarScan` property to `true`.

`mcl.UseLidarScan = true;`

Range values from scan data, specified as a vector in meters. These range values are distances from a sensor at given `angles`. The vector must be the same length as the corresponding `angles` vector.

Angle values from scan data, specified as a vector in radians. These angle values are the specific angles of the given `ranges`. The vector must be the same length as the corresponding `ranges` vector.

Target direction for the vehicle, specified as a scalar in radians. The forward direction of the vehicle is considered zero radians, with positive angles measured counterclockwise.

### Output Arguments

expand all

Steering direction for the vehicle, specified as a scalar in radians. This obstacle-free direction is calculated based on the VFH+ algorithm. The forward direction of the vehicle is considered zero radians, with positive angles measured counterclockwise.

## Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named `obj`, use this syntax:

`release(obj)`

expand all

 `show` Display `VectorFieldHistogram` information in figure window
 `step` Run System object algorithm `release` Release resources and allow changes to System object property values and input characteristics `reset` Reset internal states of System object

## Examples

collapse all

This example shows how to calculate a steering direction based on input laser scan data.

Create a `controllerVFH` object. Set the `UseLidarScan` property to `true`.

```vfh = controllerVFH; vfh.UseLidarScan = true;```

Input laser scan data and target direction.

```ranges = 10*ones(1,500); ranges(1,225:275) = 1.0; angles = linspace(-pi,pi,500); targetDir = 0;```

Create a `lidarScan` object by specifying the ranges and angles.

`scan = lidarScan(ranges,angles);`

Compute an obstacle-free steering direction.

`steeringDir = vfh(scan,targetDir);`

Visualize the `VectorFieldHistogram` computation.

```h = figure; set(h,'Position',[50 50 800 400]) show(vfh)```

## References

[1] Borenstein, J., and Y. Koren. "The Vector Field Histogram - Fast Obstacle Avoidance for Mobile Robots." IEEE Journal of Robotics and Automation. Vol. 7, Number 3, 1991, pp.278–88.

[2] Ulrich, I., and J. Borenstein. "VFH : Reliable Obstacle Avoidance for Fast Mobile Robots." Proceedings. 1998 IEEE International Conference on Robotics and Automation. (1998): 1572–1577.

## Version History

Introduced in R2019b