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 BEAM 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 geoinformation 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, BEAM/Visat 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.beam.Point', 'org.esa.beam.LineString', 'org.esa.beam.Polygon', 'org.esa.beam.MultiPoint', 'org.esa.beam.MultiLineString', 'org.esa.beam.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 BEAM/Visat.

Examples for valid CSV Files

BEAM pin export table

        # BEAM 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 BEAM pin CSV file

        #defaultCSS=symbol:pin; fill:#0000ff; fill-opacity:0.7; stroke:#ffffff; stroke-opacity:1.0; stroke-width:0.5
        org.esa.beam.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.beam.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