record

Run tracking scenario and record platform, sensor, and emitter information

Syntax

rec = record(sc)

rec = record(sc,format)

rec = record(___,Name,Value)

Description

rec = record(sc) returns a record, rec, of the evolution of the tracking scenario simulation, sc. The function starts from the beginning of the simulation and stores the record until the end of the simulation. A scenario simulation ends when either the scenario's StopTime is reached or any platform in the scenario has finished its trajectory specified by the Trajectory property.

rec = record(sc,format) also specifies the format, format, of the returned platform orientation.

example

rec = record(___,Name,Value) specifies additional recording quantities using name-value pairs. Enclose each Name in quotes.

Input Arguments

expand all

`sc` — Tracking scenario
`trackingScenario` object

Tracking scenario, specified as a trackingScenario object.

`format` — Pose orientation format
`'quaternion'` (default) | `'rotmat'`

Pose orientation format, specified as 'quaternion' or 'rotmat'. When specified as 'quaternion', the Orientation field of the platform pose structure is a quaternion. When specified as 'rotmat', the Orientation field is a rotation matrix.

Example: 'rotmat'

Data Types: char

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

`'IncludeEmitters'` — Enable recording emission information
`false` (default) | `true`

Enable recording emission information, specified as true or false. When specified as true, the rec output contains Emissions, EmitterConfigurations, EmitterPlatformIDs, and CoverageConfig fields.

`'IncludeSensors'` — Enable recording sensor information
`false` (default) | `true`

Enable recording sensor information, specified as true or false. When specified as true, the rec output contains Detections, SensorConfiguration, SensorPlatformIDs, and CoverageConfig fields.

`'InitialSeed'` — Initial random seed for recording
current random seed (default) | positive integer

Initial random seed for recording, specified as a positive integer. If specified as a positive integer, the function assigns this number to the random number generator "Twister" before the recording and resets the random number generator at the end of the recording.

`'HasOcclusion'` — Enable occlusion in signal transmission
`true` (default) | `false`

Enable occlusion in signal transmission, specified as true or false. When specified as true, the function accounts for the effect of occlusion in radar emission propagation.

`'RecordingFormat'` — Format of recording
`'Struct'` (default) | `'Recording'`

Format of recording, specified as 'Struct' or 'Recording'. When specified as 'Struct', the rec output is an array of structures. When specified as 'Recording', the rec output is a trackingScenarioRecording object.

`'CoordinateSystem'` — Coordinate system to report recorded poses
`'Cartesian'` (default) | `'Geodetic'`

Coordinate system to report recorded positions, specified as:

'Cartesian' — Report recorded poses using Cartesian coordinates in the Earth-Centered-Earth-Fixed coordinate frame.
'Geodetic' — Report recorded positions using geodetic coordinates (latitude, longitude, and altitude). Report recorded orientation, velocity, and acceleration in the local reference frame of each platform (North-East-Down by default) corresponding to the current waypoint.

You can only use this argument when the IsEarthCentered property of the tracking scenario,sc, is set to true.

Output Arguments

expand all

`rec` — Records of platform states during simulation
M-by-1 array of structures | `trackingScenarioRecording` object

Records of platform states during the simulation, returned as an M-by-1 array of structures if the RecordingFormat is specified as 'struct' (default), or a trackingScenarioRecording object if the RecordingFormat is specified as 'Recording'. M is the number of time steps in the simulation.

Each record contains the simulation time step and the recorded information at that time. The record structure has at least two fields: SimulationTime and Poses. It can also have other optional fields depending on the input.

The SimulationTime field contains the simulation time of the record. Poses is an N-by-1 array of structures, where N is the number of platforms. Each Poses structure contains these fields:

Field	Description
`PlatformID`	Unique identifier for the platform, specified as a positive integer. This is a required field with no default value.
`ClassID`	User-defined integer used to classify the type of target, specified as a nonnegative integer. Zero is reserved for unclassified platform types and is the default value.
`Position`	Position of target in scenario coordinates, specified as a real-valued 1-by-3 row vector. If the `coordinateSystem` argument is specified as `'Cartesian'`, the `Position` is the 3-element Cartesian position coordinates in meters. If the `coordinateSystem` argument is specified as `'Geodetic'`, the `Position` is the 3-element geodetic coordinates: latitude in degrees, longitude in degrees, and altitude in meters.
`Velocity`	Velocity of platform in scenario coordinates, specified as a real-valued 1-by-3 row vector. units are meters per second. The default value is `[0 0 0]`.
`Acceleration`	Acceleration of the platform in scenario coordinates, specified as a 1-by-3 row vector in meters per second squared. The default value is `[0 0 0]`.
`Orientation`	Orientation of the platform with respect to the local scenario navigation frame, specified as a scalar quaternion or a 3-by-3 rotation matrix. Orientation defines the frame rotation from the local navigation coordinate system to the current platform body coordinate system. Units are dimensionless. The default value is `quaternion(1,0,0,0)`.
`AngularVelocity`	Angular velocity of the platform in scenario coordinates, specified as a real-valued 1-by-3 vector. The magnitude of the vector defines the angular speed. The direction defines the axis of clockwise rotation. units are degrees per second. The default value is `[0 0 0]`.

The optional fields in the rec output are:

Field	Description
`Emissions`	a cell array of emissions (such as `radarEmission` and `sonarEmission`) in the scenario
`EmitterConfigurations`	a struct array of emitter configurations for each emitter
`EmitterPlatformIDs`	a numeric array of platform IDs for each emitter
`Detections`	a cell array of `objectDetection` objects generated by the sensors in the scenario
`SensorConfigurations`	a struct array of sensor configurations for each sensor
`SensorPlatformIDs`	a numeric array of platform IDs for each sensor
`CoverageConfig`	a struct array of coverage configurations for each sensor or emitter

Each emitter configuration structure contains the following fields:

Field	Description
`EmitterIndex`	Unique emitter index, returned as a positive integer.
`IsValidTime`	Valid emission time, returned as `0` or `1`. `IsValidTime` is `0` when emitter updates are requested at times that are between update intervals specified by the `UpdateInterval` property.
`IsScanDone`	Whether the emitter has completed a scan, returned as `true` or `false`.
`FieldOfView`	Field of view of the emitter, returned as a two-element vector [azimuth; elevation] in degrees.
`MeasurementParameters`	Emitter measurement parameters, returned as an array of structures containing the coordinate frame transforms needed to transform positions and velocities in the top-level frame to the current emitter frame.

Each sensor configuration structure contains the following fields:

Field	Description
`SensorIndex`	Unique sensor index, returned as a positive integer.
`IsValidTime`	Valid detection time, returned as `true` or `false`. `IsValidTime` is `false` when detection updates are requested between update intervals specified by the update rate.
`IsScanDone`	`IsScanDone` is `true` when the sensor has completed a scan.
`FieldOfView`	Field of view of the sensor, returned as a 2-by-1 vector of positive real values, [`azfov`;`elfov`]. `azfov` and `elfov` represent the field of view in azimuth and elevation, respectively.
`MeasurementParameters`	Sensor measurement parameters, returned as an array of structures containing the coordinate frame transforms needed to transform positions and velocities in the top-level frame to the current sensor frame.

Each coverage configuration structure contains these fields:

Fields of configurations

Field	Description
`Index`	A unique integer to distinguish sensors or emitters. In practice, you can use `SensorIndex` or `EmitterIndex` of the sensor or emitter objects, respectively.
`LookAngle`	The current boresight angles of the sensor or emitter, specified as: A scalar in degrees if scanning only in the azimuth direction. A two-element vector [`azimuth`; `elevation`] in degrees if scanning both in the azimuth and elevation directions.
`FieldOfView`	The field of view of the sensor or emitter, specified as a two-element vector [`azimuth`; `elevation`] in degrees.
`ScanLimits`	The minimum and maximum angles the sensor or emitter can scan from its `Orientation`. If the sensor or emitter can only scan in the azimuth direction, specify the limits as a 1-by-2 row vector [`minAz`, `maxAz`] in degrees. If the sensor or emitter can also scan in the elevation direction, specify the limits as a 2-by-2 matrix [`minAz`, `maxAz`; `minEl`, `maxEl`] in degrees.
`Range`	The range of the beam and coverage area of the sensor or emitter in meters.
`Position`	The origin position of the sensor or emitter, specified as a three-element vector [`X`, `Y`, `Z`] on the theater plot's axes.
`Orientation`	The rotation transformation from the scenario or global frame to the sensor or emitter mounting frame, specified as a rotation matrix, a quaternion, or three Euler angles in ZYX sequence.

Examples

expand all

Record a Tracking Scenario

Open Live Script

Create a new scenario and add a platform.

scene = trackingScenario;
plat = platform(scene);

Specify the platform trajectory. The distance of the trajectory is 25 meters. The trajectory velocity is 20 m/s in the x-direction.

plat.Trajectory = waypointTrajectory('Waypoints',[0 0 0; 25 0 0], ...
    'TimeOfArrival', [0 25/20]);

Run simulation and record results.

r = record(scene)

r=13×1 struct array with fields:
    SimulationTime
    Poses

Show the record at the initial time.

r(1)

ans = struct with fields:
    SimulationTime: 0
             Poses: [1x1 struct]

r(1).Poses

ans = struct with fields:
         PlatformID: 1
            ClassID: 0
           Position: [0 0 0]
           Velocity: [20 0 0]
       Acceleration: [0 0 0]
        Orientation: [1x1 quaternion]
    AngularVelocity: [0 0 0]

Show the record at the final time.

r(end)

ans = struct with fields:
    SimulationTime: 1.2000
             Poses: [1x1 struct]

r(end).Poses

ans = struct with fields:
         PlatformID: 1
            ClassID: 0
           Position: [24 0 0]
           Velocity: [20 0 0]
       Acceleration: [0 0 0]
        Orientation: [1x1 quaternion]
    AngularVelocity: [0 0 0]

Load and Record Tracking Scenario

Open Live Script

Load an air traffic control tracking scenario.

load ATCScenario scenario

Run simulation and record results.

r = record(scenario, 'quaternion', 'IncludeEmitters', true,...
    'IncludeSensors', true, 'InitialSeed', 2019)

r=3215×1 struct array with fields:
    SimulationTime
    Poses
    Emissions
    EmitterConfigurations
    EmitterPlatformIDs
    Detections
    PointClouds
    PointCloudClusters
    SensorConfigurations
    SensorPlatformIDs
    CoverageConfig

Show the record at the initial time.

r(1)

ans = struct with fields:
           SimulationTime: 0
                    Poses: [4x1 struct]
                Emissions: {0x1 cell}
    EmitterConfigurations: [0x1 struct]
       EmitterPlatformIDs: [0x1 double]
               Detections: {}
              PointClouds: {0x1 cell}
       PointCloudClusters: {0x1 cell}
     SensorConfigurations: [1x1 struct]
        SensorPlatformIDs: 1
           CoverageConfig: [1x1 struct]

Show the record at the final time.

r(end)

ans = struct with fields:
           SimulationTime: 59.9947
                    Poses: [4x1 struct]
                Emissions: {0x1 cell}
    EmitterConfigurations: [0x1 struct]
       EmitterPlatformIDs: [0x1 double]
               Detections: {}
              PointClouds: {0x1 cell}
       PointCloudClusters: {0x1 cell}
     SensorConfigurations: [1x1 struct]
        SensorPlatformIDs: 1
           CoverageConfig: [1x1 struct]

Documentation

record

Syntax

Description

Input Arguments

`sc` — Tracking scenario
`trackingScenario` object

`format` — Pose orientation format
`'quaternion'` (default) | `'rotmat'`

Name-Value Pair Arguments

`'IncludeEmitters'` — Enable recording emission information
`false` (default) | `true`

`'IncludeSensors'` — Enable recording sensor information
`false` (default) | `true`

`'InitialSeed'` — Initial random seed for recording
current random seed (default) | positive integer

`'HasOcclusion'` — Enable occlusion in signal transmission
`true` (default) | `false`

`'RecordingFormat'` — Format of recording
`'Struct'` (default) | `'Recording'`

`'CoordinateSystem'` — Coordinate system to report recorded poses
`'Cartesian'` (default) | `'Geodetic'`

Output Arguments

`rec` — Records of platform states during simulation
M-by-1 array of structures | `trackingScenarioRecording` object

Examples

Record a Tracking Scenario

Load and Record Tracking Scenario

See Also

Sensor Fusion and Tracking Toolbox Documentation

Support

Documentation

record

Syntax

Description

Input Arguments

sc — Tracking scenario trackingScenario object

format — Pose orientation format 'quaternion' (default) | 'rotmat'

Name-Value Pair Arguments

'IncludeEmitters' — Enable recording emission information false (default) | true

'IncludeSensors' — Enable recording sensor information false (default) | true

'InitialSeed' — Initial random seed for recording current random seed (default) | positive integer

'HasOcclusion' — Enable occlusion in signal transmission true (default) | false

'RecordingFormat' — Format of recording 'Struct' (default) | 'Recording'

'CoordinateSystem' — Coordinate system to report recorded poses 'Cartesian' (default) | 'Geodetic'

Output Arguments

rec — Records of platform states during simulation M-by-1 array of structures | trackingScenarioRecording object

Examples

Record a Tracking Scenario

Load and Record Tracking Scenario

See Also

Sensor Fusion and Tracking Toolbox Documentation

Support

`sc` — Tracking scenario
`trackingScenario` object

`format` — Pose orientation format
`'quaternion'` (default) | `'rotmat'`

`'IncludeEmitters'` — Enable recording emission information
`false` (default) | `true`

`'IncludeSensors'` — Enable recording sensor information
`false` (default) | `true`

`'InitialSeed'` — Initial random seed for recording
current random seed (default) | positive integer

`'HasOcclusion'` — Enable occlusion in signal transmission
`true` (default) | `false`

`'RecordingFormat'` — Format of recording
`'Struct'` (default) | `'Recording'`

`'CoordinateSystem'` — Coordinate system to report recorded poses
`'Cartesian'` (default) | `'Geodetic'`

`rec` — Records of platform states during simulation
M-by-1 array of structures | `trackingScenarioRecording` object