org.opengis.referencing.doc-files.WKT.html Maven / Gradle / Ivy
Show all versions of geoapi Show documentation
Well-Know Text (WKT) format
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
Note: In this page, the term "Coordinate System" is not exactly equivalent to
the ISO 19111 definition.
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:
CS typeDefault AXIS ISO 19111 abbreviations
Geographic Coordinate System (GEOGCS):
AXIS["Lon",EAST],AXIS["Lat",NORTH](λ, φ) Projected Coordinate System (PROJCS):
AXIS["X",EAST],AXIS["Y",NORTH](x, y) - lower case Geocentric Coordinate System (GEOCCS):
AXIS["X",OTHER],AXIS["Y",EAST],AXIS["Z",NORTH](X, Y, Z) - upper case
Note: Some default axis names are different than the abbreviations
mandated by ISO 19111. The ISO abbreviations are shown in the above table for information purpose.
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.
The <datum type> should be one of the following predefined values:
2000 - Other:
Unspecified vertical datum type. 2001 - Orthometric:
A vertical datum for orthometric heights that are measured along the plumb line. 2002 - Ellipsoidal:
A vertical datum for ellipsoidal heights that are measured along the normal to the ellipsoid
used in the definition of horizontal datum. 2003 - Barometric Altitude:
The vertical datum of altitudes or heights in the atmosphere. These are approximations of
orthometric heights obtained with the help of a barometer or a barometric altimeter. These values
are usually expressed in one of the following units: meters, feet, millibars (used to measure
pressure levels), or theta value (units used to measure geopotential height). 2004 - Normal:
A normal height system. 2005 - Geoid Model Derived:
A vertical datum of geoid model derived heights, also called GPS-derived heights. These heights
are approximations of orthometric heights (H), constructed from the ellipsoidal heights
(h) by the use of the given geoid undulation model (N) through the equation:
H=h-N. 2006 - Depth:
This attribute is used to support the set of datums generated for hydrographic engineering
projects where depth measurements below sea level are needed. It is often called a hydrographic
or a marine datum. Depths are measured in the direction perpendicular (approximately) to the
actual equipotential surfaces of the earth's gravity field, using such procedures as
echo-sounding.
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"]]