CSV File Conventions |

## CSV File Conventions

CSV files are text files and typically have the extension `.txt`, `.dat` or `.csv` . Each line in the file corresponds to a single vertex point of the geometric shape which is defined by the geographic coordinates as a mandatory file content. These coordinates must be stored in distinct columns (see below) separated by the 'tabulator' character (the 'semicolon' character in the special case of MERMAID extraction files, see here). A CSV file must have a header line as described below in order to specify column names (the only exception are SeaDAS 6.x track files which are another special case of CSV files, see here).

#### Formal Description of a valid CSV File

The formal description of a CSV File which SNAP will regard as 'valid' looks as follows:

>             feature-format         := {<property-record> NL} <feature-type-record> {NL <feature-record>}
>             feature-type-record    := {<feature-type-name>} {<sep> <attribute-header>}
>             feature-record         := {<feature-id>}           {<sep> <attribute-value>}

>             simple-format          := {<property-record> NL} <header-record>       {NL <data-record>}
>             header-record          := <attribute-header> { <sep> <attribute-header>}
>             data-record            := <attribute-value>  {<sep> <attribute-value>}

>             attribute-header       := <attribute-name> [<attribute-type-spec>]
>             attribute-type-spec    := ':'<attribute-type>
>             property-record        := '#'<property-name> '=' <property-value>
>             sep                    := TAB | [';' | ',', ...]  (TBC)

#### Comment Lines

The CSV dataset may contain introductory comment lines at the beginning of the file. These lines must start with a '#'.

#### Header Line

The header line follows after the last comment line. It contains column names which are also expected to be separated by the 'tabulator' character. Optionally, the name can be given together with a corresponding data type, which must be separated from the name by a ':'.

For a spatial interpretation of the given data, the CSV data must contain geo-information given as

- Latitude/Longitude: Column name (converted to lower case) must be either 'lat' or 'latitude' in case of Latitude, and either 'lon', 'long' or 'longitude' in case of Longitude.
- Geometry: As additional option, the Sentinel Toolbox supports geoinformation given as geometries which are conform with the Simple Features Specification published by the Open GIS Consortium. These are in particular point (Point), line (LineString) and area (Polygon) as well as their corresponding multi-variants (MultiPoint, MultiLineString, MultiPolygon).
  Consequently, a valid column header would be one of {'geometry:Point', 'geometry:LineString', 'geometry:Polygon', 'geometry:MultiPoint', 'geometry:MultiLineString', 'geometry:MultiPolygon'}.
  In addition, the first data column must contain a unique ID for the geometries (e.g. an index 0, 1, 2,...), and the header of the first column must be one of {'org.esa.snap.Point', 'org.esa.snap.LineString', 'org.esa.snap.Polygon', 'org.esa.snap.MultiPoint', 'org.esa.snap.MultiLineString', 'org.esa.snap.MultiPolygon'}.

If the CSV data set does not provide valid geoinformation as described above, the data set will be rejected as invalid.

#### Record Lines

The record lines follow after the header line. Each line contains a record with data values as specified by the column names and data types given in the header. All data values are also expected to be separated by the 'tabulator' character. The data types are either interpreted automatically or, if given, taken from the column data types in the header line.

If a column named 'Label' or 'label' is present in the CSV data, the corresponding entries will be drawn as label in the current view of the Sentinel Toolbox.

#### Examples for valid CSV Files

SNAP pin export table

>             # SNAP pin export table
>             #
>             # Product:	subset_0_of_MER_RR__1PNPDK20030813_094018_000022742019_00022_07591_4499
>             # Created on:	Thu Apr 26 11:14:57 CEST 2012

>             Name	X	Y	Lon	        Lat	        Label   Desc
>             pin_1	215.5	110.5	9.943068	43.09783	Pin 1   first
>             pin_2	257.5	111.5	10.458842	42.990147	Pin 2   second
>             pin_3	273.5	139.5	10.553919	42.664112	Pin 3   third
>             pin_4	259.5	161.5	10.302726	42.470406	Pin 4   fourth
>             pin_5	220.5	157.5	9.838505	42.601866	Pin 5   fifth
>             pin_6	199.5	135.5	9.656987	42.87649	Pin 6   sixth
>             pin_7	215.5	110.5	9.943068	43.09783	Pin 7   seventh

Internal SNAP pin CSV file

>             #defaultCSS=symbol:pin; fill:#0000ff; fill-opacity:0.7; stroke:#ffffff; stroke-opacity:1.0; stroke-width:0.5
>             org.esa.snap.Pin	geometry:Point	style_css:String	label:String	text:String	pixelPos:Point	geoPos:Point	dateTime:Date
>             pin_1	POINT (3.011064291000366 43.2885627746582)	[null]	Pin 1		POINT (476.5 658.5)	POINT (3.011064291000366 43.2885627746582)	[null]
>             pin_5	POINT (6.4610161781311035 45.858734130859375)	[null]	Pin 5		POINT (660.5 365.5)	POINT (6.4610161781311035 45.858734130859375)	[null]
>             pin_2	POINT (3.9401633739471436 42.58957290649414)	[null]	Pin 2		POINT (565.5 706.5)	POINT (3.9401633739471436 42.58957290649414)	[null]
>             pin_3	POINT (4.629702568054199 41.38515853881836)	[null]	Pin 3		POINT (651.5 803.5)	POINT (4.629702568054199 41.38515853881836)	[null]
>             pin_4	POINT (3.0791780948638916 40.82112121582031)	[null]	Pin 4		POINT (545.5 882.5)	POINT (3.0791780948638916 40.82112121582031)	[null]

Two Multipolygons

>             # MULTIPOLYGONs
>             #
>             # Product:	subset_1_MER_RR__1PQBCM20030809_101416_000002002018_00466_07534_0168
>             # Created on:	Thu Apr 12 14:48:36 CEST 2012

>             # Wavelength:							884.94403
>             org.esa.snap.Multipolygon	Name:String	Geometry:MultiPolygon	radiance_14:Double
>             0	multipolygon_1	MULTIPOLYGON (((10 47, 0 43, 6 40, 10 47)), ((2 39, 3 39, 2.5 38, 2 39)))	59.383057
>             1	multipolygon_2	MULTIPOLYGON (((8 38, 2 45, 8 42, 8 38)), ((3 35, 5 36, 3.5 39, 3 35)))	59.383057