phased.Platform

Model platform motion

Description

The phased.Platform System object™ models the translational motion of one or more platforms in space. A platform can be a target such as a vehicle or airplane, or a sonar or radar transmitter and receiver. The model assumes that the platform undergoes translational motion at constant velocity or constant acceleration during each simulation step. Positions and velocities are always defined in the global coordinate system.

To model a moving platform:

1. Create the phased.Platform object and set its properties.

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

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

sPlat = phased.Platform

sPlat = phased.Platform(Name,Value)

sPlat = phased.Platform(pos,vel,Name,Value)

Description

sPlat = phased.Platform creates a platform System object, sPlat, with default property values. The object models a stationary platform with position at the origin and velocity set to zero.

sPlat = phased.Platform(Name,Value) creates an object, sPlat, with each specified property Name set to the specified Value. You can specify additional name-value pair arguments in any order as (Name1,Value1,...,NameN,ValueN).

sPlat = phased.Platform(pos,vel,Name,Value) creates a platform object, sPlat, with InitialPosition set to pos and Velocity set to vel. Other specified property Names are set to specified Values. The pos and vel arguments are value-only. Value-only arguments do not require a specified Name but are interpreted according to their argument positions. To specify any value-only argument, specify all preceding value-only arguments.

Properties

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

MotionModel — Object motion model

'Velocity' (default) | 'Acceleration' | 'Custom'

Object motion model, specified as 'Velocity', 'Acceleration', or 'Custom'. When you set this property to 'Velocity', the platform follows a constant velocity trajectory during each simulation step. When you set this property to 'Acceleration', the platform follows a constant acceleration trajectory during each simulation step. When you set the property to 'Custom', the platform motion follows a sequence of waypoints specified by the CustomTrajectory property. The object performs a piecewise cubic interpolation on the waypoints to derive the position and velocity at each time step.

MotionModel Value	Usage
'Velocity'	If you set the VelocitySource property to 'Property', the platform moves with constant velocity determined by the Velocity property. You can specify the InitialPosition property or leave it to its default value. You can change the tunable Velocity property at any simulation step. When you set the VelocitySource property to 'Input port', you can input instantaneous velocity as an argument when using this object. Specify the initial position using the InitialPosition property or leave it as a default value.
'Acceleration'	When you set the AccelerationSource property to 'Property', the platform moves with constant acceleration determined by the Acceleration property. You can specify the InitialPosition and InitialVelocity properties or leave them to their defaults. You can change the tunable Acceleration property at any simulation step. When you set the AccelerationSource property to 'Input port', you can input instantaneous acceleration as an argument when using this object. Specify the InitialPosition and InitialVelocity properties or leave them as their defaults.
'Custom'	Specify the platform motion using a series of waypoints in the CustomTrajectory property.

Example: 'Custom'

Data Types: char | string

InitialPosition — Initial position of platform

[0;0;0] (default) | real-valued 3-by-1 column vector | real-valued 3-by-N matrix

Initial position of platform, specified as a real-valued 3-by-1 column vector in the form of [x;y;z] or a real-valued 3-by-N matrix where N is the number of platforms. Each column takes the form [x;y;z]. Position units are meters.

Example: [0 3;5 0;1.5 -6]

Data Types: double

InitialVelocity — Initial velocity of platform

[0;0;0] (default) | real-valued 3-by-1 column vector | real-valued 3-by-N matrix

Initial velocity of platform, specified as a real-valued 3-by-1 column vector in the form of [vx;vy;vz] or a real-valued 3-by-N matrix where N is the number of platforms. Each column taking the form [vx;vy;vz]. Velocity units are meters per second.

This property only applies when you set the MotionModel property to 'Velocity' and the VelocitySource to 'Input port', or when you set the MotionModel property to 'Acceleration'.

Example: [1.3 -0.3;20 1.5;0 0]

Dependencies

To enable this argument, set the MotionModel property to 'Velocity' and the VelocitySource property to 'Input port', or set the MotionModel property to 'Acceleration'.

Data Types: double

VelocitySource — Source of velocity data

'Property' (default) | 'Input port'

Source of velocity data, specified as 'Property' or 'Input port'. When you set the value of this property to 'Property', use Velocity property to set the velocity. When you set this property to 'Input port', use an input argument when using this object to set the velocity.

Example: 'Input port'

Dependencies

To enable this argument, set the MotionModel property to 'Velocity'.

Data Types: char | string

Velocity — Current velocity of platform

[0;0;0] (default) | real-valued 3-by-1 column vector | real-valued 3-by-N

Specify the current velocity of the platform as a 3-by-1 real-valued column vector in the form of [vx;vy;vz] or a 3-by-N real-valued matrix for multiple platforms. Each column taking the form [vx;vy;vz]. Velocity units are meters/sec. The dimension N is the number of platforms.

Example: [1.3 -0.3;20 1.5;0 0]

Tunable: Yes

Dependencies

To enable this argument, set the MotionModel property to 'Velocity' and the VelocitySource property to 'Property'.

Data Types: double

AccelerationSource — Source of acceleration data

'Property' (default) | 'Input port'

Source of acceleration data, specified as one of 'Property' or 'Input port'. When you set the value of this property to 'Property', specify the acceleration using the Acceleration property. When you set this property to 'Input port', use an input argument when using this object to set the acceleration.

Example: 'Input port'

Dependencies

To enable this argument, set the MotionModel property to 'Acceleration'.

Data Types: char | string

Acceleration — Acceleration of platform

[0;0;0] (default) | real-valued 3-by-1 column vector | real-valued 3-by-N matrix

Specify the current acceleration of the platform as a real-valued 3-by-1 column vector in the form [ax;ay;az] or a real-valued 3-by-N matrix with each column taking the form [ax;ay;az]. The dimension N is the number of platforms. Acceleration units are meters/sec/sec.

Example: [1;2;3]

Tunable: Yes

Dependencies

To enable this argument, set the MotionModel property to 'Acceleration' and AccelerationSource property to 'Property'.

Data Types: double

CustomTrajectory — Custom trajectory waypoints

real-valued M-by-L matrix | M-by-L-by-N array

Custom trajectory waypoints, specified as a real-valued M-by-L matrix, or M-by-L-by-N array. M is the number of waypoints. L is either 4 or 7.

• When L is 4, the first column indicates the times at which the platform position is measured. Columns 2 - 4 are position measurements in x, y, and z coordinates. The velocity is derived from the position measurements.

• When L is 7, columns 5 - 7 in the matrix are velocity measurements in x, y, and z coordinates.

When you set the CustomTrajectory property to a three-dimensional array, the number of pages, N, represent the number of platforms. Time units are in seconds, position units are in meters, and velocity units are in meters per second.

Dependencies

To enable this argument, set the MotionModel property to 'Custom'.

Data Types: double

ScanMode — Mechanical scanning mode

'None' (default) | 'Circular' | 'Sector'

Mechanical scan mode for platform, specified as 'None', 'Circular'', or 'Sector', where 'None' is the default. When you set the ScanMode property to 'Circular', the platform scan clockwise 360 degrees continuously in the azimuthal direction of the platform orientation axes. When you set the ScanMode property to 'Sector', the platform scans clockwise in the azimuthal direction in the platform orientation axes within a range specified by the AzimuthSpan property. When the platform scan reaches the span limits, the scan reverses direction and scans back to the other scan limit. Scanning happens within the orientation axes of the platform.

Example: 'Sector'

Data Types: char | string

InitialScanAngle — Initial scan angle of platform

0 (default) | 1-by-N vector

Initial scan angle of platform, specified as a 1-by-N vector where N is the number of platforms. The scanning occurs in the local coordinate system of the platform. The InitialOrientationAxes specifies the original local coordinate system. At the start of the simulation, the orientation axes specified by the InitialOrientationAxes are rotated by the angle specified in the InitialScanAngle property. The default value is zero. Units are in degrees.

Example: [30 40]

Dependencies

To enable this argument, set the ScanMode property to 'Circular' or 'Sector'.

Data Types: double

AzimuthSpan — Azimuth span

[-60 60] (default) | N-by-2 matrix

The azimuth angle span, specified as an N-by-2 matrix where N is the number of platforms. Each row of the matrix specifies the scan range of the corresponding platform in the form [ScanAngleLowerBound ScanAngleHigherBound]. The default value is [-60 60]. Units are in degrees.

Example: [-120 120]

Dependencies

To enable this argument, set the ScanMode property to 'Sector'.

Data Types: double

AzimuthScanRate — Azimuth scan rate

10 (default) | 1-by-N vector

Azimuth scan rate, specified as a 1-by-N vector where N is the number of platforms. Each entry in the vector is the azimuth scan rate for the corresponding platform. The default value is 10 degrees/second. Units are in degrees/second.

Example: [20 15]

Dependencies

To enable this argument, set the ScanMode property to 'Circular' or 'Sector'.

Data Types: double

InitialOrientationAxes — Initial orientation axes of platform

[1 0 0;0 1 0;0 0 1] (default) | 3-by-3 real-valued matrix | 3-by-3-by-N real-valued matrix

Initial orientation axes of platform, specified as a 3-by-3 real-valued orthonormal matrix for a single platform or as a 3-by-3-by-N real-valued matrix for multiple platforms. The dimension N is the number of platforms. When the orientation matrix is 3-by-3, the three columns represent the axes of the local coordinate system (xyz). When the orientation matrix is 3-by-3-by-N, for each page index, the resulting 3-by-3 matrix represents the axes of a local coordinate system.

Data Types: double

OrientationAxesOutputPort — Output orientation axes

false (default) | true

To obtain the instantaneous orientation axes of the platform, set this property to true and use the corresponding output argument when using this object. If you do not want to obtain the orientation axes of the platform, set this property to false.

Example: true

Data Types: logical

Usage

To model a moving platform, call the object with arguments, as if it were a function (described here).

Syntax

[Pos,Vel] = sPlat(T)

[Pos,Vel] = sPlat(T,V)

[Pos,Vel] = sPlat(T,A)

[Pos,Vel,Laxes] = sPlat(___)

Description

[Pos,Vel] = sPlat(T) returns the current position, Pos, and velocity, Vel, of the platform. The method then updates the position and velocity. When the MotionModel property is set to 'Velocity' and the VelocitySource property is set to 'Property', the position is updated using the equation Pos = Pos + Vel*T where T specifies the elapsed time (in seconds) for the current step. When the MotionModel property is set to 'Acceleration' and the AccelerationSource property is set to 'Property', the position and velocity are updated using the equations Pos = Pos + Vel*T + 1/2Acl*T^2 and Vel = Vel + Acl*T where T specifies the elapsed time (in seconds) for the current step.

[Pos,Vel] = sPlat(T,V) returns the current position, Pos, and the current velocity, Vel, of the platform. The method then updates the position and velocity using the equation Pos = Pos + Vel*T where T specifies the elapsed time (in seconds) for the current step. This syntax applies when you set the MotionModel property to 'Velocity' and the VelocitySource property to 'Input port'.

[Pos,Vel] = sPlat(T,A) returns the current position, Pos, and the current velocity, Vel, of the platform. The method then updates the position and velocity using the equations Pos = Pos + Vel*T + 1/2Acl*T^2 and Vel = Vel + Acl*T where T specifies the elapsed time (in seconds) for the current step. This syntax applies when you set the MotionModel property to 'Acceleration' and the AccelerationSource property to 'Input port'.

[Pos,Vel,Laxes] = sPlat(___) returns the additional output Laxes as the platform's orientation axes when you set the OrientationAxesOutputPort property to true.

Input Arguments

T — Step time

real-valued scalar

Step time, specified as a real-valued scalar. Units are seconds

Example: 4

V — Platform velocity

real-valued 3-by-N matrix

Platform velocity, specified as a real-valued 3-by-N matrix where N is the number of platforms to model. This argument applies when you set the MotionModel property to 'Velocity' and the VelocitySource property to 'Input port'. Units are meters per second.

A — Platform acceleration

real-valued 3-by-N matrix

Platform acceleration, specified as a real-valued 3-by-N matrix where N is the number of platforms to model. This argument applies when you set the MotionModel property to 'Acceleration' and the AccelerationSource property to 'Input port'. Units are meters per second-squared.

Output Arguments

Pos — Current platform position

real-valued 3-by-1 column vector | real-valued 3-by-N matrix

Current position of platform, specified as a real-valued 3-by-1 column vector in the form of [x;y;z] or a real-valued 3-by-N matrix where N is the number of platforms to model. Each column takes the form [x;y;z]. Units are meters.

Vel — Current platform velocity

real-valued 3-by-1 column vector | real-valued 3-by-N matrix

Current position of platform, specified as a real-valued 3-by-1 column vector in the form of [x;y;z] or a real-valued 3-by-N matrix where N is the number of platforms to model. Each column takes the form [x;y;z]. Units are meters.

Laxes — Current platform orientation axes

real-valued 3-by-3-by-N matrix

Current platform orientation axes, returned as real-valued 3-by-3-by-N matrix where N is the number of platforms to model. Each 3-by-3 submatrix is an orthonormal matrix. This output is enabled when you set the OrientationAxesOutputPort property to true. The current platform axes rotate around the normal vector to the path of the platform.

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)

Common to All System Objects

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

Simulate Motion of a Platform

Create a platform at the origin having a velocity of (100,100,0) meters per second. Simulate the motion of the platform for two time steps, assuming the time elapsed for each step is one second. The position of the platform is updated after each step.

sPlat = phased.Platform([0; 0; 0],[100; 100; 0]);
T = 1;

At the first call to step, the position is at its initial value.

[pos,v] = step(sPlat,T);
pos

pos = 3×1

     0
     0
     0

At the second call to step, the position changes.

[pos,v] = step(sPlat,T);
pos

pos = 3×1

   100
   100
     0

Model Motion of Circling Airplane

Start with an airplane moving along a circular track with a radius of 10 km at a horizontal speed of 100 m/s and descending at a rate of 1 m/sec. To create circular motion, specify a radially-inward acceleration and constrain the acceleration to lie in the horizontal plane. The acceleration of a body moving in a circle is $\frac{{\mathit{v}}^2}{\mathit{r}}$. The rate of descent is constant. Set the initial orientation axes matrix of the platform to the identity matrix.

Set up the initial conditions

alt = 10000;
radcirc = 10000; % 10 km
phi = 60;
initPos = [cosd(phi)*radcirc;sind(phi)*radcirc;alt];
vs = 100.0;
vx = vs*sind(phi);
vy = -vs*cosd(phi);
vz = -1;
initVel = [vx,vy,vz]';
airplane = phased.Platform('MotionModel','Acceleration', ...
    'AccelerationSource','Input port','InitialPosition',initPos, ...
    'InitialVelocity',initVel,'OrientationAxesOutputPort',true, ...
    'InitialOrientationAxes',eye(3));
accelmag = vs^2/radcirc;
initPos1 = [cosd(phi)*radcirc;sind(phi)*radcirc;0];
unitvec = initPos1/radcirc;
accel = -accelmag*unitvec;

Compute the trajectory

Compute the trajectory for 20000 integration steps at T = 0.1 s intervals

N = 20000;
tstep = .10;
posmat = zeros(3,N);
for n = 1:N
    [pos,vel,oax] = airplane(tstep,accel);   
    velcirc2 = vel(1)^2 + vel(2)^2;
    vmag = sqrt(velcirc2);
    pos1 = [pos(1),pos(2),0]';
    radcirc = sqrt(pos1'*pos1);
    unitvec = pos1/radcirc;
    accelmag = velcirc2/radcirc;
    accel = -accelmag*unitvec;
    posmat(:,n) = pos;
end

Display the final orientation of the local coordinate system.

disp(oax)

    0.1271    0.9919    0.0001
   -0.9919    0.1271    0.0003
    0.0003   -0.0001    1.0000

Plot the trajectory

plot3(posmat(1,:)/1000,posmat(2,:)/1000,posmat(3,:)/1000,'b.')
xlabel('X (km)')
ylabel('Y (km)')
zlabel('Z (km)')
axis equal
grid

Define Platform Motion Using Waypoints

This example shows

Create waypoints from parabolic motion.

x0 = 100;
y0 = -150;
z0 = 0;
vx = 5;
vy = 10;
vz = 0;
ax = 1;
ay = -1;

t = [0:2:20];
x = x0 + vx*t + ax/2*t.^2;
y = y0 + vy*t + ay/2*t.^2;
z = z0*ones(size(t));
wpts = [t.' x.' y.' z.'];

Create a platform object with motion determined using waypoints.

pltfm = phased.Platform('MotionModel','Custom','CustomTrajectory',wpts);
tstep = .5;
nsteps = 40;
X = [];

Advance the platform in time steps of one half second;.

for k = 1:nsteps
    [pos,vel] = pltfm(tstep);
    X = [X;pos'];    
end
plot(x,y,'o'); hold on
plot(X(:,1),X(:,2),'.')
hold off;

Simulate Motion of Two Platforms

Create two moving platforms. The first platform, starting at the origin, has a velocity of (100,100,0) meters per second. The second starts at (1000,0,0) meters and has a velocity of (0,200,0) meters per second. Next, specify different local coordinate axes for each platform defined by rotation matrices. Setting the OrientationAxesOutputPort property to true lets you retrieve the local coordinate axes at each step.

Set up the platform object.

pos0 = [[0;0;0],[1000;0;0]];
vel0 = [[100;100;0],[0;200;0]];
R1 = rotx(30);
R2 = roty(45);
laxes(:,:,1) = R1;
laxes(:,:,2) = R2;
sPlat = phased.Platform(pos0,vel0,...
    'OrientationAxesOutputPort',true,...
    'InitialOrientationAxes',laxes);

Simulate the motion of the platform for two time steps, assuming the time elapsed for each step is one second. The position of the platform is updated after each step.

T = 1;

At the first step, the position and velocity equal the initial values.

[pos,v,lax] = step(sPlat,T);
pos

pos = 3×2

           0        1000
           0           0
           0           0

lax

lax = 
lax(:,:,1) =

    1.0000         0         0
         0    0.8660   -0.5000
         0    0.5000    0.8660


lax(:,:,2) =

    0.7071         0    0.7071
         0    1.0000         0
   -0.7071         0    0.7071

At the second step, the position is updated.

[pos,v,lax] = step(sPlat,T);
pos

pos = 3×2

         100        1000
         100         200
           0           0

lax

lax = 
lax(:,:,1) =

    1.0000         0         0
         0    0.8660   -0.5000
         0    0.5000    0.8660


lax(:,:,2) =

    0.7071         0    0.7071
         0    1.0000         0
   -0.7071         0    0.7071

Free Falling Accelerating Platform

Find the trajectory of a platform which starts with some initial upward velocity but accelerates downward with a constant gravitational acceleration of -9.8 m/sec/sec. Update the platform position and velocity every two seconds.

Construct the platform System object™.

platform = phased.Platform('MotionModel','Acceleration','InitialPosition',[2000,100,3000]',...
    'InitialVelocity',[300,150,20]','AccelerationSource','Property','Acceleration',[0,0,-9.8]');
T = 2;
N = 100;

Call the step method for 100 time samples.

posmat = zeros(3,N);
for n = 1:N
    [pos,vel] = platform(T);
    posmat(:,n) = pos;
end

Plot the trajectory.

plot3(posmat(1,:),posmat(2,:),posmat(3,:),'b.')
axis equal
xlabel('m')
ylabel('m')
zlabel('m')
grid

More About

Platform Orientation

A platform has an associated local coordinate system defined by three orthonormal axis vectors. The direction and magnitude of the velocity vector can change with each call to use this object. When the platform undergoes curvilinear motion, the orientation of the local coordinate system axes rotates with the motion of the platform. The change of direction of the velocity vector defines a rotation matrix. The same rotation matrix is then used to rotate the local coordinate system as well. When the velocity vector maintains a constant direction, the rotation matrix is the identity matrix. The initial orientation of the local coordinate system is specified using the InitialOrientationAxes property. When you specify multiple platforms, each platform rotates independently.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

See System Objects in MATLAB Code Generation (MATLAB Coder).

Version History

Introduced in R2011a