The SeeYou CUP format, made legible.

A .cup file holds a list of waypoints — one CSV row each, with a header row naming the columns — and, optionally, a list of tasks that reference those waypoints by name. A single literal line separates them:

name,code,country,lat,lon,elev,style,rwdir,rwlen,rwwidth,freq,desc
"Lesce","LJBL",SI,4621.379N,01410.467E,504.0m,5,144,1130.0m,,123.500,"Home Airfield"
…more waypoints…
-----Related Tasks-----
"300 km Triangle","Lesce","Sv Peter","Maier","Sv Peter","Lesce"
Options,TaskTime=03:00:00,WpDis=True
ObsZone=0,Style=2,R1=2500m,A1=180,Line=1

Most .cup files in circulation have no task section at all — they are pure waypoint databases, which is how site and turnpoint collections are distributed. A file that simply ends after the separator is valid and means "no tasks".

Encoding is UTF-8, or Windows-1252 for legacy files. Datum is WGS-84 throughout. Line endings are CRLF in practice; accept LF. There is no version marker inside the file — the format has only ever grown by adding optional trailing columns and optional key/value parameters, so a current reader parses a 2004-era file unchanged.

CUPX (.cupx) is two ZIP archives concatenated — pictures under pics/, then a POINTS.CUP whose pics column names them. The CUP grammar inside is identical; CUPX is purely packaging.

CUP is CSV, in a permissive dialect. Fields are comma-separated; a field containing a comma must be double-quoted; embedded quotes are escaped by doubling them (""), per RFC 4180. Quoting is optional otherwise, and real files quote name and desc while leaving codes, coordinates and numerics bare.

Two rules turn the header from decoration into the thing you must actually parse:

Whitespace around fields is common and insignificant.   488.0m,   5   and 5103.117N   all appear in files shipped as reference test data. Trim every field before parsing it. Empty fields are legal and mean "not specified"; a row may end in a run of empty fields or a trailing comma.

Units

Numeric fields carry an optional unit suffix. When it is missing, metres are assumed. The decimal separator is always a point, and units may be mixed freely within one file.

Latitude is 9 characters, longitude 10, each ending in a hemisphere letter. This is not decimal degrees, and it is not DMS — the digits after the point are thousandths of a minute.

decimal = degrees + minutes / 60
if hemisphere is S or W: decimal = -decimal

The degrees field is zero-padded to a fixed width — 2 for latitude, 3 for longitude — and that is what makes the split unambiguous. Slice by position from the right: the two characters before the decimal point are whole minutes, everything before them is degrees.

Three decimal minutes is roughly 1.85 m of latitude. That is the format's resolution — a round trip through CUP will not preserve more.

Filter by name or meaning, or narrow by group. The waypoint columns are the CSV header keys; the task keys are the Options and ObsZone parameters below the separator.

Only name, lat and lon are practically required. name is doubly important: it must be unique, because it is the only key a task has for referencing a waypoint.

The style column is an integer 0–21. A value outside the table must be read as 0 (Unknown) rather than rejected — that is an explicit requirement of the spec, not a tolerance.

Everything after -----Related Tasks----- describes tasks. A task is one task line, optionally followed by decoration lines that apply to it. The next task begins at the next line that is not a decoration line.

description, takeoff, 1st turnpoint, 2nd turnpoint, …, last turnpoint, landing

Every field after the description is a waypoint name that must match the name column of a waypoint defined above the separator, matched as an exact string. The number of points, and of tasks, is unlimited.

"1000km FAI Triangle","0LESCE","Sv Peter","1K MAIER","1K ZELTW","Sv Peter","0LESCE"
,"0LESCE","0Start","750 Huje","750 Brenner","0Start","0LESCE",

The description is optional; when it is empty the line simply begins with a comma, and the reading application infers the task type. That leading " or , is exactly how a reader recognises a task line — everything else in the section is decoration belonging to the task above it.

Decoration lines

Point=1,"Point_3",PNT_3,,4627.136N,01412.856E,0.0m,1,,,,,,,

Point=1 is documented as "the first turnpoint (after takeoff)" — the index counts task-line columns with the takeoff at 0, so Point=1 is the third comma-separated field. Note this is offset by one from ObsZone= numbering; the two schemes are not interchangeable.

The Options line

Options,NoStart=12:34:56,TaskTime=01:45:12,WpDis=False,NearDis=0.7km,NearAlt=300.0m

WpDis is the most consequential key in the file: it decides whether this is a racing task (True — measure waypoint to waypoint) or an assigned-area task (False — measure through the actual fixes), and that in turn changes how the observation-zone parameters are interpreted. Every key is optional; an absent key means the application default. The full list is in the field explorer.

An ObsZone= line gives a point's zone as key/value pairs. Style names the orientation of the zone, not its shape — the shape comes from the combination of R1, A1, R2, A2 and Line.

An unknown or unparsable Style falls back to 1 (Symmetrical). Defaults for absent keys: R1 = 500 m, R2 = 200 m, Line = false.

Try it

Move the controls and watch the zone. The ObsZone line below is what a file would carry for the shape on screen; the bisector points up.

The full mapping

Naviter defines the keys; the geometry below is XCSoar's, and is the de-facto standard.

Three parameter combinations are additionally recognised by value, within ±2 units, as named zones:

ObsZone=0 is the start, and the start is the second waypoint on the task line — because the first is the takeoff.

task line:  desc , takeoff , start , tp1 , tp2 , … , finish , landing
column:      0        1        2      3     4          n-1       n
ObsZone:                       0      1     2          n-3      —

ObsZone=i addresses task-line column i + 2. Neither the takeoff nor the landing can carry a zone. This is what XCSoar implements, and it is consistent with the Naviter document's own "0 = Start".

It bites in both directions:

• A reader that maps ObsZone=i onto the i-th waypoint after the description applies every radius one point too early — the start's gate width lands on the takeoff, and so on down the task.
• Conversely, a great many free-flight files carry no takeoff column at all and begin the list at the start point. On those, index i really does address column i + 1, and the spec-conformant reader is the one that is wrong.

There is no flag distinguishing the two. The usable heuristic is to compare the highest ObsZone index against the number of waypoint columns C: a spec-conformant file tops out at C − 3, while a takeoff-less file reaches C − 2 or C − 1. When a file carries no zones at all, the question is moot.

Edit the file on the left. Every line is parsed live — the header row drives the column mapping, coordinates are converted to decimal, styles and units are spelled out, task columns are labelled with their role, and each observation zone is resolved to a shape. Nothing is uploaded; it all runs in the page.

• Zone indexing. The takeoff offset is the biggest source of disagreement between implementations. Detect it; do not assume it.
• Halves. A1 is a half-angle and R1 on a line is a half-width. Both fail silently when doubled or halved.
• Header-driven, not position-driven. Column order is arbitrary and trailing columns are droppable. The 11-column no-rwwidth layout is widespread enough to count as a second canonical order.
• Unescaped quotes. Files exist whose description contains a bare " — "Rabbit holes, 20" ditch south of rwy". Strict RFC 4180 parsing throws; be lenient on the trailing free-text field.
• Names are the only key. Matching is exact and case-sensitive in practice. Preserve names byte-for-byte through a round trip — do not trim, re-case or truncate a name a task might reference.
• Encoding. Legacy files are Windows-1252. A UTF-8 decode of one mangles accented site names rather than failing, so sniff for invalid sequences and fall back.
• Unknown keys and columns. Both Options and ObsZone carry vendor extensions. Skip what you do not recognise; never fail the file.
• Units default to metres when the suffix is absent, and may be mixed within one file. Never assume the file-wide unit from the first row.
• An empty task section is valid. -----Related Tasks----- as the last line means "no tasks", not "malformed".
• Style is clamped, not rejected. An out-of-range style must be read as 0 (Unknown).