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.

[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), as described in Chapter 6, Symbol sets.

Table 16.2. Debrief core symbology data fields

Symbol Style

Colour

A

Aircraft

@

White

C

Carrier

A

Blue

D

Destroyer

B

Green

F

Frigate

C

Red

H

Helicopter

D

Yellow

M

Merchant

E

Magenta

N

Minesweeper

F

Orange

P

Torpedo

G

Purple

R

Troop Carrier

H

Cyan

S

Submarine

I

Brown

T

TA Frigate

J

Light Green

U

Cruiser

K

Pink

V

Fishing Vessel

L

Gold

@

Unknown

M

Light Grey

I

Cross

N

Grey

J

Square

O

Dark Grey

K

Datum

P

White

L

Reference Position

Q

Black

Q

Circle

W

Wreck

E

Filled Square

G

Filled Circle


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.3. 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.

Table 16.4. 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


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)

;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)

;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)

;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. Towed Array Extensions

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



;TA_FORE_AFT: YYMMDD HHMMSS AAAAAA BBBBBB [DD.D HH.H] [DD.D HH.H]↵
;; data from pair of module sensors 
;; date-time, platform, sensor, two pairs of depth (m) & heading (degs) data.

;TA_MODULES: YYMMDD HHMMSS AAAAAA BBBBBB [DD.D HH.H] ... [DD.D HH.H]↵
;; data from long series of module sensors 
;; date-time, platform, sensor, pairs of depth & heading data, to the end of line.


;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)

;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)

               

16.1.6. 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: @@@@@ YYMMDD HHMMSS "NAME" DD MM SS.S H DDD MM SS.S H YYY XX.XX 
;;DYNAMIC_POLYGON: @@@@@ YYMMDD HHMMSS "NAME" 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_RECTANGLE: @@@@@ YYMMDD HHMMSS "NAME"DD MM SS.S H DDD MM SS.S H DD MM SS.S H DDD MM SS.S H XX..XX
;; symb, date-time, shape name [other fields as in the standard annotation type
;; example:
;DYNAMIC_CIRCLE: @@011 151212 143000 "Circle Track A" 54 05 12.1 N 4 0 12.4 W 1000 At time 1430 
;DYNAMIC_CIRCLE: @@011 151212 143100 "Circle Track A" 54 05 14.1 N 4 0 12.1 W 1100 At time 1431         
;DYNAMIC_POLYGON: @@011 151212 143200 "Circle Track A" 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_RECTANGLE: @@011 151212 143300 "Circle Track A" 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.7. 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.8. 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.