Conceptio › Archive › Open Geospatial Consortium (OGC)

Open Geospatial Consortium (OGC)open access

OGC GGXF geodetic data grid exchange format (version 1.0) — OGC 22-051r7

Open Geospatial Consortium · Open Geospatial Consortium (OGC)

Open Geospatial Consortium (OGC) · Standards · License: Open Access

data exchange format geospatial ogc ogc22 opengeospatialconsortium

ogc, geospatial, standard, open geospatial consortium, ggfx, ogc ggfx, 22-051r7, ogc 22-051r7, 1.0, ggxf, geodetic, data, grid, exchange, format

OGC 22-051r7 GGXF v1.0

Open Geospatial Consortium Submission Date: 2024-01-08 Approval Date: 2024-04-29 Publication Date: 2024-04-29 External identifier of this OGC® document: https://www.opengis.net/doc/GGXF/1.0 Internal reference number of this OGC® document: 22-051r7 Version: 1.0.0 Category: OGC® Implementation Standard Editor: Roger Lott

OGC GGXF geodetic data grid exchange format

Warning This document is an OGC Member approved international standard. This document is available on a royalty free, non-discriminatory basis. Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Document type: Document stage: Document language:

OGC® Implementation Standard Approved English

OGC 22-051r7 GGXF v1.0

License Agreement Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement. If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR. THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD. THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY. This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party. Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications. This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

OGC 22-051r7 GGXF v1.0

Abstract The Geodetic data Grid eXchange Format (GGXF) is designed to be a single file format that may be used for a wide range of geodetic applications requiring interpolation of regularly gridded data, including (but not limited to): •

Transformation of latitude and longitude coordinates from one geodetic coordinate reference system to another;

•

Transformation of gravity-related heights from one vertical coordinate reference system to another;

•

Reduction of ellipsoid heights to the geoid, quasi-geoid or a surface of a vertical reference frame; and

•

The description of coordinate changes due to deformation.

ii.

Keywords The following are keywords to be used by search engines and document catalogues. ogcdoc, OGC document, GGXF, geodetic, grid, exchange format, CRS, coordinate reference system, coordinate transformation

iii.

Preface A single, standard, grid file format offers the following advantages: ¾ Grid producers do not have to create file formats themselves, provide their own software to read and interpolate their gridded data or concern themselves with lack of take-up of their data due to its proprietary distribution format; ¾ Survey and geographic information software vendors need to read only one grid file format, eliminating the need to repeatedly write programs to import different grids; and ¾ End users can use a new grid file as soon as it became available, without having to wait for their application vendor to produce a software upgrade. GGXF has been designed to cope with multiple levels of data resolution, engender computational efficiency, be straightforward for grid producers to populate and easy and efficient for application developers to use. Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights. Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

iii

OGC 22-051r7 GGXF v1.0

iv.

Security Considerations No security considerations have been made for this Standard.

Submitting organizations The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

Name

Affiliation

Michael Craymer

NRCan

Chris Crook

LINZ

Martin Desruisseaux

Geomatys

Kevin Kelly

Esri

Roger Lott (editor)

IOGP

Chris Pearson

Trimble Inc

Dan Roman

NOAA

Keith Ryden

Esri

Brian Shaw

NOAA

Patrick Vorster

DALRRD

The following organizations contributed to this Document:

Name

Affiliation

Elmar Brockmann

SwissTopo

Richard Stanaway

Quickclose Pty

All questions regarding this submission should be directed to the editor or the submitters.

OGC 22-051r7 GGXF v1.0

Contents Introduction ......................................................................................................................................................vii 1

Scope .............................................................................................................................................................. 1

Normative references ............................................................................................................................... 1

3 Terms, definitions and abbreviated terms ....................................................................................... 2 3.1 Terms and definitions .............................................................................................................................. 2 3.2 Abbreviations .............................................................................................................................................. 7 4

Conformance requirements ................................................................................................................... 8

5 Overview of a GGXF file ............................................................................................................................ 9 5.1 File structure ............................................................................................................................................... 9 5.2 GGXF Conventions................................................................................................................................... 10 5.3 Geodetic content type ............................................................................................................................ 10 5.4 Interpolation CRS .................................................................................................................................... 11 5.5 Grid array .................................................................................................................................................. 11 5.6 Relationship between grid array indices and Interpolation CRS coordinates................... 13 5.6.1 Affine transformation ..................................................................................................................... 13 5.6.2 Grid extent .......................................................................................................................................... 14 5.7 Multiple grids ........................................................................................................................................... 14 5.8 Parameters ................................................................................................................................................ 17 5.8.1 General ................................................................................................................................................. 17 5.8.2 Parameter name ............................................................................................................................... 17 5.8.3 Parameter unit .................................................................................................................................. 17 5.8.4 Source CRS Axis ................................................................................................................................. 17 5.8.5 Missing data values .......................................................................................................................... 18 5.8.6 Node coordinates as parameters................................................................................................. 19 5.8.7 Parameter uncertainty ................................................................................................................... 19 5.8.8 ParameterSet ..................................................................................................................................... 19 5.8.9 Parameters in a ggxfGroup ............................................................................................................ 19 5.9 Data extent ................................................................................................................................................ 21 5.9.1 General ................................................................................................................................................. 21 5.9.2 Geographic bounding box .............................................................................................................. 22 5.9.3 Extent description ............................................................................................................................ 22 5.9.4 Geographic bounding polygon ..................................................................................................... 23 5.9.5 Temporal validity ............................................................................................................................. 23 5.9.6 Vertical extent ................................................................................................................................... 23 5.10 Miscellaneous metadata ................................................................................................................. 23 5.10.1 Content general description ......................................................................................................... 23 5.10.2 Interpolation method ...................................................................................................................... 23 5.10.3 Nominal operation accuracy ......................................................................................................... 24 5.10.4 File producer information ............................................................................................................. 24 5.10.5 License .................................................................................................................................................. 24 5.10.6 Permanent tide .................................................................................................................................. 25 5.10.7 Check data ........................................................................................................................................... 25 5.10.8 Comments............................................................................................................................................ 25 6 Encoding..................................................................................................................................................... 25 6.1 Introduction.............................................................................................................................................. 25 6.2 YAML Encoding ........................................................................................................................................ 26 6.2.1 Grid data .............................................................................................................................................. 26 6.2.2 YAML grid data syntax .................................................................................................................... 26

OGC 22-051r7 GGXF v1.0

6.2.3 YAML external grid data ................................................................................................................. 27 6.3 netCDF Encoding ..................................................................................................................................... 28 6.3.1 Introduction........................................................................................................................................ 28 6.3.2 Relationship of GGXF Conventions to ACDD ............................................................................ 28 6.3.3 GGXF netCDF structure ................................................................................................................... 29 6.3.4 Representation of structured data.............................................................................................. 29 6.3.5 Representation of grid data........................................................................................................... 31 Annex A (normative) Conformance requirements ............................................................................. 34 A.1 Core requirements.................................................................................................................................. 34 A.2 Requirements for mapping GGXF schema to a GGXF YAML text file ...................................... 40 A.3 Requirements for mapping GGXF schema to a GGXF netCDF binary file .............................. 42 Annex B (normative) GGXF Conventions ............................................................................................... 45 B.1 Introduction .............................................................................................................................................. 45 B.2 GGXF Conventions: principal keywords .......................................................................................... 49 B.3 GGXF Conventions: keywords for content attributes.................................................................. 62 B.4 GGXF Conventions: keywords for citation and responsible party attributes ..................... 78 B.5 GGXF Conventions: mapping of GGXF identifiers to netCDF attributes ................................ 80 B.6 GGXF Conventions: external grid file format ................................................................................. 82 Annex C (informative) Offsets.................................................................................................................... 84 Annex D (informative) Consolidated list of recommendations...................................................... 85 Annex E (informative) Examples .............................................................................................................. 87 E.1 GGXF file basics ........................................................................................................................................ 88 E.2 Geoid model .............................................................................................................................................. 94 E.3 Geographic 2D offsets with accuracy................................................................................................ 98 E.4 Velocity grid ............................................................................................................................................103 E.5 Deformation model ..............................................................................................................................105 E.6 Gridded geodetic data not used in coordinate transformation software ..........................108 E.7 Grid priority ............................................................................................................................................110 Annex F (informative) Revision history ...............................................................................................111 Bibliography ...................................................................................................................................................112

OGC 22-051r7 GGXF v1.0

Introduction The Geodetic data Grid eXchange Format (GGXF) is designed to be a single file format that may be used for a wide range of geodetic applications requiring interpolation of regularly gridded data, including (but not limited to): •

Transformation of latitude and longitude coordinates from one geodetic coordinate reference system to another;

•

Transformation of gravity-related heights from one vertical coordinate reference system to another;

•

Reduction of ellipsoid heights to the geoid, quasi-geoid or a surface of a vertical reference frame; and

•

The description of coordinate changes due to deformation.

The GGXF format has been designed specifically for carrying gridded geodetic parameters supporting coordinate transformations and point motion operations but has no restriction on the type of content that may be included. GGXF is designed to be extensible to all geodetic data that is presented as a grid. A single, standard, grid file format offers the following advantages: ¾ Grid producers do not have to create file formats themselves, provide their own software to read and interpolate their gridded data or concern themselves with lack of take-up of their data due to its proprietary distribution format; ¾ Survey and geographic information software vendors need to read only one grid file format, eliminating the need to repeatedly write programs to import different grids; and ¾ End users can use a new grid file as soon as it became available, without having to wait for their application vendor to produce a software upgrade. GGXF is designed to cope with multiple levels of data resolution, engender computational efficiency, be straightforward for grid producers to populate and easy and efficient for application developers to use.

vii

OGC 22-051r7 GGXF v1.0

The GGXF geodetic data grid exchange format 1 Scope The Geodetic data Grid eXchange Format (GGXF) is a file format that may be used for a wide range of geodetic applications requiring interpolation of gridded data. This Standard describes GGXF format version 1.0. GGXF supports data values for one or more userspecified parameters at grid nodes of a regularly-spaced grid constructed in a coordinate reference system (CRS) which is spatially either 2-dimensional or 3-dimensional. GGXF supports data population at varying densities. It adheres to the data model and terminology described in OGC Abstract Specification Topic 2, Referencing by coordinates. The functional model for deformation grids is described in OGC Abstract Specification Topic 24. This Standard does not support triangulated irregular networks (TINs). This Standard is applicable to producers of gridded geodetic data and to developers of software using gridded geodetic data.

2 Normative references The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this Standard. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. IETF: Internet Engineering Task Force (IETF) RFC 3339, Date and Time on the Internet: Timestamps. Available online at https://www.rfc-editor.org/rfc/rfc3339.html (accessed 2023-06-09) ISO: ISO 8601-1, Date and time ― Representations for information interchange — Part 1: Basic rules ISO: ISO 19115-1, Geographic information ― Metadata ― Part 1: Fundamentals ISO: ISO 8000-3, Quantities and units ― Part 3: Space and time OGC: OGC 06-103r4, Simple Features Access ― Part 1: Common Architecture. Available online at https://portal.ogc.org/files/?artifact_id=25355 (accessed 2021-05-26). The technical content of this document is identical to that in ISO 19125-1:2004. OGC: OGC 18-005, Abstract Specification Topic 2, Referencing by coordinates. Available online at https://docs.ogc.org/as/18-005r8/18-005r8.pdf (accessed 2023-10-27). The technical content of this document is identical to that in ISO 19111. OGC: OGC 18-010, Well-known text representation of coordinate reference systems. Available online at https://docs.ogc.org/is/18-010r11/18-010r11.pdf (accessed 2023-10-27). The technical content of this document is identical to that in ISO 19162. OGC: OGC 22-010, Abstract Specification Topic 24, Functional Model for Crustal Deformation. https://github.com/opengeospatial/CRS-DeformationModels/blob/master/products/specification/abstract-specification-functional-model-for-crustaldeformation.pdf

OGC 22-051r7 GGXF v1.0

3 Terms, definitions and abbreviated terms 3.1 Terms and definitions For the purposes of this Standard, the following terms and definitions apply. 3.1.1 child grid grid in a hierarchical grid structure that is one level of the grid hierarchy below another specified grid in that hierarchy Note 1 to entry: The other grid is the parent grid of the child grid. A child grid has only one parent grid. A child grid is spatially contained within its parent grid. Note 2 to entry: The usual function of a child grid is to provide more detail over the area of intersection with its parent grid.

3.1.2 compound coordinate reference system coordinate reference system using at least two independent coordinate reference systems Note 1 to entry: Coordinate reference systems are independent of each other if coordinate values in one cannot be converted or transformed into coordinate values in the other.

[SOURCE: ISO 19111:2019, 3.1.3] 3.1.3 coordinate epoch epoch to which coordinates in a dynamic coordinate reference system are referenced [SOURCE: ISO 19111:2019, 3.1.7] 3.1.4 coordinate operation process using a mathematical model, based on a one-to-one relationship, that changes coordinates in a source coordinate reference system to coordinates in a target coordinate reference system, or that changes coordinates at a source coordinate epoch to coordinates at a target coordinate epoch within the same coordinate reference system Note 1 to entry: Generalisation of coordinate conversion, coordinate transformation and point motion operation.

[SOURCE: ISO 19111:2019, 3.1.8] 3.1.5 coordinate transformation coordinate operation that changes coordinates in a source coordinate reference system to coordinates in a target coordinate reference system in which the source and target coordinate reference systems are based on different datums Note 1 to entry: A coordinate transformation uses parameters which are derived empirically. Any error in those coordinates will be embedded in the coordinate transformation and when the coordinate transformation is applied the embedded errors are transmitted to output coordinates. Note 2 to entry: A coordinate transformation is colloquially sometimes referred to as a 'datum transformation'. This is erroneous. A coordinate transformation changes coordinate values. It does not change the definition of the datum. In this document coordinates are referenced to a coordinate reference system. A coordinate transformation operates between two coordinate reference systems, not between two datums.

[SOURCE: ISO 19111:2019, 3.1.12]

OGC 22-051r7 GGXF v1.0

3.1.6 coordinate tuple tuple composed of coordinates Note 1 to entry: The number of coordinates in the coordinate tuple equals the dimension of the coordinate system; the order of coordinates in the coordinate tuple is identical to the order of the axes of the coordinate system.

[SOURCE: ISO 19111:2019, 3.1.13] 3.1.7 deformation change in shape of the Earth’s crust due to stress changes within the crust Note 1 to entry: This specification is specifically concerned with the manifestation of deformation on the surface of the earth and the consequent displacement of features fixed to the surface of the Earth.

[SOURCE: OGC Abstract Specification Topic 24, 4.1.4] 3.1.8 displacement change in coordinates of a point due to deformation [SOURCE: OGC Abstract Specification Topic 24, 4.1.5] 3.1.9 easting E distance in a coordinate system, eastwards (positive) or westwards (negative) from a north-south reference line [SOURCE: ISO 19111:2019, 3.1.21] 3.1.10 ellipsoidal height geodetic height h distance of a point from the reference ellipsoid along the perpendicular from the reference ellipsoid to this point, positive if upwards or outside of the reference ellipsoid Note 1 to entry: Only used as part of a three-dimensional ellipsoidal coordinate system or as part of a threedimensional Cartesian coordinate system in a three-dimensional projected coordinate reference system, but never on its own.

[SOURCE: ISO 19111:2019, 3.1.24] 3.1.11 epoch <geodesy> point in time Note 1 to entry: In this document an epoch is expressed in the Gregorian calendar as a decimal year. EXAMPLE

2017-03-25 in the Gregorian calendar is epoch 2017.23.

[SOURCE: ISO 19111:2019, 3.1.27]

OGC 22-051r7 GGXF v1.0

3.1.12 geodetic coordinate reference system two- or three-dimensional coordinate reference system based on a geodetic reference frame and having either a three-dimensional Cartesian or an ellipsoidal or a spherical coordinate system Note 1 to entry: In this document a coordinate reference system based on a geodetic reference frame and having an ellipsoidal coordinate system is geographic.

[SOURCE: ISO 19111/Amd2:2023, 3.1.31] 3.1.13 geodetic latitude ellipsoidal latitude

angle from the equatorial plane to the perpendicular to the ellipsoid through a given point, northwards treated as positive [SOURCE: ISO 19111:2019, 3.1.32] 3.1.14 geodetic longitude ellipsoidal longitude

angle from the prime meridian plane to the meridian plane of a given point, eastward treated as positive [SOURCE: ISO 19111:2019, 3.1.33] 3.1.13 geographic bounding box geographic position of an area described by the maximum and minimum latitude and longitude bounding it. Note 1 to entry: This is only an approximate reference so specifying the geographic coordinate reference system is unnecessary and bounding coordinates need only be provided with a precision of up to two decimal places of a degree.

3.1.16 geographic coordinate reference system coordinate reference system that has a geodetic reference frame and an ellipsoidal coordinate system [SOURCE: ISO 19111:2019, 3.1.35] 3.1.17 geoid height perpendicular distance from the surface of the reference ellipsoid of a specified geographic 3D coordinate reference system to a surface realizing the geoid, positive if upwards or outside of the reference ellipsoid Note 1 to entry: In this document this term is used in a general sense for any geoid model. It includes gravimetric geoids (quasi geoids), hybrid height correction models, etc.

3.1.18 graticule grid consisting of parallels of latitude and meridians of longitude

OGC 22-051r7 GGXF v1.0

3.1.19 gravity-related height H height that is dependent on the Earth’s gravity field Note 1 to entry: This refers to, amongst others, orthometric height and Normal height, which are both approximations of the distance of a point above the mean sea level, but also may include Normal-orthometric heights, dynamic heights or geopotential numbers. Note 2 to entry: The distance from the reference surface may follow a curved line, not necessarily straight, as it is influenced by the direction of gravity.

[SOURCE: ISO 19111:2019, 3.1.37] 3.1.20 height distance of a point from a chosen reference surface positive upward along a line perpendicular to that surface Note 1 to entry: A height below the reference surface will have a negative value. Note 2 to entry: Generalisation of ellipsoidal height (h) and gravity-related height (H).

[SOURCE: ISO 19111:2019, 3.1.38] 3.1.21 interpolation CRS coordinate reference system to which a grid is referenced and in which interpolation of the grid is performed 3.1.22 meridian intersection of an ellipsoid by a plane containing the shortest axis of the ellipsoid Note 1 to entry: This term is generally used to describe the pole-to-pole arc rather than the complete closed figure.

[SOURCE: ISO 19111:2019, 3.1.42] 3.1.23 northing N distance in a coordinate system, northwards (positive) or southwards (negative) from an east-west reference line [SOURCE: ISO 19111:2019, 3.1.43] 3.1.24 offset quantity that is added [to a coordinate] Note 1 to entry: The value of the offset may be positive or negative.

3.1.25 parent grid grid that is an immediate ancestor of one or more child grids Note 1 to entry: An immediate ancestor is one that is removed by one level of the grid hierarchy.

OGC 22-051r7 GGXF v1.0

3.1.26 period extent in time Note 1 to entry: A period is bounded by two different temporal positions.

[SOURCE: ISO 19108:2005, 4.1.27] 3.1.27 point motion operation coordinate operation that changes coordinates within one coordinate reference system due to the motion of the point Note 1 to entry: The change of coordinates is from those at an initial epoch to those at another epoch. Note 2 to entry: In this document the point motion is due to tectonic motion or crustal deformation.

[SOURCE: ISO 19111:2019, 3.1.48] 3.1.28 projected coordinate reference system coordinate reference system derived from a geographic coordinate reference system by applying a map projection Note 1 to entry: May be two- or three-dimensional, the dimension being equal to that of the geographic coordinate reference system from which it is derived. Note 2 to entry: In the three-dimensional case the horizontal coordinates (geodetic latitude and geodetic longitude coordinates) are projected to northing and easting and the ellipsoidal height is unchanged.

[SOURCE: ISO 19111:2019, 3.1.51] 3.1.29 root grid grid without any parent grid 3.1.30 secular motion velocity (of a point) that is continuous over an inter-seismic time period 3.1.31 sequence finite, ordered collection of related items (objects or values) that may be repeated [SOURCE: ISO 19111:2019, 3.1.55] 3.1.32 sibling grid grid that shares the same parent grid 3.1.33 source coordinate epoch coordinate epoch of the coordinate set that is input into a coordinate operation Note 1 to entry: The 'from' epoch.

OGC 22-051r7 GGXF v1.0

3.1.34 source coordinate reference system source CRS coordinate reference system to which the coordinate set input into a coordinate operation is referenced Note 1 to entry: The 'from' coordinate reference system.

3.1.35 target coordinate epoch coordinate epoch of the coordinate set that is output from a coordinate operation Note 1 to entry: The 'to' epoch.

3.1.36 target coordinate reference system target CRS coordinate reference system to which the coordinate set output from a coordinate operation is referenced Note 1 to entry: The 'to' coordinate reference system.

3.1.37 tuple ordered list of values Note 1 to entry: The number of values in a tuple is immutable.

[SOURCE: ISO 19136-1:2019, 3.1.70] 3.1.38 vertical coordinate reference system one-dimensional coordinate reference system based on a vertical reference frame [SOURCE: ISO 19111:2019, 3.1.70]

3.2 Abbreviations CDL

network Common data form (netCDF) Description Language

CRS

coordinate reference system

GGXF

Geodetic data Grid eXchange Format

netCDF

(Unidata) network Common Data Form

URI

Uniform Resource Identifier

WKT

well-known text format

OGC 22-051r7 GGXF v1.0

4 Conformance requirements Any file claiming conformance to this GGXF Standard shall satisfy the conformance requirements in Annex A. Conformance classes are shown in Table 1. Table 1 — Conformance requirements for a GGXF file

Data content core - required for: a) production of GGXF files, and b) consuming GGXF files yaml - required by those producing or consuming GGXF YAML text files netcdf - required by those producing or consuming GGXF netCDF binary files

Conformance requirements given in A.1 A.2 A.3

The normative provisions in this Standard are denoted by the URI http://www.opengis.net/spec/ggxf/1.0 All requirements that appear in this Standard are denoted by partial URIs which are relative to this base.

OGC 22-051r7 GGXF v1.0

5 Overview of a GGXF file 5.1 File structure A GGXF file consists of • A file header containing metadata applicable to the whole file; • One or more ggxfGroups, where each ggxfGroup consists of o A ggxfGroup header containing metadata applicable to the ggxfGroup; o One or more grids, each with: § A grid header containing metadata applicable to the grid; § An array of nodes. For each node one or more parameter values are given. In this Standard the term ggxfGroup is used to distinguish the concept from that of a group in a netCDF file. A conceptual diagram of the GGXF file structure is shown in Figure 1.

(a) general structure

(b) multiple grids in a single ggxfGroup

Figure 1 — Conceptual structure of a GGXF file

OGC 22-051r7 GGXF v1.0

Most gridded geodetic data does not require the full complexity of this file structure. Most requirements can be met through a subset of the full structure, through either a single grid (Figure 1c) or through a single ggxfGroup containing several nested grids (Figure 1b). The full structure (Figure 1a) permits complex data resulting from a series of deformation events such as earthquakes to be carried, with each event or component of an event described through a ggxfGroup.

5.2 GGXF Conventions The metadata in the file, ggxfGroup and grid headers is presented as key-value pairs where the key is a fixed string defined through the 'GGXF Conventions' (Annex B) and the value may be a number, a string, a list, or further nested key-value pairs.

5.3 Geodetic content type The content types listed in Table 2 are frequently encountered geodetic content. Table 2 — Content type

Content type (coordinate offsets):

Cartesian2dOffsets Cartesian3dOffsets geocentricTranslations geographic2dOffsets geographic3dOffsets verticalOffsets deviationsOfThe Vertical gravity (geoid and height correction models):

geoidModel hydroidModel (tidal surface)

velocityGrid deformationModel Most of these content types are associated with coordinate operation methods used to apply the data from the grid file in a coordinate operation. They are consistent with methods documented in geodetic parameter registries such as EPSG [1] and the ISO Geodetic Registry [3]. The GGXF file header identifies the type of content in the file using the keyword content. The content attribute is mandatory. The value of the content attribute should be the content identifier defined in the GGXF Conventions (Annex B.2) Table B.3. If the content of the file is not one of those given in the GGXF Conventions, producers should use "producerDefinedContent" as the value for content and provide a producerDefinedContentCitation. Applications that implement GGXF files are not obliged to handle producer-defined content. If the content has wide geodetic applicability, the producer should request the OGC to consider revising the GGXF Conventions to include this content type.

OGC 22-051r7 GGXF v1.0

5.4 Interpolation CRS A GGXF grid is constructed in any 2D or higher-dimension spatial coordinate reference system that is compliant with OGC Abstract Specification Topic 2, for example in a geographic (latitude and longitude) or projected (easting and northing) CRS. This CRS is called the Interpolation CRS. For a GGXF file containing multiple grids, all grids must be constructed within the same Interpolation CRS. Note: The Interpolation CRS should not be confused with the source CRS or target CRS used in coordinate operations utilising the interpolated geodetic data. For some coordinate operations they may be related, for example for 2-dimensional ellipsoidal coordinate offsets the Interpolation CRS may be the source CRS. Other coordinate operations may have an Interpolation CRS completely unrelated to source or target CRS, for example offsets between two one-dimensional vertical CRSs will require an Interpolation CRS which is 2-dimensional, usually a geographic CRS but perhaps a projected CRS.

The Interpolation CRS applicable to the file is identified in the GGXF file header through a well-known text (WKT) string conformant with OGC 18-010, Well-known text representation of coordinate reference systems. This format optionally permits the inclusion of a reference to a definition of the CRS in a register of geodetic parameters, from which further metadata regarding the CRS may be obtained. If there is a conflict between the well-known text description and the information derived through the external registry, the WKT description prevails. For many geodetic purposes the Interpolation CRS will be geographic 2D. Then: Recommendation 1

When the Interpolation CRS is geographic and the desire is to make the spacing of latitude and longitude node intervals similar in linear distance, make the node spacing in angular units in longitude (Δλ) approximately equal to Δφ/cos(φm) where Δφ is the node spacing in latitude and φm is the latitude of the middle of the grid.

A geographic CRS is unsuitable for grids covering polar areas and in very high latitudes a grid constructed in an appropriate projected CRS may be more suitable. When the Interpolation CRS is not geographic, the location of the grid in latitude and longitude terms can be identified only after conversion of Interpolation CRS coordinates.

5.5 Grid array A GGXF grid is an array of points (grid nodes) with indices i,j (and, for a 3-dimensional grid, k). The indices (i,j[,k]) on each axis of the grid take an integer value from 0 to (nodeCount - 1) where nodeCount is the maximum number of nodes along that axis. The node spacing along an axis must be constant in the Interpolation CRS. There is no requirement for the node spacing along one axis to be equal to the node spacing along another axis. Figure 2a illustrates a 2-dimensional GGXF grid where the Interpolation CRS is geographic. In this example the grid indexing uses a graphic display paradigm, with grid node coordinates starting in the top left corner at (0,0) and increasing by 1 for each node. The spacing in latitude is 3 arc-minutes and the spacing in longitude is 4 arc-minutes. Due to the convergence of the meridians the distance along the parallel nearer to the pole is less in linear units than the distance along the parallel closer to the equator. However, the grid is constructed in an Interpolation CRS in degrees, and in angular units the longitude differences of 12' at the minimum and maximum grid extent are equal, therefore this grid is rectangular in the Interpolation CRS.

OGC 22-051r7 GGXF v1.0

Grid index (0,1) φ = 40°09' N(0,0) j

(0,3)

nodeCount = (4,6) (3,5)

(0,4) N = 4570000

φ = 40°03' N(2,0)

(2,3)

(0,3) N = 4566000

(3,3)

(0,2) N = 4562000

(a) Interpolation CRS is geographic 2D Grid origin in top left

(0,0) N = 4454000

(3,1) j i

(3,0) E = 748000

λ = 7°48' E

λ = 7°40' E

λ = 7°44' E

nodeCount = (6,4) (5,3)

φ = 39°54' N(5,0)

(0,1) N = 4458000

E = 744000

(4,3)

φ = 39°57' N

E = 740000

φ = 40°00' N

λ = 7°36' E

Grid index (0,5) N = 4574000

E = 736000

φ = 40°06' N

(0,2)

(b) Interpolation CRS is projected 2D Grid origin in bottom left

Figure 2 — GGXF grid with respect to Interpolation CRS Figure 2b illustrates a 2-dimensional GGXF grid where the Interpolation CRS is projected and the spacing on both axes is 4 km. Note that in this example the grid origin (0,0) is in the bottom left corner of the grid and that the i and j axis directions in figure 2b differ from those in figure 2a. This Standard has no constraints on the grid origin location or the handedness (right-handed or left-handed1) of the grid axes. In this Standard i is always the first index and j the second index. The spatial relationship of the grid to the interpolation CRS is defined through an affine transformation, discussed in the following section. In both parts of Figure 2 the maximum extent of each axis is given as a nodeCount, shown in blue. nodeCount = (maximum index) + 1.

In a right-handed grid the j-axis is rotated 90° counter-clockwise from the i-axis when viewed from above the plane containing the two axes. In a left-handed grid the j-axis is rotated 90° clockwise from the i-axis when viewed from above the plane containing the two axes. The example grids in Figure 2a and Figure 2b are both right-handed. Annex E contains examples of right-handed and of left-handed grids. 12

OGC 22-051r7 GGXF v1.0

5.6 Relationship between grid array indices and Interpolation CRS coordinates 5.6.1

Affine transformation

For each grid in the GGXF file, the conversion from the grid indices to the interpolation CRS coordinates of the corresponding node is defined by an affine transformation. For a two-dimensional grid with indices i,j and Interpolation CRS coordinates X,Y the transformation between them can be expressed in matrix form as: æ ç è

X Y 1

ö ÷ ø

æ ç è

A1 B1 0

A2 B2 0

A0 B0 1

ö ÷ ø

æ i ö ç j ÷ è 1 ø

The two-dimensional affine transformation is defined by the six coefficients A0, A1, A2, B0, B1, B2. Note the following. • The order of elements in the leftmost matrix must match axis order of the Interpolation CRS. Here X and Y are the first and second coordinates in the Interpolation CRS tuple and should not be mistaken for axis abbreviations or implication of positive direction of the axes. • The order of elements in the rightmost matrix must match grid index order. In this Standard that order is fixed to (i,j) for all cases, regardless of the Interpolation CRS axis order and the grid row/column orientation. • The elements of the middle matrix define the position, orientation, and grid spacing of the grid in the interpolation CRS. The values and signs of the elements of the middle matrix depend upon (a) the corner of the grid at which is the grid origin, (b) the handedness of the grid axes, (c) the positive directions of the axes of the Interpolation CRS, and (d) the order of the axes of the Interpolation CRS.

For 3D (or higher) dimension grids, a row and a column are added for each additional dimension. For dimension n, the affine transform is a square matrix of size (n+1)×(n+1). For a three-dimensional grid with indices i,j,k and interpolation CRS coordinates X,Y,Z the transformation can be expressed as: æ ç ç è

X Y Z 1

ö ÷ ÷ ø

æ ç ç è

A1 B1 C1 0

A2 B2 C2 0

A3 B3 C3 0

A0 B0 C0 1

ö ÷ ÷ ø

æ i ö ç j ÷ ç k ÷ è 1 ø

Here X, Y and Z are the first, second and third coordinates in the Interpolation CRS tuple and must not be mistaken for axis abbreviations or imply positive direction of the axes. Recommendation 2

When dealing with affine coefficients in text files, data producers are encouraged write values with at least full IEEE 754 double precision, particularly when the node interval in the Interpolation CRS is defined in arc-minutes or arc-seconds that are represented as a degree with a recurring fractional part. Example: when the interpolation CRS units are degrees, a grid node spacing of 10 arc-minutes should be represented as 0.166666666666667

Note: this applies only to the YAML encoding where the text representation of decimal values is used. Recommendation 3

Implementations should use the affine coefficients without making any assumptions about the physical orientation of grid rows and columns in the interpolation CRS.

OGC 22-051r7 GGXF v1.0

5.6.2

Grid extent

The affine transformation in conjunction with the maximum node count along each axis of the grid defines the extent (envelope) of the grid expressed in the Interpolation CRS. Indices are a measure of distance from the grid origin. The maximum node count indicates the total number of nodes along the axis. The number of inter-node intervals on the axis to be used in calculating grid extent in the Interpolation CRS is (nodeCount - 1). The coordinates of the grid origin referenced to the interpolation CRS are calculated using the formula in 5.6.1 above with (for a two-dimensional grid) i=j=0. The coordinates of the corner of the grid opposite to the grid origin are calculated using the formula in 5.6.1 above with (for a two-dimensional grid) i=(iNodeCount -1), j=(jNodeCount -1).

5.7 Multiple grids A ggxfGroup defines the value of a set of parameters by interpolating values from one or more grids of data. It is often advantageous to use multiple grids. This may be because the area being described is an irregular shape (see 5.8.5), or because a subset of the area covered by the grid needs a finer grid spacing than the rest to provide the required accuracy of interpolated values. GGXF supports this by allowing a ggxfGroup to be described by multiple grids in a hierarchical structure. • A ggxfGroup contains one or more top level grids. Top level grids are called 'root grids'. Root grids have no parent grid. • Root grids may spatially intersect. o Adjacency along a common boundary is not considered to be an intersection. o All intersecting root grids must be given a unique gridPriority value. A higher gridPriority value has higher priority of use. o gridPriority is not necessary for root grids that do not intersect. • A root grid may be a parent grid for one or more child grids. o A child grid can have only one parent grid. • A child grid must be spatially contained within its parent grid. However, spatial containment does not of itself define parent-child relationships. The parent-child relationship is defined by the file structure, not by spatial extent. • Child grids having the same parent grid are termed 'sibling grids'. Sibling grids may spatially intersect. As with intersecting root grids, intersecting sibling grids must be given a gridPriority value, adjacency along a common boundary is not considered to be an intersection and gridPriority is not necessary for child grids that do not have an intersecting sibling grid. • gridPriority values must be unique amongst intersecting sibling grids within one family. Different families may share the same gridPriority values. • Should a gridPriority value be given to grids that do not intersect (e.g., for consistency in symmetry) it will not be used. • A child grid may be the parent grid of one or more child grids. Nesting may continue to any level. • A grid may have different node spacing compared to its parent or sibling grids. In the hierarchical structure exemplified in the spatial view in Figure 3a, the ggxfGroup contains three root grids A, B, and C. Grids B and C intersect so must have a gridPriority. Grid A does not intersect either of B or C so does not require a gridPriority value. Grid C cannot be a child grid of B because spatially it is not fully contained within B. Grids A and B include child grids which provide more detailed information. For grid A these are grids D and E, and for grid B they are grids F and G. Grid F itself has child grids H and J which provide more detailed information about it. Grids D and E are sibling grids; the grids in this pairing requires a gridPriority value. Grids H and J are adjacent along a common bounday but do not intersect so neither of these grids require a gridPriority value.

OGC 22-051r7 GGXF v1.0

F p

q H

J r

Figure 3a — Grid structure within a ggxfGroup – spatial view Shading indicates hierarchical nesting level Figure 3b shows how these grids are organised structurally. Grid priority is shown for the grids for which it is a mandatory attribute – intersecting root grids B and C together with child sibling grids D and E.

ggxfGro up B

gridPriority = 2

gridPriority = 1

root grids

gridPriority = 1

gridPriority = 2

nested grids

Figure 3b — Grid structure within a ggxfGroup – structural view Shading indicates hierarchical nesting level When parameter values at a location are calculated, only one of the grids in the ggxfGroup will be used. • The grid used will spatially include the location. • gridPriority of the oldest generation takes precedence. • A child grid always takes priority over their parent grid. • For sibling grids, the grid with the highest gridPriority takes precendence. For example: • at location p in the area where grids D and E intersect, grid A will not be used to evaluate the parameters as its child grids D and E take priority. Grid D has gridPriority 2, and grid E has gridPriority 1, so grid D will be used. • location q is within the extent of grid B but also within the extent of nested child grids F and H. With multiple levels of nesting the most deeply nested (youngest generation) grid takes priority. Grid H will be used for evaluation. • point r is within grid C and also within the spatial extents of grids B, F, and J. Grids B and C are intersecting root grids. An intersecting root grid with the highest priority and its children takes 15

OGC 22-051r7 GGXF v1.0

priority over an intersecting root grid with the lowest priority and its children. Grid B has gridPriority 1 and grid C has gridPriority 2, so grid C with the higher gridPriority is used in preference to grid B and also in preference to grid B's child grid F and its grandchild grid J. Should grid C itself have child grids (not the case here), these would be used in preference to C. In a scenario in which grid J is required to be the grid with highest priority and so be used in preference to grid C where these grids overlap, simply giving grid J a high gridPriority within the grid structure in Figure 3b will have no effect, because the oldest generation grid with the highest gridPriority takes precedence. Changing the priority of grid J can only be achieved by changing the grid structure. One rearrangement that would achieve this is to make grid J a root grid and then give it a higher priority than both B and C, as shown in Figure 3c.

ggxfGro up J

gridPriority = 2

gridPriority = 1

gridPriority = 3

gridPriority = 1

F H

gridPriority = 2

root grids

G nested grids

Figure 3c — Grid structure within a ggxfGroup – alternative structural view It was noted above that a child grid must be spatially contained within its parent grid but that spatial containment does not of itself define parent-child relationships. The changes from the structure shown in Figures 3b to the structure shown in Figure 3c do not impact the spatial relationships shown in Figure 3a. In the revised structure shown in Figure 3c, grid J remains spatially contained within grid F but is not a child grid. A common requirement of parameter values interpolated from a ggxfGroup is that they are mathematically continuous across the spatial extent of the ggxfGroup. Where a ggxfGroup contains multiple grids there will be boundaries across which the interpolation of the ggxfGroup transitions from one grid to another. To ensure continuity, on these boundaries the parameter values interpolated from the grid on one side of the boundary should be the same as those interpolated from the grid on the other side. Recommendation 4

Where there is a transition from one grid being used for interpolation to another, to ensure continuity the parameter values interpolated from the grid on one side of the boundary should be the same as those interpolated from the grid on the other side.

In many practical situations grids are constructed to not overlap. This is because overlapping can cause issues with continuity across the grid boundaries. None of examples E.1 through E.6 in Annex E require the use of gridPriority as they contain no intersecting sibling grids. A practical example of the application of grid priority is shown in Annex E example E.7.

OGC 22-051r7 GGXF v1.0

5.8 Parameters 5.8.1

General

In this Standard a parameter is one of a set (or tuple) of values being carried in the GGXF file at grid nodes. The number of parameters in the tuple is unlimited. The parameters in the GGXF file are declared in the file header. The sequence in which these parameters are listed in the file header is significant, indicating the order in which they are given at each grid node. The declaration includes attributes of the parameter. The attributes of parameterName, unitName, and unitSiRatio are mandatory. Two further attributes, sourceCrsAxis and noDataFlag, are conditional. The attributes of a parameter optionally may be extended to include the minimum and maximum values of the parameter in the file, the uncertainty measure for the parameter and groupAdditionMethod which for parameters that are split across multiple ggxfGroups defines how their values are combined. Within a GGXF file the attributes of a parameter (units, etc.) are unchanged across all grids in the file. In a GGXF file having multiple ggxfGroups, each ggxfGroup may have a gridParameters attribute specifying a subset of all parameters in the ggxfGroup, together with their order in the ggxfGroup. Within each ggxfGroup, every grid node must have the same tuple of parameters. 5.8.2

Parameter name

Each parameter must have a parameterName. This is the identifier for the parameter. GGXF Conventional keywords for the identifiers of those parameters supporting the content types listed in Table 2 and Table B.7 are given in Annex B.3 Table B.4. 5.8.3

Parameter unit

Each parameter must have its units declared. The GGXF Conventions in Annex B.3 Table B6 define unit identifier (unitName) and ratio to SI base unit (unitSiRatio) for units frequently encountered in geodetic data. Units other than these may be used, but when parameters have units listed in the GGXF Conventions then the unit ID and its SI Ratio exactly as given in the Conventions should be used. If unitSiRatio is given for a unit included in the Conventions and the ratio values differ, the value in the Conventions takes precedence. Recommendation 5

When parameters are in units documented in the GGXF Conventions, the unit ID and ratio to SI standard unit as given in the Conventions should be used.

Recommendation 6

Use arc-minutes or arc-seconds as the unit for parameters that are sexagesimal divisions of a degree.

5.8.4

Source CRS Axis

The parameter attribute sourceCrsAxis is included to assist applications implementing GGXF file content in a coordinate operation. sourceCrsAxis identifies the coordinate in the source CRS to which the parameter should be applied through a zero-based sequence number corresponding to the source CRS axis order. For all parameters that are variables in a coordinate operation, sourceCrsAxis must be included in the parameter declaration.

OGC 22-051r7 GGXF v1.0

Example 1: In a GGXF file with content type = geographic2dOffsets in which parameters latitudeOffset and longitudeOffset are to be applied to a source CRS in which the first axis is geodetic latitude and the second axis is geodetic longitude, the sequence values for sourceCrsAxis for the latitudeOffset and longitudeOffset parameters are 0 and 1 respectively. Example 2: In a GGXF file with content type = deformationModel in which parameters displacementEast, displacementNorth and displacementUp are to be applied to a source CRS in which the first axis is geodetic latitude, the second axis is geodetic longitude and the third axis is ellipsoidal height, the sequence values for sourceCrsAxis for the displacementEast, displacementNorth and displacementUp parameters are 1, 0 and 2 respectively. Example 3: In a GGXF file with content type = geoidModel in which the source CRS first axis is geodetic latitude, the second axis is geodetic longitude and the third axis is ellipsoidal height, the value of the attribute sourceCrsAxis for the parameter geoidHeight is 2.

The sourceCrsAxis attribute is not applicable for content types that do not directly support coordinate operations, for example content type = deviationsOfTheVertical. 5.8.5

Missing data values

Where data within a grid is missing, this Standard requires the declaration of a 'no data' value attribute to the relevant parameter. The noDataFlag value is one that cannot be mistaken for a genuine value of the parameter. The value used will depend upon the data values present in the file. If all grids in the file have all nodes completely populated, the noDataFlag is not required. However, having nodes with no data values causes difficulties in interpolation around the node. Different implementations may give different results. This can be avoided by producers populating missing data with estimated values. Recommendation 7

Recommendation 8

To assist implementations reading the GGXF file, data producers are discouraged from using noDataFlag and instead to populate all nodes of a grid with estimated values, giving extrapolated values a high uncertainty. To cover an irregularly shaped area and avoid a large number of nodes with no data, use multiple root grids. Figure 4 illustrates a hypothetical arrangement.

Figure 4 — Multiple grids covering an irregular area Recommendation 9

When interpolating grids values, implementations should raise an exception, return a no-data value, or otherwise alert users to calculations which require interpolating a no-data value.

OGC 22-051r7 GGXF v1.0

5.8.6

Node coordinates as parameters

This Standard permits the tuple of values at a grid node to include as parameters the coordinate values of the node (referenced to the Interpolation CRS). The GGXF conventions (Annex B) use the keyword node* (where * is a wildcard) for these parameters, for example nodeLatitude. While this information may be very useful to human readers of a text extract of grid content, implementations reading a GGXF file do not require these values to be explicitly given – they are implied through the grid node indices and affine transformation coefficients. Including these parameters increases the size of the GGXF file and, particularly for large grids, may lead to degraded implementation performance. They may however be useful during the production of GGXF text files using the external file option (see 6.2.3). Recommendation 10

To minimise file size, coordinates of the grid nodes should not be included as parameters in grids in a GGXF binary file. However, producers creating GGXF binary files using a GGXF YAML text file with ggxf-csv external grid files are encouraged to include node coordinates in the ggxf-csv grid files to allow software to validate the node counts and the affine coefficients. These node coordinates are not required to be included in the resultant GGXF binary file.

5.8.7

Parameter uncertainty

This Standard does not require parameter uncertainty to be included in grid data, but if required GGXF can support doing so through two mechanisms. a) For any parameter a complimentary parameter carrying the uncertainty of that parameter at each grid node may be given. For example, in a GGXF file with a content type of 'geographic2dOffsets' (see GGXF Conventions Annex B.3 Table B.3), the mandatory parameters 'latitude offset' and 'longitude offset' may be accompanied by two further parameters, 'latitude offset uncertainty' and 'longitude offset uncertainty' (see GGXF Conventions Table B.4). The uncertainties are declared in the file header as parameters in the normal way b) A single (constant) value for the uncertainty of a parameter throughout a ggxfGroup may be declared in the ggxfGroup header. For example, in a deformation model the parameter 'displacementHorizontalUncertainty' may be declared in the file header and in a ggxfGroup header a constant value for it may be declared. The displacement horizontal uncertainty then is not explicitly defined at grid nodes, but a GGXF application will treat it as if it is defined at every grid node with the declared constant value value. This is described in 5.8.9. For both mechanisms, the statistical measure used for the uncertainty is declared through one of the uncertainty measure attributes given in the GGXF Conventions (Annex B.3 Table B.10). 5.8.8

ParameterSet

This optional attribute may be used for controlling the array(s) in which parameters are stored in the GGXF netCDF implementation. This is discussed further in 6.3. 5.8.9 5.8.9.1

Parameters in a ggxfGroup Use of multiple ggxfGroups

In a GGXF file with a single ggxfGroup, every grid node will hold the ordered set of all parameters defined in the file header. For parameters that have different characteristics, multiple ggxfGroups can

OGC 22-051r7 GGXF v1.0

be used. For example, the spatial characteristics of the horizontal and vertical components of a geographic3dOffset can be quite different. This may be reflected by horizontal and vertical data having different node intervals. Because the node intervals differ, the three offsets cannot be described in a single grid without the inclusion of nodes with missing data (see 5.8.5). However, a producer could put all three parameters into the same grid by interpolating the coarser grid to the node intervals of the finer grid, at the expense of increasing file size. An alternative would be for the producer to provide them in a GGXF file with two ggxfGroups, one defining the latitudeOffset and longitudeOffset through one grid and the other defining the ellipsoidalHeightOffset through a different grid. Implementations combine the three offsets into a 3D set. A GGXF file may also have multiple ggxfGroups which define common parameters. For example, in a deformation model each ggxfGroup is characterised by its time behaviour. It may contain many ggxfGroups with parameters displacementEast, displacementNorth, and displacementUp. Each group will have a different time function. See Annex E example E.5 for a deformation model GGXF file containing multiple groups in which the gridParameters differ. 5.8.9.2 Combining parameters from multiple groups In a GGXF file containing multiple ggxfGroups, any parameter occurring in multiple ggxfGroups must have its values from each ggxfGroup combined to calculate the full parameter value that is used for the coordinate operation described by the GGXF file. By default, parameter values are combined by adding them together. If a ggxfGroup contains a time function then the parameter values interpolated from the grids in the ggxfGroup are multiplied by this value before they are added. For uncertainty parameters it may be more appropriate to combine values as the root mean square of the values from each ggxfGroup. A parameter definition in the GGXF file header may include a groupAdditionMethod attribute which can take values addition (the default) or rootMeanSquare that can be used to specify the method. 5.8.9.3 Parameter values beyond grid extent Each ggxfGroup in a GGXF file defines parameters within the spatial extent defined by its grids. ggxfGroups may have different spatial extents. The GGXF file supports coordinate operations at any location within the spatial extents of any of its ggxfGroups. At a location that is only within a subset of the ggxfGroups, the parameter values from the other ggxfGroups are treated as zero. At a location that is not within the spatial extents of any ggxfGroup in the file, parameter values are undefined. The GGXF file does not support coordinate operations at that location. Parameter values are also undefined at a location if calculating the parameter requires using a no data value in any of the ggxfGroups that apply at that location. For example, a deformation model may contain two ggxfGroups. One represents the long-term secular deformation across the entire extent of the producer’s jurisdiction. The other represents the coseismic deformation due to an earthquake and is only defined in the region affected by that event. At a point outside the extent of the earthquake ggxfGroup, the deformation is defined solely by the secular deformation ggxfGroup. At this point the earthquake ggxfGroup makes no contribution – its contribution to each parameter is zero. 5.8.9.4 gridParameters In a GGXF file with multiple ggxfGroups, only a subset of the parameters declared in the file header may be relevant to a particular ggxfGroup. That ggxfGroup can include a gridParameters attribute specifying the subset of parameters represented at each grid node, and their order. If gridParameters 20

OGC 22-051r7 GGXF v1.0

is not specified, then the grids in the ggxfGroup will hold the set of parameters declared in the file header, in the order in which they are defined. Recommendation 11

When all parameters given in the file header are used in the ggxfGroup, the gridParameters attribute should be omitted from the ggxfGroup header.

Annex E examples E.1 through E.4 contain a single ggxfGroup and omit the gridParameters in the ggxfGroup header. 5.8.9.5 constantParameters A ggxfGroup may also include a constantParameters attribute defining constant values for one or more parameters in that ggxfGroup. This facilitates a smaller file size as the values are omitted from the set of node parameters but is treated as if the constant value at each node of each grid. A constantParameters attribute can be specified only in a ggxfGroup that also contains a gridParameters attribute. A parameter cannot be specified in both the gridParameters and constantParameters attributes. The gridParameters and constantParameters attributes together define which parameters are represented in the ggxfGroup. However, the attributes of these parameters (units, etc.) are as defined in the file header.

5.8.9.6

Time functions applied to parameters

A ggxfGroup may include an attribute timeFunctions that defines a time evolution of the parameter values interpolated from the grids in the ggxfGroup. This is currently supported only for deformationModel GGXF files, but in principle other content types could include time functions. The time function may be evaluated from one or more components; these are evaluated separately and added together to calculate the total time function. For example, a time function for post-seismic displacements after an earthquake may include an exponential and a logarithmic component. If a ggxfGroup includes a time function, then a time must be specified to evaluate the parameters. The time function evaluates a scalar value at that time. The parameter values interpolated at a location (or defined through the ggxfGroup constantParameters values) are multiplied by this time function value to give the value of those parameters at that location and time.

5.9 Data extent 5.9.1

General

The spatial and, if relevant, temporal extent of all data in a GGXF file is given in the file header as discovery metadata. For both technical and legal reasons the extent over which the file content should be used may be less than the full extent of data in the file. This Standard requires the description of the applicability of the file content. This may (and often will) differ from the spatial extent of the gridded data. Example: A single grid produced by a US agency covering both Alaska and the conterminus lower 48 states will include a good proportion of Canada, but the US data should not be used there. Canada has its own equivalent dataset, and in Canada that dataset should be used.

OGC 22-051r7 GGXF v1.0

The description uses the Extent provisions from ISO 19115-1. A text description and a geographic bounding box are mandatory, temporal extent is conditional and geographic bounding polygon and vertical extent are optional. The extent of each grid in the file is not described this way. It is described through the affine transformation in conjunction with the node maxima attributes; see 5.6. However, there may be circumstances where for discovery purposes it would be useful to give the geographic extent of individual ggxfGroups or grids, for example, when the Interpolation CRS is projected rather than geographic. In this Standard this is permitted, using the contentBox attribute, but the capability is not expected to be widely used.

5.9.2

Geographic bounding box

Figure 5 — Bounding boxes ISO 19115-1 requires that bounding box longitudes are in the range −180 =< λ =< +180 degrees, positive eastwards from the prime meridian. In this Standard the interpretation made is "start from lower bound longitude λ1, then move through increasing longitude values until we reach λ2". The relative values of westBoundLongitude and eastBoundLongitude describe whether the bounding box crosses the 180° meridian. In the −180° =< λ =< +180° range, if λ1 < λ2 then the grid does not cross the 180° meridian (green box in Figure 5), but when λ1 > λ2 then the grid crosses the 180° meridian (red bounding box in Figure 5). The example in Annex E.5 includes a bounding box crossing the 180° meridian, the other examples in Annex E show the more frequent case of bounding boxes not crossing the 180° meridian. 5.9.3

Extent description

A free text description of the geographic, vertical and/or temporal extent of file contents must be given in the file header. When a grid or grids cover an irregular area, the valid application of the file content may be significantly reduced from that described by the bounding box, for example within national limits, and the text description may be used to indicate this. If relevant, the description of main subdivisions may be included.

OGC 22-051r7 GGXF v1.0

5.9.4

Geographic bounding polygon

A geographic bounding box (bbox) is a coarse description of the applicability of data. The bbox will often include areas around its periphery where data is not applicable. A more refined description can be made through a bounding polygon. However, detailed polygons can be large and working with them complex. This Standard permits the inclusion of a bounding polygon in the file header but it is not mandatory to provide a polygon, and if a polygon is provided then using that information in implementations is not mandatory. If provided, a polygon must be represented through well-known text (WKT) and adhere to the geometry requirements of OGC Implementation Standard 06-103r4, Simple Features Access ― Part 1: Common Architecture. A polygon may consist of any number of exterior and interior linear rings, as defined in OGC 06-103r4. If the polygon crosses the 180° meridian, polygon vertex longitude coordinates should be continuous across the 180° meridian in whichever of the ranges (−180° =< λ =< +360°) and (−360° =< λ =< +180°) has minimal extent beyond the range (−180° =< λ =< +180°). 5.9.5

Temporal validity

The temporal validity describes the period over which the parameters in the GGXF file are applicable, given in the file header as a start date and/or an end date, or as a start epoch and/or an end epoch. The distinction between date and epoch is the data type. Epoch is given as a number of years represented by a real number while date is given as a date/time using the syntax defined in the RFC 3339 profile of ISO 8601-1, i.e., the 8601-1 extended format YYYY-MM-DD. Temporal validity is 'discovery metadata' for the entire dataset. Deformation model datasets also define a time function for each ggxfGroup that describes how that the displacement defined in the ggxfGroup applies at a particular time. 5.9.6

Vertical extent

Limits on vertical validity of file content may be given in the file header. Minimum and maximum values are in the context of the positive direction of the vertical CRS axis (heights or depths). The vertical CRS is identified through well-known text (WKT).

5.10 Miscellaneous metadata 5.10.1 Content general description Four general metadata attributes are mandatory in a GGXF file: title, version, abstract and filename. Two others, publicationDate and digitalObjectIdentifier, are recommended. Recommendation 12

The GGXF file header should include metadata identifying the date of issue (publicationDate), and if available a digitalObjectIdentifier (DOI) for the file content. An example of a DOI is included in Annex E.1. 5.10.2 Interpolation method This Standard does not specify the method for interpolation of the gridded data but allows the file provider to recommend a method. Including this information guides implementers which contributes to ensuring that implementations output results consistent with the expectations of grid producers. Bi-linear interpolation of a 2D grid and tri-linear interpolation of a 3D grid will suffice for most 23

OGC 22-051r7 GGXF v1.0

geodetic purposes. The interpolation method is an optional attribute and when not present bi-linear interpolation of a 2D grid and tri-linear interpolation of a 3D grid should be assumed. The interpolation methods given in GGXF Conventions Annex B.3 Table B.9 are frequently encountered in geodetic content and these identifiers should be used where appropriate, but this list is not exclusive and other interpolation methods may be recommended. If a producer wishes an interpolation method not in this table to be used by implementers, the userDefinedMethodName and a userDefinedMethodFormulaCitation to its formulae should be provided. Recommendation 13

The method that is recommended to be used for interpolation of the grid(s) in a ggxfGroup should be given in the ggxfGroup header.

5.10.3 Nominal operation accuracy operationAccuracy is a single value indicating the typical error of target coordinates derived through application of this grid content assuming no errors in source coordinates. This is discovery metadata for the entire file content. Coordinate Transformation and Point Motion Operation descriptions compliant with OGC 18-005, Abstract Specification Topic 2, Referencing by coordinates are required to include this information. This operation accuracy parameter is independent of the uncertainty of a parameter in the grid. Uncertainty of any parameter in the grid may be included as an additional parameter for the grid; see 5.8.7. Recommendation 14

A GGXF file with content supporting coordinate transformation should indicate the nominal operation accuracy value applicable to the data in the file.

5.10.4 File producer information Recommendation 15

The GGXF file header should include metadata giving details of the party responsible for producing the file. The responsible party elements of the CI_Citation class from ISO 19115-1 – Metadata fundamentals should be used for this.

The 19115-1 citation and responsible party elements are in Annex B.4. Examples are included in Annex E. 5.10.5 License For the protection of both supplier and consumer of GGXF data, license information that clearly defines the data copyright (if any is declared) as well as use restrictions, citation obligations, export limitations, etc. should be included in the header metadata. There are numerous existing licenses that may be suitable to reference as well as organization specific licenses that may need to be used. Custom or generic licenses may be referenced by URL using a licenseURL attribute in the header metadata. Alternatively, the entirety of the license text may be included using the license attribute in the header metadata. Recommendation 16

Metadata describing the terms under which the GGXF file is distributed (license information) should be included in the file header.

OGC 22-051r7 GGXF v1.0

5.10.6 Permanent tide If earth tides are significant to the geodetic parameters described in the GGXF file, the tide system used may be indicated in a ggxfGroup header. 5.10.7 Check data Coordinates and/or parameter values at one or more points within the GGXF file may be included in the GGXF file header to be used as verification data using the checkPoints attribute. The check points can be at grid nodes or within grid cells; they should be within the contentApplicabilityExtent of the data in the GGXF file. Parameters are identified using the parameterName given in the file header. Coordinates referenced to the source CRS (or if no source CRS is given in the file header, referenced to the interpolation CRS) are used to identify the location of the checkpoint. For GGXF file content supporting coordinate operations, the coordinates in the target CRS or target coordinate epoch act as test points for verification of the values in the GGXF file and their application through the coordinate operation. Check data is included in examples E.3 and E.5.

5.10.8 Comments Miscellaneous comments about the data in the file may be made using the keyword comment. A single comment may be made in each element of the embedded structure: one comment in the file header, one in each ggxfGroup header, each grid header, each parameter definition, each time function definition, etc. Note: Multiple comments within one element are invalid YAML and netCDF; whether and how they are handled will depend upon the reader.

6 Encoding 6.1 Introduction This Standard specifies guidance and recommendations for two encodings: i) text; ii) binary. The GGXF YAML text file is envisaged primarily as an intermediate stage used by some file producers in the assembling of grid data. The YAML file is not intended for public distribution. The text format is both human and machine readable, but for human reading will be practical only for small grids, or small extracts of large grids. The GGXF YAML text file has an option for referencing grid data in separate files rather than including the grid data within the GGXF YAML text file. The header information in the GGXF YAML text file is then consolidated and easier to read and edit. The text file uses syntax in compliance with YAML version 1.2 [9]. YAML may be validated using various available tool such as https://codebeautify.org/yaml-validator. The GGXF binary file includes all header records together with all grids. The binary encoding does not permit reference to external grid files. In this Standard, netCDF [6], [7] is the mandatory carrier for the GGXF binary encoding.

OGC 22-051r7 GGXF v1.0

Recommendation 17

Producers who choose to use a GGXF YAML text file to create the GGXF binary file, in addition to publishing the GGXF binary file are encouraged to make the text file available to software companies who wish to utilize it for the purpose of incorporating the data into their proprietary format.

Specific provisions for the YAML and netCDF encodings are given below.

6.2 YAML Encoding 6.2.1

Grid data

The GGXF YAML format supports two alternative methods of handling grids and, if relevant, content extent polygon. For small grids and polygons the data can be included directly in the GGXF YAML file. This is a direct mapping of the GGXF structure to YAML. When the text file contains grid (and if relevant polygon) data and does not reference external files, there is a 1:1 mapping between text file content and the GGXF binary file. However, some YAML readers and text editors may not handle very large grids. To cater for this, in place of the grid (or polygon) data the GGXF YAML format may include a reference to an external file. This may also be useful for producers generating grids with software that doesn’t generate GGXF YAML files. When the text file contains references to external grid or polygon files, there is a near complete mapping between the GGXF text and binary formats; the difference is that the text format is the GGXF headers plus references to external files. Recommendation 18

For large grids producers are encouraged to have these grids in external files rather than directly in the YAML text file.

The purpose of a text GGXF file with external grid data is to allow specific software to compile the dataset to a netCDF binary GGXF file for publication. This Standard defines one supported format of external grid data files (see 6.2.3). A GGXF software provider may choose to support other external grid data formats. A producer should not assume that a GGXF text file referencing other external formats will be readable by software other than that for which it is written. 6.2.2

YAML grid data syntax

In the GGXF YAML format, all parameters at a node are given sequentially with each value separated by a comma and, optionally, a space, carriage return or new line character (YAML will ignore the space, carriage return or new line character). In the YAML syntax the grid data is represented as a nested array structure. The structure consists of an array in which each element represents the data for one value of the i index. Within this array, each element is an array representing the values of the j index, and each element of that array is an element representing the parameter values at the i,j node. Example: a grid with iNodeCount=3 and jNodeCount=5 and 2 parameters per node, each node having a parameter value in green and in blue (i.e., total of 30 values): [[[1.00, -2.70],[1.20, -2.50],[1.40, -2.30],[1.60, -2.10],[1.80, -1.90]], [[1.21, -2.74],[1.40, -2.52],[1.65, -2.31],[1.83, -2.13],[2.00, -1.92]], [[1.40, -2.78],[1.80, -2.53],[2.00, -2.33],[2.10, -2.14],[2.20, -1.93]]]

In this structure, to access the highlighted second parameter of the fourth column of the third row in the grid would use an index [i][j][p] = [2][3][1] (noting that YAML arrays are indexed from 0).

OGC 22-051r7 GGXF v1.0

GGXF allows the YAML structure to be flattened if it suits a data producer. In particular, if there is only one parameter at each node then it may be represented as a single value, rather than an array of one value. For example, a geoid height can be shown as a simple value 8.7, rather than an array [8.7]. More generally the brackets around each set of parameter value and around the data for each index may also be omitted, provided it is done consistently in the entire grid. For example, the grid above may be written as an array of values as follows. The order of elements in the grid is not changed, it is simply an array of numbers. [1.00,-2.70,1.20,-2.50,1.40,-2.30,1.60,-2.10,1.80,-1.90,1.21,-2.74,1.40,-2.52,1.65, -2.31,1.83,-2.13,2.00,-1.92,1.40,-2.78,1.80,-2.53,2.00,-2.33,2.10,-2.14,2.20,-1.93]

In this structure the highlighted element would be accessed by index [27]. However, when it is loaded into the multidimensional structure its index is unchanged and is [2,3,1]. The software reading the YAML file is responsible for correctly loading the YAML structure based on the grid shape (number of rows and columns) and the number of parameters at each node. 6.2.3 6.2.3.1

YAML external grid data General

The GGXF binary file format requires grid data to be accompanied with header data in a single file. However, the GGXF YAML text file format optionally permits the grid data to be held in one or more external files referenced from the GGXF YAML file. This feature is designed for data producers to simplify building GGXF data sets from other software. GGXF software can be used to convert the GGXF YAML format to a GGXF netCDF file for distribution. GGXF YAML files referencing external grid data files should not be used for distribution. The external grid files are referenced by the dataSource keyword in the GGXF YAML grid specification. It is used in place of the data keyword. dataSource identifies the external location of the grid data (typically through a file name or url), its format, and possibly a subset of data that are to be read from the file through a set of key-value pairs. This should include dataSourceType which identifies the format of its grid data. The dataSource attribute is specific to the text file reader implementation and cannot be used in the GGXF binary format. When there is a change to the sequence of parameters between the GGXF binary file (as described through the GGXF YAML headers) and the external file, it is made by the application creating the GGXF binary file. In accordance with the recommendations in 5.8.8, any parameters with the identifier node* should not be included in the translation into the GGXF binary file. This Standard describes one simple text file format for external files (6.2.3.2). However the GGXF YAML file may reference external grids in other formats (6.2.3.3). 6.2.3.2

GGXF external grid text file format

GGXF supports one format for external grid files - the ggxf-csv text file format - and one set of keywords to reference this. The ggxf-csv format is based on the commonly used comma separated value (CSV) file format but it allows the file to use either comma or space or tab as the separator. The dataSourceType for a GGXF external grid data file is "ggxf-csv" with an additional key separator identifying the character used to separate values in the file. The ggxf-csv text file format is defined in the GGXF Conventions in Annex B.6 Table B.17. The content of these ggxf-csv files is logically part of the GGXF YAML text file that references them. The metadata such as units given in the GGXF YAML text file applies to these parameters, except that the sequence of parameters in the ggxf-csv file may differ from the sequence defined in the GGXF YAML 27

OGC 22-051r7 GGXF v1.0

file, and the ggxf-csv file may contain node coordinates as additional parameters. The inclusion of node coordinates in the ggxf-csv file is not a requirement but they may be used by software for validating the grid affine coefficients. See E.1.3 for examples of GGXF YAML files with externally referenced grid data in the ggxf-csv text format supported in this Standard. 6.2.3.3

User-defined external grid file format

There is no restriction on the file format for external grid files referenced through dataSource. They may be in a producer-specific format. The definition of dataSourceType other than ggxf-csv and any additional keys specific to that source type is outside the scope of GGXF. If the data source is a single file then using the key gridFilename to identify the file is recommended. Software implementing a custom data source may define other keys in the dataSource attribute to describe how the grid data is provided from the external data source. Translating such grids into the GGXF binary format will require a custom extension to an application reading the GGXF YAML file. This is outside the scope of the GGXF Standard. The external file content need not conform to GGXF requirements but if this is the case then the custom software will need to include any data conversion necessary so that in the GGXF binary file the grid and the metadata in the GGXF YAML headers match. See E.5 and the GitHub link in E.7 for examples of a GGXF YAML files with grid data in a referenced external file using user-defined attributes for dataSource.

6.3 netCDF Encoding 6.3.1

Introduction

The Unidata network Common Data Form (netCDF) is used as the carrier for the GGXF binary encoding. There are several versions of netCDF: GGXF uses netCDF-4. The Unidata Program Center supports and maintains netCDF programming interfaces for C, C++, Java, and Fortran. Programming interfaces are also available for Python, IDL, MATLAB, R, Ruby, and Perl. Recommendation 19

Implementations should use the existing netCDF programming interfaces instead of trying to access the data using their own code.

The netCDF user guide recommends using the netCDF-CF (climate and forecasting) conventions. However, the CF-conventions used for defining the grid domain do not apply to GGXF files. GGXF files do not use netCDF coordinate variables for defining grid axis coordinates. Instead, in GGXF the domain coordinate reference system and its relationship with the file's grid coordinates are defined solely by the interpolationCrsWkt and affineCoeffs attributes. This GGXF specification does have a small subset of attributes in common with the netCDF-CF conventions; examples include some discovery metadata in the file header using ACDD attributes (see 6.3.2) and using netCDF data packing attributes scale_factor and add_offset (see 6.3.5.4). 6.3.2

Relationship of GGXF Conventions to ACDD

The Attribute Convention for Data Discovery (ACDD) defines a list of netCDF global attributes recommended for describing a netCDF dataset to metadata discovery systems. ACDD is encouraged in some non-geodetic communities utilising netCDF. Software tools are available to use these attributes for extracting metadata from netCDF datasets and exporting to metadata formats such as Dublin Core and ISO 19115. To facilitate the application of these software tools to a GGXF file, when implementing

OGC 22-051r7 GGXF v1.0

a GGXF file in netCDF the mapping of attribute names of certain parameters must follow that in GGXF Conventions (Annex B.5) Table B.14. Note that Table B.14 does not include all ACDD attributes. Applications reading a GGXF netCDF file may ignore any attributes that are encountered but which are not found in the GGXF Conventions. Recommendation 20

6.3.3

When reading a GGXF binary file any attributes encountered that are not in the GGXF Conventions may be ignored.

GGXF netCDF structure

The netCDF-4 structure has the following main components. •

netCDF group - A structured data object which may contain other groups.

•

netCDF variable - An array attribute of a group with an arbitrary number of dimensions. The size of the array is defined by netCDF dimensions in its direct or indirect parent groups.

•

netCDF attribute - A named attribute which containing either a single value or a list of values. netCDF attributes may be assigned to netCDF groups and to netCDF variables.

•

netCDF dimension - A special integer attribute of a netCDF group that is used to define the dimensions of a variable. It is defined in a group and may be referenced in that group and all its children and their descendants.

netCDF groups are analogous to directories in a file system. Each netCDF file has a unique "root" group. Each group is identified by a name. The root group is named "/". Each group is identified by the path "<parent_path_name>/<group_name>", except that if the parent is the root group then the path is "/<group_name>". The structural elements of a GGXF file are located in a netCDF file as follows. •

The GGXF file header is the netCDF root group at "/"

•

A ggxfGroup header is a netCDF group that is a direct child of the root group at "/<ggxfGroupName>"

•

GGXF grid headers, including the grid data, are netCDF groups that are either children of a GGXF group header or of another GGXF grid header following the nesting structure of the grids in each ggxfGroup. – Top level (root) grids in a nested grid structure area are located at "/<ggxfGroupName>/<rootGridName>". –

6.3.4 6.3.4.1

First generation child grids are located at "/<ggxfGroupName>/<rootGridName>/<childGridName>".

Representation of structured data General

Attributes in the file header, ggxfGroup header, and grid header are represented as netCDF attributes of the corresponding netCDF group except for: i) the iNodeCount, jNodeCount, and kNodeCount parameters which are stored as dimensions in the netCDF group holding the GGXF grid; and ii) structured parameters which are discussed in the following subclause.

OGC 22-051r7 GGXF v1.0

Attributes which are simple strings or numeric values are stored as netCDF attributes of the same type. Attributes which are lists of strings or numbers (such as “gridParameters”, “affineCoefficients”) are stored as netCDF list attributes. 6.3.4.2

Structured data

GGXF also defines attributes that are structured. A structured attribute is one which holds a set of name/pair value or an ordered list of values. Each of the constituent values may itself be a set of name/pair values or an ordered list of values. Examples of structured data include the parameters attribute in the file header which has several attributes (name, units, etc) and the timeFunctions attribute of deformation model content. These GGXF structured attributes are represented using multiple attributes in the netCDF group, one for each string or numeric value held within the structured attribute plus one for the count of these values. These netCDF attributes are named using a naming convention that appends a string which encodes the structure to the GGXF attribute name. GGXF attributes containing a list of values are replaced by: i)

A netCDF attribute defining the number of elements in the list, named by appending “.count” to the name of the GGXF attribute that holds the list;

ii) A netCDF attribute for each element of the list, named by a) appending to the name of the GGXF attribute that holds the list a zero-based sequence number “.0”, “.1”, ... . b) GGXF attributes containing key/value pairs are replaced by a netCDF attribute for each pair named by appending “.” and the keyword to (a) above. The following example illustrates this for the parameters attribute of the GGXF file header. This example has four parameters (count = 4, zero-based sequence number 0 to 3), each with the three attributes of parameter name, unit identifier and unit SI ratio. :parameters.count = 4 ; :parameters.0.parameterName = "latitudeOffset" ; :parameters.0.unit = "arc-second" ; :parameters.0.unitSiRatio = 4.84813681109536e-06 ; :parameters.1.parameterName = "longitudeOffset" ; :parameters.1.unit = "arc-second" ; :parameters.1.unitSiRatio = 4.84813681109536e-06 ; :parameters.2.parameterName = "latitudeOffsetUncertainty" ; :parameters.2.unit = "metre" ; :parameters.2.unitSiRatio = 1.0 ; :parameters.3.parameterName = "longitudeOffsetUncertainty" ; :parameters.3.unit = "metre" ; :parameters.3.unit = 1.0 ;

The following example illustrates this for deformation model time functions. The timeFunctions attribute of a ggxfGroup contains a list of values each of which is a set of name/pair values. This example includes a step function and a ramp function, these having different attributes. :timeFunctions.count = 2 ; :timeFunctions.0.functionType = "step" ; :timeFunctions.0.eventDate = "2009-07-15T00:00:00Z" ; :timeFunctions.0.functionReferenceDate = "2010-01-01T00:00:00Z" ; :timeFunctions.1.functionType = "ramp" ; :timeFunctions.1.startDate = "2009-07-15T00:00:00Z" ;

OGC 22-051r7 GGXF v1.0

:timeFunctions.1.endDate = "2009-10-01T00:00:00Z" ; :timeFunctions.1.functionReferenceDate = "2010-09-01T00:00:00Z" ; :timeFunctions.1.scaleFactor = 0.3 ;

6.3.5 6.3.5.1

Representation of grid data ParameterSet

In the GGXF logical model each GGXF grid contains a single array containing the tuple of parameters defined at each grid node. In the GGXF netCDF implementation this is represented by one or more NetCDF variables, each holding the grid node values for a subset of parameters. A variable holding two or more GGXF parameters is referred to as a “vector variable”. The parameter attribute parameterSet is used to define the netCDF variable to which a GGXF parameter is assigned. When two or more GGXF parameters are assigned the same value for their parameterSet attribute, they are combined into a single netCDF vector variable. For example, if three GGXF parameters displacementNorth, displacementEast, displacementUp all have parameterSet value “displacement”, they are combined into a single netCDF variable called 'displacement'. If four GGXF parameters latitudeOffset, latitudeOffsetUncertainty, longitudeOffset and longitudeOffsetUncertainty are assigned parameterSet attributes of offset, offsetUncertainty, offset and offsetUncertainty respectively, the GGXF parameters latitudeOffset and longitudeOffset will be combined in a NetCDF vector variable called offset while the GGXF parameters latitudeOffsetUncertainty and longitudeOffset will be combined in a second netCDF vector variable called offsetUncertainty. The parameterSet attribute is optional. If parameterSet is not defined then the parameterName is used as the name of the netCDF variable holding the parameter. For example, if a parameterSet value was not given to either of two GGXF parameters latitudeOffset and longitudeOffset, they are held in two separate netCDF variables called 'latitudeOffset' and 'longitudeOffset' respectively. Recommendation 21

Consider defining different parameter sets for parameters and their uncertainties, for example 'offset' and 'offsetUncertainty'. Applications not needing to utilise the uncertainty data can then skip the offsetUncertainty variable.

Recommendation 22

In creating the name of a parameter set, avoid 'count' as this is may create a conflict with its use in the definition of structured data and in netCDF vector variable naming.

6.3.5.2

Parameter sequence

The order of parameters in the netCDF variables is defined in the file header. This may be overridden by the optional gridParameters attribute in the ggxfGroup containing the grid. gridParameters may define a subset of all parameters which are in the group and/or define a new sequence. Note that where the grid data is used in a transformation between a source CRS and a target CRS, the parameters in the netCDF file are not necessarily in the same order as the axes in the source CRS to which the grid data is to be applied. The source CRS axis corresponding to each parameter should be defined in the GGXF parameter definitions in the GGXF file header - see 5.8.4. 6.3.5.3

netCDF variable size

The size of a netCDF variable is defined by netCDF dimension attributes. Each variable will have a dimension for each interpolation coordinate axis. These netCDF dimensions are called iNodeCount, 31

OGC 22-051r7 GGXF v1.0

jNodeCount, (kNodeCount for 3-dimensional interpolation grids) and are defined in the netCDF group representing the grid. The values correspond to the node count. Vector variables have an additional netCDF dimension representing the number of parameters at each grid node. This is defined in the netCDF group containing the grid. The name of this dimension is arbitrary. Recommendation 23

The dimension defined in netCDF group for the number of parameters in a grid variable should be the parameterSet name appended with “Count”. For example, the dimension of the parameterSet "displacement" should be named “displacementCount".

Each netCDF variable in a grid therefore will have dimensions (iNodeCount,jNodeCount) for variable representing a single GGXF parameter, or (iNodeCount,jNodeCount,setCount) for a variable representing a vector of GGXF parameters in the parameterSet set. 6.3.5.4

Data packing and numeric type

In a GGXF netCDF file the variables holding grid data can be of any numeric type. There is no requirement that all the variables in a GGXF netCDF file are of the same numeric type. The variables may have netCDF conventional attributes scale_factor and add_offset to define a scale factor and offset used to facilitate packing the data into a smaller numeric type. The scale_factor and add_offset attributes are assigned individually to each netCDF variable in a GGXF file. The values need not be the same for each variable. When scaled data is written, the producing application should first subtract the offset and then divide by the scale factor. The units of a variable should be representative of the unpacked data. When reading a GGXF netCDF file, after the data values of a packed variable have been read, they are to be multiplied by the scale_factor and have add_offset added to them. If both attributes are present, the data is scaled before the offset is added. 6.3.5.5

No data value

Each parameter in a GGXF file may have a noDataFlag defined that is used at grid nodes where the value of the parameter is missing or not defined. Any parameter that has missing values somewhere in the GGXF file must have the noDataFlag attribute defined. In a netCDF GGXF file this value is not used in the variables that hold grid data. Instead, each variable may have a missing_value attribute defined. This is a conventional netCDF attribute. It is not used in a GGXF YAML file. noDataFlag is in the domain of the parameter, whereas missing_value is in the domain of the netCDF variable. missing_value is used to represent any missing value in the variable. The missing_value attribute must be of the same numeric type as the data in the netCDF variable on which it is defined, which may be packed data. Each variable in a GGXF netCDF file may use a different value for the missing_value attribute. If all the parameter values are defined at every node in the netCDF variable, then the variable does not require a missing_value attribute. Recommendation 24

If a grid has missing values a producing application should determine a suitable missing_value for each grid data variable it creates. The application should use this value in place of the noDataFlag in the variable. The missing_value attribute of a variable should be either larger than the largest actual packed data value or smaller than the smallest actual packed data value in the variable.

OGC 22-051r7 GGXF v1.0

Recommendation 25

A reading application encountering values matching the missing_value attribute in a variable should identify and treat the corresponding unpacked values as undefined.

OGC 22-051r7 GGXF v1.0

Annex A (normative) Conformance requirements

A.1 Core requirements The GGXF core requirements are those that shall be satisfied by both data providers and data users. To conform to the core requirements of this Standard a GGXF file shall as a minimum include requirements given in Table A.1. Where appropriate, text in italic font gives the keyword from the GGXF Conventions. All requirements below are identified by partial URIs which are relative to the base http://www.opengis.net/spec/ggxf/1.0/ The identifiers given in this Standard use camelCase for clarity, but they are not case sensitive. Table A.1 — GGXF core requirements

Identifier

Requirement

req/core/conventions

GGXF Conventions A A GGXF file shall adhere to the GGXF Conventions. B The GGXF file header shall begin with the GGXF Convention identifier ggxfVersion to which the file conforms. C The name and GGXF version number for files conforming to this Standard is "GGXF-1.0".

req/core/header

Header A A GGXF file shall contain header information describing the data in the file. The file shall have three header elements: (i) a file header containing metadata applicable to the whole file describing the file content and its provenance, (ii) for each ggxfGroup in the file, a ggxfGroup header containing metadata applicable to that ggxfGroup, and (iii) for each grid in the file, a grid header containing metadata applicable to that grid.

req/core/groupIdentifier

ggxfGroup identifier A Each ggxfGroup shall have an identifier which is unique within the file. The identifier shall be specified in the ggxfGroup header. The ggxfGroup identifier shall be specified through the GGXF Conventions identifier ggxfGroupName and be the first attribute in the ggxfGroup header block. The identifier shall be a Unicode Identifier.

req/core/gridIdentifier

Grid identifier A Each grid shall have an identifier which is unique within the file. The identifier shall be defined in the grid header and be specified through the GGXF Conventions identifier gridName. The identifier shall be a Unicode Identifier.

req/core/content

Content type A A GGXF file shall contain a single content type. This shall be specified in the file header by the content attribute.

OGC 22-051r7 GGXF v1.0

Identifier

Requirement

req/core/fileMetadata

Title, version, abstract and file name A The GGXF file header shall include attributes title, version, abstract and filename.

req/core/interpolationCrs

Interpolation CRS A All grids in a GGXF file shall be constructed in the same Interpolation CRS. This Interpolation CRS shall be any 2D or higher-dimension coordinate reference system that is compliant with OGC 18-005, Abstract Specification Topic 2, Referencing by B coordinates. The GGXF file header shall include a description of the Interpolation CRS using well-known text (WKT), using the GGXF Conventions identifier interpolationCrsWkt. The well-known text shall be compliant with OGC Implementation Standard 18-010, Well-known text representation of coordinate reference systems. C When the WKT string contains a reference to an external registry describing the CRS, if there is a conflict between the well-known text description and the information derived through the http URI, the WKT description shall prevail.

req/core/sourceTargetCrs

Source and target CRS (Conditional) A When the GGXF content is used in a coordinate operation, the GGXF file header shall include a description of the source CRS and target CRS in well-known text (WKT) using the GGXF Conventions identifiers sourceCrsWkt and targetCrsWkt respectively. The well-known text shall be compliant with OGC 18-010. B If a WKT string contains a reference to an external registry describing the CRS, if there is a conflict between the well-known text description and the information derived through the http URI, the WKT description shall prevail.

req/core/geogExtent

Geographic extent A The GGXF file header shall include a description of the geographic applicability of file content using the GGXF Conventions identifiers "contentApplicabilityExtent.boundingBox.southBoundLatitude", "contentApplicabilityExtent.boundingBox.westBoundLongitude", "contentApplicabilityExtent.boundingBox.northBoundLatitude", "contentApplicabilityExtent.boundingBox.westBoundLongitude" and "contentApplicabilityExtent.extentDescription".

OGC 22-051r7 GGXF v1.0

Identifier

Requirement

req/core/boundingPolygon

Bounding polygon (Conditional) A The GGXF file header may include a refined description of the applicable geographic extent using the GGXF Conventions identifier contentApplicabilityExtent.boundingPolygon. If provided, the polygon representation shall be in well-known text (WKT) and adhere to the geometry requirements of OGC Implementation Standard 06-103r4, Simple Features Access ― Part 1: Common Architecture, the vertices shall be in geographic coordinates (latitude and longitude), and if the polygon crosses the 180° meridian the polygon vertex longitude coordinates shall be continuous across the 180° meridian in either one of the ranges (−180° =< λ =< +360°) and (−360° =< λ =< +180°), preferably that which has minimal extent beyond the range (−180° =< λ =< +180°).

req/core/temporalExtent

Temporal extent (Conditional) A When one or more grids in a GGXF file have limits on their temporal applicability, the full temporal extent of the file content shall be given in the file header through either a) startDate and/or endDate or b) startEpoch and/or endEpoch B When a start date is given and an end date is missing, the temporal validity of the data in the file continues from the start date. If a start epoch is given and an end epoch is missing, the temporal validity of the data in the file continues from the start epoch. C When an end date is given and a start date is missing, the temporal validity of the data in the file applies before and up to the end date. If an end epoch is given and a start epoch is missing, the temporal validity of the data in the file applies before and up to the end epoch. D When temporal extent is not given, there is no constraint on temporal validity of the data in the file.

req/core/producer

Data producer metadata (Conditional) A When citation or responsible party metadata is included in the file header, for any attributes not explicitly given in the GGXF Conventions the ISO 19115-1 UML role names shall be used as keywords.

OGC 22-051r7 GGXF v1.0

Identifier

Requirement

req/core/grid

GGXF grid A A GGXF grid shall be an array indexed by integer values i and j where 0 <= i < iNodeCount, 0 <= j < jNodeCount, (and in the 3dimensional case 0 <= k < kNodeCount). B A 2D grid shall be rectangular in its Interpolation CRS and a 3D grid shall be cuboid in its Interpolation CRS. Note: 'rectangular' and 'cuboid' mean that the lengths of opposite edges of the grid have the same distance in Interpolation CRS units, for example an arc-rectangle with north and south sides along different parallels of latitude but both extending 20 degrees of longitude.

C On any one axis of a GGXF grid, the spacing of nodes in the Interpolation CRS shall be constant. D For a grid of dimensions i by j and with p parameters at each node there shall be i.j.p values in the block of data for the grid. req/core/affineCoeffs

Affine transformation A For each GGXF grid the relationship of the grid indices to Interpolation CRS coordinates shall be described in the grid header through affine transformation coefficients (affineCoeffs).

req/core/nodeCount

Node count A For each axis of the grid, the maximum node count shall be given in the grid header (iNodeCount, jNodeCount [kNodeCount].

req/core/interpolationMethod

Grid interpolation method

A GGXF file producers should specify the required grid interpolationMethod in the ggxfGroup header information. B GGXF file user software shall apply the interpolation method specified in the ggxfGroup header. If no interpolation method is specified, bilinear shall be assumed. req/core/nestedGrid

Nested grids (Conditional) A For ggxfGroups with nested grids, the extent of a child grid shall be contained within the extent of its parent grid. They may share a common external boundary. The parent-child relationships within the grids belonging to a ggxfGroup shall be defined through the ggxfGroup structure. B To evaluate ggxfGroup parameters in nested grids, a child grid shall be used in preference to its parent.

req/core/gridPriority

Grid priority (Conditional) A When sibling grids intersect, different integer gridPriority values for each intersecting sibling shall be given in the grid header. B Where sibling grids intersect, to evaluate the ggxfGroup parameters a sibling grid with a higher gridPriority and all its direct or indirect child grids shall be used in preference to the sibling with lower gridPriority and all its direct or indirect child grids.

OGC 22-051r7 GGXF v1.0

Identifier

Requirement

req/core/param/attributes

Parameters and their attributes A All parameters in the GGXF file shall be defined in the GGXF file header. B For each parameter, its parameterName, unitName and the unitSiRatio shall be given. C When unitSiRatio is given for a unit included in the GGXF Conventions and its value differs from that in the Conventions, the value in the Conventions shall take precedence. D This list of parameter attributes may be extended to include minimumValue, maximumValue, uncertaintyMeasure, and the parameterSet in which the parameter is grouped in a data array.

req/core/uncertaintyMeasure

Uncertainty measure (Conditional) A When uncertainty estimates are included as parameters, the measure for uncertainty as given in the GGXF Conventions shall be included in the parameter definition.

req/core/param/sequence

Parameter sequence A The sequence in which the parameters are listed shall be the sequence of the parameters at each grid node. B This sequence may be amended for a ggxfGroup. In a ggxfGroup containing only a subset of the parameters declared for the whole GGXF file, the subset and its sequence shall be identified in a groupParameters attribute in the ggxfGroup header.

req/core/param/count

Parameter count A Each node of all grids within a ggxfGroup shall contain the same tuple of parameters. For a grid of dimensions i by j and with p parameters at each node there shall be i.j.p values in the block of data for the grid.

req/core/param/mandatory

Mandatory parameters A As a minimum, those parameters given in the GGXF Conventions as being mandatory for the content type shall be included in the tuple.

req/core/param/sourceCrsAxis

Source CRS Axis (Conditional)

A For parameters used in a coordinate operation, the sequence value of the sourceCrsAxis to which the parameter is applied shall also be included. req/core/param/missingData

Missing data (Conditional) A When a parameter is missing a value at any grid node in the GGXF file, the value for a noDataFlag specific to the parameter shall also be included. A noDataFlag value shall be one that cannot be mistaken for a genuine parameter value. The flag may be omitted if a value is provided at every node of every grid in the file at which the parameter applies.

req/core/param/nodeCoords

Node coordinates (Conditional) A If coordinate values for nodes are included as parameters, they shall match the values calculated from the node indices using the affine transformation.

OGC 22-051r7 GGXF v1.0

Identifier

Requirement

req/core/param/constantValue Parameter with constant value (Conditional) A In a ggxfGroup containing a parameter with a constant value throughout all grids in the ggxfGroup, the parameter and its constant value shall be identified in the ggxfGroup header. Any parameter declared to have a constant value in a ggxfGroup shall be omitted from the tuple of parameters at grid nodes in the grids in the ggxfGroup. B Any parameter declared to have a constant value in a ggxfGroup shall be treated as if it was defined at grid nodes. req/core/permanentTide

Permanent tide (Conditional) A If relevant to the ggxfGroup content, the permanent tideSystem used shall be indicated in the ggxfGroup header.

OGC 22-051r7 GGXF v1.0

A.2 Requirements for mapping GGXF schema to a GGXF YAML text file Requirements for mapping the GGXF schema into the GGXF YAML text file format are given in Table A.2. Where appropriate, text in italic font gives the keyword from the GGXF Conventions. All requirements are identified by partial URIs which are relative to the base http://www.opengis.net/spec/ggxf/1.0/. The terms 'mapping' and 'collection' in Table A.2 are as defined in the YAML specification. Table A.2 — GGXF YAML text file requirements

Identifier

Requirement

req/yaml/version

Version A GGXF YAML text files shall adhere to the requirements of YAML version 1.2.

req/yaml/filename

File name A GGXF YAML text files shall have the file name extension ".yaml".

req/yaml/structure

File structure A A GGXF YAML text file shall be structured as a mapping containing the GGXF file header attributes B A GGXF YAML text file shall include an attribute “ggxfGroups” containing a collection of mappings. Each ggxfGroup shall be represented by a mapping in the ggxfGroups collection. C Each ggxfGroup shall contain an attribute “grids” containing a collection of mappings. Each grid header in the ggxfGroup shall be represented by a mapping in the “grids” collection. D Each mapping representing a grid may contain an attribute “childGrids” containing a collection of mappings. Each child grid of a grid shall be represented by a mapping in the “childGrids” collection.

OGC 22-051r7 GGXF v1.0

Identifier

Requirement

req/yaml/gridData

Grid data A For each grid, the GGXF YAML file shall contain either an attribute "data" containing the array of the parameter values in the grid within the YAML text file, or an attribute "dataSource" defining an external data source from which the array of parameter values shall be read. B A grid "data" attribute shall contain an entry for each interpolation axis value and for each parameter in the grid. The data shall be represented as a nested array structure of dimensions [ni][nj][np] or [ni][nj][nk][np] where ni, nj, and nk are the number of nodes in the grid, as defined in the grid header, and np is the number of parameters at each node as defined in the ggxfGroup that contains the grid. The YAML structure may be flattened by combining all of the grid axes provided that the order of numeric values is not changed. For example a structure of dimension [ni][nj][np] could be flattened to dimension [ni × nj × np]. C Regardless of the flattening of the nested array structure the order of the parameter values in the YAML representation is unaltered. The location of the pth parameter at node (i,j) shall be given by the formula (i × nj + j) × np + p where the indices i, j and p are all zero based. D In a three dimensional grid with indices(i, j, k) the formula shall be: ((i × nj + j ) × nk + k) × np + p

req/yaml/gridBracketing Grid value bracketing A Parameter values for the whole grid shall be within one pair of square brackets with all parameters at a node given sequentially and each value separated by a comma. B Optionally, additional square bracketing may be inserted around both the set of parameters at each node and each row of nodes.

OGC 22-051r7 GGXF v1.0

Identifier

Requirement

req/yaml/ggxf-csv

External grid value file A A ggxf-csv external grid data text file shall contain one header line followed by one line for each grid node in the order specified in req/yaml/gridData. The line containing the parameters for node (i,j) shall be: 2 + i × nj + j Note: 2 is added to the line number as there is 1 header line, and line numbers are conventionally 1 based. The header line is line 1 and the first line of data is line 2.

B In a three dimensional grid the line containing the parameters for node (i,j,k) shall be at line number: 2 + ( i × nj + j ) × nk + k C The values in the header line shall be the grid node parameter identifiers from the GGXF Conventions and shall define the order of parameter values in the subsequent lines. The set of identifiers shall include the grid node parameters defined in the ggxfGroup within which the external grid file is referenced and may also include node coordinate identifiers. D The values on each subsequent line shall be the parameter values at a grid node in the order defined by the header line. Missing parameter values in the grid shall be identified by the noDataFlag value defined for the parameter in the GGXF file header. E Each line shall have the same number of values. Values shall be separated by the character given through the separator key and optionally may be additionally padded with spaces. F Each line shall be terminated by the line feed (new line) character (U+000A). The line feed may be immediately preceded by a carriage return character (U+000D).

A.3 Requirements for mapping GGXF schema to a GGXF netCDF binary file Requirements for mapping the GGXF schema into the GGXF netCDF binary file format are given in Table A.3. Where appropriate, text in italic font gives the keyword from the GGXF Conventions. All

OGC 22-051r7 GGXF v1.0

requirements are identified by partial http://www.opengis.net/spec/ggxf/1.0/

URIs

which

are

relative

the

base

Table A.3 — GGXF netCDF binary file requirements

Identifier

Requirement

req/netcdf/filename

File name A GGXF netCDF binary files shall have the file name extension ".ggxf"

req/netcdf/structure

File structure A The GGXF file header attributes shall be held in the netCDF root group. Each ggxfGroup shall be represented by a netCDF group that is a child B group of the root group. Every child group of the root group represents a ggxfGroup. Each grid shall be represented by a netCDF group. Each root grid of a C ggxfGroup is represented by a netCDF group that is a child group of that representing the ggxfGroup. Each child grid of a grid is represented by a netCDF group that is a child group of the netCDF group representing its parent grid.

req/netcdf/attributes

Attributes A Attributes of the file, ggxfGroup, and grid headers shall be represented as netCDF attributes of the corresponding netCDF group, except: •

• • B

The node count attributes of a grid (iNodeCount, jNodeCount, kNodeCount) shall be held as netCDF dimensions of the netCDF group containing the grid. iNodeCount shall correspond to netCDF dimenion 0, jNodeCount shall correspond to netCDF dimenion 1, and so on. The ggxfGroupName parameter of a ggxfGroup is held as the name of the netCDF group representing the ggxfGroup The gridName parameter of a grid is held as the name of the netCDF group representing the grid

GGXF attributes holding a string value, or a numeric value, or a list of string values, or a list of numeric values shall be represented by a single netCDF attribute. GGXF attributes holding more complex structured values shall be represented by multiple netCDF attributes C as described in the GGXF Conventions. GGXF attributes in a netCDF file shall use the name specified in the GGXF Conventions.

OGC 22-051r7 GGXF v1.0

Identifier

Requirement

req/netcdf/variable

Parameter values A The array of parameter values of a grid shall be represented by one or more netCDF variables in the netCDF group representing the grid. Each variable shall be named by the parameterSet of the parameter it contains; if parameterSet is not defined then the variable shall be named by the parameterName of the parameter. B Parameters of the ggxfGroup that have the same parameterSet name shall be combined into a single netCDF variable. The order of parameters in the variable shall be the order defined in the gridParameters attribute in the ggxfGroup containing the grid, or, if that is not defined, in the order defined in the parameters attribute in the GGXF file header. C A grid variable containing the data for a single GGXF parameter shall have dimensions (iNodeCount, jNodeCount) or (iNodeCount, jNodeCount, kNodeCount). D A grid variable containing data for two or more GGXF parameters shall have dimensions (iNodeCount, jNodeCount, parameterSetCount) where 'parameterSet' is replaced by the name of the parameterSet. The parameterSetCount value shall be defined as a dimension in the netCDF group representing the ggxfGroup containing the grid.

OGC 22-051r7 GGXF v1.0

Annex B (normative) GGXF Conventions

B.1 Introduction The GGXF Conventions are a controlled vocabulary of identifiers used in file, ggxfGroup, and grid header records to describe file content. Most are key-value pairs. To conform to YAML requirements, identifiers (keywords) are case-sensitive. To aid readability, keywords formed from multiple words or abbreviations are given in upper camel case. A consolidated list of all GGXF identifiers is given in Table B.1 Primary keywords and definitions are given in clause B.2 Table B.2. In some cases, reference is made to supplementary Tables B.3 through B.11 in clause B.3 which give controlled vocabularies for attributes. In addition, for citation information GGXF uses the UML role names from the ISO 19115 (Metadata) Citation and Responsible Party classes as keywords; selected example keywords are shown in clause B.4 Table B.12. Mapping of GGXF attributes to netCDF is given in clause B.5 Tables B.13 through B.16. Keywords for the GGXF external grid file format are given in clause B.6 Table B.17. These tables collectively form the GGXF Conventions. In each table the identifiers are listed alphabetically. Clause

Table

Content

B.2 principle keywords

Table B.2

header attribute keywords

B.3 content keywords

Table B.3 Table B.4 Table B.5 Table B.6 Table B.7 Table B.8 Table B.9 Table B.10 Table B.11

content identifier keywords parameter identifier keywords tidal surface identifier keywords gravity reduction method identifier keywords unit identifier keywords and ratio to SI standard unit time function identifier keywords attributes required by time functions interpolation method identifier keywords uncertainty measure identifier keywords

B.4 citation keywords

Table B.12

example citation and responsible party attributes from ISO 19115-1

B.5 mapping GGXF to netCDF

Table B.13 Table B.14 Table B.15 Table B.16

categories for netCDF attribute mapping GGXF file header attributes to netCDF variables ggxfGroup header attributes to netCDF variables GGXF grid header attributes to netCDF variables

B.6 external grid files

Table B.17

definitions for optional external simple text file

To propose an extension to the GGXF Conventions submit a change request to the OGC, for attention of the CRS SWG.

OGC 22-051r7 GGXF v1.0

Table B.1 — GGXF conventions: keywords GGXF keyword 1CED

GGXF keyword

Defined in Table

degree

B.2 table B.7

1CEE

B.3 table B.11 B.3 table B.11

depthOffset

1CEP

B.3 table B.11

depthOffsetUncertainty

B.2 table B.4 B.2 table B.4

1DRMS

B.3 table B.11

deviationEast

B.2 table B.4

1SE

B.3 table B.11

deviationEastUncertainty

B.2 table B.4

1SEP

B.3 table B.11

deviationNorth

B.2 table B.4

2CED

B.3 table B.11

deviationNorthUncertainty

B.2 table B.4

2CEE

B.3 table B.11

deviationsOfTheVertical

B.2 table B.3

2CEP

B.3 table B.11

digitalObjectIdentifier

2DRMS

B.3 table B.11

displacementEast

B.2 table B.2 B.2 table B.4

2SE

B.3 table B.11

displacementEastUncertainty

B.2 table B.4

3SE

B.3 table B.11

displacementHorizontalUncertainty

B.2 table B.4

abstract

B.2 table B.2

displacementNorth

B.2 table B.4

affineCoeffs

B.2 table B.2

displacementNorthUncertainty

B.2 table B.4

AiryIsostatic

displacementUp

B.2 table B.4

arc-minute

B.2 table B.6 B.2 table B.7

displacementUpUncertainty

B.2 table B.4

arc-second

B.2 table B.7

eastBoundLongitude

bicubic

B.2 table B.10

eastingOffset

B.2 table B.2 B.2 table B.4

bilinear

B.2 table B.10

eastingOffsetUncertainty

B.2 table B.4

biquadratic

B.2 table B.10

ellipsoidalHeightOffset

B.2 table B.4

boundingBox

B.2 table B.2

ellipsoidalHeightOffsetUncertainty

B.2 table B.4

boundingPolygon

B.2 table B.2

endDate

B.2 table B.2

Cartesian2dOffsets

B.2 table B.3

endEpoch

B.2 table B.2

Cartesian3dOffsets

B.2 table B.3

epoch

B.2 table B.2

B.2 table B.5

eventDate

B.2 table B.2

centimetre

eventEpoch

B.2 table B.2

checkPoints

B.2 table B.7 B.2 table B.2

exponential

childGrids

B.2 table B.2

extentDescription

B.2 table B.8 B.2 table B.2

citation

B.2 table B.10

extentTemporal

B.2 table B.2

cm/yr

B.2 table B.7

extentVertical

B.2 table B.2

comma

extentVerticalCrsWkt

B.2 table B.2

comment

B.6 table B.17 B.2 table B.2

extentVerticalMaximum

B.2 table B.2

constantParameters

B.2 table B.2

extentVerticalMinimum

B.2 table B.2

content

B.2 table B.2

filename

B.2 table B.2

contentApplicabilityExtent

B.2 table B.2

foot

B.2 table B.7

contentBox

B.2 table B.2

freeAir

cyclic

frequency

data

B.2 table B.8 B.2 table B.2

B.2 table B.6 B.2 table B.2

functionReferenceDate

B.2 table B.2

dataSource

B.2 table B.2

functionReferenceEpoch

B.2 table B.2

dataSourceType

B.2 table B.2

functionType

B.2 table B.2

date

B.2 table B.2

geocentricTranslations

deformationModel

B.2 table B.3

geocentricXOffset

B.2 table B.3 B.2 table B.4

OGC 22-051r7 GGXF v1.0

GGXF keyword

Defined in Table

geocentricXOffsetUncertainty

B.2 table B.4

interpolationMethod

B.2 table B.2

geocentricYOffset

B.2 table B.4

interpolationMethodCitation

B.2 table B.2

geocentricYOffsetUncertainty

B.2 table B.4

ISLW

geocentricZOffset

B.2 table B.4

jNodeCount

B.2 table B.5 B.2 table B.2

geocentricZOffsetUncertainty

B.2 table B.4

kNodeCount

B.2 table B.2

geographic2dOffsets

B.2 table B.3

LAT

geographic3dOffsets

B.2 table B.3

latitudeOffset

B.2 table B.5 B.2 table B.4

geoidHeight

B.2 table B.4

latitudeOffsetUncertainty

B.2 table B.4

geoidHeightUncertainty

B.2 table B.4

license

B.2 table B.2

geoidModel

B.2 table B.3

licenseURL

B.2 table B.2

ggxfGroupName

linear

B.2 table B.8

ggxfGroups

B.2 table B.2 B.2 table B.2

LLWLT

B.2 table B.5

ggxfVersion

B.2 table B.2

logBase10

B.2 table B.8

ggxf-csv

B.6 table B.17

logBaseE

gravity

longitudeOffset

gravityAnomaly

B.2 table B.3 B.2 table B.4

B.2 table B.8 B.2 table B.4

longitudeOffsetUncertainty

B.2 table B.4

gravityAnomalyUncertainty

B.2 table B.4

gravityDisturbance

B.2 table B.4

m/s

B.2 table B.5 B.2 table B.7

gravityDisturbanceUncertainty

B.2 table B.4

m/yr

B.2 table B.7

gravityFormula

B.2 table B.2

mas/yr

B.2 table B.7

gravityFormulaReferenceEllipsoid

B.2 table B.2

metre

B.2 table B.7

gravityReductionMethod

B.2 table B.2

MHHW

B.2 table B.5

gravityReductionModelType

B.2 table B.2

MHW

B.2 table B.5

gravityReferenceFrame

B.2 table B.2

MHWST

B.2 table B.5

gridFilename

B.2 table B.2

milliarc-second

B.2 table B.7

gridName

B.2 table B.2

milligal

B.2 table B.7

gridParameters

B.2 table B.2

millimetre

B.2 table B.7

gridPriority

B.2 table B.2

missing_value

grids

B.2 table B.2

MLLW

B.2 table B.2 B.2 table B.5

groupAdditionMethod

B.2 table B.2

MLLWST

B.2 table B.5

HAT

MLW

B.2 table B.5

heightOffset

B.2 table B.5 B.2 table B.4

MLWST

B.2 table B.5

heightOffsetUncertainty

B.2 table B.4

mm/yr

B.2 table B.7

HHWLT

B.2 table B.4

MSL

B.2 table B.5

B.2 table B.4

noDataFlag

hydroidHeight

B.2 table B.4

nodeDepth

B.2 table B.2 B.2 table B.4

hydroidHeightUncertainty

B.2 table B.4

nodeEasting

B.2 table B.4

hydroidModel

B.2 table B.3

nodeEllipsoidalHeight

B.2 table B.4

hyperbolicTangent

B.2 table B.8

nodeGeocentricX

B.2 table B.4

incompleteBouguer

nodeGeocentricY

B.2 table B.4

iNodeCount

B.2 table B.6 B.2 table B.2

nodeGeocentricZ

B.2 table B.4

interpolationCoordinateEpoch

B.2 table B.2

nodeHeight

B.2 table B.4

interpolationCrsCoordinates

B.2 table B.2

nodeLatitude

B.2 table B.4

interpolationCrsWkt

B.2 table B.2

nodeLongitude

B.2 table B.4

OGC 22-051r7 GGXF v1.0

GGXF keyword

Defined in Table

nodeNorthing

B.2 table B.4

startDate

B.2 table B.2

nodeSouthing

B.2 table B.4

startEpoch

B.2 table B.2

nodeWesting

B.2 table B.4

step

B.2 table B.8

noInterpolation

B.2 table B.10

tab

B.6 table B.17

northBoundLatitude

targetCoordinateEpoch

northingOffset

B.2 table B.2 B.2 table B.4

targetCrsCoordinates

B.2 table B.2 B.2 table B.2

northingOffsetUncertainty

B.2 table B.4

targetCrsWkt

B.2 table B.2

operationAccuracy

B.2 table B.2

tidalSurface

B.2 table B.2

parameterCheckValues

B.2 table B.2

timeConstant

B.2 table B.2

parameterMaximumValue

B.2 table B.2

timeFunctions

B.2 table B.2

parameterMinimumValue

B.2 table B.2

title

B.2 table B.2

parameterName

B.2 table B.2

tricubic

B.2 table B.10

parameters

B.2 table B.2

trilinear

parameterSet

B.2 table B.2

uncertaintyMeasure

B.2 table B.10 B.2 table B.2

parameterValue

B.2 table B.2

unitName

B.2 table B.2

ppb

B.2 table B.7

unitSiRatio

B.2 table B.2

ppb/yr

B.2 table B.7

unitType

B.2 table B.2

ppm

B.2 table B.7

unity

B.2 table B.7

ppm/yr

B.2 table B.7

unity/s

B.2 table B.7

PrattIsostatic

B.2 table B.6

userDefinedMethodExample

B.2 table B.2

producerDefinedContent

userDefinedMethodFormula

B.2 table B.2

producerDefinedContentCitation

B.2 table B.3 B.2 table B.2

userDefinedMethodFormulaCitation

B.2 table B.2

publicationDate

B.2 table B.2

velocityEast

B.2 table B.4

quadratic

velocityEastUncertainty

B.2 table B.4

radian

B.2 table B.8 B.2 table B.7

velocityGrid

rad/s

B.2 table B.7

velocityNorth

B.2 table B.3 B.2 table B.4

ramp

B.2 table B.8

velocityNorthUncertainty

B.2 table B.4

refinedBouguer

B.2 table B.6

velocityUp

B.2 table B.4

RMSE

B.2 table B.11

velocityUpUncertainty

B.2 table B.4

scaleFactor

B.2 table B.2

velocityX

B.2 table B.4

second

B.2 table B.7

velocityXUncertainty

B.2 table B.4

separator

B.6 table B.17

velocityY

B.2 table B.4

simpleBouguer

velocityYUncertainty

B.2 table B.4

sourceCoordinateEpoch

B.2 table B.6 B.2 table B.2

velocityZ

B.2 table B.4

sourceCrsAxis

B.2 table B.2

velocityZUncertainty

B.2 table B.4

sourceCrsCoordinates

B.2 table B.2

version

B.2 table B.2

sourceCrsWkt

B.2 table B.2

verticalOffsets

B.2 table B.3

southBoundLatitude

B.2 table B.2

westBoundLongitude

southingOffset

B.2 table B.4

westingOffset

B.2 table B.2 B.2 table B.4

southingOffsetUncertainty

B.2 table B.4

westingOffsetUncertainty

B.2 table B.4

space

B.6 table B.17

year

B.2 table B.7

OGC 22-051r7 GGXF v1.0

B.2 GGXF Conventions: principal keywords Table B.2 — GGXF conventions: header attribute identifier Attribute identifier (keyword)

Definition

Data type

Domain (valid values)

abstract

Brief narrative summary of content of the GGXF file or ggxfGroup.

characterString

affineCoeffs

Ordered list of coefficients A0, A1, A2, B0, B1 and B2 of the 2D affine parametric transformation used to convert the grid indices to the Interpolation CRS coordinates and vice versa. For a 3D grid the order in the sequence of coefficients shall be A0, A1, A2, A3, B0, B1, B2, B3, C0, C1, C2 and C3. Refer to clause 5.6.

sequence

boundingBox

Geographic bounding box describing an extent through keys southBoundLatitude, westBoundLongitude, northBoundLatitude and eastBoundLongitude.

set

southBoundLatitude westBoundLongitude northBoundLatitude eastBoundLongitude

boundingPolygon

List of points given in geographic (latitude longitude) coordinates describing an extent using the simple features geometry of OGC Implementation Standard 06-103r4, Simple Features Access ― Part 1: Common Architecture. (ISO 19125-1), in particular through exterior linear ring(s) and optionally (for excluded enclaves) interior linear rings. For each ring the final vertex shall be the same as the first vertex.

characterString

Well-known text (WKT) syntax for geometry as defined in OGC Implementation Standard 06103r4 (ISO 19125-1), Simple features.

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition

Data type

Domain (valid values)

checkPoints

Keyword in a GGXF file header to indicate the start of list of test data included to assist file users verify their reading of data at grid nodes or interpolated points. Each check point shall include either interpolationCrsCoordinates or sourceCrsCoordinates. When the GGXF file content is used in coordinate operations the check point must include sourceCrsCoordinates and should also include targetCrsCoordinates. A check point may also include parameterCheckValues.

set

childGrids

Keyword in a YAML grid header to indicate the start of list of child grids contained within a parent grid.

set

comment

Free-text comment that may be included in a file header, ggxfGroup header or grid header block.

characterString

constantParameters

Keyword in a ggxfGroup header to indicate the start of a list of parameter identifiers for parameters in the ggxfGroup that have constant values. Each item of the list shall have two attributes, parameterName and parameterValue.

set

parameterName parameterValue

content

Identification of the content of the GGXF file. For data used in coordinate transformations given through a cryptic description of the coordinate operation method which utilises the data in the file.

characterString

Table B.3 — GGXF conventions: content identifier

contentApplicabilityExtent

Keyword in a GGXF file header to indicate the start of a list of extents of the technical and legal applicability of the file content. Content applicability extent may differ from the extent of the file or ggxfGroup content which is described through contentBox. contentApplicabilityExtent shall have two attributes, extentDescription and boundingBox. Optionally this list may be extended to include boundingPolygon, extentTemporal and extentVertical.

set

boundingBox boundingPolygon extentDescription extentTemporal extentVertical

contentBox

Geographic bounding box describing the extent of the ggxfGroup or grid content through boundingBox. Used when the interpolation CRS is not geographic. See also contentApplicabilityExtent.

set

boundingBox

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition

Data type

Domain (valid values)

data

Keyword in a GGXF YAML text file indicating the array of grid parameter values.

sequence

dataSource

Keyword in a GGXF YAML text file grid definition indicating key-value pairs identifying an external file containing the grid data.

set

dataSourceType

characterString

Table B.17 — GGXF conventions: external grid file format

dateTime

RFC 3339, Date and Time on the Internet.

dataSource must have one attribute dataSourceType. If the dataSourceType is ggxf-csv then dataSource must include attributes gridFilename and separator. Other user-specific attributes are permitted. They must be different to any keywords in these Conventions. These are implementation specific and not part of the GGXF Conventions. Note: dataSource is not valid in a GGXF binary file which must contain all header and grid data. dataSourceType

Identifier for the type of external file referenced in a GGXF YAML text file through dataSource. This Standard supports one value for this attribute, ggxf-csv; any other user-defined identifier is permitted but is not part of these Conventions.

date

Instant in time given as a date/time data type with syntax in conformance with the RFC 3339 profile of the ISO 8601-1 extended format.

ISO 8601-1, Representation of date and time.

EXAMPLE 2017-03-25. Note: GGXF implementations are not required to support the extensions defined in ISO 8601 part 2, extensions. The 'extensions' of ISO 8601-2 should not to be confused with the 'extended format' of ISO 8601-1. digitalObjectIdentifier

Digital identifier (DOI) for the model described by the GGXF gridded data compliant with the requirements of ISO 26234.

characterString

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition

Data type

Domain (valid values)

Discovery metadata describing the eastern longitude of a geographic bounding box (contentApplicabilityExtent and contentBox), expressed in decimal degrees (positive east) in the range -180 =< λ =< 180. If the geographic bounding box crosses the 180° meridian then eastBoundLongitude < westBoundLongitude, else eastBoundLongitude > westBoundLongitude.

real

endDate

date at the end of a time period. For temporal extent if end date is omitted the temporal extent includes all times at and after the temporal extent startDate. For a deformation model, the time function has a constant value at and after this time.

dateTime

endDate > startDate

endEpoch

epoch at the end of a time period. For a deformation model, the time function has a constant value at and after this time.

real

>0 endEpoch > startEpoch

epoch

Instant in time expressed in the Gregorian calendar as a decimal year.

real

eastBoundLongitude

-180 =< eastBoundLongitude =< 180 eastBoundLongitude ≠ westBoundLongitude

EXAMPLE 2017-03-25 in the Gregorian calendar is epoch 2017.23. eventDate

date used as parameter used in a deformation model the time function.

dateTime

eventEpoch

epoch used as a parameter in a deformation model the time function.

real

extentDescription

Discovery metadata textual description of the geographic, vertical and temporal extents of the content of the GGXF file.

characterString

extentTemporal

Discovery metadata describing the temporal extent of the applicability of file content, expressed through startDate and endDate.

set

Discovery metadata describing the vertical extent of the applicability of file content, expressed through extentVerticalMaximum, extentVerticalMinimum and extentVerticalCrsWKT.

set

extentVertical

startDate, endDate {count(startDate + endDate)≥1} extentVerticalMaximum, extentVerticalMinimum, extentVerticalCrsWkt

OGC 22-051r7 GGXF v1.0

Definition

Data type

Domain (valid values)

extentVerticalCrsWkt

Description in well-known text conformant to OGC 18-010 of the vertical coordinate reference system to which the values of extentVerticalMaximum and extentVerticalMinimum are referenced.

characterString

OGC 18-010, Well-known text representation of coordinate reference systems.

extentVerticalMaximum

Maximum vertical extent for the GGXF file content. Whether this is a height or a depth, and its units, are defined through extentVerticalCrsWkt.

real

extentVerticalMaximum > extentVerticalMinimum

extentVerticalMinimum

Minimum vertical extent for the GGXF file content. Whether this is a height or a depth, and its units, are defined through extentVerticalCrsWkt.

real

extentVerticalMinimum < extentVerticalMaximum

filename

Name and extension of a GGXF file.

characterString

It is required that the extension for GGXF text files be ".yaml" and for GGXF binary files the extension be ".ggxf"

frequency

Number of cycles per year of a deformation cyclic time function.

real

functionReferenceDate

Date at which a deformation time function has value zero. A constant value may be added to a time function to set it to zero at this date. Some deformation time function types require a reference date for their definition. Each time function using a reference date has its own date; deformation time functions within a single ggxfGroup may have different reference dates.

dateTime

functionReferenceEpoch

Epoch at which a deformation time function has value zero. A constant value may be added to a time function to set it to zero at this epoch. Some deformation time function types require a reference epoch for their definition. Each time function using a reference epoch has its own epoch; deformation time functions within a single ggxfGroup may have different reference epochs.

real

functionType

GGXF identifier of the type of deformation time function.

characterString

Attribute identifier (keyword)

Table B.8 — GGXF conventions: time function identifier

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition

Data type

Domain (valid values)

ggxfGroupName

Identifier which is unique within the GGXF file for this ggxfGroup.

characterString

Valid Unicode identifier, unique within the GGXF file

ggxfGroups

Keyword in a GGXF file header to indicate the start of a list of ggxfGroups contained within the file.

sequence

ggxfGroups

ggxfVersion

Version of the GGXF format for the file.

real

gravityFormula

Formula used to compute the gravity anomaly or gravity disturbance. The suffix '(height)' indicates that the height dependent version of the formula was used. The formulas are based on a particular ellipsoid which is specified through gravityFormulaReferenceEllipsoid.

characterString

International Gravity Formula 1930 International Gravity Formula 1930 (height) International Gravity Formula 1967 International Gravity Formula 1967 (height) International Gravity Formula 1980, International Gravity Formula 1980 (height) Somigliana gravity formula WELMEC gravity formula WGS 84 Ellipsoidal Gravity Formula WGS 84 Ellipsoidal Gravity Formula (height)

Note: References for the formula are given in the Bibliography.

gravityFormulaReferenceEllipsoid

Name of the ellipsoid used with gravityFormula. If the ellipsoid is non-standard or is a sphere, also include its defining parameters.

characterString

gravityReductionMethod

GGXF identifier of the method used to reduce gravity data.

characterString

Table B.6 — GGXF conventions: gravity reduction method identifier

gravityReductionModelType

Model used to compute the gravity anomaly or gravity disturbance.

characterString

planar spherical

gravityReferenceFrame

Name of the realization of the gravity reference system. EXAMPLE IGSN71

characterString

gridFilename

Identifier of an external file containing the grid data referenced in a GGXF text file through dataSource. Typically this is a file name or url.

characterString

gridName

Identifier for a grid which is unique within the grids in a GGXF file.

characterString

Valid Unicode identifier, unique within the GGXF file

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword) gridParameters

Definition Ordered list of the parameters represented in the tuple of values at each node of each grid in the ggxfGroup. Each element of the list shall match the parameterName of a parameter defined in the file header parameters attribute.

Data type

Domain (valid values)

orderedSet

Required only when a subset of the parameters declared in the file header are present at nodes in the grid(s) in the ggxfGroup, or when the order of parameters at the nodes differs from the order defined in the file header. When gridParameters is not specified, nodes throughout the ggxfGroup have all parameters in the order specified in the parameters file header attribute. Note: Attributes for each parameter are defined in the file header through parameter. gridPriority

Attribute used to indicate priority of intersecting sibling grids. Grid priority only applies between intersecting siblings. Grid priority is required for all intersecting sibling grids. All intersecting root grids in a ggxfGroup and all intersecting sibling child grids in a nested structure are intersecting sibling grids.

integer

grids

Keyword in a YAML ggxfGroup header to indicate the start of list of grids contained within the ggxfGroup.

sequence

groupAdditionMethod

Optional attribute of a parameter definition specifying how parameter values are combined if they are defined in more than one ggxfGroup.

characterString

interpolationCoordinateEpoch

Coordinate epoch of interpolationCrsCoordinates.

real

interpolationCrsCoordinates

Tuple of coordinates at a check point referenced to the interpolation CRS defined in the GGXF file header. The sequence of coordinates shall be that defined for the CRS in the file header.

sequence

Unique within a set of intersecting siblings.

addition (the default) rootMeanSquare

If the interpolation CRS coordinates have time dependency they shall be accompanied by an interpolationCoordinateEpoch attribute.

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition

Data type

Domain (valid values)

interpolationCrsWkt

Description of the coordinate reference system to which grid nodes in the GGXF file are referenced, given in wellknown text conformant to OGC 18-010.

characterString

OGC 18-010, Well-known text representation of coordinate reference systems.

interpolationMethod

Identifier of interpolation algorithm recommended by data provider for interpolating data values at locations not coincident with grid nodes.

characterString

Table B.10 — GGXF conventions: interpolation method identifier

interpolationMethodCitation

Reference for interpolation algorithm recommended by data provider for interpolating data values at locations not coincident with grid nodes.

characterString

ISO 19115-1, Metadata fundamentals, CI_Citation

iNodeCount

Number of nodes on the i-axis of the grid. The maximum index (equal to the number of inter-node intervals) on this axis is (iNodeCount - 1).

integer

jNodeCount

Number of nodes on the j-axis of the grid. The maximum index (equal to the number of inter-node intervals) on this axis is (jNodeCount - 1).

integer

kNodeCount

Number of nodes on the k-axis of the grid. The maximum index (equal to the number of inter-node intervals) on this axis is (kNodeCount - 1).

integer

license

License under which the file is distributed.

characterString

licenseURL

URL of the license under which the file is distributed. If the text in the file does not agree with the URL reference text the text in the file shall take precedence.

characterString

missing_value

Attribute of a netCDF variable defining the value that indicates missing or undefined data in the variable. Must be either larger than the largest actual packed data value or smaller than the smallest actual packed data value in the variable.

real

Note: not used in a GGXF YAML file - see noDataFlag. noDataFlag

Attribute of a parameter in a GGXF file to indicate missing or undefined data. Must be a value that cannot be mistaken for a genuine parameter value.

real

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition Discovery metadata describing the northern latitude of a geographic bounding box (contentApplicabilityExtent and contentBox), expressed in decimal degrees (positive north) in the range -90 =< φ =< 90 and northBoundLatitude > southBoundLatitude.

real

operationAccuracy

Nominal accuracy of the coordinate operation described through the file contents, expressed in metres. Gives position error estimates for target coordinates of this coordinate operation, assuming no errors in source coordinates. This is a single value for the complete file content. Uncertainty estimates throughout the grid may be given as separate parameters.

real

parameterCheckValues

Value of a parameter at a checkPoint. The parameter shall be identified through its parameterName.

real

northBoundLatitude

Domain (valid values)

Data type

-90 =< northBoundLatitude =< 90 northBoundLatitude > southBoundLatitude

>= 0

Note: not to be confused with parameterValue. parameterMaximumValue

The maximum value of this parameter in the GGXF file.

real

parameterMinimumValue

The minimum value of this parameter in the GGXF file.

real

parameterName

GGXF identifier of the parameter.

characterString

Table B.4 — GGXF conventions: grid node parameter identifier

parameters

Keyword in a GGXF file header to indicate the start of an ordered list of all parameters at nodes in the GGXF file. For GGXF files with multiple ggxfGroups, different subsets of the listed parameters may be present in different ggxfGroups.

orderedSet

Each parameter shall have three attributes: parameterName, its unitName and the unitSiRatio. When a parameter is used in a coordinate operation it shall have one further attribute, soureCrsAxis.

When multiple parameters are listed, the sequence in which they are given shall match the sequence of parameter values at grid nodes throughout the GGXF file except where the sequence is overridden by a gridParameters attribute within a ggxfGroup.

When a parameter is missing a value at any grid node in the GGXF file, the parameter shall have a noDataFlag attribute. Optionally this list of parameter attributes may be extended to include parameterMinimumValue, parameterMaximumValue, uncertaintyMeasure, parameterSet and groupAdditionMethod.

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition

Data type

parameterSet

Name of the variable in which the parameter is stored in the GGXF netCDF file. If parameterSet is omitted the parameter is assumed to be stored in a 1D array with the same name as the parameterName.

characterString

parameterValue

Constant value of this parameter in the ggxfGroup.

real

Domain (valid values)

Note: Not to be confused with parameterCheckValues. producerDefinedContentCitation

Citation for content type not explicitly catered for through these Conventions. The citation should inform users what the file content is and how it should be used.

characterString

publicationDate

Date when the data in the file was issued.

dateTime

scaleFactor

Scalar value by which deformation time functions are multiplied. Mainly applicable where the deformation time function includes multiple components which are scaled relative to each other.

real

ISO 19115-1, Metadata fundamentals, CI_Citation

Note: Not to be confused with the map projection parameter or netCDF attribute having the same name. sourceCoordinateEpoch

Coordinate epoch of sourceCrsCoordinates.

real

sourceCrsAxis

Zero-based sequence number of the axis in the source CRS to which a parameter is to be applied in a coordinate operation. Examples: (i) in a GGXF file supporting a coordinate operation applying latitudeOffset and longitudeOffset to a source CRS in which the first axis is geodetic latitude and the second axis is geodetic longitude, the values for sourceCrsAxis for the latitudeOffset and longitudeOffset parameters are 0 and 1 respectively. (ii) in a GGXF file supporting a coordinate operation applying geoidHeight to a source CRS in which the first axis is geodetic latitude, the second axis is geodetic longitude and the third axis is ellipsoidal height, the value of the attribute sourceCrsAxis for the parameter geoidHeight is 2.

integer

> -1

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition

Domain (valid values)

Data type

sourceCrsCoordinates

Tuple of coordinates at a check point referenced to the source CRS defined in the GGXF file header. If no source CRS is declared the coordinates(s) are referenced to the interpolation CRS. The sequence of coordinates shall be that defined for the CRS in the file header.

sequence

If the source CRS coordinates have time dependency they shall be accompanied by a sourceCoordinateEpoch attribute.

sourceCrsWkt

Description of the coordinate reference system to which parameter values interpolated from the GGXF grid are applied in the coordinate operation described through the file, given in well-known text conformant to OGC 18-010.

characterString

OGC 18-010, Well-known text representation of coordinate reference systems.

southBoundLatitude

Discovery metadata describing the southern latitude of a geographic bounding box (contentApplicabilityExtent and contentBox), expressed in decimal degrees (positive north) in the range -90 =< φ =< 90 and southBoundLatitude < northBoundLatitude.

real

-90 =< southBoundLatitude =< 90

startDate

date at the start of a time period. For temporal extent, if start date is omitted the temporal extent includes all times before and up to the temporal extent endDate. For a deformation model, the time function has a constant value before and up to this time.

dateTime

startDate < endDate

startEpoch

epoch at the start of a time period. For a deformation model, the time function has a constant value before and up to this time.

real

targetCoordinateEpoch

Coordinate epoch of targetCrsCoordinates.

real

targetCrsCoordinates

The tuple of coordinates at a check point referenced to the target CRS defined in the GGXF file header. The sequence of coordinates shall be that defined for the CRS in the file header.

sequence

If the target CRS coordinates have time dependency they shall be accompanied by a targetCoordinateEpoch attribute.

targetCrsWkt

Description of the coordinate reference system that is the target in the coordinate operation described through the file given in well-known text conformant to OGC 18-010.

characterString

OGC 18-010, Well-known text representation of coordinate reference systems.

tidalSurface

Surface derived from a hydroidModel to which depths are referenced.

characterString

Table B.5 — GGXF conventions: tidal surface identifier

southBoundLatitude < northBoundLatitude

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition

Data type

Domain (valid values)

timeConstant

Time duration expressed in years used in the definition of some types of deformation time function.

real

timeFunctions

Keyword in a ggxfGroup header to indicate the start of list of time functions applied to grid data within the ggxfGroup. Each time function shall have a functionType and one or more additional attributes. The time functions are summed to calculate the scale factor applying to a ggxfGroup at a given date/epoch.

sequence

title

Name by which the dataset is known

characterString

uncertaintyMeasure

Statistical probability measure of an uncertainty parameter.

characterString

Table B.11 — GGXF conventions: uncertainty measure identifier

unitName

Identifier of the unit in which a parameter is given.

characterString

Table B.7 — GGXF conventions: unit identifier

unitSiRatio

Ratio of a unit to the SI base unit of that unit type, given as units per SI base unit.

real

Table B.7 — GGXF conventions: unit identifier

Table B.8 — GGXF conventions: deformation time function identifier

Examples: an arc-second = ((pi/180) / 3600) has a unit SI ratio of 4.84813681109536E-06 radian. A foot has a unit SI ratio of 0.3048 metre. Parts per million has a unit SI ratio of 1.0E-6 unity. If unitSiRatio is given for a unit included in Annex B.6 of these Conventions and the SI ratio values differ, the value in these conventions takes precedence. userDefinedMethodExample

Example of input and output from a user-defined operation method used to apply data in the GGXF file.

characterString

userDefinedMethodFormula

Formula (text string) for a user-defined transformation or point motion operation method used to apply data in the GGXF file.

characterString

userDefinedMethodFormulaCitation

Citation for formula(s) for a user-defined transformation or point motion operation method used to apply data in the GGXF file.

characterString

ISO 19115-1, Metadata fundamentals, CI_Citation

OGC 22-051r7 GGXF v1.0

Attribute identifier (keyword)

Definition

Data type

version

Version identifier for the data.

characterString

westBoundLongitude

Discovery metadata describing the western longitude of a geographic bounding box (contentApplicabilityExtent and contentBox), expressed in decimal degrees (positive east) in the range -180 =< λ =< 180. If the geographic bounding box crosses the 180° meridian then westBoundLongitude > eastBoundLongitude, else westBoundLongitude < eastBoundLongitude.

real

Domain (valid values) -180 =< westBoundLongitude =< 180 westBoundLongitude ≠ eastBoundLongitude

OGC 22-051r7 GGXF v1.0

B.3 GGXF Conventions: keywords for content attributes For the header attribute content (refer to Table B.2), the GGXF conventional identifier in Table B.3 should be used. For each content type, those parameters which are mandatory are given in this table and defined in Table B.4. These mandatory parameters are listed in alphabetical order. In the GGXF file the order is not constrained but whatever the order is it must be declared in the file or ggxfGroup header. For each of these parameters, a corresponding uncertainty parameter is optional. For example, if the content type requires a latitudeOffset parameter, then it also supports an optional latitudeOffsetUncertainty parameter. Refer to Annex C for information about offsets. Table B.3 — GGXF conventions: content identifier

Definition

Mandatory parameters

Differences in coordinates between two 2-dimensional CRSs having Cartesian coordinates. Interpolated offsets are parameters to be added to the coordinates referenced to the source coordinate reference system:

Two offsets, these being consistent with the source CRS positive axis directions, for example: eastingOffset northingOffset

File content identifier Cartesian2dOffsets

XT = XS + δX YT = YS + δY Cartesian3dOffsets

Differences in coordinates between two 3-dimensional CRSs having Cartesian coordinates. Interpolated offsets are parameters to be added to the coordinates referenced to the source coordinate reference system:

Three offsets, these being consistent with the source CRS positive axis directions, e.g.,:

XT = XS + δX

YT = YS + δY

heightOffset southingOffset westingOffset

ZT = ZS + δZ Note: use geocentricTranslations when the coordinate reference systems are geodetic with geocentric Cartesian coordinate system. deformationModel

or southingOffset westingOffset

Describes secular and episodic geodynamic motion. The functional model required for use with this version of the GGXF format is given in OGC Abstract Specification Topic 24.

eastingOffset heightOffset northingOffset

Each group of a deformation model must define one or both of the following sets of parameters: displacementEast displacementNorth or displacementUp and/or their uncertainties. When uncertainties are included, displacementHorizontalUncertainty shall not be included if displacementEastUncertainty or displacementNorthUncertainty is included. Each group must include a timeFunctions attribute defining one or more time functions. Refer to Table B.8

OGC 22-051r7 GGXF v1.0

File content identifier

Definition

deviationsOfTheVertical

Deviation of the gravity vector from the ellipsoidal normal, resolved into north and east components. Positive when the downward gravity vector is to the south and west of the ellipsoid normal.

Mandatory parameters deviationEast deviationNorth

Notes: (i) deviation of the vertical is sometimes called deflection of the vertical. The term ‘deviation of the vertical’ is used here, since the term deflection of the vertical could be misinterpreted as including the curvature of the plumbline. (ii) The surface at which the deviation applies can be included in a comment or in the abstract. geocentricTranslations

Differences in coordinates between two 3-dimensional geodetic CRSs having geocentric Cartesian coordinates. Interpolated offsets are parameters to be added to the coordinates referenced to the source coordinate reference system:

geocentricXOffset (δX) geocentricYOffset (δY) geocentricZOffset (δZ)

XT = XS + δX YT = YS + δY ZT = ZS + δZ Note: A specialised form of Cartesian3dOffsets. geographic2dOffsets

Differences in geodetic latitude and geodetic longitude between two geographic CRSs. Interpolated offsets are parameters to be added to the latitude and longitude referenced to the source geographic coordinate reference system:

latitudeOffset (δφ) longitudeOffset (δλ)

φT = φS + δφ λT = λS + δλ geographic3dOffsets

Differences in geodetic latitude, geodetic longitude and ellipsoid height between two geographic CRSs. Interpolated offsets are parameters to be added to the latitude, longitude and ellipsoidal height referenced to the source geographic coordinate reference system:

latitudeOffset (δφ) longitudeOffset (δλ) ellipsoidalHeightOffset (δh)

φT = φS + δφ λT = λS + δλ hT = hS + δh

OGC 22-051r7 GGXF v1.0

Definition

File content identifier geoidModel

Height of a height reference surface above the ellipsoid surface associated with a specified geographic 3D CRS, positive upwards from the reference ellipsoid. In this Standard this content type is used for geoid models, quasigeoid models, and height correction (hybrid) models without distinction. The interpolated offset ('geoid' height, ζ) is a subtractive correction to the ellipsoidal height in the specified (source) geographic coordinate reference system:

Mandatory parameters geoidHeight (ζ)

HT = hS - ζ Notes: (i) Differences in gravity-related height between two vertical CRSs should be described as verticalOffsets. (ii) The type of geoid model can be included in the abstract or in a comment immediately following content type (see example E.2). gravity

Gravity anomaly or gravity disturbance data.

gravityAnomaly, gravityDisturbance A GGXF file containing gravity anomaly or gravity disturbance content must include in the file header the attributes gravityFormula, gravityFormulaReferenceEllipsoid, gravityReductionMethod, gravityReductionModelType and gravityReferenceFrame.

OGC 22-051r7 GGXF v1.0

Definition

File content identifier hydroidModel

Height difference between the ellipsoid surface associated with a specified geographic 3D CRS and an identified tidal surface of a vertical coordinate reference system, positive upwards from the reference ellipsoid. The interpolated offset (height correction) is a subtractive correction to the ellipsoidal height in the specified (source) geographic coordinate reference system:

Mandatory parameters hydroidHeight (C) A GGXF file containing hydroid model content must include an attribute tidalSurface. See Table B.5 for valid tidal surface identifiers.

HT = hS - C Because it is normally applied to a target CRS in the depth domain the height correction model relationship to ellipsoidal height has its sign reversed: DT = C - hS In a marine context depth of the seabed below the tidal surface is derived from observed water depth and observed three-dimensional position including ellipsoidal height, both observations to a common vessel reference point, and the ellipsoid height of the tidal surface interpreted from the hydroid model. D = (Dobs – hobs) + C velocityGrid

Describes secular motion within a specified CRS from a specified coordinate epoch through velocity values. The components into which the velocity is resolved (for example: east, north, up) are described through the tuple of grid node parameters in the ggxfGroup gridParameters attribute or if gridParameters is not defined by the ordered list in the file parameters attribute. See Table B.4.

Two or three parameters. Either velocityEast velocityNorth or velocityEast velocityNorth velocityUp or velocityX velocityY velocityZ

OGC 22-051r7 GGXF v1.0

Definition

Mandatory parameters

Differences in gravity-related height or depth between two vertical CRSs. For source and target CRSs with height coordinate systems the interpolated offset (height difference) is a parameter to be added to the gravity-related height referenced to the source vertical coordinate reference system:

One offset, this being consistent with the source CRS positive axis direction, i.e.,:

File content identifier verticalOffsets

heightOffset (δH) or depthOffset (δD)

HT = HS + δH For source and target CRSs with depth coordinate systems the interpolated offset (depth difference) is a parameter to be added to the depth referenced to the source vertical coordinate reference system: DT = DS + δD producerDefinedContent

Content is not given above.

producerDefinedContentCitation

Producers should provide details of the content including parameters and how they should be treated through a citation. Implementations are not obliged to handle producer-defined content.

The set of parameters at grid nodes is described in ggxfGroup headers as an ordered list in the gridParameters attribute, or if that is not defined by the ordered list in the file header parameters attribute. All grids within the ggxfGroup must have the same set of parameters. GGXF conventional keywords for the identifiers of these parameters are given in Table B.4. Table B.4 — GGXF conventions: grid node parameter identifier

Parameter identifier depthOffset

Definition Parameter to be added to a depth that is referenced to the source vertical CRS to obtain the depth referenced to the target CRS. Note: default unit is that of the source CRS.

depthOffsetUncertainty

Uncertainty estimate of the depthOffset. The measure is described through uncertaintyMeasure.

deviationEast

East-west component (η) of the deviation of the vertical at the Earth's surface, positive eastwards (positive when the plumbline intersects the celestial sphere east of the ellipsoidal normal, i.e., when the downward gravity vector is deviated to the west of the ellipsoid normal). η = (astronomic longitude Λ minus geodetic longitude λ) * cos(geodetic latitude φ).

deviationEastUncertainty

Uncertainty estimate of the deviationEast. The measure is described through uncertaintyMeasure.

OGC 22-051r7 GGXF v1.0

Parameter identifier

Definition

deviationNorth

North-south component (ξ) of the deviation of the vertical at the Earth's surface, positive northwards (positive when the plumbline intersects the celestial sphere north of the ellipsoidal normal, i.e., when the downward gravity vector is deviated to the south of the ellipsoid normal). ξ = (astronomic latitude Φ minus geodetic latitude φ).

deviationNorthUncertainty

Uncertainty estimate of the deviationNorth. The measure is described through uncertaintyMeasure.

displacementEast

Easterly component of a displacement, to be added to the source CRS longitude or easting to obtain the longitude or easting in the target CRS. Note: Default unit is that of the source CRS.

displacementEastUncertainty

Uncertainty estimate of the displacementEast component. The measure is described through uncertaintyMeasure.

displacementHorizontalUncertainty

Single uncertainty estimate covering both displacementEast and displacementNorth components. The measure is described through uncertaintyMeasure.

displacementNorth

Northerly component of a displacement, to be added to the source CRS latitude or northing to obtain the latitude or northing in the target CRS. Note: Default unit is that of the source CRS.

displacementNorthUncertainty

Uncertainty estimate of the displacementNorth component. The measure is described through uncertaintyMeasure.

displacementUp

Upwards component of a displacement, to be added to the source CRS height to obtain the height in the target CRS. Sometimes called vertical displacement. Note: Default unit is that of the source CRS.

displacementUpUncertainty

Uncertainty estimate of the displacementUp. The measure is described through uncertaintyMeasure.

eastingOffset

Parameter to be added to an easting that is referenced to the source CRS to obtain the easting referenced to the target CRS. Note: Default unit is that of the source CRS easting.

eastingOffsetUncertainty

Uncertainty estimate of the eastingOffset. The measure is described through uncertaintyMeasure.

ellipsoidalHeightOffset

Parameter to be added to an ellipsoidal height in the Source CRS to obtain the ellipsoidal height in the Target CRS. Note: Default unit is that of the source CRS ellipsoidal height.

ellipsoidalHeightOffsetUncertainty

Uncertainty estimate of the ellipsoidalHeightOffset. The measure is described through uncertaintyMeasure.

geocentricXOffset

Parameter to be added to a geocentric Cartesian X coordinate that is referenced to the source CRS to obtain a geocentric_X coordinate referenced to the target CRS.

geocentricXOffsetUncertainty

Uncertainty estimate of the geocentricXoffset. The measure is described through uncertaintyMeasure.

geocentricYOffset

Parameter to be added to a geocentric Cartesian Y coordinate that is referenced to the source CRS to obtain a geocentric_Y coordinate referenced to the target CRS.

geocentricYOffsetUncertainty

Uncertainty estimate of the geocentricYoffset. The measure is described through uncertaintyMeasure.

OGC 22-051r7 GGXF v1.0

Parameter identifier

Definition

geocentricZOffset

Parameter to be added to a geocentric Cartesian Z coordinate that is referenced to the source CRS to obtain a geocentric_Z coordinate referenced to the target CRS.

geocentricZOffsetUncertainty

Uncertainty estimate of the geocentricZoffset. The measure is described through uncertaintyMeasure.

geoidHeight

Parameter to be subtracted from an ellipsoidal height that is referenced to the source CRS to obtain a gravity-related height referenced to the target vertical CRS. Note: This attribute does not distinguish between gravimetric geoid, quasi-geoid or hybrid geoid models.

geoidHeightUncertainty

Uncertainty estimate of the geoidHeight. The measure is described through uncertaintyMeasure.

gravityAnomaly

Difference between gravity on the geoid and normal gravity on the surface of the reference ellipsoid for that geocentric latitude. Δg = g - γ. The reference for normal gravity shall be identified through a gravityFormula attribute (Table B.2) given in the file header. The figure of the Earth used in the gravity formula shall be identified through a gravityFormulaReferenceEllipsoid attribute. A gravityReductionMethod attribute (Table B.6) must be included in the file header. The spherical or planar model used in gravity reduction shall be given in the file header through a gravityReductionModelType attribute (Table B.2).

gravityAnomalyUncertainty

Uncertainty estimate of the gravityAnomaly. The measure is described through uncertaintyMeasure.

gravityDisturbance

Difference between gravity at a point (usually on the surface of the Earth) and normal gravity at that point. ΔgP = gP - γP. γP is computed by applying the height-dependent standard gravity formula correction for the ellipsoidal height of the point to the magnitude of normal gravity at the ellipsoid. The reference for normal gravity is identified through a gravityFormula attribute (Table B.2) given in the file header. The figure of the Earth used in the gravity formula shall be identified through a gravityFormulaReferenceEllipsoid attribute. A gravityReductionMethod attribute (Table B.6) must be included in the file header. The spherical or planar model used in gravity reduction is given in the file header through a gravityReductionModelType attribute (Table B.2).

gravityDisturbanceUncertainty

Uncertainty estimate of the gravityDisturbance. The measure is described through uncertaintyMeasure.

heightOffset

Parameter to be added to a gravity-related height that is referenced to the source vertical CRS to obtain a gravity-related height referenced to the target CRS.

heightOffsetUncertainty

Uncertainty estimate of the heightOffset. The measure is described through uncertaintyMeasure.

OGC 22-051r7 GGXF v1.0

Parameter identifier

Definition

hydroidHeight

Parameter to be subtracted from an ellipsoidal height that is referenced to the source CRS to obtain a gravity-related height referenced to the target vertical CRS and tidal datum. The tidal surface should be identified through a tidalSurface attribute (Table B.5) given in the file header.

hydroidHeightUncertainty

Uncertainty estimate of the hydroidHeight. The measure is described through uncertaintyMeasure.

latitudeOffset

Parameter to be added to the source CRS geodetic latitude to obtain the target CRS geodetic latitude. Note: When geodetic latitude is in degrees, latitudeOffset is permitted to be in arc-minutes or arc-seconds.

latitudeOffsetUncertainty

Uncertainty estimate of the latitudeOffset. The measure is described through uncertaintyMeasure.

longitudeOffset

Parameter to be added to the source CRS geodetic longitude to obtain the target CRS geodetic longitude.

longitudeOffsetUncertainty

Uncertainty estimate of the longitudeOffset. The measure is described through uncertaintyMeasure.

nodeDepth

Depth at a node of a grid where the Interpolation CRS is a compound CRS including a vertical component carrying depths. Note: See 5.8.6, including recommendation 7.

nodeEasting

Easting at a node of a grid where the Interpolation CRS is projected. Note: See 5.8.6, including recommendation 7.

nodeEllipsoidalHeight

Ellipsoidal height (geodetic height) at a node of a grid where the Interpolation CRS is geographic 3D. Note: See 5.8.6, including recommendation 7.

nodeGeocentricX

X coordinate at a node of a grid where the Interpolation CRS is geodetic with geocentric Cartesian coordinate system. Note: See 5.8.6, including recommendation 7.

nodeGeocentricY

Y coordinate at a node of a grid where the Interpolation CRS is geodetic with geocentric Cartesian coordinate system. Note: See 5.8.6, including recommendation 7.

nodeGeocentricZ

Z coordinate at a node of a grid where the Interpolation CRS is geodetic with geocentric Cartesian coordinate system. Note: See 5.8.6, including recommendation 7.

nodeHeight

Gravity-related height at a node of a grid where the Interpolation CRS is a compound CRS including a vertical component carrying gravity-related heights. Note: See 5.8.6, including recommendation 7.

nodeLatitude

Geodetic latitude at a node of a grid where the Interpolation CRS is geographic. Note: See 5.8.6, including recommendation 7.

nodeLongitude

Geodetic longitude at a node of a grid where the Interpolation CRS is geographic. Note: See 5.8.6, including recommendation 7.

nodeNorthing

Northing at a node of a grid where the Interpolation CRS is projected. Note: See 5.8.6, including recommendation 7.

OGC 22-051r7 GGXF v1.0

Parameter identifier nodeSouthing

Definition Southing at a node of a grid where the Interpolation CRS is projected. Note: See 5.8.6, including recommendation 7.

nodeWesting

Westing at a node of a grid where the Interpolation CRS is projected. Note: See 5.8.6, including recommendation 7.

northingOffset

Parameter to be added to the source CRS northing to obtain the target CRS northing.

northingOffsetUncertainty

Uncertainty estimate of the northingOffset. The measure is described through uncertaintyMeasure.

southingOffset

Parameter to be added to the source CRS southing to obtain the target CRS southing. Applies to transformations between projected CRSs with an axis positive southwards.

southingOffsetUncertainty

Uncertainty estimate of the southingOffset. The measure is described through uncertaintyMeasure.

velocityEast

Easterly component of the velocity vector at a point.

velocityEastUncertainty

Uncertainty estimate of the velocityEast.

velocityNorth

Northerly component of the velocity vector at a point.

velocityNorthUncertainty

Uncertainty estimate of the velocityNorth.

velocityUp

Up component of the velocity vector at a point.

velocityUpUncertainty

Uncertainty estimate of the velocityUp.

velocityX

Geocentric X component of the velocity vector at a point.

velocityXUncertainty

Uncertainty estimate of the geocentric X velocity (velocityX).

velocityY

Geocentric Y component of the velocity vector at a point.

velocityYUncertainty

Uncertainty estimate of the geocentric Y velocity (velocityY).

velocityZ

Geocentric Z component of the velocity vector at a point.

velocityZUncertainty

Uncertainty estimate of the geocentric Z velocity (velocityZ).

westingOffset

Parameter to be added to the source CRS westing to obtain the target CRS westing. Applies to transformations using Cartesian2Doffsets between projected CRSs with an axis positive westwards.

westingOffsetUncertainty

Uncertainty estimate of the westingOffset.

OGC 22-051r7 GGXF v1.0

When the file content (refer to Table B.3) is hydroidModel, the tidalSurface to which ellipsoidal heights are reduced through applying the hydroid model should be described through the GGXF tidal surface identifier given in Table B.5. The definitions are from the International Hydrographic Organization (IHO). Table B.5 — GGXF conventions: tidal surface identifier

Identifier

Tidal Surface Definition

Chart Datum. The plane of reference to which charted depths and drying heights are related. In tidal areas CD is chosen to show the least depth of water found in any place under ‘normal’ meteorological conditions.

HAT

Highest Astronomical Tide. The highest tide level which can be predicted to occur under average meteorological conditions and under any combination of astronomical conditions.

HHWLT

Higher High Water Large Tide. The average of the highest high waters, one from each of 19 years of observations.

High Water. The highest level reached at a place by the water surface in one tidal cycle. When used on inland (non-tidal) waters it is generally defined as a level which the daily mean water level exceeds less than 5% of the time.

ISLW

Indian Spring Low Water. The level below MSL equal to the sum of the amplitudes of the harmonic constituents M2, S2, K1 and O1. ISLW approximates mean lower low water spring tides (MLLWS).

LAT

Lowest Astronomical Tide. The lowest tide level which can be predicted to occur under average meteorological conditions and under any combination of astronomical conditions.

LLWLT

Lower Low Water Large Tide. The average of the lowest low waters, one from each of 19 years of observations.

Low Water. The lowest level reached by the water surface in one tidal cycle. When used in inland (non-tidal) waters it is generally defined as a level which the daily mean water level would fall below less than 5% of the time.

MHHW

Mean Higher High Water. The average height of the higher high waters at a place over a 19year period.

MHW

Mean High Water. The average height of the high waters at a place over a 19-year period.

MHWST

Mean High Water Spring Tides. The average height of the high waters of spring tides.

MLLW

Mean Lower Low Water. The average height of the lower low waters at a place over a 19year period.

MLLWST

Mean Lower Low Water Spring Tides. The average height of the lower low water spring tides at a place.

MLW

Mean Low Water. The average height of all low waters at a place over a 19-year period.

MLWST

Mean Low Water Spring Tides. The average height of the low waters of spring tides.

MSL

Mean Sea Level. The average height of the surface of the sea at a tide station for all stages of the tide over a 19-year period, usually determined from hourly height readings measured from a fixed predetermined reference level.

OGC 22-051r7 GGXF v1.0

When the file content (refer to Table B.3) is gravity and a parameter (Table B.4) is either gravityAnomaly or gravityDisturbance, the method by which the anomalies are reduced should be described through the GGXF gravity reduction method identifier given in Table B.6. Table B.6 — GGXF conventions: gravity reduction method identifier

Gravity Reduction Method Identifier

Definition

AiryIsostatic

Gravity anomaly or gravity disturbance derived by applying the system of topographic mass compensation defined by the Airy-Heiskanen isostatic reduction method.

freeAir

Gravity anomaly or gravity disturbance derived by adding the vertical gradient of gravity scaled by height to measured surface gravity.

incompleteBouguer

Gravity anomaly or gravity disturbance derived by removing only the Bouguer plate from measured surface gravity.

PrattIsostatic

Gravity anomaly or gravity disturbance derived by applying the system of topographic mass compensation defined by the Pratt-Hayford isostatic reduction method.

refinedBouguer

Gravity anomaly or gravity disturbance derived by removing the Bouguer plate from measured surface gravity, applying the free-air reduction and the terrain correction.

simpleBouguer

Gravity anomaly or gravity disturbance derived by removing the Bouguer plate from measured surface gravity and applying the free-air reduction.

The units in which parameters are given in the GGXF grid is described through an ordered list of unit identifier (unitName) and the ratio of the unit to the SI standard unit for that unit type (unitSiRatio), refer to Table B.2. The inclusion of ratio to the standard SI unit permits the use of units not in the GGXF Conventions. GGXF conventional identifiers for units are given in Table B.7. The GGXF conventional identifier should be used when it is applicable to file content. This list is not exclusive and may be extended using ISO 80000-3, Quantities and units - Part 3: Space and time, or other parts of ISO 80000 as required. Table B.7 — GGXF conventions: unit identifier and ratio to SI standard unit Unit identifier

Definition

SI standard unit

unitSiRatio (Ratio to SI standard unit)

arcminute

Angle unit of one sixtieth (1/60) of a degree.

radian

0.000290888208665722

arcsecond

Angle unit of one sixtieth (1/60) of an arc-minute.

radian

4.84813681109536E-06

centimetre

Length unit of one hundredth (1/100) of a metre.

metre

0.01

cm/yr

Length rate of centimetre per year.

m/s

3.16887651727315E-10

degree

Angle unit of one three hundred and sixtieth (1/360) part of a circle.

radian

0.0174532925199433

foot

Length unit by definition 0.3048 metre exactly. Sometimes referred to as the International foot.

metre

0.3048

Note: other types of foot with different ratio to the metre exist. In GGXF these must not use the four character string 'foot' as their unit identifier.

metre

SI standard unit for length.

metre

1.0

m/s

SI standard unit for length rate, metre per second.

m/s

1.0

OGC 22-051r7 GGXF v1.0

Unit identifier

Definition

SI standard unit

unitSiRatio (Ratio to SI standard unit)

m/yr

Length rate of metre per year.

m/s

3.16887651727315E-08

milliarcsecond

Angle unit of one thousandth (1/1000) of an arcsecond.

radian

4.84813681109536E-09

mas/yr

Angle rate of milliarc-second per year.

rad/s

1.53631468932076E-16

milligal

Acceleration unit of one thousandth (1/1000) of a Gal where 1 Gal = 1 cm/s/s).

m/s2

0.00001

millimetre

Length unit of one thousandth (1/1000) of a metre.

metre

0.001

mm/yr

Length rate of millimetre per year.

m/s

3.16887651727315E-11

ppb

parts per billion. Scale unit of where billion is one thousandth (1/1000) of a million.

unity

0.000000001

ppb/yr

parts per billion per year.

unity/s

3.16887651727315E-17

ppm

Scale unit of parts per million.

unity

0.000001

ppm/yr

Scale rate of parts per million per year.

unity/s

3.16887651727315E-14

radian

SI standard unit for angle.

radian

1.0

rad/s

SI standard unit for angle rate, radian per second.

rad/s

1.0

second

SI standard unit for time.

second

1.0

unity

Standard unit for scale.

unity

1.0

unity/s

Standard unit for scale rate, unity per second.

unity/s

1.0

year

Time unit. In the GGXF conventions it is a fixed duration in seconds as defined by the International Union of Geological Sciences (IUGS) and International Union of Pure and Applied Chemistry (IUPAC). This approximation is adequate for giving unit SI ratios for angle, length and scale rates.

second

31556925.445

Source: Pure and Applied Chemistry, Vol. 83, No. 5, pp. 1159–1162, 2011.

OGC 22-051r7 GGXF v1.0

Deformation model time functions are defined in OGC Abstract Specification Topic 24, Functional Model for Crustal Deformation. In a deformation model GGXF file, each ggxfGroup header defines one or more time functions. The sum of these is applied as a scale factor to all grids within the ggxfGroup. Each time function has a functionType attribute defining the function type and other attributes depending on the function type. GGXF conventional keywords for the time function types are given in Table B.8 and the attributes applicable to each type are summarised in Table B.9. Refer to the crustal deformation functional model specification for each time function formula. Table B.8 — GGXF conventions: deformation time function identifier

Time function identifier

Definition

cyclic

Deformation model time function describing deformation proportional to the sine of elapsed time. A cyclic time function shall have two attributes: either functionReferenceDate or functionReferenceEpoch, and frequency. Additionally, a cyclic time function may have up to three further attributes: scaleFactor, startDate or startEpoch and endDate or endEpoch.

exponential

Deformation model time function describing deformation proportional to the exponential of time elapsed after an event. An exponential time function shall have two attributes: either startDate or startEpoch, and timeConstant. Additionally, an exponential time function may have up to four further attributes: scaleFactor, startDate or startEpoch, endDate or endEpoch, and functionReferenceDate or functionReferenceEpoch.

hyperbolicTangent

Deformation model time function describing deformation proportional to the hyperbolic tangent of time elapsed before or after an event. A hyperbolic tangent time function shall have two attributes: either eventDate or eventEpoch, and timeConstant. Additionally, a hyperbolic tangent time function may have up to four further attributes: scaleFactor, startDate or startEpoch, endDate or endEpoch, and functionReferenceDate or functionReferenceEpoch.

linear

Deformation model time function describing deformation growing proportionally to elapsed time. A linear time function shall have one attribute, either functionReferenceDate or functionReferenceEpoch. Additionally, a linear time function may have up to three further attributes: scaleFactor, startDate or startEpoch , and endDate or endEpoch.

logBaseE

Deformation model time function describing deformation proportional to the natural logarithm (base e) of time elapsed after an event. A natural logarithmic time function shall have two attributes: either eventDate or eventEpoch, and timeConstant. Additionally, a logaritmic time function may have up to four further attributes: scaleFactor, startDate or startEpoch, endDate or endEpoch, and functionReferenceDate or functionReferenceEpoch.

logBase10

Deformation model time function describing deformation proportional to the base 10 logarithm of time elapsed after an event. A base 10 logarithmic time function shall have two attributes: either eventDate or eventEpoch, and timeConstant. Additionally, a base 10 logaritmic time function may have up to four further attributes: scaleFactor, startDate or startEpoch, endDate or endEpoch, and functionReferenceDate or functionReferenceEpoch.

quadratic

Deformation model time function describing deformation growing proportionally to the square of elapsed time. A quadratic time function shall have one attribute: either functionReferenceDate or functionReferenceEpoch. Additionally, a quadratic time function may have up to three further attributes: scaleFactor, startDate or startEpoch and endDate or endEpoch.

OGC 22-051r7 GGXF v1.0

Definition

Time function identifier ramp

Deformation model time function describing deformation growing proportional to elapsed time from a start time to an end time. A ramp time function shall have two attributes: either startDate or startEpoch, and endDate or endEpoch. Additionally, a ramp time function may have up to two further attributes: scaleFactor, and functionReferenceDate or functionReferenceEpoch.

step

Deformation model time function describing an instantaneous change to displacement at an event time. A step time function shall have one attribute, eventDate or eventEpoch. Additionally, a step time function may have up to four further attributes: scaleFactor, startDate or startEpoch, endDate or endEpoch, and functionReferenceDate or functionReferenceEpoch.

Table B.9 — GGXF conventions: attributes required by time functions

√ √ √

? ? ? ? ? ? ?

√ √

? ? ? ? ? ?

scale factor

? ? ? ? ? ? ?

function reference date or epoch

√ √

√

end date or epoch

√ √

√

start date or epoch

√ √

frequency

time constant

√ √

Optional attributes

function reference date or epoch

event date or epoch

√ √ √ √ √ √ √ √ √

end date or epoch

cyclic exponential hyperbolic tangent linear logBaseE logBase10 quadratic ramp step

start date or epoch

Time function identifier (functionType)

function type

Mandatory attributes

? ? ? ? ? ? ? ? ?

For issues associated with calendar arithmetic using dates refer to annex D of OGC Abstract Specification Topic 2, Referencing by coordinates. Recommendation 26

To avoid problems with calendar arithmetic, use epoch rather than date.

For the header attribute interpolationMethod (refer to Table B.2), the interpolation methods given in Table B.10 are frequently encountered in geodetic use and these attribute values should be used where appropriate. The recommended formula are provided through the formula citation. Note that where multiple citations are given, application of their formula may lead to different interpolation results, particularly near the edge of grids. Bilinear and trilinear interpolation methods are unambiguous. This

OGC 22-051r7 GGXF v1.0

list of interpolation methods is not exclusive and may be extended through the use of the interpolation method identifier and name (userDefinedMethodName and userDefinedMethodFormulaCitation). Table B.10 — GGXF conventions: interpolation method identifier

Interpolation method identifier bicubic

bilinear

biquadratic

tricubic trilinear

citation

Description

Example Formula Citation

Cubic polynomial interpolant used for interpolating two variables on a twodimensional rectilinear grid.

Press et al., 2007 [12], pp.136-139

Interpolation of two variables on a rectilinear 2D grid performed using linear interpolation first in one direction, and then again in the other direction.

Press et al., 2007 [12], pp.132-134

Quadratic polynomial interpolant used for interpolating two variables on a twodimensional rectilinear grid.

Smith, 2022 [15]

Cubic polynomial interpolant used for interpolating three variables on a threedimensional rectilinear grid. Linear interpolation of three variables on a three-dimensional rectilinear grid performed using linear interpolation sequentially in each of the three directions. The interpolation method is not included in the GGXF Conventions but is described through a userDefinedMethodFormulaCitation conformant to ISO 19115-1, Metadata fundamentals. Be aware that GGXF file reading software may not handle this!

Lekien and Marsden, 2005 [11]

Russell, 1995 [13]; Shi et al., 2005 [14]. Young and Gregory, 1988 [17], pp.342-343 Russell, 1995 [13] Russell, 1995 [13] Shi et al., 2005 [14]. Arata, 1995 [9] Wagner, 2008 [16] Haynes et al., 2007 [10]

OGC 22-051r7 GGXF v1.0

For the header attribute uncertaintyMeasure (refer to Tables B.2 and B.5), the GGXF identifier in Table B.11 should be used. Measures have been taken from references [4], [5]. Table B.11 — GGXF conventions: uncertainty measure identifier

Uncertainty measure identifier

Definition

One-dimensional Accuracy Indicators 1SE

Standard Error of the mean. 68% probability.

2SE

Twice the Standard Error. 95% probability.

3SE

Three times the Standard Error. 99% probability.

RMSE

Root Mean Square Error. Standard deviation of residuals. 68% probability. Note: Standard deviation (SD) is not a measure of accuracy, but of precision. Standard error of the mean yields a confidence interval, which more correctly expresses accuracy.

Two-dimensional Accuracy Indicators 1CEE

Standard Confidence EllipsE. An ellipse, centred on the mean, whose boundary is expected to include the true value with 39% probability.

2CEE

Standard Confidence EllipsE. An ellipse, centred on the mean, whose boundary is expected to include the true value with 95% probability.

1CEP

Circular Error Probable. The radius of a circle, centred on the mean, whose boundary is expected to include the true value with 50% probability.

2CEP

Circular Error Probable. The radius of a circle, centred on the mean, whose boundary is expected to include the true value with 95% probability.

1DRMS

Distance Root Mean Squared. Square root of the trace of a two-dimensional covariance matrix. 66% probability.

2DRMS

Twice the Distance Root Mean Squared. Square root of the trace of a two-dimensional covariance matrix. 97% probability.

Three-dimensional Accuracy Indicators 1CED

Standard Confidence EllipsoiD . An ellipsoid, centred on the mean, whose boundary is expected to include the true value with 20% probability.

2CED

Standard Confidence EllipsoiD . An ellipsoid, centred on the mean, whose boundary is expected to include the true value with 95% probability.

1SEP

Spherical Error Probable. The radius of a sphere, centred on the mean, whose boundary is expected to include the true value with 50% probability.

OGC 22-051r7 GGXF v1.0

For the header attribute tideSystem (refer to Table B.2), the permanent tide identifiers given in Table B.12 shall be used. These attributes are from the IERS Conventions 2010 chapter 1.1 [2]. Table B.12 — GGXF conventions: permanent tide identifier

Earth tide identifier

Definition

conventionalTideFree

instantaneous geopotential or instantaneous crust position after removal of total tidal effects through the application of conventional Love numbers.

instantaneous

observed geopotential or observed crust location.

meanCrust

conventionalTideFree crust with permanent deformation due to tidal potential restored using conventional Love numbers.

meanTide

zeroTide geopotential with permanent part of the tide-generating potential restored.

tideFree

zeroTide geopotential or meanCrust with permanent deformation produced by the tidal potential removed using the secular or fluid-limit value for the relevant Love number.

zeroTide

conventionalTideFree geopotential with permanent deformation due to tidal potential restored using conventional Love numbers.

B.4 GGXF Conventions: keywords for citation and responsible party attributes The GGXF file header should include metadata giving details of the party responsible for producing the file. The CI_Citation and CI_Responsibility classes from ISO 19115-1 - Metadata fundamentals should be used for this. The attributes from these ISO 19115-1 classes are part of the GGXF Conventions with their UML role names being used as GGXF keywords. The 19115-1 UML diagram is shown in Figure B.1 and selected example attributes in Table B.12. Their use is exemplified in Annex E.

OGC 22-051r7 GGXF v1.0

Figure B.1 - Citation and responsible party information classes from ISO 19115-1 Table B.12 — GGXF conventions: example citation attributes from ISO 19115-1 GGXF keyword

Definition (from ISO 19115-1)

Data Type

city

city of the location

characterString

country

country of the address address line for the location EXAMPLE Street number and name., suite number, etc. location (address) for on-line access using a Uniform Resource Locator/ Uniform Resource Identifier address or similar addressing scheme such as http://www.statkart.no/isotc211 name of the party (individual or organization) In GGXF this is interpreted to be the authority producing the GGXF file. ZIP or other postal code.

characterString

publicationDate

date identifies when the resource was issued.

dateTime

title

name by which the cited information is known.

characterString

deliveryPoint

onlineResourceLinkage

partyName

postalCode

Domain

characterString

Text restricted to URL (see IETF RFC 3986)

characterString

OGC 22-051r7 GGXF v1.0

B.5 GGXF Conventions: mapping of GGXF identifiers to netCDF attributes When GGXF uses a concept that previously has been adopted in netCDF and associated conventions, where possible the GGXF Conventions have adopted the netCDF identifier. However, some netCDF attribute identifiers are insufficiently specific for geodetic purposes and in these cases the GGXF Conventions have defined a different identifier. When implemented in netCDF these GGXF identifiers are changed to the nearest equivalent netCDF attribute name. Annex B.5 describes this mapping. Tables B.14 to B.16 give the mapping to netCDF attributes of GGXF file header, ggxfGroup header and grid header identifiers respectively. In these tables the attributes are given a Category indicating from where the name originates. The Category acronyms used in Tables B.14 to B.16 are given in Table B.13. Note that GGXF uses upperCamelCase for its identifier whilst netCDF favours snake_case. All GGXF Convention identifiers that do not appear in the following Tables B.14 to B.16 are used in netCDF with the GGXF upperCamelCase identifier unchanged. Table B.13. Categories in netCDF attribute mapping Category

Description

acdd

Represented as a netCDF attribute. Attribute name comes from the Attribute Convention for Data Discovery (ACDD).

ggxf

Represented as a netCDF attribute. Attribute name comes from the GGXF Conventions.

netcdf

Represented as a netCDF attribute. Attribute name comes from the netCDF conventions.

dimension

Represented as a netCDF dimension.

directory

Defined by the name of the netCDF group representing the grid.

childGrids

yaml

Child netCDF groups of the group representing the grid.

B.6 GGXF Conventions: external grid file format The GGXF binary file format requires grid data to be accompanied with header data in a single file. The GGXF YAML text file format optionally permits the grid data to be held in an external file referenced from the GGXF YAML file. There is no restriction on the file format that data producers may use for such external grid files. In general, these are not supported by GGXF. An optional very simple text format for

OGC 22-051r7 GGXF v1.0

external grid files which is supported by the GGXF format is defined in Table B.17. It is referenced from a GGXF YAML text file dataSource attribute when dataSourceType = ggxf-csv. Table B.17 — GGXF conventions: external grid file format GGXF identifier

Description

comma

Universal Coded Character Set (UCS) character code U+002C, used as the value separator in a ggxf-csv file.

ggxf-csv

Text file containing one header line followed by one line for each grid node in the row major order specified in req/yaml/gridData. Each line contains one or more values. In the header line the values are the grid node parameter identifiers from the GGXF Conventions (see Table B.4). These values and and their sequence define the parameter values in the subsequent lines. The set of identifiers must include the grid node parameters defined in the ggxfGroup within which the external grid file is referenced. Node coordinate identifiers may be included. The values on each subsequent line are the parameter values at a grid node in the order defined by the header line. Missing parameter values in the grid are identified by the noDataFlag value defined for the parameter in the GGXF file header. Each line must have the same number of values. Values must be separated by the character given through the separator key and optionally may be additionally padded with spaces. Each line is terminated by the line feed (new line) character (U+000A). The line feed may be immediately preceded by a carriage return character (U+000D).

separator

Character used as a value separator in the ggxf-csv text file. Supported values are comma, space and tab. Values are separated by either a single comma or tab (which may be padded with spaces) or by one or more space characters.

space

Universal Coded Character Set (UCS) character code U+0020, used as the value separator in a ggxf-csv file.

tab

Universal Coded Character Set (UCS) code U+0009 (horizontal tabulation), used as the value separator in a ggxf-csv file.

See Annex E.1.3 for examples of the ggxf-csv file format.

OGC 22-051r7 GGXF v1.0

Annex C (informative) Offsets A common source of confusion in coordinate transformations is whether a transformation is defined by the offset of the coordinate axes in which coordinates are defined, or by the consequent change to the coordinates representing a location. These definitions are numerically equal but of opposite sign. Completely separating the content of a grid file from applications that write or read that content is impossible. Consequently, there are constraints on GGXF file content that are set by expectation of the reading application's behaviour. One of these is the sign of the direction in which offsets are applied. Mathematically, if the origin of a one-dimensional coordinate system is shifted along the positive axis and placed at a point with ordinate A, then the transformation formula is: Xnew = Xold – A However, it is common practice in coordinate reference system transformations to apply the shift as an addition, with the sign of the shift parameter value having been suitably reversed to compensate for the practice. Hence transformations allow calculation of coordinates in the target system by adding a correction parameter to the coordinate values of the point in the source system: Xt = Xs + A where Xs and Xt are the values of the coordinates in the source and target coordinate systems and A is the value of the transformation parameter to transform source coordinate reference system coordinate to target coordinate reference system coordinate. In GGXF, offsets are additive. Offset methods are reversible. For the reverse transformation, the offset parameter value is applied with its sign reversed. Not all coordinate operation methods utilise offsets. For example, a geoid model utilises the well-known geodetic relationship h = H + N and to obtain the gravity-related height H the geoid height N interpolated from a GGXF file is subtracted from the ellipsoidal height h, that is H = h – N. The application of offsets is included in Annex E examples E.3 and E.4, whilst E.2 exemplifies a GGXF file containing geoid heights.

OGC 22-051r7 GGXF v1.0

Annex D (informative) Consolidated list of recommendations Recommendation 1 (clause 5.4)

Recommendation 2 (clause 5.6)

Example: when the interpolation CRS units are degrees, a grid node spacing of 10 arc-minutes should be represented as 0.166666666666667

Recommendation 3 (clause 5.6)

Implementations should use the affine coefficients without making any assumptions about the physical orientation of grid rows and columns in the interpolation CRS.

Recommendation 4 (clause 5.7)

Recommendation 5 (clause 5.8.3)

When parameters are in units documented in the GGXF Conventions, the unit ID and ratio to SI standard unit as given in the Conventions should be used.

Recommendation 6 (clause 5.8.3)

Use arc-minutes or arc-seconds as the unit for parameters that are sexagesimal divisions of a degree.

Recommendation 7 (clause 5.8.5)

To assist implementations reading the GGXF file, data producers are discouraged from using the no data flag and instead to populate all nodes of a grid with estimated values, giving extrapolated values a high uncertainty.

Recommendation 8 (clause 5.8.5)

To cover an irregularly shaped area and avoid a large number of nodes with no data, use multiple root grids.

Recommendation 9 (clause 5.8.5)

When interpolating grids values, implementations should raise an exception, return a no-data value, or otherwise alert users to calculations which require interpolating a no-data value.

Recommendation 10 (clause 5.8.6)

Recommendation 11 (clause 5.8.9.4)

When all parameters given in the file header are used in the ggxfGroup, the gridParameters attribute should be omitted from the ggxfGroup header.

OGC 22-051r7 GGXF v1.0

Recommendation 12 (clause 5.10.1)

The GGXF file header should include metadata identifying the date of issue (publicationDate), and if available a digitalObjectIdentifier (DOI) for the file content.

Recommendation 13 (clause 5.10.2)

The method that is recommended to be used for interpolation of the grid(s) in a ggxfGroup should be given in the ggxfGroup header.

Recommendation 14 (clause 5.10.3)

A GGXF file with content supporting coordinate transformation should indicate the nominal operation accuracy value applicable to the data in the file.

Recommendation 15 (clause 5.10.4)

Recommendation 16 (clause 5.10.5)

Metadata describing the terms under which the GGXF file is distributed (license information) should be included in the file header.

Recommendation 17 (clause 6.1)

Recommendation 18 (clause 6.2.1)

For large grids producers are encouraged to have these grids in external files rather than directly in the YAML text file.

Recommendation 19 (clause 6.3.1)

Implementations should use the existing netCDF programming interfaces.

Recommendation 20 (clause 6.3.2)

When reading a GGXF binary file any attributes encountered that are not in the GGXF Conventions may be ignored.

Recommendation 21 (clause 6.3.5.1)

Consider defining different parameterSets for parameters and their uncertainties, for example 'offset' and 'offsetUncertainty'. Applications not needing to utilise the uncertainty data can then skip the offsetUncertainty variable.

Recommendation 22 (clause 6.3.5.1)

In creating the name of a parameter set, avoid 'count' as this is may create a conflict with its use in the definition of structured data and in netCDF vector variable naming.

Recommendation 23 (clause 6.3.5.3)

Recommendation 24 (clause 6.3.5.5)

Recommendation 25 (clause 6.3.5.5)

A reading application encountering values matching the missing_value attribute in a variable should identify and treat the corresponding unpacked values as undefined.

Recommendation 26 (Annex B Table B.9)

To avoid problems with calendar arithmetic, use epoch rather than date.

OGC 22-051r7 GGXF v1.0

Annex E (informative) Examples These text examples are given following the YAML syntax requirements. Attributes that are character strings are given within double quotation marks when free text, but character strings that are values from the GGXF Conventions are unquoted. This GGXF specification requires that GGXF YAML files include either a full grid or a reference to an external file containing the grid. However, when for illustration purposes the example includes an extract from the full grid, in the example the file extension is changed from ".yaml" to ".gxt"; then only the header records in the example are valid GGXF text file content. Note that in YAML indentations are significant. Because of their file size most GGXF files will have a binary encoding. Examples of GGXF binary files are given in the GGXF Github repository. The features illustrated in these examples include but are not limited to: Feature E.1 Deformation model Geoid model Latitude and longitude offsets Velocity grid Deviations (deflections) of the vertical Gravity anomalies Accuracy as a gridded parameter Affine coefficients Bounding box Bounding polygon Check data Citation of information source DOI ggxfGroups: single ggxfGroup ggxfGroups: multiple ggxfGroups Grids: single grid Grids: multiple non-overlapping grids Grids: nested grids Grid priority Grid data: in YAML file Grid data: in external file Grid data: extract (example, non-compliant) Parameters: single parameter at a node Parameters: multiple parameters at a node Parameters: variety across ggxfGroups Parameters: constant value

E.2

Example E.3 E.4

E.5 x

E.6

E.7

x x

x x x

x x x x x

x x

x x x

x x

x x x x x

x x x

OGC 22-051r7 GGXF v1.0

E.1 GGXF file basics This simple hypothetical example includes two butt-joining grids with the longitudinal spacing of the northern grid increased in comparison to that of the southern grid. The grid node indices i,j for perimeter nodes of each grid are shown in Figure E.1, with the interpolation CRS graticule coordinates also shown. The content applicability extent is shown as a green dashed polygon. The parameters in the grid (latitude offset and longitude offset) are contoured diagrammatically in Figure E.2 so that they may be compared with the values in the grid array at the end of the example. Including metadata in the file header for contact details for the producer and distributer of the file and file date of issue is recommended. In this example such data is omitted; this is for brevity of the illustrated records.

(3,0) φ = 40°00' N (0,0)

λ = 7°52' E

λ = 7°48' E

λ = 7°44' E

λ = 7°40' E

λ = 7°36' E

Figure E.1 — Butt-joining grid extents E.1.1

1. . 61 2. 8 0

Latitude offset

(increases from northwest to southeast)

2 -. 20 -. 22 -. 24 . 6

(3,1) (3,2) (0,4) (0,2) (0,3) (0,1) j (jNodeCount = 5) (1,4) φ = 39°57' N i (iNodeCount = 3) Content app licability (2,0) (2,1) (2,2) (2,3) (2,4) φ = 39°54' N

(2,2)

φ = 40°03' N

. 1 0 .1

φ = 40°06' N

(0,1) 0,2) j (jNodeCount = 3) i (iNodeCount = 4) (1,2)

(0,0) φ = 40°09' N

Longitude offset (increases from west to east)

Figure E.2 — Gridded data

YAML representation

ggxfVersion: "GGXF-1.0" content: geographic2dOffsets title: "Catalino Canyon transformation" version: "2022-06" abstract: "Example transformation constructed for purposes of illustration." filename: "Catalano_Canyon.yaml" digitalObjectIdentifier: "https://doi.org/10.1000/182" contentApplicabilityExtent: extentDescription: "Italy - Mediterranean Sea west of Sardinia - Catalano Canyon." boundingBox: southBoundLatitude: 39.9 westBoundLongitude: 7.6 northBoundLatitude: 40.15 eastBoundLongitude: 7.87 boundingPolygon: Polygon(( 40.09 7.72, 40.12 7.71, 39.92 7.84, 39.93 7.64, 40.05 7.64, 40.09 7.72 ))

OGC 22-051r7 GGXF v1.0

interpolationCrsWkt: &crs | GEOGCRS["ED50", DATUM["European Datum 1950", ELLIPSOID["International 1924",6378388,297,LENGTHUNIT["metre",1]]], CS[ellipsoidal,2], AXIS["Geodetic latitude (Lat)",north],AXIS["Geodetic longitude (Lon)",east], ANGLEUNIT["degree",0.0174532925199433]] sourceCrsWkt: *crs targetCrsWkt: | GEOGCRS["ETRF2000", DATUM["European Terrestrial Reference Frame 2000", ELLIPSOID["GRS 1980",6378137,298.257222101,LENGTHUNIT["metre",1]]], CS[ellipsoidal,2], AXIS["Geodetic latitude (Lat)",north], AXIS["Geodetic longitude (Lon)",east], ANGLEUNIT["degree",0.0174532925199433]] operationAccuracy: 2 parameters: - parameterName: latitudeOffset parameterSet: "offset" sourceCrsAxis: 0 unitName: arc-second unitSiRatio: 4.84813681109536E-06 - parameterName: longitudeOffset parameterSet: "offset" sourceCrsAxis: 1 unitName: arc-second unitSiRatio: 4.84813681109536E-06 ggxfGroups: - ggxfGroupName: "Catalano_Canyon" interpolationMethod: bilinear grids: - gridName: "North" affineCoeffs: [ 40.15, -0.05, 0.0, 7.6, 0.0, 0.1 ] iNodeCount: 4 jNodeCount: 3 data: [ 0.86, -2.62, 1.06, -2.34, 1.20, -2.04, 0.91, -2.64, 1.13, -2.36, 1.30, -2.06, 0.95, -2.66, 1.20, -2.38, 1.50, -2.08, 1.00, -2.70, 1.30, -2.40, 1.60, -2.10 ] - gridName: "South" affineCoeffs: [ 40.0, -0.05, 0.0, 7.6, 0.0, 0.0666666666666667 ] iNodeCount: 3 jNodeCount: 5 data: [ 1.00, -2.70, 1.20, -2.50, 1.40, -2.30, 1.60, -2.10, 1.80, -1.90, 1.20, -2.74, 1.40, -2.52, 1.65, -2.31, 1.83, -2.13, 2.00, -1.92, 1.40, -2.78, 1.80, -2.53, 2.00, -2.33, 2.10, -2.14, 2.20, -1.93 ]

The grid data is shown above in rows and columns for illustration, with both parameters included in one array. The latitude offsets (which increase from northwest to southeast) are in green and longitude offsets are in blue. See E1.3 for an example of these grids being referenced externally through the gridSource attribute. E.1.2

netCDF representation

The full GGXF netCDF file for this example is available on GitHub here. A CDL file with the GGXF netCDF header records for this example is available on GitHub here. These have been produced from the YAML data in E.1.1 above; that data is also on Github here.

OGC 22-051r7 GGXF v1.0

E.1.3 External grid files In the building of GGXF files, if a data producer chooses to use a GGXF YAML text file in conjunction with external grid files in the simple ggxf-csv text format supported by GGXF, the ggxf Group and its grid definitions in E.1.1 would be replaced by: ggxfGroups: - ggxfGroupName: "Catalano_Canyon" interpolationMethod: bilinear grids: - gridName: "North" affineCoeffs: [ 40.15, -0.05, 0.0, 7.6, 0.0, 0.1 ] iNodeCount: 4 jNodeCount: 3 dataSource: gridFilename: "Catalano_Canyon_North.txt" dataSourceType: ggxf-csv separator: space - gridName: "South" affineCoeffs: [ 40.0, -0.05, 0.0, 7.6, 0.0, 0.0666666666666667 ] iNodeCount: 3 jNodeCount: 5 dataSource: gridFilename: "Catalano_Canyon_South.csv" dataSourceType: ggxf-csv separator: comma

Then the external grid files are: Catalano_Canyon_North.txt in ggxf-csv format with space as separator: nodeLatitude nodeLongitude latitudeOffset longitudeOffset 40.15 7.60 0.86 -2.62 40.15 7.70 1.06 -2.34 40.15 7.80 1.20 -2.04 40.10 7.60 0.91 -2.64 40.10 7.70 1.13 -2.36 40.10 7.80 1.30 -2.06 40.05 7.60 0.95 -2.66 40.05 7.70 1.20 -2.38 40.05 7.80 1.50 -2.08 40.00 7.60 1.00 -2.70 40.00 7.70 1.30 -2.40 40.00 7.80 1.60 -2.10

Catalano_Canyon_South.csv in ggxf-csv format with comma as separator: nodeLatitude,nodeLongitude,latitudeOffset,longitudeOffset 40.0000000,7.6000000,1.00,-2.70 40.0000000,7.6666667,1.20,-2.50 40.0000000,7.7333333,1.40,-2.30 40.0000000,7.8000000,1.60,-2.10 40.0000000,7.8666667,1.80,-1.90 39.9500000,7.6000000,1.20,-2.74 39.9500000,7.6666667,1.40,-2.52 39.9500000,7.7333333,1.65,-2.31 39.9500000,7.8000000,1.83,-2.13 39.9500000,7.8666667,2.00,-1.92 39.9000000,7.6000000,1.40,-2.78 39.9000000,7.6666667,1.80,-2.53 39.9000000,7.7333333,2.00,-2.33 39.9000000,7.8000000,2.10,-2.14 39.9000000,7.8666667,2.20,-1.93

OGC 22-051r7 GGXF v1.0

E.1.4

Parameter indexing and interpolation

A GGXF file producer may choose the grid origin to be at any location within the interpolation CRS and be either right or left-handed. They then must ensure that the affine coefficients and node counts correctly relate these to the interpolation CRS. The most frequently used arrangements are where the grid is based on an interpolation CRS with axes positive north and east and with the grid origin chosen to be in either the north-west (upper left) or southwest (lower left) corner. In both of these cases the grid may be left- or right-handed. In the text representations of GGXF the i-axis will be that in which the node coordinates are changing most slowly. For example, in the ggxf-csv grids for Catalano Canyon, nodeLongitude is changing at each node but nodeLatitude is changing only when there is a change of row, so nodeLatitude is changing slowest and is the i-axis. The most frequently used arrangements are shown in Figure E.3a for a right-handed grid (where the i axis is rotated 90° clockwise from the j axis) and Figure E.3b for a left-handed grid (the i axis is rotated 90° counterclockwise from the j axis). i

j 0,0 1

0, jNodeCount-1 2 3…

0,0 1 0, jNodeCount-1 2 j

iNodeCount 1,

iNodeCount-1, 0

3…

jNodeCount 1 iNodeCount 1,

0, jNodeCount-1 0,0

jNodeCount 1

j 3… 2

iNodeCount-1, 0

iNodeCount 1, jNodeCount 1 iNodeCount 1,

iNodeCount-1, 0

i 1

2 3…

0,0

jNodeCount 1 0, jNodeCount-1

Figure E.3a — Right-handed grids

Figure E.3b — Left-handed grids

Implementers should not need to be concerned about the handedness of the grid: they should use the affine coefficients and node counts included in the header information.

OGC 22-051r7 GGXF v1.0

Commentary The arrangements for the two-dimensional Catalano Canyon North and South grids are shown in Figure E.4.

(1,2)

i φ = 39°57' N

φ = 40°03' N

(2,2)

φ = 39°54' (2,0) N

(3,2) λ = 7°48' E

λ = 7°44' E

(3,1) λ = 7°40' E

λ = 7°36' E

φ = 40°00' (3,0) N

λ = 7°36' E

i φ = 40°06' N

j (0,1)

(0,2)

(0,3)

(0,4) (1,4)

(2,1)

(2,2)

(2,3)

(2,4) λ = 7°52' E

φ = 40°00' N (0,0)

λ = 7°48' E

(0,2)

λ = 7°44' E

j (0,1)

λ = 7°40' E

φ = 40°09' (0,0) N

Figure E.4 — Array sequencing for Catalano Canyon example grids The ggxfGroup header record declares that the interpolation method to be used for these Catalona Canyon grids is bilinear. Therefore parameter values from the surrounding four grid nodes are required for interpolation. In this example, the interpolation CRS and the source CRS are the same. Note that grid indices are zerobased, but in the grid header the NodeCount attributes are 1-based. So the maximum node index value = (nodeCount - 1). The coordinates of the grid extent expressed in the interpolation CRS can be determined from the affine coefficients and node counts, as described in 5.6.2. Assume that a coordinate transformation is required for source CRS location 39°58'N, 7°42'E. By applying the affine transformation to each grid in turn, this location is found to not fall in the North grid and to fall in the South grid at grid values i=0.7, j=1.5. Surrounding South grid nodes at i=0 and i=1 with j=1 and j=2 are required. The indices for these four nodes are indexed on [(i), (j), parameter(p)]. From requirement req/yaml/gridData the location of the pth parameter at node (i,j) is given by the formula (i × nj + j) × np + p In the array

[ 1.00, -2.70, 1.20, -2.50, 1.40, -2.30, 1.60, -2.10, 1.80, -1.90, 1.20, -2.74, 1.40, -2.52, 1.65, -2.31, 1.83, -2.13, 2.00, -1.92, 1.40, -2.78, 1.80, -2.53, 2.00, -2.33, 2.10, -2.14, 2.20, -1.93 ]

(shown here by row for reader convenience) the indices for the first parameter (latitudeOffset, p=0) then are 3, 5, 13 and 15, and for the second parameter (longitudeOffset, p=1) are 4, 6, 14 and 16. The parameter values at the four grid nodes surrounding the required location which are read from the array are shown in Figure E.5, with node coordinates in red, values for the first parameter (latitudeOffset) in green and values for the second parameter (longitudeOffset) in blue.

OGC 22-051r7 GGXF v1.0

φ = 40°00' N (0,1) -2.50

φ = 39°58' N

(0,2) -2.30

Interpolation point

φ = 39°57' N -2.52 (1,1)

-2.31 (1,2) λ = 7°48' E

λ = 7°42' E

1.65 (1,2) λ = 7°48' E

λ = 7°40' E

φ = 39°57' N 1.40 (1,1)

Interpolation point

λ = 7°42' E

φ = 39°58' N

(0,2) 1.40

λ = 7°40' E

φ = 40°00' N (0,1) 1.20

Figure E.5 — Parameter values to be interpolated Bilinear interpolation for the first parameter (latitudeOffset) gives δφ = 1.45000 arc-seconds. For the second parameter (longitudeOffset), δλ = -2.41000 arc-seconds. Then applying the interpolated offsets (rounded to a resolution of 3 decimal places of an arc-second) to the source CRS coordinates, coordinates transformed into the target CRS are: 39°58' + 1.450" 7°42' + (-2.410)"

= 39°58'01.450"N = 7°41'57.590"E

OGC 22-051r7 GGXF v1.0

E.2 Geoid model This example of a single grid uses extracts from the South Africa geoid 2010. The example illustrates: • • • •

GGXF header records; extracts from the geoid model grid; use of the affine transformation to determine the grid cell in which a location falls; interpolation of the parameter value (hybrid geoid height) at the location.

The area covered by the grid is illustrated in Figure E.6 below. This area may be described in the header through the contentBox records, but it is not necessary to do so because it is described through the affine transformation and node counts in the grid header. The area of applicability of the grid is restricted to South Africa, as outlined in red. This is described in the header through the mandatory contentApplicabilityExtent bounding box (dashed green line) and textual description records. The location of a point of interest for which the geoid height parameter is interpolated in the grid is shown in green. Its interpolation is described in the commentary at the end of the example.

Interpolated location

Content applicability bounding box

Figure E.6 — Geoid model grid extent and applicability

OGC 22-051r7 GGXF v1.0

E.2.1

YAML representation

ggxfVersion: "GGXF-1.0" content: geoidModel comment: "hybrid geoid" title: "South_African_geoid_2010" version: "2010" abstract: "Model for converting ellipsoidal heights determined using NGI's TrigNet to orthometric heights on the South African Land Levelling Datum, to an accuracy of 10 cm (design requirements). Accuracy is 7cm absolute and relative <2cm + GNSS related error." filename: "SAGEOID2010.yaml" contentApplicabilityExtent: boundingBox: southBoundLatitude: -34.89 westBoundLongitude: 16.45 northBoundLatitude: -22.13 eastBoundLongitude: 32.96 extentDescription: "South Africa - mainland onshore." interpolationCrsWkt: | GEOGCRS["ITRF2005", DYNAMIC[FRAMEEPOCH[2000.0]], DATUM["International Terrestrial Reference Frame 2005", ELLIPSOID["GRS 1980",6378137,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,2], AXIS["Geodetic latitude (Lat)",north], AXIS["Geodetic longitude (Lon)",east], ANGLEUNIT["degree",0.0174532925199433]] sourceCrsWkt: | GEOGCRS["ITRF2005", DYNAMIC[FRAMEEPOCH[2000.0]], TRF["International Terrestrial Reference Frame 2005", ELLIPSOID["GRS 1980",6378137,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,3], AXIS["Geodetic latitude (Lat)",north, ANGLEUNIT["degree",0.0174532925199433]], AXIS["Geodetic longitude (Lon)",east, ANGLEUNIT["degree",0.0174532925199433]], AXIS["Ellipsoidal height (h)",up,LENGTHUNIT["metre",1]]] targetCrsWkt: | VERTCRS["VI LLD height", VDATUM["South Africa Land Levelling Datum"], CS[vertical,1], AXIS["Gravity-related height (H)",up], LENGTHUNIT["metre",1]] operationAccuracy:

0.07

partyName: deliveryPoint: city: postalCode: country: onlineResourceLinkage:

"Chief Directorate: National Geospatial Information" "Private Bag X10" "Mowbray" "7705" "South Africa" "ftp://ftp.trignet.co.za/South_African_Geoid"

parameters: - parameterName: geoidHeight sourceCrsAxis: 2 unitName: metre unitSiRatio: 1.0 ggxfGroups: - ggxfGroupName: "SA geoid 2010" interpolationMethod: bilinear grids:

OGC 22-051r7 GGXF v1.0

- gridName: "SA geoid 2010" affineCoeffs: [-35.0, 0.04166666666667, 0.0, 16.0, 0.0, 0.04166666666667] iNodeCount: 313 jNodeCount: 409 data: [ 26.055, 26.121, ... 3.866, 3.826 ]

Commentary As there is only one parameter, the attribute parameterSet is redundant and not used. The grid is shown here as a tabulation of rows and columns for illustration: j=0

j=1

j=280 j=280.8

[ 30.136, 30.158, ... 13.591, 30.194, 30.198, ... 13.674, : : : 33.958, 34.062, ... 25.452,

j=281

j=407

j=408

13.526, ... 3.866, 3.826, 13.615, ... 3.926, 3.891, : : : 25.417, ... 16.143, 15.909, X

33.888, 34.839, ... 25.640, : : : 26.050, 26.114, ... 26.630, 26.055, 26.121, ... 26.618, λ=16°

25.583, ... 16.309, 16.074, : : : 26.609, ... 29.725, 29.768, 26.599, ... 29.745, 29.789 ] λ=27.7°

# i=312 # i=311

φ=-22°

# i=219 φ=-25.9°, i=218.4 # i=218 # i=1 # i=0

φ=-35°

λ=33°

From the interpolation CRS WKT definition the CRS type is geographic with axis order latitude, longitude and its units can be seen to be degrees. The coordinates in the interpolation CRS of the grid origin and the of opposite corner of the grid can be determined from the affine transformation coefficients and node counts (refer to 5.6). Here the grid envelope lower corner is at ((-35.0 + (1 - 1) *0.0),(16 + (1 - 1) * 0.0)) = (35°S, 16°E) and the grid opposite corner is at ((-35.0 + (313 - 1) * 0.04166666666667),(16.0 + (409 - 1) * 0.04166666666667)) = (22°S, 33°E). In this example of a GGXF file containing a single grid, these derived values are the same as those that could be given through the optional metadata describing the extent of all grids in the file (contentBox). Indexing starts at the southwest corner and goes west to east along rows and the south to north. (312,408) φ = 22°00' S(312,0)

(0,408) λ = 33°00' E

(0,1) (0,2) λ = 16°05' E

λ = 16°00' E

φ = 35°00' S(0,0)

λ = 16°02' 30"E

Figure E.7 — Array sequencing for South Africa geoid model

OGC 22-051r7 GGXF v1.0

To interpolate the grid for the geoid height at ITRF2005 position (25°54'S, 27°42'E) = (-25.9, 27.7), use the affine transformation to determine that the grid indices for this location are i=218.4, j=280.8. The grid nodes surrounding this location and the geoid height are shown in blue in the grid array above. Then, using the declared interpolation method (bilinear), the geoid height at the location is interpolated between these node values and evaluated as 25.526 metres. Referring to the GGXF Conventions (Annex B.3) for the definition of content type geoidModel for the formula (HT = hS - C), for the point at 25°54'S, 27°42'E with an ITRF2005 ellipsoidal height (hS) of 1450m, the SA LLD height (HT) is (1450.000 - 25.526) = 1424.474 metres. The ggxf-csv file with the full grid data for the full South Africa geoid 2010 is available on Github here. The GGXF YAML text file is available on Github here.

E.2.2

netCDF representation

The full South Africa geoid 2010 file in the GGXF netCDF binary file format is available on GitHub here. A CDL file with the GGXF netCDF header records for the South Africa geoid 2010 file is available on GitHub here. Further examples of GGXF files for geoid models for Puerto Rico and the US Virgin Islands are available on Github here. In these datasets one ggxf-csv file covers both Puerto Rico and the US Virgin Islands. There are separate GGXF files for the two areas because they have different vertical datums.

OGC 22-051r7 GGXF v1.0

E.3 Geographic 2D offsets with accuracy This example uses extracts from the NTv2 grid for Canada. Parameters at the grid nodes are latitude and longitude offsets and their accuracies. The complete NTv2_0 file consists of four butt-joining grids (east, west, north and Arctic), the first three of which have a total of 110 nested child grids. This example shows two of the parent grids (west and east) and three butt-joining child grids (Sarnia, Toronto and Windsor) The grid node spacing is 5 x 5 arc-minutes for the parent grids and 30 x 30 arc-seconds for child grids. The child grids share common boundaries. The example assumes a study area bounded by 42°24'36"N, 81°45'18"W in the southwest and 42°25'24"N, 81°44'42"W in the northeast. The study area requires grid data to be interpolated from all three child grids and their parent (see Figure E.8). φ = 60°00'N (648,0) (0,0)

jNodeCount = 157

(0,156)φ = 47°00'N (648,156)

φ = 42°25'24"N (0,0)

(not to scale)

λ = 83°10'W

φ = 42°24'36"N

φ = 46°40'N (350,0)

(0,0) jNodeCount φ = =43°25'N 241 (100,0)

λ = 82°35'W

Canada iNodeCount = 649 west

(0,0)

λ = 44°00'W

j λ = 88°00'W

λ = 142°00'W

Canada iNodeCount = 529 east

(528,0)

φ = 60°00'N

Sarn ia

iNodeCount = 101

Toro iNodeCount = 351 nto

jNodeCount = 511 (99,119) (1,509) jNodeCount =(100,119) 121 (0,509)

(99,120) (100,120) (0,510) (1,510) (0,120) φ = 42°25'N (170,0) (169,0) (75,211) (76,211)

λ = 78°50'W

λ = 81°45'W

(0,0)

(350,510)

Study (169,1) (170,1) Win area (75,212) (76,212) iNodeCount dsor = 171

(0,60)jNodeCount φ = 41°55'N = 61 (0,240)

(170,60) φ = 40°00'N

(528,240)

λ = 81°44'42"W λ = 81°45'18"W Figure E.8 — Extents for grids in this example E.3.1

YAML representation

ggxfVersion: "GGXF-1.0" content: geographic2dOffsets title: "National Transformation v2" version: "2_0" abstract: "Transformation of geodetic latitude and longitude referenced to NAD27 to latitude and longitude referenced to NAD83(Original)." filename: "27to83.yaml" publicationDate: "1995-02" partyName: "Geodetic Survey Division, Natural Resources Canada" onlineResourceLinkage: "https://webapp.geod.nrcan.gc.ca/geod/data-donnees/transformations.php" licenseURL: "https://open.canada.ca/en/open-government-licence-canada" contentApplicabilityExtent: boundingBox: southBoundLatitude: 40.0 westBoundLongitude: -141.0 northBoundLatitude: 60.0 eastBoundLongitude: -44.0 extentDescription: "Canada south of 60°N"

OGC 22-051r7 GGXF v1.0

interpolationCrsWkt: &crs | GEOGCRS["NAD27", DATUM["North American Datum 1927", ELLIPSOID["Clarke 1866",6378206.4,294.9786982,LENGTHUNIT["metre",1]]], CS[ellipsoidal,2], AXIS["Geodetic latitude (Lat)",north], AXIS["Geodetic longitude (Lon)",east], ANGLEUNIT["degree",0.0174532925199433]] sourceCrsWkt: *crs targetCrsWkt: | GEOGCRS["NAD83(Original)", DATUM["North American Datum 1983", ELLIPSOID["GRS 1980",6378137,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,2], AXIS["Geodetic latitude (Lat)",north], AXIS["Geodetic longitude (Lon)",east], ANGLEUNIT["degree",0.0174532925199433]] operationAccuracy: 1.5 parameters: - parameterName: latitudeOffset parameterSet: "offset" sourceCrsAxis: 0 unitName: arc-second unitSiRatio: 4.84813681109536E-06 - parameterName: longitudeOffset parameterSet: "offset" sourceCrsAxis: 1 unitName: arc-second unitSiRatio: 4.84813681109536E-06 - parameterName: latitudeOffsetUncertainty parameterSet: "offsetUncertainty" sourceCrsAxis: 0 unitName: metre unitSiRatio: 1.0 uncertaintyMeasure: "2SE" - parameterName: longitudeOffsetUncertainty parameterSet: "offsetUncertainty" sourceCrsAxis: 1 unitName: metre unitSiRatio: 1.0 uncertaintyMeasure: "2SE" checkPoints: - sourceCrsCoordinates:[ 43.06, -82.37 ] targetCrsCoordinates: [ 43.060037667, -82.369913139 ] parameterCheckValues: latitudeOffsetUncertainty: 0.0073 longitudeOffsetUncertainty: 0.0037 ggxfGroups: - ggxfGroupName: "National Transformation v2_0" interpolationMethod: bilinear grids: - gridName: "CAwest" affineCoeffs: [ 60.0, 0.0, -0.083333333333333, -142.0, 0.083333333333333, 0.0 ] iNodeCount: 649 jNodeCount: 157 data:

# Grid 1 data extract (dLat, dLon, uncertaintyLat, uncertaintyLon) # First column i,j = (0,0) ... i,j = (0,156) (along 142°W from 60°N to 47°N) # Last column i,j = (648,0) ... i,j = (648,156) (along 88°W from 60°N to 47°N)

[ -1.369, -7.569, 0.597, 1.118, ... 0.743, 0.420, 0.898, 1.314, : : : : : : : : -2.294, -8.433, 0.624, 0.418, ... 0.176, -0.835, 0.012, 0.023 ]

OGC 22-051r7 GGXF v1.0

- gridName: "CAeast" affineCoeffs: [ 60.0, 0.0, -0.083333333333333, -88.0, 0.083333333333333, 0.0 ] iNodeCount: 529 jNodeCount: 241 data: [0.743, 0.420, 0.898, 1.314, ... -0.190, 6.536, 0.140, 0.067, : : : : : : : : : : : : 0.164, 0.416, 0.019, 0.034, 0.164, 0.417, 0.017, 0.033,... 0.201, 0.868, 0.014, 0.004, 0.165, 0.418, 0.025, 0.046, 0.164, 0.417, 0.018, 0.036,... 0.200, 0.865, 0.014, 0.004, 0.381, -0.529, 0.028, 0.031, ... 2.705, 5.478, 0.118, 0.136] childGrids: - gridName: "ONtronto" affineCoeffs: [46.6666666666667, 0.0, -0.008333333333333, -81.75, 0.008333333333333, 0.0 ] iNodeCount: 351 jNodeCount: 511 data: [0.141, 0.353, 0.154, 0.116, 0.141, 0.354, 0.141, 0.111, ... 0.205, 0.824, 0.031, 0.045, : : : : : : : : : : : : 0.164, 0.416, 0.019, 0.034, 0.164, 0.417, 0.017, 0.033, ... 0.201, 0.868, 0.014, 0.004, 0.165, 0.418, 0.025, 0.046, 0.164, 0.417, 0.018, 0.036, ... 0.200, 0.865, 0.014, 0.004] - gridName: "ONsarnia" affineCoeffs: [43.4166666666667, 0.0, -0.008333333333333, -82.5833333333333, 0.008333333333333, 0.0 ] iNodeCount: 101 jNodeCount: 121 data: [ 0.136, 0.304, 0.006, 0.003, ... 0.152, 0.388, 0.014, 0.007, 0.151, 0.389, 0.014, 0.007, : : : : : : : : : : : : 0.146, 0.324, 0.028, 0.069, ... 0.164, 0.416, 0.019, 0.034, 0.164, 0.417, 0.017, 0.033, 0.146, 0.326, 0.027, 0.074, ... 0.165, 0.418, 0.025, 0.046, 0.164, 0.417, 0.018, 0.036 ] - gridName: "ONwinsor" affineCoeffs: [42.4166666666667, 0.0, -0.008333333333333, -83.1666666666666, 0.008333333333333, 0.0 ] iNodeCount: 171 jNodeCount: 61 data: [ 0.154, 0.269, 0.002, 0.001, ... 0.165, 0.418, 0.025, 0.046, 0.164, 0.417, 0.018, 0.036, 0.154, 0.269, 0.002, 0.001, ... 0.166, 0.419, 0.027, 0.058, 0.164, 0.417, 0.018, 0.037, : : : : : : : : : : : : 0.158, 0.250, 0.033, 0.028, ... 0.157, 0.413, 0.020, 0.051, 0.157, 0.414, 0.020, 0.052 ]

Commentary Firstly, note that the GGXF format requires longitudes to be positive eastwards but in the NTv2 format longitudes are positive westwards. Therefore, the signs of the longitude offsets in a GGXF file are reversed from those found in an NTv2 file. The second parameter value in the ONwinsor GGXF grid above, the longitude offset at i=0,j=0 of 0.269 arc-seconds (highlighted in red) would be given in the NTv2_0.gsb file as -0.269 arc-seconds. Secondly, in the native NTv2 format the grid origin is in the southeast corner, the node sequence increasing westerly along the southernmost parallel of latitude, then moving northwards along further parallels, as depicted in Figure E.9a. However, the data in this example has been prepared using routines from the GDAL library and the sequencing has been inverted to an origin in the northwest corner and the handedness transposed, as shown in figure E.9b.

100

OGC 22-051r7 GGXF v1.0

i iNodeCount -1,

iNodeCount-1, 0

jNodeCount -1

0, jNodeCount-1

iNodeCount-1, 0

3…

… 3 2 1

jNodeCount-1

0,0

iNodeCount -1, jNodeCount -1

Figure E.9a — Node sequencing in an NTv2 file

Figure E.9b — Node sequencing in this example

From the interpolation CRS WKT definition the CRS type is geographic and its units can be seen to be degrees. Then, as the rotation values in this affine transformation are zero, coordinates of the envelope lower and upper corner coordinates in the Interpolation CRS may be determined from the affine coefficients and axis node counts. For the Canada west grid these are at (47°N 142°W) and (60°N 88°W), for the Windsor grid the grid envelope lower corner is at ((42.4166667 + (61-1) * -0.0083333), (83.1666667 + (171-1) * 0.0)) = (41°55'N, 83°10'W) and the grid envelope upper corner to be at ((42.4166667 + (61-1) * 0.0), (-83.1666667 + (171-1) * 0.0083333)) = (42°25'N, 81°45'W).

(Note: in this text the recurring decimal degree values have been rounded to seven decimal places: in the actual data these would be carried to double precision).

However, to identify the grid(s) in which a point of interest falls it is not necessary to convert the grid definitions to graticule coordinates. Instead, the graticule coordinates are converted to grid indices using the affine transformation coefficients. Doing this for the four corners of our study area in turn determines that: • • • • • •

The grid index in the CAwest grid for the study area northwest corner is i=722.9, j=210.9. Both i and j values exceed the (nodeCount-1) values of the grid (648, 156) so the study area is outside of the CAwest grid. All four corners of the study area fall within the CAeast grid. The study area southwest corner also falls in the Windsor grid at index 169.4, 0.8. The study area northwest corner also falls in the Sarnia grid at index 99.4, 119.2. The study area northeast corner also falls in the Toronto grid at index 0.6, 509.2. The study area southeast corner does not fall in any child grid. Offsets for the southeastern part of the study area have to be interpolated from the CAeast grid, in which the study area southeast corner is at index 75.1, 211.8.

For the study area southwest corner the four grid node indices for interpolation within the ONwinsor grid are: i,j = 169,0 i,j = 170,0 i,j = 169,1 i,j = 170,1 The values for latitude and longitude offset at these grid nodes are shown in the grid extract above in green and blue respectively. Bi-linear interpolation for δφ gives 0.1651" and for δλ gives 0.4178". Then, referring to the GGXF Conventions (Annex B.3) for the definition of content type given in the file header (geographic2dOffsets), offsets are applied as additions. Using the formulas (φT = φS + δφ) and (λT = λS + δλ), the point at NAD27 latitude φS and longitude λS of 42°24'36"N, 81°45'18"W (west being negative) transforms to NAD83(Original) latitude φT and longitude λT of 42°24'36.165"N, 81°45'17.582"W. The accuracies can be interpolated in a similar fashion, with δφ = 0.165" = 5.09m ± 0. 23m and δλ = 0.4178" = 9.55m ± 0. 05m.

101

OGC 22-051r7 GGXF v1.0

Note that the parameter values at common nodes on the child grid boundaries have identical values. For example, ONsarnia (99,120) and (100,120) are at the same location as ONwinsor (169,0) and (170,0) respectively and both have parameter values of δφ = 0.165", δλ = 0.417", Nacc = 0.025m, Eacc = 0.046m and δφ = 0.164", δλ = 0.417", Nacc = 0.025m, Eacc = 0.036m respectively. This facilitates continuity of interpolation across the boundary. E.3.2

netCDF representation

The full NRCan NTv2_0 file converted to the GGXF YAML file format and using external file referencing through the dataSource attribute is available on Github here. The full NRCan NTv2_0 file migrated to the GGXF netCDF file format is available on GitHub here) A CDL file with only the netCDF header records is available on GitHub here.

102

OGC 22-051r7 GGXF v1.0

E.4 Velocity grid The following hypothetical example illustrates secular motion described through velocities. This hypothetical example uses data taken from the first ggxfGroup of example E.5 modelling secular deformation. (For consistency with other components the actual New Zealand deformation model published by LINZ from which extracts are used in E.5 describes secular motion as displacements to which a time function is applied). E.4.1

YAML representation

ggxfVersion: "GGXF-1.0" content: velocityGrid title: "NZ hypothetical velocity grid" version: "2011" abstract: "Hypotherical example to illustrate secular motion described through velocities." filename: "NZ hypothetical velocity grid.yaml" comment: | The parent grid describes secular deformation derived from NUVEL-1A rotation rates. The child grid describes secular deformation derived from the GNS model 2011 v4. contentApplicabilityExtent: extentDescription: "New Zealand onshore and EEZ." boundingBox: southBoundLatitude: -55.95 westBoundLongitude: 160.6 northBoundLatitude: -25.88 eastBoundLongitude: -171.2 interpolationCrsWkt: | GEOGCRS["NZGD2000", DATUM["New Zealand Geodetic Datum 2000", ELLIPSOID["GRS 1980",6378137,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,2], AXIS["Geodetic latitude (Lat)",north,ANGLEUNIT["degree",0.0174532925199433]], AXIS["Geodetic longitude (Lon)",east,ANGLEUNIT["degree",0.0174532925199433]], ID["EPSG",4167,URI["http://www.opengis.net/def/crs/epsg/0/4167"]]] sourceCrsWkt: | GEOGCRS["NZGD2000", DATUM["New Zealand Geodetic Datum 2000", ELLIPSOID["GRS 1980",6378137,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,3], AXIS["Geodetic latitude (Lat)",north,ANGLEUNIT["degree",0.0174532925199433]], AXIS["Geodetic longitude (Lon)",east,ANGLEUNIT["degree",0.0174532925199433]], AXIS["Ellipsoidal height (h)",up,LENGTHUNIT["metre",1]], ID["EPSG",4959,URI["http://www.opengis.net/def/crs/epsg/0/4959"]]] targetCrsWkt: | GEOGCRS["ITRF96", DYNAMIC[FRAMEEPOCH[1997.0]], TRF["International Terrestrial Reference Frame 1996", ELLIPSOID["GRS 1980",6378137,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,3], AXIS["Geodetic latitude (Lat)",north,ANGLEUNIT["degree",0.0174532925199433]], AXIS["Geodetic longitude (Lon)",east,ANGLEUNIT["degree",0.0174532925199433]], AXIS["Ellipsoidal height (h)",up,LENGTHUNIT["metre",1]]] ID["EPSG",7907,URI["http://www.opengis.net/def/crs/epsg/0/7907"]]] operationAccuracy: 0.01 parameters: - parameterName: velocityEast parameterSet: "velocity" sourceCrsAxis: 1 unitName: m/yr unitSiRatio: 3.16887651727315E-08

103

OGC 22-051r7 GGXF v1.0

- parameterName: velocityNorth parameterSet: "velocity" sourceCrsAxis: 0 unitName: m/yr unitSiRatio: 3.16887651727315E-08 ggxfGroups: - ggxfGroupName: "national_velocity_model" interpolationMethod: bilinear grids: - gridName: "grid_nuvel1a_eez" affineCoeffs: [ -25.0, 0.0, -0.5, 158.0, 0.5, 0.0 ] iNodeCount: 73 jNodeCount: 67 data: [ 0.023004, 0.051255, ... -0.059495, 0.033768, : : : : -0.017214, 0.026107, ... -0.033665, 0.033706 ] childGrids: - gridName: "grid_igns2011_nz" affineCoeffs: [ -33.0, 0.0, -0.1, 165.5, 0.1, 0.0 ] iNodeCount: 141 jNodeCount: 151 data: [ 0.01239, 0.04615, ... 0.00702, 0.03462, : : : : -0.02301, 0.03381, ... -0.03692, 0.03216 ]

Commentary From the affine coefficients and axis node counts, for the grid derived from Nuvel 1 the envelope lower corner can be determined to be at (58°S 158°E) and the envelope upper corner to be at (25°S 194°E) = (25°S 166°W). For the IGNS model the envelope lower corner can be determined to be at (48°S 165°30'E) and the envelope upper corner to be at (33°S 179°30'E). The example above is extracted from the New Zealand deformation model, in which it is included as one of the components of deformation. The full New Zealand deformation model is exemplified in E.5. E.4.2

netCDF representation

A GGXF netCDF file for the velocity grids for Alaska (see E.7) is available on GitHub here. The YAML file using ggxf-csv external grids for the Alaska velocity grids from which the GGXF netCDF file was produced is available on GitHub here. A CDL file with only the netCDF header records for the Alaska velocity grids is available on GitHub here.

104

OGC 22-051r7 GGXF v1.0

E.5 Deformation model This example demonstrates the use of multiple ggxfGroups used to describe a deformation model. It uses selected extracts from the New Zealand NZGD2000 deformation model version 20180701. The full model consists of a national secular deformation model and 12 patches describing deformation from major earthquakes. This deformation model is represented in GGXF by 32 ggxfGroups with each ggxfGroup describing one of the model's components. Only parts of 2 of the 32 components in the model, illustrating secular, co-seismic and post-seismic elements, are included in this example. E.5.1

YAML representation

The example is of a preparation text file including references to the external grids. The keywords for that external grid referencing are not part of this Standard but specific to the file producer and are shown in grey italic text. ggxfVersion: "GGXF-1.0" content: deformationModel title: "New Zealand Deformation Model" version: "20180701" abstract: "Defines the secular model (National Deformation Model) and patches for significant deformation events since 2000." filename: "nzgd2000-20180701-subset.yaml" partyName: "Land Information New Zealand" deliveryPoint: | Level 7, Radio New Zealand House 155 The Terrace PO Box 5501 city: "Wellington" postalCode: "6145" electronicMailAddress: "[email protected]" onlineResourceLinkage: "http://www.linz.govt.nz/nzgd2000" publicationDate: "2018-07-01" license: "Creative Commons Attribution 4.0 International" contentApplicabilityExtent: extentDescription: "New Zealand onshore and EEZ." boundingBox: southBoundLatitude: -55.94 westBoundLongitude: 160.62 northBoundLatitude: -25.89 eastBoundLongitude: -171.23 boundingPolygon: Polygon ((-32.42 168.65, -34.98 168.10, -37.58 170.07, -40.60 167.30, -44.32 162.17, -51.17 160.62, -54.97 165.11, -55.94 168.78, -54.70 173.54, -53.26 174.64, -51.66 174.48, -53.04 178.46, -51.94 182.69, -50.45 183.84, -47.76 184.00, 46.81 187.31, -44.68 188.77, -42.93 188.53, -41.50 187.23, -40.26 182.07, -36.91 182.64, -34.59 180.22, -34.45 182.66, -33.12 184.50, -29.73 185.92, -27.47 185.34, 25.89 182.29, -27.22 179.01, -31.55 177.28, -34.32 179.37, -30.85 172.97, -30.88 171.22, -32.42 168.65)) interpolationCrsWkt: | GEOGCRS["NZGD2000", DATUM["New Zealand Geodetic Datum 2000", ELLIPSOID["GRS 1980",6378137,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,2], AXIS["Geodetic latitude (Lat)",north,ANGLEUNIT["degree",0.0174532925199433]], AXIS["Geodetic longitude (Lon)",east,ANGLEUNIT["degree",0.0174532925199433]], ID["EPSG",4167,URI["http://www.opengis.net/def/crs/epsg/0/4167"]]] sourceCrsWkt: | GEOGCRS["NZGD2000", DATUM["New Zealand Geodetic Datum 2000", ELLIPSOID["GRS 1980",6378137,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,3], AXIS["Geodetic latitude (Lat)",north,ANGLEUNIT["degree",0.0174532925199433]], AXIS["Geodetic longitude (Lon)",east,ANGLEUNIT["degree",0.0174532925199433]],

105

OGC 22-051r7 GGXF v1.0

AXIS["Ellipsoidal height (h)",up,LENGTHUNIT["metre",1]], ID["EPSG",4959,URI["http://www.opengis.net/def/crs/epsg/0/4959"]]] targetCrsWkt: | GEOGCRS["ITRF96", DYNAMIC[FRAMEEPOCH[1997.0]], TRF["International Terrestrial Reference Frame 1996", ELLIPSOID["GRS 1980",6378137,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,3], AXIS["Geodetic latitude (Lat)",north,ANGLEUNIT["degree",0.0174532925199433]], AXIS["Geodetic longitude (Lon)",east,ANGLEUNIT["degree",0.0174532925199433]], AXIS["Ellipsoidal height (h)",up,LENGTHUNIT["metre",1]]] ID["EPSG",7907,URI["http://www.opengis.net/def/crs/epsg/0/7907"]]] operationAccuracy: 0.01 parameters: - parameterName: displacementEast parameterSet: "displacement" sourceCrsAxis: 1 unitName: metre unitSiRatio: 1.0 - parameterName: displacementNorth parameterSet: "displacement" sourceCrsAxis: 0 unitName: metre unitSiRatio: 1.0 - parameterName: displacementUp parameterSet: "displacement" sourceCrsAxis: 2 unitName: metre unitSiRatio: 1.0 - parameterName: displacementHorizontalUncertainty parameterSet: "displacementUncertainty" unitName: metre unitSiRatio: 1.0 uncertaintyMeasure: 2CEP - parameterName: displacementUpUncertainty parameterSet: "displacementUncertainty" unitName: metre unitSiRatio: 1.0 uncertaintyMeasure: 2SE checkPoints: - sourceCrsCoordinates: [ -50.757000000, 165.271000000, 49.2000 ] sourceCoordinateEpoch: 2008.3 targetCrsCoordinates: [ -50.756997865, 165.270996670, 49.2000 ] targetCoordinateEpoch: 2008.3 - sourceCrsCoordinates: [ -50.757000000, 165.271000000, 49.2000 ] sourceCoordinateEpoch: 2018.3 targetCrsCoordinates: [ -50.756995292, 165.270992658, 49.2000 ] targetCoordinateEpoch: 2018.3 ggxfGroups: - ggxfGroupName: "nz_linz_nzgd2000-ndm-grid02" comment: "Secular deformation model" interpolationMethod: bilinear gridParameters: - displacementEast - displacementNorth constantParameters: - parameterName: displacementHorizontalUncertainty parameterValue: 0.001 - parameterName: displacementVerticalUncertainty parameterValue: 0.0 timeFunctions: - functionType: linear functionReferenceDate: "2000-01-01T00:00:00Z"

106

OGC 22-051r7 GGXF v1.0

grids: - gridName: "ndm_grid_nuvel1a_eez" comment: "Secular deformation model derived from NUVEL-1A rotation rates" affineCoeffs: [-25.0,0.0,-0.5,158.0,0.5,0.0] iNodeCount: 73 jNodeCount: 67 dataSource: dataSourceType: GDAL gdalSource: "GTIFF_DIR:1:nz_linz_nzgd2000-ndm-grid02.tif" childGrids: - gridName: "ndm_grid_igns2011_nz" comment: "Secular deformation model derived from GNS model 2011 V4" affineCoeffs: [-33.0,0.0,-0.1,165.5,0.1,0.0] iNodeCount: 141 jNodeCount: 151 dataSource: dataSourceType: GDAL gdalSource: "GTIFF_DIR:2:nz_linz_nzgd2000-ndm-grid02.tif" - ggxfGroupName: "nz_linz_nzgd2000-ds20090715-grid011" comment: "Dusky Sound (Fiordland) earthquake July 2009." interpolationMethod: bilinear gridParameters: - displacementEast - displacementNorth - displacementUp constantParameters: - parameterName: displacementHorizontalUncertainty parameterValue: 0.03 - parameterName: displacementVerticalUncertainty parameterValue: 0.05 timeFunctions: - functionType: ramp startEpoch: 2009.536 endEpoch: 2009.536 functionReferenceEpoch: 2011.666 scaleFactor: 1.05 - functionType: ramp startEpoch: 2009.536 endEpoch: 2011.666 functionReferenceEpoch: 2011.666 scaleFactor: 0.29 grids: - gridName: "patch_ds_20090715_grid_ds_P0_L1" affineCoeffs: [-50.125,0.0,-0.125,165.4,0.15,0.0] iNodeCount: 11 jNodeCount: 11 dataSource: dataSourceType: GDAL gdalSource: "GTIFF_DIR:1:nz_linz_nzgd2000-ds20090715-grid011.tif"

E.5.2

netCDF representation

The YAML above is based on a small subset of the New Zealand deformation model. The full deformation model file converted to the GGXF YAML file format and using external file referencing through the dataSource attribute is available on Github here. The full New Zealand deformation model file migrated to the GGXF netCDF file format is available on GitHub here). A CDL file with only the netCDF header records is available on GitHub here.

107

OGC 22-051r7 GGXF v1.0

E.6 Gridded geodetic data not used in coordinate transformation software E.6.1

Deviation (deflection) of the vertical

This example illustrates gridded geodetic data that is not used directly in coordinate transformation software. The example uses deviation of the vertical (sometimes referred to as deflections of the normal) data for Puerto Rico held in a single grid. Because the data is not used for coordinate transformations or point motion operations, there is no source CRS or target CRS and sourceCrsAxis is not given. Description of the interpolation CRS to which the data is referenced is still required. E.6.2

YAML representation of deviation (deflection) of the vertical data

ggxfVersion: "GGXF-1.0" content: deviationsOfTheVertical title: "PRVI DOV 2018" version: "2018" abstract: "PRVI hybrid deflection model. Deflections are at the Earth's surface" filename: d2018prvi.yaml contentApplicabilityExtent: extentDescription: "US Puerto Rico and Virgin Islands - onshore." boundingBox: southBoundLatitude: 17.67 westBoundLongitude: -65.09 northBoundLatitude: 18.42 eastBoundLongitude: -64.6 partyName: "National Geodetic Survey, National Oceanic and Atmospheric Administration" deliveryPoint: "1315 East West Hwy" city: "Silver Spring" postalCode: "20910" country: "United States of America" onlineResourceLinkage: "https://geodesy.noaa.gov/PC_PROD/GEOID18/Format_ascii/g2018p0.asc.zip" interpolationCrsWkt: | GEOGCRS["NAD83 (2011)", DATUM["North American Datum 1983 (2011) epoch 2010.00", ELLIPSOID["GRS 1980",6378137.0,298.2572221,LENGTHUNIT["metre",1]]], CS[ellipsoidal,2], AXIS["Geodetic latitude (Lat)",north], AXIS["Geodetic longitude (Lon)",east], ANGLEUNIT["degree",0.0174532925199433]] parameters: parameterName: deviationEast unitName: arc-second unitSiRatio: 4.84813681109536E-06 parameterName: deviationNorth unitName: arc-second unitSiRatio: 4.84813681109536E-06 ggxfGroups: - ggxfGroupName: "Puerto Rico Virgin Islands DEFLEC18" interpolationMethod: biquadratic grids: - gridName: "Puerto Rico Virgin Islands DEFLEC18" affineCoeffs: [15.0, 0.016666666666667, 0.0, -69.0, 0.0, 0.016666666666667] iNodeCount: 361 jNodeCount: 301 data: []

108

OGC 22-051r7 GGXF v1.0

E.6.3

netCDF representation of deviation (deflection) of the vertical data

The YAML above omits the grid data. The full YAML file including the grid data is available on Github here. The full file for PRVI deviations of the vertical in the GGXF netCDF file format is available on GitHub here. A CDL file with only the netCDF header records is available on GitHub here.

E.6.4

Gravity anomaly data

Snippets of YAML header records for gravity anomaly and gravity disturbance data are given below. Example 1 - Gravity anomaly ggxfVersion: "GGXF-1.0" content: gravity : gravityFormula: "International Gravity Formula 1980" gravityFormulaReferenceEllipsoid: "GRS 1980" gravityReductionMethod: "refinedBouger" gravityReductionModelType: "spherical" : parameters: parameterName: gravityAnomaly unitName: milligal unitSiRatio: 0.00001 :

Example 2 - Gravity disturbance ggxfVersion: "GGXF-1.0" content: gravity : gravityFormula: "WGS 84 Ellipsoidal Gravity Formula (height)" gravityFormulaReferenceEllipsoid: "WGS 84" gravityReductionMethod: "freeAir" gravityReductionModelType: "planar" : parameters: parameterName: gravityDisturbance unitName: milligal unitSiRatio: 0.00001 :

109

OGC 22-051r7 GGXF v1.0

E.7 Grid priority The gridPriority attribute is used to identify which of intersecting sibling grids should take priority for use in interpolation of nested grids (refer to 5.6). The example below uses velocity grids from the US NGS HDTP application to illustrate the application of grid priority in GGXF. HDTP includes ten velocity grids covering the conterminus US (CONUS) and Alaska. Their spatial extents are shown in Figure E.10. HDTP prioritises their use through ranking with 1 being the highest rank and 10 the lowest rank.

Figure E.10 — Spatial view of HDTP grids In GGXF these grids may be represented in separate ggxfGroups for CONUS and Alaska with each grid being a root grid in their respective region. Being root grids they are siblings and because they all intersect with at least one sibling in their ggxfGroup, all require a gridPriority (in GGXF higher ranked grids have higher priority). The mapping from HDTP to GGXF structure is shown in Figure E.11.

ggxfGr oup

ggxfG roup

Alaska ConusSanA Mainl South StElia South Pacifi West North South EastC and centr east CONU ndrea s cNW CA CA ONUS y ty AK rankHDTP AK HDTP =al 10 rankHDTP = 8 rankHDTP = 7 rankHDTP = 9 rankHDTP =S4 rankHDTP = 5 rankHDTP =s3 rankHDTP = 1 rankHDTP = 2 rank = 6

gridPriority gridPriority = 1Velocit gridPriority =3 gridPriority =4 gridPriority =2 gridPriority =3 gridPriority = 2Veloci gridPriority =4 gridPriority =6 gridPriority =5 =1

Figure E.11 — Structural view of GGXF grids The HDTP grids for Alaska converted to the GGXF YAML file format and using external file referencing through the dataSource attribute is available on Github here. The full set of HDTP grids for Alaska in the GGXF netCDF file format is available on GitHub here.

110

OGC 22-051r7 GGXF v1.0

Annex F (informative) Revision history Date 2022-1217 2023-0109

Release 1.0.1

Author Roger Lott

Paragraph modified

1.0.2

Roger Lott

Annex A.1 req/core/content,

2023-0825

1.0.3

Roger Lott

2023-1002

1.0.4

Roger Lott

2023-1027

1.0.5

Roger Lott

2023-1220

1.0.6

Roger Lott

2024-0108

1.0.7

Roger Lott

2024-0112

1.0.8

Roger Lott

Description First release.

Correct reference to content keyword. Correct affine coefficient sequence (from B.2 affineCoeffs, C.1 120 to 012). Document Gravity content added. Log base 10 time function added to track changes to Topic 24. Text edits to incorporate OAB and public ballot feedback. 5.5, 5.6, 6.2.2, Annex A.1 Removed ambiguity in grid req/core/grid, Annex C.1, node sequencing. Minor typos Annex E. corrected. Annex B (GGXF Added Conventions). interpolationCrsCoordinates and interpolationCoordinateEpoch, minor modification to definition of checkPoints. 2, Normative references. URIs for Topic 2 and CRS WKT updated. Annex C Annex C.1 removed with some content consolidated into 5.6. Document Corrected minor typos, including figure numbering in Annex E. Annex B tables B.1, B.8 and To track changes to Topic 24, B.9. renamed velocity and Example E.5 acceleration time functions as linear and quadratic respectively. Submitting organizations Contributor affiliations (Preface). updated.

111

OGC 22-051r7 GGXF v1.0

Bibliography [1]

EPSG Geodetic Parameter Dataset, https://epsg.org (accessed 2020-05-26).

[2]

IERS Conventions (2010), https://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html/ (accessed 2021-0526).

[3]

ISO Geodetic Registry, https://geodetic.isotc211.org (accessed 2020-05-26).

[4]

Langley, R. B. (1991). The mathematics of GPS. GPS World, 2(7), 45-50.

[5]

Leenhouts, P. P. (1985). On the computation of bi-normal radial error. NAVIGATION, Journal of the Institute of Navigation, 32(1), 16-28.

[6]

netCDF User's Guide, https://docs.unidata.ucar.edu/nug/current/index.html (accessed 202305-26).

[7]

Unicode Standard Annex #31, https://unicode.org/reports/tr31/#Default_Identifier_Syntax, (accessed 2021-05-26).

[8]

YAML specification, https://yaml.org/spec/1.2/ (accessed 2021-05-26).

References for Table B.9 (Interpolation method identifier) [9]

Arata, Louis K. "Tricubic interpolation." Graphics Gems V (1995): 107-110.

[10]

Haynes, Andrew L., and Clare E. Parnell. "A trilinear method for finding null points in a threedimensional vector space." Physics of Plasmas 14, no. 8 (2007): 082107.

[11]

Lekien, Francois, and J. Marsden. "Tricubic interpolation in three dimensions." International Journal for Numerical Methods in Engineering 63, no. 3 (2005): 455-471.

[12]

Press, William H., Saul A. Teukolsky, William T. Vetterling, and Brian P. Flannery. Numerical recipes 3rd edition: The art of scientific computing. Cambridge university press, 2007.

[13]

Russell, William S. "Polynomial interpolation schemes for internal derivative distributions on structured grids." Applied Numerical Mathematics 17, no. 2 (1995): 129-171.

[14]

Shi, Wen Zhong, Q. Q. Li, and C. Q. Zhu. "Estimating the propagation error of DEM from higherorder interpolation algorithms." International Journal of Remote Sensing 26, no. 14 (2005): 3069-3084.

[15]

Smith, D. "Biquadratic Interpolation." NOAA Technical Memorandum NOS NGS 84, 2022. https://geodesy.noaa.gov/library/pdfs/NOAA_TM_NOS_NGS_0084.pdf (accessed 2022-11-26).

[16]

Wagner, Rick. "Multi-linear interpolation." Beach Cities Robotics (2008).

[17]

Young, David M., and Robert Todd Gregory. "A survey of numerical mathematics". Vol. 1. Dover, 1988.

112

OGC 22-051r7 GGXF v1.0

References for gravity formula [18]

International Gravity Formula 1930: Cassinis, G. (1930). "Sur l’adoption d’une formule internationale pour la pesanteur normale". Bulletin Géodésique 26(1), 40-49.

[19]

International Gravity Formula 1967: "Geodetic Reference System 1967". International Association of Geodesy (IAG) special publication no. 3, August 1971.

[20]

International Gravity Formula 1980: Moritz, H. "Geodetic Reference System 1980". Bulletin Géodésique 54:395–405

[21]

Somigliana gravity formula: Somigliana, C. (1929). "Teoria generale del campo gravitazionale dell'ellipsoide di rotazione". Memorie della società astronomica italiana, 4, 425.

[21]

WELMEC gravity formula: Schwartz, R. and Lindau, A. "Das europäische Gravitationszonenkonzept nach WELMEC für eichpflichtige Waagen". Physikalisch-Technische Bundesanstalt, Braunschweig.

[22]

WGS 84 Ellipsoidal Gravity Formula: "World Geodetic System 1984 - Its Definition and Relationships with Local Geodetic Systems". National Geospatial-Intelligence Agency (NGA) NGA.STND.0036.

113

OGC GGXF geodetic data grid exchange format (version 1.0) — OGC 22-051r7

Related documents