Extensible 3D (X3D)
Part 1: Architecture and base components

25 Geospatial component

# 25.1 Introduction

## 25.1.1 Name

The name of this component is "Geospatial". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.5.4 Component statement).

## 25.1.2 Overview

This clause describes the Geospatial component of this document. This includes how to associate real world locations to elements in the X3D world as well as specifying nodes particularly tuned for geospatial applications. Table 25.1 provides links to the major topics in this clause.

Table 25.1 — Topics

25.1 Introduction 25.1.1 Name 25.1.2 Overview 25.2 Concepts 25.2.1 Overview 25.2.2 Spatial reference frames 25.2.3 Specifying a spatial reference frame 25.2.4 Specifying geospatial coordinates 25.2.5 Dealing with high-precision coordinates 25.2.6 Geospatial navigation issues 25.3 Node reference 25.3.1 GeoCoordinate 25.3.2 GeoElevationGrid 25.3.3 GeoLocation 25.3.4 GeoLOD 25.3.5 GeoMetadata 25.3.6 GeoOrigin 25.3.7 GeoPositionInterpolator 25.3.8 GeoProximitySensor 25.3.9 GeoTouchSensor 25.3.10 GeoTransform 25.3.11 GeoViewpoint 25.4 Support levels Figure 25.1 — Loading of GeoLOD levels Table 25.1 — Topics Table 25.2 — Supported spatial reference frames Table 25.3 — Supported earth ellipsoids Table 25.4 — Supported earth geoids Table 25.5 — GeoMetadata keywords and values Table 25.6 — Geospatial component support levels

# 25.2 Concepts

## 25.2.1 Overview

This section contains discussions of various important concepts that are integral to the Geospatial component, providing support for geographic and geospatial applications. This support includes the ability to embed geospatial coordinates in certain X3D nodes, to support high-precision geospatial modeling, and to handle large multi-resolution terrain databases. These concepts are described below. The Geospatial component includes conventions that are defined by the Spatial Reference Model (see ISO/IEC 18026).

In total, the following nodes comprise the Geospatial component. These nodes are defined as follows.

- GeoCoordinate
- GeoElevationGrid
- GeoLocation
- GeoLOD
- GeoMetadata
- GeoOrigin
- GeoPositionInterpolator
- GeoProximitySensor
- GeoTouchSensor
- GeoTransform
- GeoViewpoint

## 25.2.2 Spatial reference frames

X3D defines an implicit Cartesian, right-handed three-dimensional coordinate system for modeling purposes, as defined in 4.3.6 Standard units and coordinate system. However, most geo-referenced data are provided in a geodetic or projective spatial reference frame. A geodetic (or geographic) spatial reference frame is related to the ellipsoid used to model the earth, for example the latitude/longitude system. A projective spatial reference frame employs a projection of the ellipsoid onto some simple surface such as a cone or a cylinder, for example, the Lambert Conformal Conic (LCC) or the Universal Transverse Mercator (UTM) projections. In order to be useful to the geospatial community, X3D provides support for a number of nodes that can use spatial reference frames for modeling purposes. The spatial reference frames supported by X3D are defined in Table 25.2.

Table 25.2 — Supported spatial reference frames

Code | Name
--- | ---
GD | Geodetic spatial reference frame
GC | Geocentric spatial reference frame
UTM | Universal Transverse Mercator
WM | Web Mercator

The code GDC shall be synonymous to GD, and the code GCC shall be synonymous to GC. However, these two synonyms may be subject to future deprecation. In addition to these spatial reference frames, X3D defines 23 standard ellipsoids in order to model the shape of the earth. These are all defined in Table 25.3.

Table 25.3 — Supported earth ellipsoids

Code | Ellipsoid Name | Semi-Major Axis (metres) | InverseFlattening (F-1)
--- | --- | --- | ---
AA | Airy 1830 | 6377563.396 | 299.3249646
AM | Modified Airy | 6377340.189 | 299.3249646
AN | Australian National | 6378160 | 298.25
BN | Bessel 1841 (Namibia) | 6377483.865 | 299.1528128
BR | Bessel 1841 (Ethiopia Indonesia...) | 6377397.155 | 299.1528128
CC | Clarke 1866 | 6378206.4 | 294.9786982
CD | Clarke 1880 | 6378249.145 | 293.465
EA | Everest (India 1830) | 6377276.345 | 300.8017
EB | Everest (Sabah & Sarawak) | 6377298.556 | 300.8017
EC | Everest (India 1956) | 6377301.243 | 300.8017
ED | Everest (W. Malaysia 1969) | 6377295.664 | 300.8017
EE | Everest (W. Malaysia & Singapore 1948) | 6377304.063 | 300.8017
EF | Everest (Pakistan) | 6377309.613 | 300.8017
FA | Modified Fischer 1960 | 6378155 | 298.3
HE | Helmert 1906 | 6378200 | 298.3
HO | Hough 1960 | 6378270 | 297
ID | Indonesian 1974 | 6378160 | 298.247
IN | International 1924 | 6378388 | 297
KA | Krassovsky 1940 | 6378245 | 298.3
RF | Geodetic Reference System 1980 (GRS 80) | 6378137 | 298.257222101
SA | South American 1969 | 6378160 | 298.25
WD | WGS 72 | 6378135 | 298.26
WE | WGS 84 | 6378137 | 298.257223563

Finally, X3D supports the specification of a geoid representing mean sea level. The list of geoids supported is presented in Table 25.4.

Table 25.4 — Supported earth geoids

Code | Name
--- | ---
WGS84 | WGS84 geoid

Internally, an X3D browser will transform all geographic coordinates into earth-fixed geocentric coordinates ( i.e., an (x,y,z) displacement from the center of the earth in units of length base units). This is a 3D Cartesian coordinate system that best integrates with X3D's implicit coordinate system. In addition, an offset may be applied to these geocentric coordinates if a GeoOrigin node is supplied (see 25.2.5 Dealing with high-precision coordinates). The resulting coordinates are cast to single-precision and are the final values used for rendering. This process means that we provide support for increased precision around an area of interest, and also enable data specified in multiple spatial reference frames to be fused into a single context.

## 25.2.3 Specifying a spatial reference frame

All the X3D nodes that allow inclusion of geographic coordinates support a field called geoSystem. This field is used to specify the particular spatial reference frame that will be used for the geospatial coordinates in that node. This is an MFString field that can include a number of arguments to fully designate the spatial reference frame. Each argument appears in a separate string within the MFString array. Argument matching is case sensitive. Optional arguments may appear in any order. The following values are supported.

- " GD" - Geodetic spatial reference frame (latitude/longitude). An optional argument may be used to specify the ellipsoid using one of the ellipsoid codes that are defined in Table 25.3. If no ellipsoid is specified, then "WE" is assumed ( i.e., the WGS84 ellipsoid). An optional "WGS84" string can be specified if you wish all elevations to relative to the WGS84 geoid ( i.e., mean sea level) (see Table 25.4); otherwise, all elevations will be relative to the ellipsoid. An example spatial reference frame definition of this format is [ "GD", "WD" ] for a geodetic spatial reference frame based upon the WGS72 ellipsoid with all elevations being relative to that ellipsoid.

- " UTM" - Universal Transverse Mercator. One further required argument shall be supplied for UTM in order to specify the zone number (1..60). This is given in the form "Z<n>", where <n> is the zone number. An optional argument of "S" may be supplied in order to specify that the coordinates are in the southern hemisphere (otherwise, northern hemisphere will be assumed). A further optional argument may be used to specify the ellipsoid using one of the ellipsoid codes that are defined in Table 25.3. If no ellipsoid is specified, then "WE" is assumed ( i.e., the WGS84 ellipsoid). An optional "WGS84" string can be specified if you wish all elevations to relative to the WGS84 geoid ( i.e., mean sea level (see Table 25.4)); otherwise, all elevations will be relative to the ellipsoid. An example spatial reference frame definition of this format is [ "UTM", "Z10", "S", "easting_first" ] for a southern hemisphere UTM spatial reference frame in zone 10 with all elevations being with respect to mean sea level.

- " GC" - Earth-fixed Geocentric with respect to the WGS84 ellipsoid. No additional arguments are supported. An example spatial reference frame definition of this format is [ "GC" ].

- " WM" - Web Mercator projection used for all web mapping (slippy maps). An example spatial reference frame definition of this format is [ "WM" ].

If no geoSystem field is specified, the default value is [ GD", "WE" ].

## 25.2.4 Specifying geospatial coordinates

Once the spatial reference frame has been defined, a single geographic coordinate is specified as an SFVec3d. Lists of geographic coordinates are encoded as an MFVec3d. The meaning of each component value depends upon the particular spatial reference frame that was defined via the geoSystem field in the same node. Given the following geoSystem definitions, the meaning of each component is defined as follows.

- GD: (<latitude>, <longitude>, <elevation>) or (<longitude>, <latitude>, <elevation>). The order of latitude and longitude is controlled by the geoSystem field. If "latitude_first" is specified, the order is latitude then longitude. If "longitude_first" is specified, the order is longitude then latitude. If neither is specified, "latitude_first" is the default. Elevation is always specified third. Latitude and longitude are given in units of angle base units. The following assumes an angle base unit of degrees. If a UNIT statement for angle base units has been provided, the following values for latitude and/or longitude should be suitable converted to that angle base units. Latitude is in the range −90..+90, and longitude can be in the range −180..+180 or 0..360 (0 deg longitude is the same point in both cases). Longitudinal values are relative to the Greenwich Prime Meridian. Elevation is given in units of length base units above the ellipsoid (the default) or above the WGS84 geoid (if you supplied the "WGS84" parameter in the geoSystem field).
  EXAMPLE (37.4506, −122.1834, 0) is the latitude/longitude coordinate for Menlo Park, California, USA.

- UTM: (<northing>, <easting>, <elevation>) or (<easting>, <northing>, <elevation>). The order of northing and easting is controlled by the geoSystem field. If "northing_first" is specified, the order is northing then easting. If "easting_first" is specified, the order is easting then northing. If neither is specified, "northing_first" is the default. Elevation is always specified third. Northings, eastings, and elevation are all given in units of length base units. The zone of the coordinate, and whether it is in the southern hemisphere, are defined in the geoSystem string. Elevation is given with reference to the ellipsoid (the default) or the WGS84 geoid (if the "WGS84" parameter is specified in the geoSystem field).
  EXAMPLE (4145173, 572227, 0) is the zone 10 northern hemisphere UTM coordinate for Menlo Park, California, USA.

- GC: (<x>, <y>, <z>). These values are all given in units of metres. The coordinate represents an offset from the center of the planet, based upon the WGS84 ellipsoid. The z-axis passes through the poles while the x-axis cuts through the latitude/longitude coordinate (0,0) degrees.
  EXAMPLE (−2700301, −4290762, 3857213) is the geocentric coordinate for Menlo Park, California, USA.

- WM: (<x>, <y>, <elevation>). These values are all given in units of metres. The x and y values represent Web Mercator coordinates with an origin at 0 degrees latitude and longitude, based upon the WGS84 ellipsoid. The elevation is also with respect to the WGS84 ellipsoid.
  EXAMPLE (-13601393.87, 4502102.12, 0) is the Web Mercator coordinate for Menlo Park, California, USA.

## 25.2.5 Dealing with high-precision coordinates

Most computer graphics systems, including X3D, use single-precision floating point values to model and render all geometry. This is a natural design constraint since computer graphics typically deals with small screens (up to around 1600 x 1280 pixels), and locally bounded regions. As a result, there is no need to use double-precision values because any increases in accuracy that it brings would be lost in sub-pixel noise.

However, single-precision is insufficient to model data over the range of the earth at accurate ground resolutions. With only 23 bits of mantissa, a coordinate can be accurate to only one part in 8 million (223-1); or about 6 or 7 decimal digits of precision. Since the equatorial radius of the earth (considered as an example planetary body) is 6,378,137 m (under the WGS84 ellipsoid), it is not possible to achieve resolutions better than around 0.8 metres using single-precision floating point numbers (6,378,137 / 8,388,607 = 0.8). Below this threshold, various floating point rounding artifacts such as vertices coalescing and camera jitter will occur.

This geo-referencing problem is one avoided by establishing a geo-referenced local coordinate system (LCS). An absolute geo-referenced location is defined as the origin of the LCS. This becomes the reference point that correlates to the X3D world's (0,0,0) origin. Any subsequent geospatial locations are translated into X3D's Cartesian coordinate system relative to this LCS origin. Moreover, by allowing the user to define these local frames easily, the creator of the geo-referenced data uses the accuracy of a single-precision floating point representation by creating X3D worlds of only limited local extent. This is the purpose of the GeoOrigin node as specified via the geoOrigin field of the geographic X3D nodes. The GeoOrigin node and all geoOrigin fields are often unnecessary since X3D browsers can automatically provide local origins as necessary).

To illustrate this concept, imagine an example where the GeoOrigin is specified as (310385.0 e, 4361550.0 n, 0 m, zone 13) in UTM coordinates. This may be transformed to a double-precision geocentric coordinate of (−1459877.12, −4715646.92, 4025213.19). Then a supplied absolute UTM coordinate of (310400.0 e, 4361600.0 n, 0 m, zone 13) may be transformed internally to a geocentric coordinate of (−1459854.51, −4715620.48, 4025252.11). Finally, this absolute geocentric coordinate can be transformed to a single-precision local Cartesian coordinate system by subtracting the GeoOrigin location to give (22.61, 26.44, 38.92), which is within single-precision range.

## 25.2.6 Geospatial navigation issues

There are a number of navigation issues that are specific to the task of browsing large geographic areas. One important issue is addressed here, that of elevation scaled velocity.

The velocity at which users can navigate around a world should depend upon their height above the terrain.

EXAMPLE When flying over the coast at a height of 100 metres above the terrain, a velocity of 100 metres per second might be considered relatively fast. However, when approaching the earth from outer space, a velocity of 100 metres per second would be intolerably slow. Creators of geographic visualization systems have therefore learned to scale the velocity of the user's navigation in an attempt to maintain a constant pixel flow across the screen. A simple linear relationship between velocity and the user's elevation above an ellipsoid such as WGS84 often provides an acceptable and easily computable solution to this problem. This behavior is addressed by the GeoViewpoint node.

# 25.3 Node reference

## 25.3.1 GeoCoordinate

    GeoCoordinate : X3DCoordinateNode {
      SFNode   [in,out] metadata  NULL        [X3DMetadataObject]
      MFVec3d  [in,out] point     []          (-∞,∞)
      SFNode   []       geoOrigin NULL        [GeoOrigin]
      MFString []       geoSystem ["GD","WE"] (see 25.2.3)
    }

The GeoCoordinate node specifies a list of coordinates in a spatial reference frame. It is used in the coord field of vertex-based geometry nodes including IndexedFaceSet, IndexedLineSet, and PointSet.

The geoOrigin field is used to specify a local coordinate frame for extended precision as described in 25.2.5 Dealing with high-precision coordinates.

The geoSystem field is used to define the spatial reference frame and is described in 25.2.3 Specifying a spatial reference frame.

The point array is used to contain the actual geospatial coordinates and should be provided in a format consistent with that specified for the particular geoSystem (see above). The geospatial coordinates are transparently transformed into a geocentric, curved-earth representation. For example, this would allow a geographer to create a X3D world where all coordinates are specified in terms of latitude, longitude, and elevation.

## 25.3.2 GeoElevationGrid

    GeoElevationGrid : X3DGeometryNode {
      MFDouble [in]     set_height
      SFNode   [in,out] color           NULL        [X3DColorNode]
      SFNode   [in,out] metadata        NULL        [X3DMetadataObject]
      SFNode   [in,out] normal          NULL        [X3DNormalNode]
      SFNode   [in,out] texCoord        NULL        [X3DTextureCoordinateNode]
      SFFloat  [in,out] yScale          1.0         [0,∞)
      SFBool   []       ccw             TRUE
      SFBool   []       colorPerVertex  TRUE
      SFDouble []       creaseAngle     0           [0,∞)
      SFVec3d  []       geoGridOrigin   0 0 0       (-∞,∞)
      SFNode   []       geoOrigin       NULL        [GeoOrigin]
      MFString []       geoSystem       ["GD","WE"] (see 25.2.3)
      MFDouble []       height          [0 0]       (-∞,∞)
      SFBool   []       normalPerVertex TRUE
      SFBool   []       solid           TRUE
      SFInt32  []       xDimension      0           (0,∞)
      SFDouble []       xSpacing        1.0         [0,∞)
      SFInt32  []       zDimension      0           (0,∞)
      SFDouble []       zSpacing        1.0         [0,∞)
    }

The GeoElevationGrid node specifies a uniform grid of elevation values within some spatial reference frame. These are then transparently transformed into a geocentric, curved-earth representation. For example, this would allow a geographer to create a height field where all coordinates are specified in terms of latitude, longitude, and elevation.

The fields color, colorPerVertex, texCoord, normal, and normalPerVertex all have the same meaning as for ElevationGrid (see 13.3.4 ElevationGrid). Similarly, if necessary, tessellation is applied as specified in 13.3.4 ElevationGrid.

The ccw, solid, and creaseAngle fields are described in 11.2.3 Common geometry fields.

The geoOrigin field is used to specify a local coordinate frame for extended precision as described in 25.2.5 Dealing with high-precision coordinates.

The geoSystem field is used to define the spatial reference frame and is described in 25.2.3 Specifying a spatial reference frame.

The geoGridOrigin field specifies the geographic coordinate for the south-west corner (bottom-left) of the dataset. This value should be specified as described in 25.2.4 Specifying geospatial coordinates.

The height array contains xDimension × zDimension floating point values that represent elevation above the ellipsoid or the geoid, as appropriate. These values are given in row-major order from west to east, south to north. When the geoSystem is "GD", xSpacing refers to the number of units of longitude in angle base units between adjacent height values and zSpacing refers to the number of units of latitude in angle base units between vertical height values. When the geoSystem is "UTM", xSpacing refers to the number of eastings (length base units) between adjacent height values and zSpacing refers to the number of northings (length base units) between vertical height values.

EXAMPLE If xDimension = n and the grid spans d units horizontally, the xSpacing value should be set to:

> d / ( n−1).

The yScale value can be used to produce a vertical exaggeration of the data when it is displayed. By default, this value is 1.0 (no exaggeration). If this value is set greater than 1.0, all heights will appear larger than actual.

## 25.3.3 GeoLocation

    GeoLocation : X3DGroupingNode {
      MFNode   [in]     addChildren                [X3DChildNode]
      MFNode   [in]     removeChildren             [X3DChildNode]
      MFNode   [in,out] children       []          [X3DChildNode]
      SFBool   [in,out] bboxDisplay    FALSE
      SFVec3d  [in,out] geoCoords      0 0 0       (-∞,∞)
      SFNode   [in,out] metadata       NULL        [X3DMetadataObject]
      SFBool   [in,out] visible        TRUE
      SFNode   []       geoOrigin      NULL        [GeoOrigin]
      MFString []       geoSystem      ["GD","WE"] (see 25.2.3)
      SFVec3f  []       bboxCenter     0 0 0       (-∞,∞)
      SFVec3f  []       bboxSize       -1 -1 -1    [0,∞) or −1 −1 −1
    }

The GeoLocation node provides the ability to geo-reference any standard X3D model. That is, to take an ordinary X3D model, contained within the children field of the node, and to specify its geospatial location. This node is a grouping node that can be thought of as a Transform node. However, the GeoLocation node specifies an absolute location, not a relative one, so content developers should not nest GeoLocation nodes within each other.

The geoOrigin field is used to specify a local coordinate frame for extended precision as described in 25.2.5 Dealing with high-precision coordinates.

The geoSystem field is used to define the spatial reference frame and is described in 25.2.3 Specifying a spatial reference frame.

The geometry of the nodes in children is to be specified in units of metres in X3D coordinates relative to the location specified by the geoCoords field. The geoCoords field should be provided in the format described in 25.2.3 Specifying a spatial reference frame.

The geoCoords field can be used to dynamically update the geospatial location of the model; for example, an event might be sent from a GeoPositionInterpolator node.

In addition to placing a X3D model at the correct geospatial location, the GeoLocation node will also adjust the orientation of the model appropriately. The standard X3D coordinate system specifies that the +Y axis = up, +Z = out of the screen, and +X = towards the right. The GeoLocation node will set the orientation so that the +Y axis is the up direction for that local area (the normal to the tangent plane on the ellipsoid), −Z points towards the north pole, and +X is east.

## 25.3.4 GeoLOD

    GeoLOD : X3DChildNode, X3DBoundedObject {
      SFBool   [in,out] bboxDisplay    FALSE
      SFNode   [in,out] metadata       NULL        [X3DMetadataObject]
      SFBool   [in,out] visible        TRUE
      MFNode   [out]    children                   [X3DChildNode]
      SFInt32  [out]    level_changed
      SFVec3d  []       center         0 0 0       (-∞,∞)
      MFString []       child1Url      []          [URI]
      MFString []       child2Url      []          [URI]
      MFString []       child3Url      []          [URI]
      MFString []       child4Url      []          [URI]
      SFNode   []       geoOrigin      NULL        [GeoOrigin]
      MFString []       geoSystem      ["GD","WE"] (see 25.2.3)
      SFFloat  []       range          10          [0,∞)
      MFString []       rootUrl        []          [URI]
      MFNode   []       rootNode       []          [X3DChildNode]
      SFVec3f  []       bboxCenter     0 0 0       (-∞,∞)
      SFVec3f  []       bboxSize       -1 -1 -1    [0,∞) or −1 −1 −1
    }

The GeoLOD node provides a terrain-specialized form of the LOD node. It is a grouping node that specifies two different levels of detail for an object using a tree structure, where 0 to 4 children can be specified, and also efficiently manages the loading and unloading of these levels of detail.

The level of detail is switched depending upon whether the user is closer or farther than range length base units from the geospatial coordinate center. If provided, the range field contains monotonically increasing values that shall be greater than zero. If no values are provided, the X3D browser is allowed to dynamically choose transition ranges based on performance.

The center field should be specified as described in 25.2.4 Specifying geospatial coordinates.

The geoOrigin field is used to specify a local coordinate frame for extended precision as described in 25.2.5 Dealing with high-precision coordinates.

The geoSystem field is used to define the spatial reference frame and is described in 25.2.3 Specifying a spatial reference frame.

The visible field specifies whether or not the content within a node is visually displayed. The value of this field has no effect on animation behaviors, collision behaviors, event passing, or other non-visual characteristics.

When the user is outside the specified range, only the geometry for rootUrl or rootNode are displayed. When the viewer enters the specified range, this geometry is replaced with the contents of the four children files defined by child1Url through child4Url. The four children files are loaded into memory only when the user is within the specified range. Similarly, these are unloaded from memory when the user leaves this range. Figure 25.1 illustrates this process. The child URLs shall be arranged in the same order as in the figure; i.e., child1Url represents the bottom-left quadtree child. It is valid to specify less than four child URLs; in which case, the GeoLOD should switch to the children nodes when all of the specified URLs have been loaded. This latter feature can support tree structures other than quadtrees, such as binary trees.

Figure 25.1 — Loading of GeoLOD levels

The rootUrl and rootNode fields provide two different ways to specify the geometry of the root tile. You may use one or the other. The rootNode field lets you include the geometry for the root tile directly within the X3D file; whereas the rootUrl field lets you specify a URL for a file that contains the geometry. The result of specifying a value for both of these fields is undefined.

The children field is used to expose a portion of the scene graph for the currently loaded set of nodes. The value returned as an event is an MFNode containing the currently selected tile. This will either be the node specified by the rootNode field or the nodes specified by the child1Url, child2Url, child3Url, and child4Url fields. The GeoLOD node shall generate a new children output event each time the scene graph is changed (EXAMPLE whenever nodes are loaded or unloaded). When the new children event is generated, the GeoLOD node shall also generate a level_changed event with value 0 or 1, where 0 indicates the rootNode field and 1 indicates the nodes specified by the child1Url, child2Url, child3Url, and child4Url fields.

The GeoLOD node may optionally be implemented with support for a cache of the most recent nodes that have been loaded. This cache should be global across all GeoLOD instances in a scene. This will improve performance when navigating large terrain models by avoiding excessive loading and unloading when a user makes small changes in viewpoint.

NOTE Nested GeoLOD nodes can lead to unexpected or undefined behaviour.

## 25.3.5 GeoMetadata

    GeoMetadata : X3DInfoNode, X3DUrlObject {
      SFTime   [in,out] autoRefresh          0.0  [0,∞)
      SFTime   [in,out] autoRefreshTimeLimit 3600.0  [0,∞)
      MFNode   [in,out] data                 []
      SFString [in,out] description          ""
      SFBool   [in,out] load                 TRUE
      SFNode   [in,out] metadata             NULL [X3DMetadataObject]
      MFString [in,out] summary              []
      MFString [in,out] url                  []   [URI]
    }

The GeoMetadata node supports the specification of metadata describing any number of geospatial nodes. This is similar to a WorldInfo node, but specifically for describing geospatial information.

There are a number of standards and representations for geospatial metadata. Rather than adopt any particular standard, the purpose of the GeoMetadata node is to provide links to any of these complete metadata descriptions, with the option to also supply a short, human-readable summary. More specific metadata can be specified using the metadata field available in each node.

The url field is used to specify a hypertext link to an external, complete metadata description. Multiple URL strings can be specified in order to provide alternative locations for the same metadata information. The summary field may be used to specify the format of the metadata in the case where this cannot be deduced easily.

The summary string array contains a set of keyword/value pairs, with each keyword and its subsequent value contained in a separate string; i.e., there should always be an even (or zero) number of strings. This provides a simple, extensible mechanism to include metadata elements that are human-readable and easy to parse. Table 25.5 specifies a number of keywords and the format that should be used to describe their values. If an unknown keyword is found, it (and its associated value) are ignored.

Table 25.5 — GeoMetadata keywords and values

Keyword | Value
--- | ---
title | A name to succinctly identify the dataset to user. For example, "San Francisco, CA".
description | A brief textual description or summary of the content of the dataset. For example, "LANDSAT 7 satellite imagery taken over northern Scotland".
coordinateSystem | The spatial reference frame used to represent the data ( e.g., GD, UTM, or LCC). The list of valid codes that can be used in this field are defined in ISO/IEC 18026. In the case of UTM, the zone number should also be specified in the format "UTM Z x", where the zone number is in the range [1,60]. For example, "UTM Z11".
horizontalDatum | The name of the geodetic datum. The list of valid codes that can be used in this field are defined in ISO/IEC 18026. For example, "W84".
verticalDatum | The name of the vertical datum (geoid). The list of valid codes that can be used in this field are defined in ISO/IEC 18026. For example, "W84".
ellipsoid | The name of the geodetic ellipsoid. The list of valid codes that can be used in this field are defined in ISO/IEC 18026. For example, "WE".
extent | The bounding coordinates for the dataset given in spatial reference frame specified by the coordinateSystem keyword. These are provided in the order eastmost, southmost, westmost, northmost. An example for GD is: "-180.0 -90.0 180.0 90.0".
resolution | The resolution, or ground sample distance, given in units of length base units. For example, "30".
originator | A string defining the originator of the data, for example the author, agency, organization, publisher, etc. For example, "John Doe, Any Corporation, Some Town, Some Country"
copyright | Any appropriate copyright declaration that pertains to the data. For example, "(c) Copyright 2000, Any Corporation. All rights reserved. Freely distributable."
date | A single date/time, or a date/time range, defining the valid time period to which the data pertains. Dates are specified in the format "YYYY MM DD [HH:MM]". Years in the current time period should be specified using four digits (EXAMPLE "1999" or "2001"). Years can have other than four digits and can be negative. A date range is specified by supplying two values separated by a "-" (hyphen) character. An optional time can be supplied should this level of accuracy be required. Times are to be specified in 24-hour format with respect to GMT. For example, "1999 01 01 00:00 - 1999 12 31 23:59".
metadataFormat | A string that specifies the format of the external metadata description specified by the url field of the GeoMetadata node. For example, "FGDC", "ISO TC211", "CEN TC287", or "OGC".
dataUrl | A hypertext link to the source data used to create the X3D node(s) to which this metadata pertains. Multiple dataUrl keyword/value pairs can be specified in order to provide alternative locations for the same source data. For example, "https://www.foo.bar/data/sf1".
dataFormat | A free-text string that describes the format of the source data used to create the X3D node(s) to which this metadata pertains. This refers to the source data specified by the dataUrl keyword (if present). For example, "USGS 5.5-min DEM".

Metadata values from the summary field can be equivalently encoded via MetadataSet containing related X3DMetadataObject nodes.

The data field is used to list all of the other nodes in a scene by DEF name that reference the data described in the GeoMetadata node. For example, if the GeoMetadata node is describing a height field grid, the appropriate GeoElevationGrid node might be included inside the data field. The nodes in the data field are not rendered, so DEF/USE can be used in order to first describe them and then to use them in the scene graph. This approach allows associating multiple data nodes with a single GeoMetadata node, specifying multiple GeoMetadata nodes within a single scene, and also provides a mechanism to easily locate all of the data that pertain to any particular metadata entry. If the data field is not specified, it is assumed that the GeoMetadata node pertains to the entire scene.

## 25.3.6 GeoOrigin

    GeoOrigin : X3DNode {
      SFVec3d  [in,out] geoCoords 0 0 0       (-∞,∞)
      SFNode   [in,out] metadata  NULL        [X3DMetadataObject]
      MFString []       geoSystem ["GD","WE"] (see 25.2.3)
      SFBool   []       rotateYUp FALSE
    }

The GeoOrigin node defines an absolute geospatial location and an implicit local coordinate frame against which geometry is referenced. This node is used to translate from geographical coordinates into a local Cartesian coordinate system which can be managed by the X3D browser.

GeoOrigin node usage is discouraged because different models built with separate GeoOrigin nodes cannot be easily combined. GeoOrigin is still needed in some situations to achieve correct visual fidelity. Relevant GeoOrigin examples may include fine positioning in a global context, to aid deployment to handheld devices which may use lower-precision arithmetic in their graphics pipelines.

The geoCoords field is used to specify a local coordinate frame for extended precision as described in 25.2.5 Dealing with high-precision coordinates.

The geoSystem field is used to define the spatial reference frame and is described in 25.2.3 Specifying a spatial reference frame.

The rotateYUp field is used to specify whether coordinates of nodes that use this GeoOrigin are to be rotated such that their up direction is aligned with the X3D Y axis. The default behavior is to not perform this operation. This means that the local up direction will depend upon the location of the GeoOrigin with respect to the planet surface. The principal reason for performing the rotation is to ensure that standard navigation modes such as "FLY" and "WALK", which assume that +Y = up, will function correctly. Specifying rotateYUp to be TRUE may incur an extra computational overhead in order to perform the rotation for each point.

## 25.3.7 GeoPositionInterpolator

    GeoPositionInterpolator : X3DInterpolatorNode {
      SFFloat  [in]     set_fraction                 (-∞,∞)
      MFFloat  [in,out] key              []          (-∞,∞)
      MFVec3d  [in,out] keyValue         []
      SFNode   [in,out] metadata         NULL        [X3DMetadataObject]
      SFVec3d  [out]    geovalue_changed
      SFVec3f  [out]    value_changed
      SFNode   []       geoOrigin        NULL        [GeoOrigin]
      MFString []       geoSystem        ["GD","WE"] (see 25.2.3)
    }

The GeoPositionInterpolator node provides an interpolator capability where key values are specified in geographic coordinates and the interpolation is performed within the specified spatial reference frame.

The geoOrigin field is used to specify a local coordinate frame for extended precision as described in 25.2.5 Dealing with high-precision coordinates.

The geoSystem field is used to define the spatial reference frame and is described in 25.2.3 Specifying a spatial reference frame.

The fields key, set_fraction, and value_changed have the same meaning as in the PositionInterpolator node.

The keyValue array is used to contain the actual coordinates and should be provided in a format consistent with that specified for the particular geoSystem.

The geovalue_changed field outputs the the interpolated coordinate in the spatial reference frame specified by geoSystem. This can be passed to other GeoX3D nodes that support a field of this form ( e.g., GeoViewpoint and GeoLocation).

## 25.3.8 GeoProximitySensor

    GeoProximitySensor : X3DEnvironmentalSensorNode {
      SFVec3d    [in,out] center                   0 0 0       (-∞,∞)
      SFString   [in,out] description              ""
      SFBool     [in,out] enabled                  TRUE
      SFVec3d    [in,out] geoCenter                0 0 0       (-∞,∞)
      SFNode     [in,out] metadata                 NULL        [X3DMetadataObject]
      SFVec3f    [in,out] size                     0 0 0       [0,∞)
      SFVec3f    [out]    centerOfRotation_changed
      SFTime     [out]    enterTime
      SFTime     [out]    exitTime
      SFVec3d    [out]    geoCoord_changed
      SFBool     [out]    isActive
      SFRotation [out]    orientation_changed
      SFVec3f    [out]    position_changed
      SFNode     []       geoOrigin                NULL        [GeoOrigin]
      MFString   []       geoSystem                ["GD","WE"] (see 25.2.3)
    }

The GeoProximitySensor node generates events when the viewer enters, exits, and moves within a region in space (defined by a box).
A GeoProximitySensor node generates isActive events as the viewer enters and exits the rectangular box defined by its geoCenter and size fields. This box is oriented tangent to the ellipsoid in a local coordinate system. Starting with version 3.3, the geoCenter field is renamed center.
The fields geoSystem and geoOrigin are described in 25.2.3 Specifying a spatial reference frame and 25.2.5 Dealing with high-precision coordinates, respectively.
The geoCoord_changed generates an event that returns the geospatial coordinates of the viewer's position in the spatial reference frame specified by geoSystem for the viewer's position whenever a position_changed event is generated. The geoCoord_changed value corresponds to the world position returned by position_changed.

The remaining fields are defined in 22.4.1 ProximitySensor.

## 25.3.9 GeoTouchSensor

    GeoTouchSensor : X3DTouchSensorNode {
      SFString [in,out] description         ""
      SFBool   [in,out] enabled             TRUE
      SFNode   [in,out] metadata            NULL        [X3DMetadataObject]
      SFVec3f  [out]    hitNormal_changed
      SFVec3f  [out]    hitPoint_changed
      SFVec2f  [out]    hitTexCoord_changed
      SFVec3d  [out]    hitGeoCoord_changed
      SFBool   [out]    isActive
      SFBool   [out]    isOver
      SFTime   [out]    touchTime
      SFNode   []       geoOrigin           NULL        [GeoOrigin]
      MFString []       geoSystem           ["GD","WE"] (see 25.2.3)
    }

A GeoTouchSensor node tracks the location and state of a pointing device and detects when the user points at geometry contained by the parent group of the GeoTouchSensor. This node provides the same functionality as a TouchSensor but also provides the ability to return the geographic coordinate under the pointing device.

The description field in the GeoTouchSensor node specifies a textual description of the GeoTouchSensor node. This may be used by X3D browser-specific user interfaces that wish to present users with more detailed information about the GeoTouchSensor.

A GeoTouchSensor can be enabled or disabled by sending an event of value TRUE or FALSE to the enabled field. A disabled GeoTouchSensor does not track user input or send events.

The geoOrigin field is used to specify a local coordinate frame for extended precision as described in 25.2.5 Dealing with high-precision coordinates.

The geoSystem field is used to define the spatial reference frame and is described in 25.2.3 Specifying a spatial reference frame.

The fields hitNormal_changed, hitPoint_changed, hitTexCoord_changed, isActive, isOver, and touchTime all have the same meaning as in the TouchSensor node.

The hitGeoCoord_changed field is generated while the pointing device is pointing towards the GeoTouchSensor's geometry ( i.e., when isOver is TRUE). It is a field containing the geospatial coordinate for the point of intersection between the pointing device's location and the underlying geometry. The value of the geoSystem string defines the spatial reference frame of the geospatial coordinate. For example, given the default geoSystem value of "GD", the hitGeoCoord_changed field will be in the format (<latitude> <longitude> <elevation>) (see 25.2.4 Specifying geospatial coordinates).

## 25.3.10 GeoTransform

    GeoTransform : X3DGroupingNode {
      MFNode     [in]     addChildren                  [X3DChildNode]
      MFNode     [in]     removeChildren               [X3DChildNode]
      MFNode     [in,out] children         []          [X3DChildNode]
      SFBool     [in,out] bboxDisplay      FALSE
      SFVec3d    [in,out] geoCenter        0 0 0       (-∞,∞)
      SFNode     [in,out] metadata         NULL        [X3DMetadataObject]
      SFRotation [in,out] rotation         0 0 1 0     [-1,1] or (-∞,∞)
      SFVec3f    [in,out] scale            1 1 1       (-∞,∞)
      SFRotation [in,out] scaleOrientation 0 0 1 0     [-1,1] or (-∞,∞)
      SFVec3f    [in,out] translation      0 0 0       (-∞,∞)
      SFBool     [in,out] visible          TRUE
      SFVec3f    []       bboxCenter       0 0 0       (-∞,∞)
      SFVec3f    []       bboxSize         -1 -1 -1    [0,∞) or −1 −1 −1
      SFNode     []       geoOrigin        NULL        [GeoOrigin]
      MFString   []       geoSystem        ["GD","WE"] (see 25.2.3)
    }

The GeoTransform node is a grouping node that defines a coordinate system for its children to support the translation and orientation of geometry built using GeoCoordinate nodes within the local world coordinate system. The X-Z plane of a GeoTransform coordinate system is tangent to the ellipsoid of the spatial reference frame at the location specified by the geoCenter field.

The geoCenter field specifies, in the spatial reference frame specified by the geoSystem field, the location at which the local coordinate system is centered.
The fields geoSystem and geoOrigin are described in 25.2.3 Specifying a spatial reference frame and 25.2.5 Dealing with high-precision coordinates, respectively.
The remaining fields are defined in 10.4.4 Transform.

## 25.3.11 GeoViewpoint

    GeoViewpoint : X3DViewpointNode {
      SFBool     [in]     set_bind
      SFVec3d    [in,out] centerOfRotation  0 0 0             (-∞,∞)
      SFString   [in,out] description       ""
      SFFloat    [in,out] farDistance       -1                -1 or (0,∞)
      SFFloat    [in,out] fieldOfView       π/4               (0,π)
      SFBool     [in,out] jump              TRUE
      SFNode     [in,out] metadata          NULL              [X3DMetadataObject]
      SFNode     [in,out] navigationInfo    NULL              [NavigationInfo]
      SFFloat    [in,out] nearDistance      -1                -1 or (0,∞)
      SFRotation [in,out] orientation       0 0 1 0           (-∞,∞) or -1 1
      SFVec3d    [in,out] position          0 0 100000        (-∞,∞)
      SFBool     [in,out] retainUserOffsets FALSE
      SFBool     [in,out] viewAll           FALSE
      SFTime     [out]    bindTime
      SFBool     [out]    isBound
      SFNode     []       geoOrigin         NULL              [GeoOrigin]
      MFString   []       geoSystem         ["GD","WE"]       (see 25.2.3)
      SFFloat    []       speedFactor       1.0               [0,∞)
    }

The GeoViewpoint node allows the specification of a viewpoint in terms of a geospatial coordinate. This node can be used wherever a Viewpoint node can be used and can be combined with Viewpoint nodes in the same scene. The fieldOfView, jump, description, set_bind, bindTime, and isBound fields and events have the same behavior as the standard Viewpoint node. When a GeoViewpoint node is bound, it overrides the currently bound Viewpoint and NavigationInfo nodes in the scene.

The geoOrigin field is used to specify a local coordinate frame for extended precision as described in 25.2.5 Dealing with high-precision coordinates.

The geoSystem field is used to define the spatial reference frame and is described in 25.2.3 Specifying a spatial reference frame.

The position is used to define the actual coordinate at which the viewpoint is to be located. It should be provided in a format consistent with that specified by geoSystem. There is also a set_position field which can be routed from the geovalue_changed field of a GeoPositionInterpolator node in order to animate the position of the GeoViewpoint.

The orientation string defines a relative orientation from the local orientation frame that is defined by the position field. By default, the orientation of the viewpoint will always be aligned such that the +Y axis is the up vector for the local area (the normal to the tangent plane on the ellipsoid), -Z points towards the north pole, and +X is east. Therefore, if a GeoViewpoint is created that always looked straight down, no matter where on the planetary body is being observed, an orientation value of [ 1 0 0 -1.57 ] is used. The set_orientation field can be routed from the value_changed field of an OrientationInterpolator in order to animate the orientation of the GeoViewpoint.

The GeoViewpoint node may be implemented as if there is an embedded NavigationInfo node that is bound and unbound with the GeoViewpoint node. As such, a X3D browser should internally set the speed, avatarSize, and visibilityLimit fields to an appropriate value for the viewpoint's elevation. The X3D browser should also continually update the speed field as the user moves in order to support elevation scaled velocity (see 25.2.6 Geospatial navigation issues). It is recommended that the speed of user interaction be defined as:

> ( elevation / 10.0 ) speed base units

where elevation is the user's elevation above the WGS84 ellipsoid in units of speed base units. It is also recommended that the same scaling factor be applied to the avatarSize vector.

The speedFactor field of the GeoViewpoint node is used as a multiplier to the elevation-based velocity that the node sets internally; i.e., this is a relative value and not an absolute speed as is the case for the NavigationInfo node.

The viewAll field controls behavior in the same manner as occurs for Viewpoint node.

# 25.4 Support levels

The Geospatial component provides one level of support as specified in Table 25.6.

Table 25.6 — Geospatial component support levels

Level | Prerequisites | Nodes/Features | Support
--- | --- | --- | ---
1 | Core 1 Time 1 Networking 1 Grouping 3 Rendering 1 Shape 1 Geometry3D 1 Interpolator 1 Point device sensor 1 Navigation 1 |  |
|  | GeoCoordinate | All fields fully supported.
|  | GeoElevationGrid | All fields fully supported.
|  | GeoLocation | All fields fully supported.
|  | GeoLOD | All fields fully supported.
|  | GeoMetadata | All fields fully supported.
|  | GeoOrigin | All fields fully supported.
|  | GeoPositionInterpolator | All fields fully supported.
|  | GeoTouchSensor | All fields fully supported.
|  | GeoViewpoint | All fields fully supported.
2 | Core 1 Time 1 Networking 1 Grouping 3 Rendering 1 Shape 1 Geometry3D 1 Interpolator 1 Environmental device sensor 1 Navigation 1 |  |
|  | All Level 1 Geospatial nodes | All fields fully supported.
|  | GeoProximitySensor | All fields fully supported.
|  | GeoTransform | All fields fully supported.