M-File Help: Vehicle

M-File Help: Vehicle | View code for Vehicle

# Vehicle

Car-like vehicle class

This class models the kinematics of a car-like vehicle (bicycle model) on a plane that moves in SE(2). For given steering and velocity inputs it updates the true vehicle state and returns noise-corrupted odometry readings.

## Methods

init | initialize vehicle state
f | predict next state based on odometry
step | move one time step and return noisy odometry
control | generate the control inputs for the vehicle
update | update the vehicle state
run | run for multiple time steps
Fx | Jacobian of f wrt x
Fv | Jacobian of f wrt odometry noise
gstep | like step() but displays vehicle
plot | plot/animate vehicle on current figure
plot_xy | plot the true path of the vehicle
add_driver | attach a driver object to this vehicle
display | display state/parameters in human readable form
char | convert to string

## Class methods

plotv | plot/animate a pose on current figure

## Properties (read/write)

x | true vehicle state: x, y, theta (3x1)
V | odometry covariance (2x2)
odometry | distance moved in the last interval (2x1)
rdim | dimension of the robot (for drawing)
L | length of the vehicle (wheelbase)
alphalim | steering wheel limit
maxspeed | maximum vehicle speed
T | sample interval
verbose | verbosity
x_hist | history of true vehicle state (Nx3)
driver | reference to the driver object
x0 | initial state, restored on init()

## Examples

Create a vehicle with odometry covariance

    v = Vehicle( diag([0.1 0.01].^2 );

and display its initial state

    v

now apply a speed (0.2m/s) and steer angle (0.1rad) for 1 time step

    odo = v.update([0.2, 0.1])

where odo is the noisy odometry estimate, and the new true vehicle state

    v

We can add a driver object

    v.add_driver( RandomPath(10) )

which will move the vehicle within the region -10&lt;x&lt;10, -10&lt;y&lt;10 which we can see by

    v.run(1000)

which shows an animation of the vehicle moving for 1000 time steps between randomly selected wayoints.

## Notes

- Subclasses the MATLAB handle class which means that pass by reference semantics apply.

## Reference

Robotics, Vision & Control, Chap 6 Peter Corke, Springer 2011

## See also

RandomPath, EKF

# Vehicle.Vehicle

Vehicle object constructor

v = Vehicle(v_act, options) creates a Vehicle object with actual odometry covariance v_act (2x2) matrix corresponding to the odometry vector [dx dtheta].

## Options

'stlim', A | Steering angle limited to -A to +A (default 0.5 rad)
'vmax', S | Maximum speed (default 5m/s)
'L', L | Wheel base (default 1m)
'x0', x0 | Initial state (default (0,0,0) )
'dt', T | Time interval
'rdim', R | Robot size as fraction of plot window (default 0.2)
'verbose' | Be verbose

## Notes

- Subclasses the MATLAB handle class which means that pass by reference semantics apply.

# Vehicle.add_driver

Add a driver for the vehicle

V.add_driver(d) connects a driver object d to the vehicle. The driver object has one public method:

    [speed, steer] = D.demand();

that returns a speed and steer angle.

## Notes

- The Vehicle.step() method invokes the driver if one is attached.

## See also

Vehicle.step, RandomPath

# Vehicle.char

Convert to a string

s = V.char() is a string showing vehicle parameters and state in a compact human readable format.

## See also

Vehicle.display

# Vehicle.control

Compute the control input to vehicle

u = V.control(speed, steer) is a control input (1x2) = [speed,steer] based on provided controls speed,steer to which speed and steering angle limits have been applied.

u = V.control() as above but demand originates with a "driver" object if one is attached, the driver's DEMAND() method is invoked. If no driver is attached then speed and steer angle are assumed to be zero.

## See also

Vehicle.step, RandomPath

# Vehicle.display

Display vehicle parameters and state

V.display() displays vehicle parameters and state in compact human readable form.

## Notes

- This method is invoked implicitly at the command line when the result of an expression is a Vehicle object and the command has no trailing semicolon.

## See also

Vehicle.char

# Vehicle.f

Predict next state based on odometry

xn = V.f(x, odo) is the predicted next state xn (1x3) based on current state x (1x3) and odometry odo (1x2) = [distance, heading_change].

xn = V.f(x, odo, w) as above but with odometry noise w.

## Notes

- Supports vectorized operation where X and XN (Nx3).

# Vehicle.Fv

Jacobian df/dv

J = V.Fv(x, odo) is the Jacobian df/dv (3x2) at the state x, for odometry input odo (1x2) = [distance, heading_change].

## See also

Vehicle.F, Vehicle.Fx

# Vehicle.Fx

Jacobian df/dx

J = V.Fx(x, odo) is the Jacobian df/dx (3x3) at the state x, for odometry input odo (1x2) = [distance, heading_change].

## See also

Vehicle.f, Vehicle.Fv

# Vehicle.init

Reset state of vehicle object

V.init() sets the state V.x := V.x0, initializes the driver object (if attached) and clears the history.

V.init(x0) as above but the state is initialized to x0.

# Vehicle.plot

Plot vehicle

V.plot(options) plots the vehicle on the current axes at a pose given by the current state. If the vehicle has been previously plotted its pose is updated. The vehicle is depicted as a narrow triangle that travels "point first" and has a length V.rdim.

V.plot(x, options) plots the vehicle on the current axes at the pose x.

H = V.plotv(x, options) draws a representation of a ground robot as an oriented triangle with pose x (1x3) [x,y,theta]. H is a graphics handle.

V.plotv(H, x) as above but updates the pose of the graphic represented by the handle H to pose x.

## Options

'scale', S | Draw vehicle with length S x maximum axis dimension
'size', S | Draw vehicle with length S
'color', C | Color of vehicle.
'fill' | Filled

## See also

Vehicle.plotv

# Vehicle.plot_xy

Plots true path followed by vehicle

V.plot_xy() plots the true xy-plane path followed by the vehicle.

V.plot_xy(ls) as above but the line style arguments ls are passed to plot.

## Notes

- The path is extracted from the x_hist property.

# Vehicle.plotv

Plot ground vehicle pose

H = Vehicle.plotv(x, options) draws a representation of a ground robot as an oriented triangle with pose x (1x3) [x,y,theta]. H is a graphics handle. If x (Nx3) is a matrix it is considered to represent a trajectory in which case the vehicle graphic is animated.

Vehicle.plotv(H, x) as above but updates the pose of the graphic represented by the handle H to pose x.

## Options

'scale', S | Draw vehicle with length S x maximum axis dimension
'size', S | Draw vehicle with length S
'color', C | Color of vehicle.
'fill' | Filled with solid color as per 'color' option
'fps', F | Frames per second in animation mode (default 10)

## Example

Generate some path 3xN

    p = PRM.plan(start, goal);

Set the axis dimensions to stop them rescaling for every point on the path

    axis([-5 5 -5 5]);

Now invoke the static method

    Vehicle.plotv(p);

## Notes

- This is a class method.

## See also

Vehicle.plot

# Vehicle.run

Run the vehicle simulation

V.run(n) runs the vehicle model for n timesteps and plots the vehicle pose at each step.

p = V.run(n) runs the vehicle simulation for n timesteps and return the state history (Nx3) without plotting. Each row is (x,y,theta).

## See also

Vehicle.step

# Vehicle.run2

Run the vehicle simulation with control inputs

p = V.run2(T, x0, speed, steer) runs the vehicle model for a time T with speed speed and steering angle steer. p (Nx3) is the path followed and each row is (x,y,theta).

## Notes

- Faster and more specific version of run() method.
- Used by the RRT planner.

## See also

Vehicle.run, Vehicle.step, RRT

# Vehicle.step

Advance one timestep

odo = V.step(speed, steer) updates the vehicle state for one timestep of motion at specified speed and steer angle, and returns noisy odometry.

odo = V.step() updates the vehicle state for one timestep of motion and returns noisy odometry. If a "driver" is attached then its DEMAND() method is invoked to compute speed and steer angle. If no driver is attached then speed and steer angle are assumed to be zero.

## Notes

- Noise covariance is the property V.

## See also

Vehicle.control, Vehicle.update, Vehicle.add_driver

# Vehicle.update

Update the vehicle state

odo = V.update(u) is the true odometry value for motion with u=[speed,steer].

## Notes

- Appends new state to state history property x_hist.
- Odometry is also saved as property odometry.

# Vehicle.verbosity

Set verbosity

V.verbosity(a) set verbosity to a. a=0 means silent.

© 1990-2014 Peter Corke.