Download and Install
Quick Start

Driver Interfaces


Full Software Listings

Dev Guide

Users Logo
Mailing lists



[ComponentsStand-Alone ComponentsIceBox ServicesC++Linux]

A Local Navigation component: follows a waypoint-defined path while avoiding obstacles. More...

A Local Navigation component: follows a waypoint-defined path while avoiding obstacles.

  • orca_interface_home
  • orca_interface_status
  • orca_interface_pathfollower2d [LocalNav.Provides.PathFollower2d]
  • orca_interface_rangescanner2d [LocalNav.Requires.Observations]
  • orca_interface_localise2d [LocalNav.Requires.Localisation]
  • orca_interface_velocitycontrol2d [LocalNav.Requires.VelocityControl2d]
  • orca_interface_odometry2d [LocalNav.Requires.Odometry2d]
  • LocalNav.Config.Driver (string)
    • Which local nav algorithm to use
    • Valid values: { "vfhdriver" }
    • Default: "vfhdriver"
  • LocalNav.Config.TimestampsCheckEnabled (int)
    • Whether to enable checking the difference between odometry, laser, and localiser timestamps
    • Default: 1

Local Nav

LocalNav implements the orca_interface_pathfollower2d interface. It receives a path, defined by set of waypoints, and follows it while avoiding obstacles. The specfics of the algorithm used to follow the path are defined in the driver.

The parameters used in following a path come from three places. In order of precedence, they are:

1. The parameters of the driver, read from the configuration file,

2. The maximum approach speed/turnrate for each waypoint, specified in the path, and

3. The schedule defined by the path.

The third item exists because the path defines the times at which the robot should arrive at each waypoint. To ignore this constraint, set all waypoint times to 'now' or 'yesterday', and the robot will move as fast as possible within the constraints set by items 1 and 2.

The second item is again defined by the path object. Regardless of the schedule, the robot won't exceed the max approach speed/turnrate defined for a waypoint. Set these to something massive to ignore this constraint.

The first item takes precedence over the other two. Regardless of the specifics of the path, the robot will obey the parameters set in the driver. These should be set to ensure that the robot's motion is within reasonable safe limits.

Vector Field Histogram Plus (VFH+) driver

The VFH driver implements the Vector Field Histogram Plus (VFH+) local navigation method by Ulrich and Borenstein. VFH+ provides real-time obstacle avoidance and waypoint-following capabilities for mobile robots.

VFH configuration

VFH Has lots of parameters. See the next section for hints on configuration.

Some important configuration parameters:

  • LocalNav.Config.Vfh.SafetyDist0ms (double) [m]
    • the distance the robot should keep from obstacles when travelling at 0 m/s.
  • LocalNav.Config.Vfh.SafetyDist1ms (double) [m]
    • the distance the robot should keep from obstacles when travelling at 1 m/s.
  • LocalNav.Config.Vfh.FreeSpaceCutoff0ms (double) [m]
    • Controls how close the robot has to be to an obstacle to be afraid of it, when travelling at 0 m/s. A small value makes the robot cautious, a large value makes it brave.
  • LocalNav.Config.Vfh.FreeSpaceCutoff1ms (double) [m]
    • See FreeSpaceCutoff0ms. The value used scales linearly with speed.
  • LocalNav.Config.Vfh.ObsCutoff0ms (double) [m]
    • Setting this differently to FreeSpaceCutoff0ms causes VFH to use some hysteresis in deciding what an obstacle is. For laser range-finders, setting it to FreeSpaceCutoff0ms seems to work just fine.
  • LocalNav.Config.Vfh.ObsCutoff1ms (double) [m]
    • see ObsCutoff0ms
  • LocalNav.Config.Vfh.WeightDesiredDir (double)
    • To force it to commit, VFH is provided with a built-in tendency to stick to its previous course of action. WeightDesiredDir and WeightCurrentDir determine the strength of this tendency.
  • LocalNav.Config.Vfh.WeightCurrentDir (double)
    • see WeightDesiredDir
  • LocalNav.Config.Vfh.CellSize (double) [m]
    • VFH builds a small local Occupancy Grid map for obstacle detection. This controls the width of each occupancy grid cell.
  • LocalNav.Config.Vfh.GridWidthInCells (int)
    • This parameter, together with CellSize, determine the size of the local occupancy grid.
  • LocalNav.Config.Vfh.GridWidthInCells (int)
    • The number of bins in VFH's local histogram.
  • LocalNav.Config.Vfh.MaxAcceleration (double) [m/s2]
    • maximum acceleration
  • LocalNav.Config.Vfh.MaxTurnrate0ms (double) [deg/s]
    • maximum turnrate at 0 m/s.
  • LocalNav.Config.Vfh.MaxTurnrate1ms (double) [deg/s]
    • maximum turnrate at 1m/s.
  • LocalNav.Config.Vfh.AbsoluteMaxTurnrate (double) [deg/s]
    • this is for safety. We'll never turn faster than this.
  • LocalNav.Config.Vfh.MinTurnRadiusSafetyFactor (double)
    • MinTurnRadius is calculated for the current speed and max turnrate. It is then multiplied by minTurnRadiusSafetyFactor, to account for side-slip while cornering quickly.
    • default 1.10

For the next three speed arguments: These are the absolute max values that VFH will use. Setting a path with a long time between waypoints will cause VFH to go slower.

  • LocalNav.Config.Vfh.MaxSpeed (double) [m/s]
    • the robot's maximum speed -- it will never try to go faster than this.
  • LocalNav.Config.Vfh.MaxSpeedNarrowOpening (double) [m/s]
    • Max speed while travelling through a narrow opening (defined as an opening of less than 80degrees). This is thresholded if the max_speed is decreased at run-time.
  • LocalNav.Config.Vfh.MaxSpeedWideOpening (double) [m/s]
    • Max speed while travelling along the border of an obstacle, when the opening is greater than 80 degrees. This is thresholded if the max_speed is decreased at run-time.


Hints for Configuration

(some of this is taken from the Player VFH documentation):

To get initiated with VFH, a good idea is to start with the default values, which are all pretty reasonable. Then start experimenting with safetyDist[0|1]ms and FreeSpaceCutoff[0|1]ms (and ObsCutoff[0|1]ms), to get a feeling for how they affect performance. Once comfortable, make the speed-controlling parameters more aggressive. In general, SafetySist determines how close the robot will come to an obstacle while turning (around a corner for instance). Setting this too low causes the robot to clip obstacles, while setting it too conservatively stops the robot getting through gaps like doorways. FreeSpaceCutoff determines how close a robot will get to an obstacle in the direction of motion before turning to avoid.

For 'slow' robots (like Pioneers), MaxSpeedNarrowOpening and MaxSpeedWideOpening can be set to MaxSpeed. The 0ms and 1ms variables can also be set to the same values as each other. From experience, it is recommeded that MaxTurnrate[0|1]ms should be at least 15% of MaxSpeed.

For 'fast' vehicles like Segways, firstly be aware that VFH control is potentially very dangerous: start conservatively and change things slowly. The speed-dependent parameters are much more important here: it helps to set the 0ms and 1ms variable differently. To control the dynamics, it's good to set MaxSpeedNarrowOpening very slow, and MaxSpeedWideOpening reasonably slow. This causes the robot to slow down generally near obstacles, so if it does collide it's less likely to be catastrophic. MaxTurnrate[0|1]ms is also important for controlling how aggressively the robot turns.

Unless you are familiar with the VFH algorithm, I don't recommend deviating from the default values for CellSize, WindowDiameter, or SectorAngle.

Notes and credits

The algorithm implemented here is described in this paper:

@inproceedings { 
  Author = {Ulrich, I. and Borenstein, J.},
  Title = {VFH+: Reliable Obstacle Avoidance for Fast Mobile Robots},
  BookTitle = {IEEE International Conference on Robotics and Automation(ICRA '98)},
  Pages = {1572--1577},
  Year = {1998}

The code that implements the VFH algorithm was taken from Player, heavily modified, then re-submitted to the Player project.


Localnav has an internal simulator which can be used for automated testing. When TestInSimulationMode is enabled, LocalNav will use this internal simulator rather than hooking up to external sources of information. It will establish the following interfaces to provide external access to the state of the simulated world:

  • orca_interface_laserscanner2d [LocalNav.Provides.TestLaserScanner]
  • orca_interface_localise2d [LocalNav.Provides.TestLocalise]
  • orca_interface_ogmap [LocalNav.Provides.TestOgMap]

The following configuration parameters affect the behaviour of TestInSimulationMode:

  • LocalNav.Config.TestInSimulationMode (bool)
    • Enables/Disables test-in-simulation-mode
    • Default: 0
  • LocalNav.Config.Test.BatchMode (bool)
    • In non-batch-mode, the simulator will wait for a keypress before stepping forward.
    • Default: 0
  • LocalNav.Config.Test.NumWaypoints (int)
    • The size of the path to follow in simulation.
      • The first few waypoints are deterministic, then a number of random waypoints is added to create a path of the required size.
    • Default: 10
  • LocalNav.Config.Test.MaxLateralAcceleration (double) [m/s/s]
    • When the test simulator reports the capabilities of the simulated vehicle, this is the reported max lateral acceleration (constrains max turnrate at speed).
    • Default: 1.0
  • LocalNav.Config.Test.CheckLateralAcceleration (bool)
    • If true, check that the driver doesn't exceed the specified max lateral acceleration.
      • Fail the test if it's exceeded.
    • Default: 0
  • LocalNav: Alex Brooks
  • VFH: Chris Jones, Brian Gerkey, Alex Brooks

Webmaster: Tobias Kaupp (tobasco at

Generated for Orca Robotics by  doxygen 1.4.5