Chapter 16. Debrief file formats

16.1. Replay file format

16.1.1. Track data

Debrief accepts files in the Replay datafile format. This format uses an character string containing data/time, vessel name, position, heading, depth and speed. More than one vessel track can be stored in each file. The gaps between the data fields can be any whitespace characters, that is any number of spaces or tabs, but there must be a value for each data field.

[Note]Note

Whilst file formats recorded here are shown against an 80 character index marker - the fields can be of any width - the data is broken down using delimiters, not fixed field widths.

The file-naming convention for files in the Replay format is to have a .REP suffix.

Through an extension to the format, annotation data can also be accepted. The annotation data format is described below. Whilst annotation and track data may be stored in single file, it is recommended that they are stored in separate files, to ease reading and plotting track-data only.

The standard data format is as follows:

            
1234567890123456789012345678901234567890123456789012345678901234567890123456789
YYMMDD HHMMSS.SSS XXXXXX SY DD MM SS.SS H DDD MM SS.SS H CCC.C SS.S DDD xx...xx
             

or since Autumn 2004 multi-word track names can be entered by enclosing them in double-quotation marks (") and 4-figure year values are supported:

            
12345678901234567890123456789012345678901234567890123456789012345678901234567890
YYYYMMDD HHMMSS.SSS "XYX XYX XYX" SY DD MM SS.SS H DDD MM SS.SS H CCC.C SS.S DDD xx...xxx
                  

The field descriptions are:

Table 16.1. Fields in Debrief position entry

Field number

Description

1

Date, either 2 of 4 figure date, followed by month then date

2

Time

3

Vessel Name - either as single, unquoted word, or as a multi-word phrase enclosed in quotation marks.

4

Symbology (2 or 5 chars, see below)

5

Latitude Degrees (Debrief is able to handle decimal degrees - provide zeros for mins and secs)

6

Latitude Minutes (Debrief is able to handle decimal mins - provide zeros for secs)

7

Latitude Seconds

8

Latitude Hemisphere

9

Longitude Degrees (Debrief is able to handle decimal degrees - provide zeros for mins and secs)

10

Longitude Minutes (Debrief is able to handle decimal mins - provide zeros for secs)

11

Longitude Seconds

12

Longitude Hemisphere

13

Heading (0..359.9 degrees)

14

Speed (knots)

15

Depth (metres) [a]

16Text label (optional). Any text appearing after the depth value is used as a label for that position. If no label is supplied a time-related label is generated. Note: since Jan 2018 it has been possible to also provide a comment. See Section 16.1.5, “Entry comments”

[a] Where depth data is not available, the IEE symbol NaN (Not a Number) may be used. Debrief reflects the absence of this data where applicable.


16.1.2. Symbology attributes

The symbology data field describes the representation required for this vessel track, specifying the colour of track to use and symbol-type to represent that vehicle. The Symbol style read in is used when tracks are to be shown by using symbol (in 2D or 3D). Control of when symbols are shown, and examples of the symbols are shown in Chapter 6, Symbol sets.

Table 16.2. Debrief symbology color codes

Colour

A

Blue

J

Light Green

B

Green

K

Pink

C

Red

L

Gold

D

Yellow

M

Light Grey

E

Magenta

N

Grey

F

Orange

O

Dark Grey

G

Purple

P

White

H

Cyan

Q

Black

I

Brown

  


Table 16.3. Debrief symbology symbol codes

Internal SymbolsSVG Symbols

A

Aircraft

a

Merchant

C

Carrier

b

Fishing

D

Destroyer

c

Pleasure_craft

F

Frigate

d

Coastguard law enforcement

H

Helicopter

e

Friend Surface

M

Merchant

f

Friend Subsurface

N

Minesweeper

g

Neutral Air

P

Torpedo

h

Neutral Surface

R

Troop Carrier

i

Neutral Subsurface

S

Submarine

j

Enemy Air

T

TA Frigate

k

Enemy Surface

U

Cruiser

l

Enemy Subsurface

V

Fishing Vessel

m

Unknown Air

@

Unknown

n

Unknown Surface

I

Cross

o

Unknown Subsurface

J

Square

p

Buoy_1

K

Datum

q

Buoy_2

L

Reference Position

r

Missile

Q

Circle

s

Torpedo

W

Wreck

t

Generic arrow

E

Filled Square

u

Drop point

G

Filled Circle

v

Splash point

0

Active Buoy

w

Vector_1

1

DIFAR Buoy

x

Vector_2

2

LOFAR Buoy

  

3

BARRA Buoy

  

4

Hidar Buoy

  

5

Kingpin Marker

  


Here's an illustration of how the new colors appear against the range of Debrief background colors:

Figure 16.1. 2015 Debrief shades

2015 Debrief shades


[Note]Note

In 2015 the Debrief symbology attributes were extended to allow richer formatting to be applied to data on import. The new attributes mean it is possible to use a 2 or 5 character symbology element for each REP line. This was of particular value in supporting quick turnaround, in-stride, fast-look analysis. It is also of value when high volumes of annotations are produced using a simulation environment such as Odin.

Table 16.4. Debrief extended symbology data fields

Line Type

Line Thickness

Fill Style

@

SOLID

0

Hairwidth

0

No-fill

A

DOTTED

1

1 pixel

1

Solid fill

B

DOT_DASH

2

2 pixels

2

Semi-transparent fill

C

SHORT_DASHES

3

3 pixels

  

D

LONG_DASHES

4

4 pixels

  

E

UNCONNECTED

5

5 pixels

  


[Note]Note

In 2017 the Debrief symbology attributes were extended to allow the provision of some optional named parameters. The first of these is the specification of the layer into which the annotation should be inserted. Note: in the initial implementation spaces are not allowed in the entries. The second of these is the specification of the SVG Symbol to be used in the track.

Table 16.5. Debrief extended symbology data fields

Example

Usage

[LAYER=Other_Target_Layer]

Put this annotation into the layer named "Other_Target_Layer". Note: spaces not allowed. Use this mechanism to load a track as a high performing Lightweight Track.

[SYMBOL=SVG_ICON_NAME]

This annotation places the specified icon as a symbol. Note: spaces not allowed. Icon name must be the exact name that appears in the SVG Section.


Please, take a look at the following example of the extended symbology at use

            
951212 050700.000 NELSON @C[SYMBOL=missile] 22 11 10.08 N 21 43 20.34 W 270.5   2.0      0 
951212 050701.000 COLLINGWOOD @C[SYMBOL=torpedo,LAYER=Support] 22 11 10.08 N 21 43 20.34 W 270.5   2.0      0 
                  

16.1.3. Annotation Data Intro

In addition to the positional vessel track data, annotations can also be added. Each annotation is placed on a single line in a replay file, each line beginning with the comment marker; a semi-colon ';'.To put a comment on a line, begin with two semi-colons.

[Note]Note

Note, when null positions are entered for Sensor data, the position is taken from the track named in "ownship name". Debrief finds the nearest track location equal to or greater than the indicated time, and uses this as the sensor lat and long.

[Note]Note

As with normal positional data, annotation entries which use a track/ownship name may contain multi-word phrases if they are enclosed in quotation marks ("), and the year can be expressed as 2 or 4 figures.

[Note]Note

Debrief can handle decimal values for degrees or minutes. If you original data is in decimal degrees or degrees plus decimal minutes feel free to use these values directly, but remember to provide a zero for the unused column(s). Examples of this are shown below.

                  
;; example using D, M, S
951212 050100.000 NELSON @C 22 11 10.58 N 21 42 2.98 W 269.7 2.0 0
;; example using D
951212 050100.000 NELSON @C 22.455 0 0 N 21.432 0 0 W 269.7 2.0 0
;; example using D, M
951212 050100.000 NELSON @C 22 11.6678 0 N 21 42.543 0 W 269.7 2.0 0
                  
                

[Note]Note

Where labels are provided for shapes, Debrief allows multi-line text labels - just insert a \n character to indicate the line-break

Annotation positions are specified in degrees as in the standard replay file format, and symbology representations are as in the above tables.

16.1.4. Core Elements

The format for the different types of annotations is:

            
123456789012345678901234567890123456789012345678901234567890123456789
0123456789012345678901234567890 

;LINE: @@ DD MM SS H DDD MM SS.S H DD MM SS.S H DDD MM SS H XX.XXX 
;; symb, start lat & long, end lat & long, text label (optional) 

;VECTOR: @@ DD MM SS H DDD MM SS.S H RRR BBB XX.XXX
;; symb, start lat & long, range (yds), brg (degs) , text label (optional)

;TEXT: @@ DD MM SS H DDD MM SS H XX..XX 
;; symb, lat & long, text (note: trailing text is optional, so just the symbol can be specified) 

;NARRATIVE:  YYMMDD HHMMSS  TTT.TTT  XX..XX 
;; dtg, track name, narrative entry 

;TIMETEXT: @@ YYMMDD HHMMSS DD MM SS.S H DDD MM SS.S H XX..XX 
;; symb, date, lat & long, text 

;PERIODTEXT: @@ YYMMDD HHMMSS YYMMDD HHMMSS DD MM SS.S H DDD MM SS.S H 
DDD XX..XX 
;; symb, start date, end date, lat & long, Depth(optional) text 

;GRID: @@ DD MM SS.S H DDD MM SS.S H MM.MM MM.MM XX..XX 
;; symb, centre lat & long (N13) lat increment, long increment, text 

;RECT: @@ DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H XX..XX
;; symb, tl corner lat & long, br corner lat & long, label

;POLY: @@ YYMMDD HHMMSS YYMMDD HHMMSS DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H  XX...XX
;POLY: @@ DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H  XX...XX
;; symb, start date (optional), end date (optional), lat & long 1, lat & long 2, lat & long xxx (until end of line, or non-numeric label encountered)

;POLYLINE: @@ YYMMDD HHMMSS YYMMDD HHMMSS DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H  XX...XX
;POLYLINE: @@ DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H  XX...XX
;; (this is an open polygon) symb, start date (optional), end date (optional), lat & long 1, lat & long 2, lat & long xxx (until end of line, or non-numeric label encountered)

;SGSAGEOG: @@ YYMMDD HHMMSS YYMMDD HHMMSS DD MM SS.S H DDD MM SS.S H 
DD MM SS.S H DDD MM SS.S H XX..XX 
;; symb, start date, end date, tl lat & long, br lat & long, 
text label (1 word) 

;SGSAGRID: @@ YYMMDD HHMMSS YYMMDD HHMMSS AA NN AA NN XX..XX 
;; symb, start date, end date, tl corner, br corner, text label (1 word) 

;WHEEL: @@ YYMMDD HHMMSS DD MM SS.S H DDD MM SS.S H YYY YYY XX.XX
;; symb, centre date, centre lat, centre long, inner radius (yards), 
outer radius (yards), label

;CIRCLE: @@ DD MM SS.S H DDD MM SS.S H YYY XX.XX 
;; symb, centre lat, centre long, radius (yards), label 

;ELLIPSE: BD YYMMDD HHMMSS DD MM SS.SS H DD MM SS.SS H CCC XXXX YYYY xx.xx 
;; symb, date, time, lat, long, orientation, maxima (yards), 
minima (yards), label 

;BRG: BD YYMMDD HHMMSS DD MM SS.SS H DD MM SS.SS H CCC XXXX xx.xx 
;; symb, date, time, lat, long, orientation, length (yards), label (one word) 

;SENSOR: YYMMDD HHMMSS.SSS AAAAAA @@ DD MM SS.SS H DDD MM SS.SS H 
BBB.B RRRR yy..yy xx..xx 
;; date, ownship name, symbology, sensor lat/long (or the single word NULL), 
bearing (degs), range(yds) [or the single world NULL], sensor name, label (to end of line),
, optional comment - see Section 16.1.5, “Entry comments”

;SENSOR2: YYMMDD HHMMSS.SSS AAAAAA @@ DD MM SS.SS H DDD MM SS.SS H BBB.B CCC.C 
FFF.F RRRR yy..yy xx..xx
;; date, ownship name, symbology, sensor lat/long (or the single word NULL), 
bearing (degs) [or the single word NULL], ambigous bearing (degs) [or the 
single word NULL], frequency(Hz) [or the single word NULL],  range(yds) 
[or the single word NULL], sensor name, label (to end of line), optional
comment - see Section 16.1.5, “Entry comments”

;SENSOR3: YYMMDD HHMMSS.SSS AAAAAA @@ DD MM SS.SS H DDD MM SS.SS H BBB.B  CCC.C 
FFF.F GGG.G RRRR yy..yy xx..xx
;; date, ownship name, symbology, sensor lat/long (or the single word NULL), 
bearing (degs) [or the single word NULL], bearing accuracy (degs) 
[or the single word NULL], frequency(Hz) [or the single word NULL], 
frequency accuracy (Hz) [or the single word NULL], range(yds) 
[or the single word NULL], sensor name, label (to end of line), optional
comment - see Section 16.1.5, “Entry comments”

;TMA_POS: YYMMDD HHMMSS.SSS AAAAAA @@ DD MM SS.SS H DDD MM SS.SS H 
TT...TT OOO.O  XXXX YYYY  CCC SSS DDD xx.xx 
;; date, time, ownship name, symbology, tma lat, tma long, track name, 
ellipse orientation (deg from north),  maxima (yds), minima (yds), course, 
speed, depth (m), label string

;TMA_RB: YYMMDD HHMMSS.SSS AAAAAA @@ BBB.B RRR.R TT...TT OOO.O 
XXXX YYYY  CCC SSS DDD xx.xx 
;; date, time, ownship name, symbology, bearing (deg), range (yds), 
track name, elipse orientation (deg from north),  maxima (yds), minima (yds), 
course, speed, depth (m), label string

;NARRATIVE:  YYMMDD HHMMSS  TTT.TTT  XX..XX
 ;; dtg, track name, narrative entry. Note the track name can be multi-word if 
surrounded by quotes (").

;NARRATIVE2:  YYMMDD HHMMSS  TTT.TTT AA..AA XX..XX
 ;; dtg, track name, narrative entry-type, narrative entry.  Note the track name 
and entry type can be multi-word if surrounded by quotes (").
               

16.1.5. Entry comments

Note: some entry types allow an additional comment to be appended to the end of an entry. The comment follows a // separator.


951212 050100.000 NONSUCH @A@00 22 12 10.51 N 21 32 14.81 W 269.9 2.0 0
;; label is normal DTG value, comment is empty (legacy behaviour)

951212 050200.000 NONSUCH @A@00 22 12 10.51 N 21 32 14.81 W 269.9 2.0 0 Standard label
;; label is "Standard label", comment is empty (legacy behaviour)

951212 050300.000 NONSUCH @A@00 22 12 10.51 N 21 32 27.27 W 268.7 2.0 0 Standard label // Custom comment
;; label is "Standard label", comment is "Custom comment"

951212 050400.000 NONSUCH @BA10 22 12 10.28 N 21 32 40.33 W 270.6 2.0 0 // Custom comment
;; label is normal DTG value, comment is "Custom comment"

;SENSOR2: 951212 051600.000 NEL_STYLE2 @B NULL 59.3 300.8 49.96 NULL SENSOR LABEL // COMMENT
;; label is "SENSOR LABEL", comment is "COMMENT"
          
          

For track positions, it's possible to indicate whether the comment should be shown, using the Comment Showing attribute of the position. The comment is always placed opposite the label, even if the label isn't shown

16.1.6. Towed Array Extensions

In Spring 2017 additional annotations were introduced to support more complex Towed Array datasets



;TA_FORE_AFT: 090722 041522 NONSUCH SENSOR_A_1 44.2 260.2 45.4 262.3
;; data from module sensors, in depth/heading pairs
;; date-time, platform, sensor, two pairs of depth (m) & heading (degs) data.  Or replace the pairs with four NULL values.

;TA_MODULES: YYMMDD HHMMSS AAAAAA BBBBBB DD.D HH.H ... DD.D HH.H
;; 12 sets of depth/heading data from module sensors. Either first 4, or last 8 will be populated
;; the other pairs should have zero values
;; date-time, platform, sensor, pairs of depth & heading data, to the end of line.
;; But, if you're not interested in the spec at all, you could just include four NULL values.

;TA_COG_ABS: YYMMDD HHMMSS AAAAAA BBBBBB LAT.Y LONG.X DD.D
;; absolute measurement of towed array aperture Centre of Gravity
;; date-time, platform, sensor, lat/long (Degrees) depth (m). Lat/Lon/D may be null.

;TA_COG_REL: YYMMDD HHMMSS AAAAAA BBBBBB XX.X YY.Y DD.D
;; relative measurement of towed array aperture Centre of Gravity
;; date-time, platform, sensor, x/y/depth(m). X/Y/D may be null

               

16.1.7. Dynamic Elements

In addition to individual annotation shapes it is possible to define a dynamic annotation. Do this by using a series of dynamic annotations, all with the same annotation name. Once loaded, Debrief will only show the shape nearest to the current scenario time (according to the Time Controller). The dynamic annotations largely take the same format as their non-dynamic equivalents as described above, save for the introduction of a Shape Name

The format for the different types of dynamic annotations is:

            
;;DYNAMIC_CIRCLE: @@@@@ "NAME" YYMMDD HHMMSS DD MM SS.S H DDD MM SS.S H YYY XX.XX 
;;DYNAMIC_POLY: @@@@@ "NAME" YYMMDD HHMMSS DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H  XX...XX
;;DYNAMIC_RECT: @@@@@ "NAME" YYMMDD HHMMSS DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H XX..XX
;; symb, shape name, date-time [other fields as in the standard annotation type]
;; example:
;DYNAMIC_CIRCLE: @@011 "Circle Track A" 151212 143000 54 05 12.1 N 4 0 12.4 W 1000 At time 1430 
;DYNAMIC_CIRCLE: @@011 "Circle Track B" 151212 143100 54 05 14.1 N 4 0 12.1 W 1100 At time 1431         
;DYNAMIC_POLY: @@011 "Circle Track C" 151212 143200 54 05 15.1 N 4 0 12.1 W  54 06 15.1 N 4 0 11.1 W  54 05 13.1 N 4 1 14.1 W At time 1432         
;DYNAMIC_RECT: @@011 "Circle Track D" 151212 143300 54 05 17.1 N 4 0 12.1 W  54 05 10.1 N 4 0 12.6 W At time 1433
            
            

16.1.8. Dynamic Track Annotations

It is also possible to attach annotations to tracks - so that the annotation moves (and rotates) with the track. These annotations can be grouped. This allows the dynamic shape itself to change dimensions during its life, but with the whole collection of shapes switched on and off as one.

Here are a series of examples (but note that the REP lines have been abbreviated):

The format for the different types of dynamic track annotations is shown below. Note that each line may contain a series of definitions, and that the distance units are in yards.

            
;SENSORARC YYMMDD HHMMSS.SSS YYMMDD HHMMSS.SSS TRACKNAME SYMBOLOGY LEFT RIGHT INNER OUTER [LEFT RIGHT INNER OUTER] LABEL
;; (start time, end time, parent track, styling, min-max angles of the arc, inner-outer radiuses, collective label.
;; simple example

;SENSORARC 951212 062800 951212 063000 NELSON @@ -75 35 0 1000 "fwd dynamic"
;; dynamic example - so donut spreads outwards in time using 3 steps

;SENSORARC: 951212 053000 951212 054000 NELSON @A 0 360 500 1000 CZ_Ring
;SENSORARC: 951212 054000 951212 055000 NELSON @B 0 360 600 1100 CZ_Ring
;SENSORARC: 951212 055000 951212 060000 NELSON @C 0 360 700 1200 CZ_Ring
            
            

[Note]Note

A NULL can be provided instead of one or more of the times. This will result in the dynamic shape being used for part or all of the track lifetime.

16.1.9. Formatting helpers

Entries can be included in REP files to help format data as it is loaded. These commands can specify the frequency at which labels/symbols are shown, or perform other presentation configuration, either on specific tracks/layers or for all data.

[Tip]Tip

You can use these helpers to create a set of default look & feels for your plots. Create a set of label, symbol, arrow markers to suit your data, then store them in a REP file, called something like LONG_RANGE_FORMAT.REP. Then, when conducting a new piece of analysis of long range tracks, start by opening this REP file. Now, when you drag in your tracks, they will all get formatted according to your preferred styling.

The format for these helpers is shown below.

            
;FORMAT_FIX: 30_min_lab LABEL NULL NULL TRUE 1800000
;; 30_min_lab - name for this formatter (shown in outline view) 
;; LABEL - what we're applying to (SYMBOL, LABEL, ARROW)
;; NULL - track name we apply to (or null for all tracks)
;; NULL - symbology we apply to (e.g. @A) (or null for all tracks) 
;; TRUE - whether interval should fall on regular interval or start
;;        from first data point
;; 1800000 - interval (in millis) to apply formatting

;FORMAT_FIX: 10_min_sym SYMBOL NELSON NULL TRUE 600000 
;; show symbol on every 10 minute marker (00:00,00:10, 00:20, etc) 
;;    for track Nelson

;FORMAT_LAYER_HIDE: format_name layer_name
;; name for this formatter, name of the layer to hide 

;FORMAT_LAYER_HIDE: format_name layer_1_name "layer 2 name"
;; name for this formatter, name of the layers to hide
;;     quotes can be used if name contains spaces 

;FORMAT_TRACK_NAME_AT_END: format_name track_names
;; name for this formatter, list of track names for which the name 
;;     should be shown at the end, or empty to apply to all tracks
            
            

[Note]Note

A NULL can be provided instead of one or more of the times. This will result in the dynamic shape being used for part or all of the track lifetime.