API Documentation and Usage

Once the Dubins package is installed it can be imported using the command

using Dubins

The methods that can be used without the qualifier Dubins. include

dubins_shortest_path, dubins_path,
dubins_path_length, dubins_segment_length,
dubins_segment_length_normalized,
dubins_path_type, dubins_path_sample,
dubins_path_sample_many, dubins_path_endpoint,
dubins_extract_subpath

The constants and other variables that can be used without the qualifier Dubins. include

DubinsPathType, SegmentType, DubinsPath,
LSL, LSR, RSL, RSR, RLR, LRL,
EDUBOK, EDUBCOCONFIGS, EDUBPARAM,
EDUBBADRHO, EDUBNOPATH, EDUBBADINPUT

Any method in the Dubins package would return an error code. The error codes that are defined within the package are

const EDUBOK = 0                # no error
const EDUBCOCONFIGS = 1         # colocated configurations
const EDUBPARAM = 2             # path parameterization error
const EDUBBADRHO = 3            # the rho value is invalid
const EDUBNOPATH = 4            # no connection between configurations with this word
const EDUBBADINPUT = 5          # uninitialized inputs to functions

Dubins paths/shortest Dubins path

The shortest path between two configurations is computed using the method dubins_shortest_path() as

errcode, path = dubins_shortest_path([0.0, 0.0, 0.], [1., 0.0, 0.], 1.)

Here, path is an object of type DubinsPath, [0.0, 0.0, 0.] is the initial configuration, [1., 0.0, 0.] is the final configuration and 1. is the turn radius of the Dubins vehicle. A configuration is a 3-element vector with the x-coordinate, y-coordinate, and the heading angle. The above code would return a non-zero error code in case of any errors. If the error code is non-zero, then nothing is returned for the path.

A Dubins path of a specific type can be computed using

errcode, path = dubins_path(zeros(3), [10.0, 0.0, 0.], 1., RSL)

where, the last argument is the type of Dubins path; it can take any value in LSL, LSR, RSL, RSR, RLR, LRL. Again here, tf the error code is non-zero, then nothing is returned for the path.

The length of a Dubins path is computed after a function call to dubins_shortest_path() or dubins_path() as

val = dubins_path_length(path)

The length of each segment (1-3) in a Dubins path and the type of Dubins path can be queried using

val1 = dubins_segment_length(path, 1)
val2 = dubins_segment_length(path, 2)
val3 = dubins_segment_length(path, 3)
path_type = dubins_path_type(path)

The second argument in the method dubins_segment_length() is the segment number. If a segment number that is less than 1 or greater than 3 is used, the method will return Inf.

Sub-path extraction

A sub-path of a given Dubins path can be extracted as

errcode, path = dubins_path(zeros(3), [4., 0.0, 0.], 1., LSL)

errcode, subpath = dubins_extract_subpath(path, 2.)

The second argument of the function dubins_extract_subpath() is a parameter that has to lie in the interval [0,dubins_path_length(path)], failing which the function will return a EDUBPARAM error-code and a nothing for the path

After extracting a sub-path, the end-point of the sub-path can be queried using the method dubins_path_endpoint(subpath),. This function returns EDUBOK on successful completion and a 3-element vector representing the configuration of the end-point of the sub-path.

Sampling a Dubins path

Sampling the configurations along a Dubins path is a useful feature that can aid in writing additional plotting features. To that end, the package includes two functions that can achieve the same goal of sampling in two different ways; they are dubins_path_sample() and dubins_path_sample_many(). The usage of the method dubins_path_sample() is illustrated by the following code snippet:

errcode, path = dubins_path([0.0, 0.0, 0.], [4., 0.0, 0.], 1., LSL)

errcode, qsamp = dubins_path_sample(path, 0.)
# qsamp will take a value [0.0, 0.0, 0.], which is the initial configuration
# the call to dubins_path_sample() should always be preceded by a successful call to dubins_path() or dubins_shortest_path()

errcode, qsamp = dubins_path_sample(path, 4.)
# qsamp will take a value [4., 0.0, 0.], which is the final configuration

errcode, qsamp = dubins_path_sample(path, 2.)
# qsamp will take a value [2., 0.0, 0.], the configuration of the vehicle after travelling for 2 units

The second argument of the function dubins_path_sample() is a parameter that has to lie in the interval [0,dubins_path_length(path)], failing which the function will return a EDUBPARAM error-code and nothing

As one can observe from the above code snippet, dubins_path_sample() samples the Dubins path only once. Sampling an entire Dubins path using a step size, can be achieved using the method dubins_path_sample_many(). The dubins_path_sample_many() takes in two arguments:

the Dubins path that needs to be sampled, and
the step size denoting the distance along the path for subsequent samples.

The following code snippet samples a Dubins path using a step size:

errcode, path = dubins_path([0.0, 0.0, 0.], [4., 0.0, 0.], 1., LSL)
errcode, configurations = dubins_path_sample_many(path, 1.)

The output of the above code snippet is

julia> errcode
0
julia> configurations
4-element Array{Any,1}:
 [0.0, 0.0, 0.0]
 [1.0, 0.0, 0.0]
 [2.0, 0.0, 0.0]
 [3.0, 0.0, 0.0]

The same behaviour can also be achieved by using the dubins_path_sample() multiple times, one for each step. For more examples, the readers are refered to the unit tests in the file test/test_api.jl.