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 part of  ISO/IEC 19775. 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.

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.

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.

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

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 must 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", "WGS84" "GD" ], 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 (2²³-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

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
}

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 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.

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       (-∞,∞) 
  SFVec3d    [in,out] center                   0 0 0       (-∞,∞) (starting with vs. 3.3)
  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       (-∞,∞) (0,∞)
  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.