# Well-Known Text format

Many entities in this specification can be printed in a well-known text format. This allows objects to be stored in databases (persistence), and transmitted between interoperating computer programs. Each entity has a keyword in upper case (for example, `DATUM` or `UNIT`) followed by the defining, comma-delimited, parameters of the object in brackets. Some objects are composed of objects so the result is a nested structure. Implementations are free to substitute standard brackets ( ) for square brackets [ ] and should be prepared to read both forms of brackets. The definition for WKT is shown below using Extended Backus Naur Form (EBNF). The WKT for a math transform can be used inside a engineering coordinate reference system, so it is shown first.

## Math Transform WKT

    <math transform> = <param mt> | <concat mt> | <inv mt> | <passthrough mt>
    <param mt>       = PARAM_MT["<classification name>" {,<parameter>}* ]
    <parameter>      = PARAMETER["<name>", <value>]
    <value>          = <number>
    <concat mt>      = CONCAT_MT[<math transform> {,<math transform>}* ]
    <inv mt>         = INVERSE_MT[<math transform>]
    <passthrough mt> = PASSTHROUGH_MT[<integer>, <math transform>]

## Coordinate System WKT

    <coordinate system>  = <horz cs> | <geocentric cs> | <vert cs> | <compd cs> | <fitted cs> | <local cs>
    <horz cs>            = <geographic cs> | <projected cs>
    <projected cs>       = PROJCS["<name>", <geographic cs>, <projection>, {<parameter>,}* <linear unit> {,<twin axes>}{,<authority>}]
    <projection>         = PROJECTION["<name>" {,<authority>}]
    <geographic cs>      = GEOGCS["<name>", <datum>, <prime meridian>, <angular unit> {,<twin axes>} {,<authority>}]
    <datum>              = DATUM["<name>", <spheroid> {,<to wgs84>} {,<authority>}]
    <spheroid>           = SPHEROID["<name>", <semi-major axis>, <inverse flattening> {,<authority>}]
    <semi-major axis>    = <number>
    <inverse flattening> = <number>
    <prime meridian>     = PRIMEM["<name>", <longitude> {,<authority>}]
    <longitude>          = <number>
    <angular unit>       = <unit>
    <linear unit>        = <unit>
    <unit>               = UNIT["<name>", <conversion factor> {,<authority>}]
    <conversion factor>  = <number>
    <geocentric cs>      = GEOCCS["<name>", <datum>, <prime meridian>, <linear unit> {,<axis>, <axis>, <axis>} {,<authority>}]
    <authority>          = AUTHORITY["<name>", "<code>"]
    <vert cs>            = VERT_CS["<name>", <vert datum>, <linear unit>, {<axis>,} {,<authority>}]
    <vert datum>         = VERT_DATUM["<name>", <datum type> {,<authority>}]
    <datum type>         = <number>
    <compd cs>           = COMPD_CS["<name>", <head cs>, <tail cs> {,<authority>}]
    <head cs>            = <coordinate system>
    <tail cs>            = <coordinate system>
    <twin axes>          = <axis>, <axis>
    <axis>               = AXIS["<name>", NORTH | SOUTH | EAST | WEST | UP | DOWN | OTHER]
    <to wgs84s>          = TOWGS84[<seven param>]
    <seven param>        = <dx>, <dy>, <dz>, <ex>, <ey>, <ez>, <ppm>
    <dx>                 = <number>
    <dy>                 = <number>
    <dz>                 = <number>
    <ex>                 = <number>
    <ey>                 = <number>
    <ez>                 = <number>
    <ppm>                = <number>
    <fitted cs>          = FITTED_CS["<name>", <to base>, <base cs>]
    <to base>            = <math transform>
    <base cs>            = <coordinate system>
    <local cs>           = LOCAL_CS["<name>", <local datum>, <unit>, <axis>, {,<axis>}* {,<authority>}]
    <local datum>        = LOCAL_DATUM["<name>", <datum type> {,<authority>}]

## Description of WKT keywords

### AUTHORITY

This is an optional clause that allows an external authority to manage the definition of an entity.

### AXIS

The name of the axis is for human consumption. The enumerated value that follows is to allow software to correctly overlay different coordinate systems. If the optional `AXIS` terms are not present, then the default values are assumed. They are:

Geographic Coordinate System: | `AXIS["Lon",EAST],AXIS["Lat",NORTH]`
Projected Coordinate System: | `AXIS["X",EAST],AXIS["Y",NORTH]`
Geocentric Coordinate System: | `AXIS["X",OTHER],AXIS["Y",EAST],AXIS["Z",NORTH]`

However, if these terms are present, and have non-default values, then implementations must be prepared to swap and reverse the coordinates of geometry before attempting to overlay graphics.

### COMPD_CS

This indicates a compound coordinate system, which combines the coordinate of two other coordinate systems. For example, a compound 3D coordinate system could be made up of a horizontal coordinate system and a vertical coordinate system.

### CONCAT_MT

A transform defined by the concatenation of sub-transforms. The dimension of the output space of the first transform must match the dimension of the input space in the second transform (if defined), and so on for the remaining sub-transforms.

### DATUM

This indicates the horizontal datum, which corresponds to the procedure used to measure positions on the surface of the Earth.

### FITTED_CS

This indicates a fitted coordinate system. The math transform is used to construct a map from the fitted coordinate system to the base coordinate system. The transform is often an affine map. The math transform works from the fitted CS to the base CS so that the fitted CS can have a smaller dimension that the base CS. This is often quite useful. For example, a fitted coordinate system could be a 2D plane approximately tangential to the Earth, but based on a WGS84 geocentric 3D coordinate system.

### GEOCCS

A 3D coordinate system, with its origin at the center of the Earth. The X axis points towards the prime meridian. The Y axis points East or West. The Z axis points North or South. By default the Z axis will point North, and the Y axis will point East (e.g. a right handed system), but you should check the axes for non-default values.

### GEOGCS

A coordinate system based on latitude and longitude. Some geographic coordinate systems are Lat/Lon, and some are Lon/Lat. You can find out which this is by examining the axes. You should also check the angular units, since not all geographic coordinate systems use degrees.

### INVERSE_MT

A math transform defined as the inverse of another transform.

### LOCAL_DATUM

This indicates the local datum.

### LOCAL_CS

This indicates a local, ungeoreferenced coordinate system. Such coordinate systems are often used in CAD systems. They can also be used for local surveys, where the relationship between the surveyed site and the rest of the world is not important. The number of `AXIS` clauses indicates the dimension of the local coordinate system.

### PARAMETER

A named projection parameter value. The units of the parameter must be inferred from its context. If the parameter is inside a `PROJCS`, then its units will match the units of the `PROJCS`. If the parameter is inside a `PARAM_MT`, then its units will be meters and degrees for linear and angular values respectively.

### PARAM_MT

A parameterized math transform. All the linear parameters are expressed in meters, and all the angular parameters are expressed in degrees. Other parameters should use S.I. units where possible. (E.g. use Kg for mass, and seconds for time.)

The <classification name> is a coded value that specifies the formulae used by the math transform. See Parameterized Transforms for legal values, and the corresponding parameters.

### PASSTHROUGH_MT

This is a math transform that passes through a subset of ordinates to another transform. This allows transforms to operate on a subset of ordinates. For example, if you have (Lat,Lon,Height) coordinates, then you may wish to convert the height values from meters to feet without affecting the (Lat,Lon) values. If you wanted to affect the (Lat,Lon) values and leave the Height values alone, then you would have to swap the ordinates around to (Height,Lat,Lon). You can do this with an affine map.

The <integer> argument is the index of the first affected ordinate. The <math transform> argument is the transform to pass coordinates onto.

### PRIMEM

This defines the meridian used to take longitude measurements from. The units of the <longitude> must be inferred from the context. If the `PRIMEM` clause occurs inside a `GEOGCS`, then the longitude units will match those of the geographic coordinate system. If the `PRIMEM` clause occurs inside a `GEOCCS`, then the units will be in degrees.

The longitude value defines the angle of the prime meridian relative to the Greenwich Meridian. A positive value indicates the prime meridian is East of Greenwich, and a negative value indicates the prime meridian is West of Greenwich.

### PROJCS

This indicates a projected coordinate system. The `PROJECTION` sub-clause contains the classification name used by `MathTransformFactory`, and the `PARAMETER` clauses specify the parameters. However, the units used by `MathTransformFactory` are always meters and degrees, and the units in the `PARAMETER` clauses are in the linear/angular units of the `PROJCS`/`GEOGCS` respectively. So if you are writing code to read or write WKT, then you must do the unit conversions - be careful!

(Notice that this handling of units is slightly different from the way the EPSG 4 database works. In the EPSG 4 database, each transformation parameter value defines its own units. However, 99% of the EPSG projection parameter units are the same as the units of the corresponding projected coordinate system.)

### PROJECTION

This describes a projection from geographic coordinates to projected coordinates. It is used inside a `PROJCS` to define the parameters of the projection transform.

### SPHEROID

This describes a spheroid, which is an approximation of the Earth's surface as a squashed sphere. In this document, the terms "spheroid" and "ellipsoid" are synonymous. The term "`SPHEROID`" is used in WKT for compatibility with Simple Features. However, the term "ellipsoid" is preferred elsewhere in this specification.

### TOWGS84

This indicates a list of up to 7 Bursa Wolf transformation parameters. These parameters can be used to approximate a transformation from the horizontal datum to the WGS84 datum. However, it must be remembered that this transformation is only an approximation. For a given horizontal datum, different Bursa Wolf transformations can be used to minimize the errors over different regions.

If the `DATUM` clause contains a `TOWGS84` clause, then this should be its "preferred" transformation, which will often be the transformation which gives a broad approximation over the whole area of interest (e.g. the area of interest in the containing geographic coordinate system). Sometimes, only the first three or six parameters are defined. In this case the remaining parameters must be zero. If only three parameters are defined, then they can still be plugged into the Bursa Wolf formulas, or you can take a short cut. The Bursa Wolf transformation works on geocentric coordinates, so you cannot apply it onto geographic coordinates directly. If there are only three parameters then you can use the Molodenski or abridged Molodenski formulas.

The `DATUM` clause may not contain a `TOWGS84` clause in the following situations:

- The writing application was using the Simple Features specification, which does not specify `TOWGS84` as a valid keyword
- The writing application did not have an available transformation.
- There is no possible transformation. For example, the horizontal datum could be a surface that rotates relative to the Earth's surface.

In particular, if the `DATUM` does contain a `TOWGS84` clause, and the parameter values are zero, then the receiving application can assume that the writing application believed that the datum is approximately equal to WGS84.

### UNIT

This describes units used for values elsewhere within the parent WKT clause (sometimes including descendants of the parent clause). The physical dimension (i.e. type) of the units is determined by context. For example, in a `GEOGCS` the type of the units is angular. In a `VERT_CS` the type of the units is linear. Within a `UNIT` clause, the units are described by relating them to a fundamental unit of that type with a conversion factor. For linear units, the conversion factor is the scalar value that converts the described units into meters. For angular units, the conversion factor is the scalar value that converts the described units into radians.

### VERT_DATUM

This indicates the vertical datum, or method used for vertical measurements.

### VERT_CS

This indicates a vertical coordinate system.

## WKT Example

The following example shows a 3D compound coordinate system, which is made by combining a projected coordinate system and a vertical coordinate system. This is the same coordinate system as used for the XML Example.

    COMPD_CS["OSGB36 / British National Grid + ODN",
        PROJCS["OSGB 1936 / British National Grid",
            GEOGCS["OSGB 1936",
                DATUM["OSGB_1936",
                    SPHEROID["Airy 1830",6377563.396,299.3249646,AUTHORITY["EPSG","7001"]],
                    TOWGS84[375,-111,431,0,0,0,0],
                    AUTHORITY["EPSG","6277"]],
                PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],
                UNIT["DMSH",0.0174532925199433,AUTHORITY["EPSG","9108"]],
                AXIS["Lat",NORTH],
                AXIS["Long",EAST],
                AUTHORITY["EPSG","4277"]],
            PROJECTION["Transverse_Mercator"],
            PARAMETER["latitude_of_origin",49],
            PARAMETER["central_meridian",-2],
            PARAMETER["scale_factor",0.999601272],
            PARAMETER["false_easting",400000],
            PARAMETER["false_northing",-100000],
            UNIT["metre",1,AUTHORITY["EPSG","9001"]],
            AXIS["E",EAST],
            AXIS["N",NORTH],
            AUTHORITY["EPSG","27700"]],
        VERT_CS["Newlyn",
            VERT_DATUM["Ordnance Datum Newlyn",2005,AUTHORITY["EPSG","5101"]],
            UNIT["metre",1,AUTHORITY["EPSG","9001"]],
            AXIS["Up",UP],
            AUTHORITY["EPSG","5701"]],
        AUTHORITY["EPSG","7405"]]