Skip to content

Allow aliases in GeoTIFF CRS #122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
desruisseaux wants to merge 4 commits into
base: master
Choose a base branch
from
Draft

Allow aliases in GeoTIFF CRS #122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
44174a9
In table E.1 (Summary of GeoKey IDs and names), move the `CoordinateE…
desruisseaux Jul 4, 2023
496db8b
Break long sentences in shorter sentences in sections 7.2.2, 7.5, B.3…
desruisseaux Jul 3, 2023
31af2c5
Standardize the encoding of multiple names in a citation GeoKeys.
desruisseaux Jul 10, 2023
349eb85
When multi-names are used in a citation, allow the same keys to be re…
desruisseaux Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions ...led Test Suite/abstract_tests/Citation_GeoKeys/TEST_GeodeticCitationGeoKey.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,10 @@

Verify that the contents read is KeyLength characters long not including the NULL.

If the content ends with the pipe character (`|`, ASCII decimal code 124),
verify each entry separated by the `|` character is a key-value pair
with the key and the value separated by the `=` character (ASCII decimal code 61).

If the content contains key-value pairs, verify that all keys are one of the following:
`GCS Name`, `Datum`, `Ellipsoid`, `Primem`, `AUnits`.
Multi-occurrences of those keys are allowed.
2 changes: 1 addition & 1 deletion GeoTIFF_Standard/standard/abstract_tests/TIFF_Tests/TEST_Ascii_Param.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
|http://www.opengis.net/spec/GeoTIFF/1.1/req/GeoKeyDirectoryTag.keyEntryValueOffset
|http://www.opengis.net/spec/GeoTIFF/1.1/req/GeoAsciiParamsTag.ID
|http://www.opengis.net/spec/GeoTIFF/1.1/req/GeoAsciiParamsTag.count
|http://www.opengis.net/spec/GeoTIFF/1.1/req/CitationGeoKeys
|http://www.opengis.net/spec/GeoTIFF/1.2/req/CitationGeoKeys
|===

*Purpose:* Verify ASCII parameters
Expand Down
207 changes: 126 additions & 81 deletions GeoTIFF_Standard/standard/annex-b.adoc
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions GeoTIFF_Standard/standard/annex-e.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -254,7 +254,7 @@ __Table E.1 - Summary of GeoKey IDs and names __
5+<| [underline]#Dynamic CRS Parameter Keys#
^| 5120
^| Double
<| CoordinateEpochGeoKey
<|
<| (as GeoTIFF v1.2)
<|
<| CoordinateEpochGeoKey
|====
82 changes: 62 additions & 20 deletions GeoTIFF_Standard/standard/clause_7_requirements.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,15 +99,15 @@ include::requirements/Configuration_Keys/requirements_class_GTRasterTypeGeoKey.a

This GeoKey defines the type of Model coordinate reference system used, to which the transformation from the raster space is made:

* Model CRS is unknown or unspecified;
* Model CRS is unknown or unspecified;

* Model CRS is a Geographic 2D CRS;
* Model CRS is a Geographic 2D CRS;

* Model CRS is a Geocentric CRS;
* Model CRS is a Geocentric CRS;

* Model CRS is a Projected CRS; and

* Model CRS is user-defined.
* Model CRS is user-defined.

If the Model coordinate reference system is from the GeoTIFF standard CRS register (i.e., EPSG register),
then only the registered CRS code need be specified.
Expand All @@ -117,13 +117,15 @@ If the Model coordinate reference system is not from the GeoTIFF standard CRS re
then it requires the specification of some or all CRS elements.
See <<Requirements for definition of user-defined Model CRS>>.

The GeoTIFF v1.0 format has also been used to describe pseudo-3D compound CRSs consisting of a projected CRS and a vertical CRS or a geographic 2D CRS and a vertical CRS,
The GeoTIFF v1.0 format has also been used to describe pseudo-3D compound CRSs
consisting of a projected CRS and a vertical CRS or a geographic 2D CRS and a vertical CRS,
as well as a geographic 3D CRS.
In this document, this usage is permitted but not explicitly described through the GTModelTypeGeoKey.
Recommendations are given in Annex D.

include::requirements/Configuration_Keys/requirements_class_GTModelTypeGeoKey.adoc[]
NOTE: The GTCitationGeoKey is also provided to give an ASCII reference to published documentation on the overall configuration of the GeoTIFF file (see <<Requirements Class Citation GeoKeys>>).
NOTE: The GTCitationGeoKey is also provided to give an ASCII reference to published documentation
on the overall configuration of the GeoTIFF file (see <<Requirements Class Citation GeoKeys>>).

=== Raster to Model Coordinate Transformation Requirements

Expand Down Expand Up @@ -190,50 +192,90 @@ include::requirements/Vertical_GeoKeys/requirements_class_VerticalGeoKey.adoc[]
The _GTCitationGeoKey_ is provided to give an ASCII reference to published documentation on the overall configuration of the GeoTIFF file.
The _GeodeticCitationGeoKey_,
_ProjectedCitationGeoKey_ and _VerticalCitationGeoKey_ are used to describe Model CRS elements through ASCII free text.
A citation may be included with a CRS identified through the GeoTIFF CRS register (<<Requirements for definition of Model CRS (when Model CRS is from GeoTIFF CRS register)>>).
A citation may be included with a CRS identified through the GeoTIFF CRS register
(<<Requirements for definition of Model CRS (when Model CRS is from GeoTIFF CRS register)>>).
A citation is mandatory for a user-defined CRSs and CRS objects (<<Requirements for definition of user-defined Model CRS>>).
The _GeodeticCitationGeoKey_, _ProjectedCitationGeoKey_ and _VerticalCitationGeoKey_ are used with CRSs and CRS components.

NOTE: In GeoTIFF 1.0 the GeodeticCitationGeoKey key was called GeogCitationGeoKey and the ProjectedCitationGeoKey key was called PCSCitationGeoKey.

A _GeodeticCitationGeoKey_, _ProjectedCitationGeoKey_ and _VerticalCitationGeoKey_ may contain multiple names
for two reasons:

* For providing the names of components such as datum, ellipsoid, prime meridian or unit of measurement.
* For adding an arbitrary amount of aliases for the same component.

If a citation contains multiple names, then all names are encoded as key-value pairs
separated by the pipe character (`|`, ASCII decimal code 124).
For each pair, the key and the value are separated by the `=` character (ASCII decimal code 61).
Each key can be one of the following:

[[citation_object_names]]
[width="90%",options="header"]
|==================================================
|Key name |Description
|GCS Name |Name of the geodetic CRS
|Datum |Name of the datum
|Ellipsoid |Name of the ellipsoid
|Primem |Name of the prime meridian
|AUnits |Name of the angular unit of measurement
|==================================================

The same key can be repeated multiple times.
All occurrences of a key after the first one are aliases.
Examples:

* `GCS Name = WGS84|Datum = World Geodetic System 1984 ensemble|Datum = D_WGS_1984|Ellipsoid = WGS_1984|Primem = Greenwich|AUnits = Decimal_Degree|`
* `GCS Name = Moon 2000|Datum = D_Moon_2000|Ellipsoid = Moon_2000_IAU_IAG|Primem = Reference_Meridian|AUnits = Decimal_Degree|`

include::requirements/Citation_Keys/requirements_class_CitationGeoKeys.adoc[]

=== Requirements for definition of user-defined Model CRS

The GeoKeys described in this section are needed only when Model CRSs are not available from the GeoTIFF CRS register and the CRS or one or more of its component objects is user-defined,
The GeoKeys described in this section are needed only when Model CRSs are not available
from the GeoTIFF CRS register and the CRS or one or more of its component objects is user-defined,
that is if one or more of ProjectedCRSGeoKey, GeodeticCRSGeoKey, or VerticalGeoKey has a value of 32767.

NOTE: Anyone not interested in constructing a user-defined model CRS can ignore this section.

NOTE: It should be noted that the implicit axis order of user-defined CRS definitions is fixed at (lon,lat,height) in case of geographic and (east,north,height) in case of projected regardless of the model space CRS definition. This convention was implicit in GeoTIFF 1.0 and still is valid in this revision. As with GeoTIFF 1.0, it is not possible to express a user-defined CRS that deviates from this axis order convention. The intention is to address this limitation in a future revision.
NOTE: It should be noted that the implicit axis order of user-defined CRS definitions is fixed at (lon,lat,height)
in case of geographic and (east,north,height) in case of projected regardless of the model space CRS definition.
This convention was implicit in GeoTIFF 1.0 and still is valid in this revision.
As with GeoTIFF 1.0, it is not possible to express a user-defined CRS that deviates from this axis order convention.
The intention is to address this limitation in a future revision.

==== Requirements Class Units GeoKeys

These keys are used to specify Units of Measure (UoM) through the identification of a unit from the GeoTIFF CRS register or to indicate that the unit is user-defined.
These keys are used to specify Units of Measure (UoM) through the identification of a unit from the GeoTIFF CRS register
or to indicate that the unit is user-defined.

The *GeogAngularUnitsGeoKey* key is used to specify the angular unit for:

* the axes in user-defined geographic 2D CRSs;
* the horizontal axes in user-defined geographic 3D CRSs;
* the longitude from the reference meridian in user-defined prime meridians; and
* user-defined map projection parameters that are angles.
* the axes in user-defined geographic 2D CRSs;
* the horizontal axes in user-defined geographic 3D CRSs;
* the longitude from the reference meridian in user-defined prime meridians; and
* user-defined map projection parameters that are angles.

The *GeogAzimuthUnitsGeoKey* key is used to specify the angular unit for user-defined map projection parameters when these differ from the angular unit described through the GeogAngularUnitsGeoKey.
The *GeogAzimuthUnitsGeoKey* key is used to specify the angular unit for user-defined map projection parameters
when these differ from the angular unit described through the GeogAngularUnitsGeoKey.

The *GeogLinearUnitsGeoKey* key is used to specify the linear unit for:

* the axes in user-defined geocentric Cartesian CRSs;
* the height axis of a user-defined geographic 3D CRS; and
* for user-defined ellipsoid axes.
* the height axis of a user-defined geographic 3D CRS; and
* for user-defined ellipsoid axes.

The *ProjLinearUnitsGeoKey* key is used to specify the linear units for:

* the axes of a user-defined projected CRS; and
* map projection parameters that are lengths.
* the axes of a user-defined projected CRS; and
* map projection parameters that are lengths.

The *VerticalUnitsGeoKey* key is used to specify the linear unit for:

* the axis of a user-defined vertical CRS.
* the axis of a user-defined vertical CRS.

If a user-defined unit is used, then the unit name shall be specified by a citation GeoKey.
See <<Requirements Class Citation GeoKeys>>.

include::requirements/Units_Keys/requirements_class_UnitsGeoKeys.adoc[]

Expand Down
21 changes: 20 additions & 1 deletion ...ard/standard/requirements/Citation_Keys/requirements_class_CitationGeoKeys.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[cols="1,4",width="90%"]
|===
2+|*Requirements Class 15.0: CitationGeoKeys* {set:cellbgcolor:#CACCCE}
2+|http://www.opengis.net/spec/GeoTIFF/1.1/req/CitationGeoKeys
2+|http://www.opengis.net/spec/GeoTIFF/1.2/req/CitationGeoKeys
{set:cellbgcolor:#FFFFFF}

|Requirement 15.1 {set:cellbgcolor:#CACCCE}
Expand All @@ -19,4 +19,23 @@ _The VerticalCitationGeoKey SHALL have ID = 4097_
|http://www.opengis.net/spec/GeoTIFF/1.1/req/CitationGeoKeys.type +
_The CitationGeoKeys SHALL have type = ASCII_
{set:cellbgcolor:#FFFFFF}

|Requirement 15.3 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.2/req/CitationGeoKeys.name.pair +
_The CitationGeoKeys MAY contain multiple names as key-value pairs,
with each pair separated by the `|` character and, for any given pair,
the key separated from the value by the `=` character._
{set:cellbgcolor:#FFFFFF}

|Requirement 15.4 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.2/req/CitationGeoKeys.name.key +
_If multi-names encoding is used, then the keys SHALL be one of the following:
`GCS Name`, `Datum`, `Ellipsoid`, `Primem`, `AUnits`._
{set:cellbgcolor:#FFFFFF}

|Requirement 15.5 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.2/req/CitationGeoKeys.alias +
_If multi-names encoding is used and the same key is used more than once,
then all occurrences after the first one SHOULD be aliases._
{set:cellbgcolor:#FFFFFF}
|===
10 changes: 5 additions & 5 deletions ...ndard/requirements/Configuration_Keys/requirements_class_GTModelTypeGeoKey.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,15 @@ _The GTModelTypeGeoKey SHALL have type = SHORT_
|http://www.opengis.net/spec/GeoTIFF/1.1/req/GTModelTypeGeoKey.value +
_The GTModelTypeGeoKey value SHALL be:_

* 0 to indicate that the Model CRS in undefined or unknown; or
* 0 to indicate that the Model CRS in undefined or unknown; or

* 1 to indicate that the Model CRS is a 2D projected coordinate reference system, indicated by the value of the ProjectedCRSGeoKey; or
* 1 to indicate that the Model CRS is a 2D projected coordinate reference system, indicated by the value of the ProjectedCRSGeoKey; or

* 2 to indicate that the Model CRS is a geographic 2D coordinate reference system, indicated by the value of the GeodeticCRSGeoKey; or
* 2 to indicate that the Model CRS is a geographic 2D coordinate reference system, indicated by the value of the GeodeticCRSGeoKey; or

* 3 to indicate that the Model CRS is a geocentric Cartesian 3D coordinate reference system, indicated by the value of the GeodeticCRSGeoKey; or
* 3 to indicate that the Model CRS is a geocentric Cartesian 3D coordinate reference system, indicated by the value of the GeodeticCRSGeoKey; or

* 32767 to indicate that the Model CRS type is user-defined.
* 32767 to indicate that the Model CRS type is user-defined.
{set:cellbgcolor:#FFFFFF}

|Requirement 8.5 {set:cellbgcolor:#CACCCE}
Expand Down
31 changes: 21 additions & 10 deletions ..._Standard/standard/requirements/Units_Keys/requirements_class_UnitsGeoKeys.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,54 +19,65 @@ _The VerticalUnitsGeoKey SHALL have ID = 4099_

|Requirement 16.2 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.1/req/UnitsGeoKey.type +
_The GeogAngularUnitsGeoKey, the GeogAzimuthUnitsGeoKey, the GeogLinearUnitsGeoKey, the ProjLinearUnitsGeoKey and the VerticalUnitsGeoKey SHALL each have type = SHORT_
_The GeogAngularUnitsGeoKey, the GeogAzimuthUnitsGeoKey, the GeogLinearUnitsGeoKey, the ProjLinearUnitsGeoKey and the VerticalUnitsGeoKey
SHALL each have type = SHORT_
{set:cellbgcolor:#FFFFFF}

|Requirement 16.3 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.1/req/UnitsGeoKey.reserved +
_GeogAngularUnitsGeoKey, GeogAzimuthUnitsGeoKey, GeogLinearUnitsGeoKey, ProjLinearUnitsGeoKey and VerticalUnitsGeoKey values in the range 1-1023 SHALL be reserved._
_GeogAngularUnitsGeoKey, GeogAzimuthUnitsGeoKey, GeogLinearUnitsGeoKey, ProjLinearUnitsGeoKey and VerticalUnitsGeoKey
values in the range 1-1023 SHALL be reserved._

NOTE: In GeoTIFF v1.0 the range 0001-2000 was used for obsolete GeoTIFF codes.
{set:cellbgcolor:#FFFFFF}

|Requirement 16.4 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.1/req/UnitsGeoKey.angular +
_GeogAngularUnitsGeoKey and GeogAzimuthUnitsGeoKey values in the range 1024-32766 SHALL be EPSG Unit Of Measure (UOM) codes with type = angle._
_GeogAngularUnitsGeoKey and GeogAzimuthUnitsGeoKey
values in the range 1024-32766 SHALL be EPSG Unit Of Measure (UOM) codes with type = angle._

NOTE: In GeoTIFF v1.0 the range was 9100-9199
{set:cellbgcolor:#FFFFFF}

|Requirement 16.5 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.1/req/UnitsGeoKey.linear +
_GeogLinearUnitsGeoKey, ProjLinearUnitsGeoKey and VerticalUnitsGeoKey values in the range 1024-32766 SHALL be EPSG Unit Of Measure (UOM) codes with type = length._
_GeogLinearUnitsGeoKey, ProjLinearUnitsGeoKey and VerticalUnitsGeoKey
values in the range 1024-32766 SHALL be EPSG Unit Of Measure (UOM) codes with type = length._

NOTE: In GeoTIFF v1.0 the range was 9000-9099. Several values in this range have been deprecated or deleted from the EPSG Dataset and should no longer be used. See <<annex-g.adoc#deprecated_units_codes,Table G.3 - Deprecated and deleted EPSG Unit of Measure codes>>
NOTE: In GeoTIFF v1.0 the range was 9000-9099.
Several values in this range have been deprecated or deleted from the EPSG Dataset and should no longer be used.
See <<annex-g.adoc#deprecated_units_codes,Table G.3 - Deprecated and deleted EPSG Unit of Measure codes>>
{set:cellbgcolor:#FFFFFF}

|Requirement 16.6 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.1/req/UnitsGeoKey.userdefinedAngular +
_A GeogAngularUnitsGeoKey or a GeogAzimuthUnitsGeoKey value of 32767 SHALL be a user-defined angular unit. If the value is 32767 (User-Defined) then the GeodeticCitationGeoKey and the GeogAngularUnitSizeGeoKey SHALL be populated_
_A GeogAngularUnitsGeoKey or a GeogAzimuthUnitsGeoKey value of 32767 SHALL be a user-defined angular unit.
If the value is 32767 (User-Defined) then the GeodeticCitationGeoKey and the GeogAngularUnitSizeGeoKey SHALL be populated_
{set:cellbgcolor:#FFFFFF}

|Requirement 16.7 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.1/req/UnitsGeoKey.userdefinedGeogLinear +
_A GeogLinearUnitsGeoKey value of 32767 SHALL be a user-defined linear unit. If the value is 32767 (User-Defined) then the GeodeticCitationGeoKey and the GeogLinearUnitSizeGeoKey SHALL be populated_
_A GeogLinearUnitsGeoKey value of 32767 SHALL be a user-defined linear unit.
If the value is 32767 (User-Defined) then the GeodeticCitationGeoKey and the GeogLinearUnitSizeGeoKey SHALL be populated_
{set:cellbgcolor:#FFFFFF}

|Requirement 16.8 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.1/req/UnitsGeoKey.userdefinedProjLinear +
_A ProjLinearUnitsGeoKey value of 32767 SHALL be a user-defined linear unit. If the value is 32767 (User-Defined) then the ProjectedCitationGeoKey and the ProjLinearUnitSizeGeoKey SHALL be populated._
_A ProjLinearUnitsGeoKey value of 32767 SHALL be a user-defined linear unit.
If the value is 32767 (User-Defined) then the ProjectedCitationGeoKey and the ProjLinearUnitSizeGeoKey SHALL be populated._
{set:cellbgcolor:#FFFFFF}

|Requirement 16.9 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.1/req/UnitsGeoKey.userdefinedVertical +
_A VerticalUnitsGeoKey value of 32767 (user defined) SHALL not be used_

NOTE: The rationale for this is that it would require a VerticalUnitSizeGeoKey, which does not exist in GeoTIFF 1.0. For vertical units, this document supports only EPSG linear units.
NOTE: The rationale for this is that it would require a VerticalUnitSizeGeoKey, which does not exist in GeoTIFF 1.0.
For vertical units, this document supports only EPSG linear units.
{set:cellbgcolor:#FFFFFF}

|Requirement 16.10 {set:cellbgcolor:#CACCCE}
|http://www.opengis.net/spec/GeoTIFF/1.1/req/UnitsGeoKey.private +
_GeogAngularUnitsGeoKey, GeogAzimuthUnitsGeoKey, GeogLinearUnitsGeoKey, ProjLinearUnitsGeoKey and VerticalUnitsGeoKey values in the range 32768-65535 SHALL be private._
_GeogAngularUnitsGeoKey, GeogAzimuthUnitsGeoKey, GeogLinearUnitsGeoKey, ProjLinearUnitsGeoKey and VerticalUnitsGeoKey
values in the range 32768-65535 SHALL be private._
{set:cellbgcolor:#FFFFFF}
|===