View source for Terrain height/slope visualization via autogenerated texture coordinates

=== Summary of discussion on geospatial email list in 7/2015 ===

Looking for convenient ways to color contour elevation or slope of terrain (or other surfaces), new (GEO-)HEIGHT and (GEO-)SLOPE modes for the TextureCoordinateGenerator node were proposed and developed. With this modes, it is only necessary to provide a colormap as a 1d texture in the Appearance node and the TextureCoordinateGenerator node with one of the new modes with a geometry node such (Geo)ElevationGrid in order to achieve the desired effect. An implementation of the new modes is available in a github fork of x3dom.

=== Motivation and initial discussion ===

It is very common to contour terrain DEMs or to color by them elevation. A recommended solution on the x3dom-user mailing list was to define texture coordinates as [normalized height, 0] for each grid point and then use a 1d texture to map colors to height. This is a good solution since it allows for easily swapping out the color scale. For example, it is possible to limit the number of colors for a striped, contoured appearance.

It is very possible to use this solution for a (Geo)Elevationgrid: calculate the texture coordinates from the height field and put them in a texture coordinate node. However, since it is such a common situation and since there is a (minor) calculation involved, it would make sense to make this procedure much more accessible in some way. At first, introducing a (convenience) boolean option "heightTexCoords" to GeoElevationgrid which automatically generates the texture coordinates based on height was considered.

By default the option would determine min. and max. of the height field and generate texture coordinates (height-min.)/(max.-min.) , 0 for each node.

It would then be also very useful to able to specify min. and max. height directly by a MFDouble field  "height_range" [min., max.] .

Another option may be discretization of the texture coordinates into a limited number of values by a SFInt32 field "height_steps": U_discrete = int(U * hsteps)/hsteps or so where U is the normalized height. This effect can be achieved with higher fidelity by a discretized texture map as well but would be convenient to have. For example, it would be straightforward to generate 100m contours by providing a height_range of [-3000,0] and height_steps of 30. Some more discussion and thought would be required since the contours would not be very accurate due to information loss. It would be probably better to have such a discretization option for the texture map.

If multiple options are provided, the source for texture coordinates would need to be prioritized:

1) explicitly defined: TextureCoordinate node
2) heightTexCoords
3) default as in spec.

Testing for correctness should be possible by comparing manually added texture coordinates with automatically generated texture coordinates.

: Other considerations from an application perspective are:

# It would be nice if this technique could be applied to mesh data as well as grid data; 
# Marine geologists and geophysicists like to shade the color according to slope magnitude or synthetic illumination (see the man page for mbm_grdtiff). With X3D we can add a light to the scene and get synthetic illumination, but shading by slope magnitude would have to be done some other way. The mbm_grdtiff tool has several options that serve to distill decades of use case capture – maybe some of these are optional attributes that could go along with a new heightTexCoords attribute.
# If a color node is used there should be a way to pass in a color lookup table. (An advantage of using the more general texture approach is that the x3d author specifies the color lookup with the texture.)

Finding a general solution for mesh data including IndexedFaceSets leads to the suggestion to define a new mode for TextureCoordinateGenerator. Then it would be necessary to distinguish between geocentric coordinates and regular coordinates to determine height, making the problem a little complex.

Slope or dip based coloring/texturing could be quite interesting and is something we actually do quite a bit in geosciences. It would be possible to calculate slope (and aspect) for each grid node, for example according to

http://resources.arcgis.com/en/help/main/10.1/index.html#//009z000000vz000000

using the 3x3 grid around a node. At the borders, one could just use the closest values to fill in. It should also be possible to use the calculated mesh normals.

Another approach would be using normals which are calculated or provided for mesh vertices. Since geocentric positions are used, it would be necessary to use a reference vertical direction.

The advantage of using colors would be that a color node may be a bit more user friendly than textures. However, X3D only has rgb colors, not palleted colors, and pixel textures effectively allow for using color values similar to color nodes.

=== Planning discussion on the TextureCoordinateGenerator node ===

The TextureCoordinateGenerator mode appears to be designed to enable dynamic updates of texture coordinates based on eye position/orientation, vertex positions and vertex normals using a number of modes which correspond to fixed functions of these inputs. As an OpenGL function this concept is replaced by fully programmable shaders. For example, x3dom implements the SPHERE mode in code inserted into the full shader used for rendering. Other modes, such as SPHERE-LOCAL are implemented outside the shader because they are static with respect to the eye position/orientation.

A SLOPE mode would be somewhat similar SPHERE-LOCAL mode in that it would use components of the local normal, here the z component for S and 0 for T. This should would work for non-geospatial meshes where the XZ plane is horizontal. Similarly, it should be possible to add a HEIGHT mode which uses the normalized Y coordinate for S.

One presumably could do this as part of the shader code as well although in x3dom it is harder to see where to start with such an effort. Perhaps follow how the SPHERE mode is coded ?

There is a "COORD" mode in the spec.

http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#t-Texturecoordgeneration

which uses vertex coordinates in some way and could be similar to a HEIGHT mode. It does not seem to be implemented in x3dom.

For geospatial meshes it makes sense to define a specialized mode,  a GEO-HEIGHT mode, to indicate that the coordinate system is geocentric. It would be first necessary to derive the heights from the geocentric mesh coordinates (potentially taking into account GeoOrigin transformations). The other option would be to look into the parent node, and use the height field in case of GeoElevationGrid, or the z-component of GeoCoordinates but this would not work for geocentric geosystem.

By default, S would be scaled to full height range of the mesh. One could use the parameter field of the TextureCoordinateGenerator node to specify a custom height range and perhaps a discretization as outlined earlier.

For a GEO-SLOPE mode, it would be necessary to calculate the angle between the provided normal and the local Up (or Down) direction. For rotateYUp scenes presumably one could just use the normal, or undo the rotation.

That brings up the question if it is acceptable to introduce geo-modes to TextureCoordinateGenerator in terms of x3d components and profiles. It may be necessary to introduce a GeoTextureCoordinateGenerator node ?

In summary, leaning towards using new TextureCoordinateGenerator modes instead of new GeoElevationGrid fields  would cover more use cases. However, it requires some more processing to deal with the geocentric coordinates, eg. may be a bit harder to implement. In x3dom, it would touch Mesh.js which is used by a lot of nodes.

The idea came up to use slope and height together to address a 2D Texture in a HEIGHT-SLOPE mode. This would allow for things like white snow not covering steep spots which could remain brown. Another application would be to use a color map with increasing intensity or saturation or darkness of color in the T direction to emphasize steep slopes but still have elevation contouring. This would compete with light-derived shading but may be interesting.

Another standard but not very common use of a 2d color map is to visualize slope and aspect - the direction of slope - together. However, this gets quite far into GIS processing and may be better handled outside of X3D, eg. by customized texture coordinates.


=== Implementation and concrete examples ===

Following the concepts outlined in the discussion the new modes were implemented in a fork of x3dom:

http://andreasplesch.github.io/x3dom/#geoElevationGrid-texture

All examples benefit from reading the descriptons and in particular from looking at the x3d content in the html source.

The implementation plugs into the calcTexCoords() function in the x3dom Mesh.js file:

https://github.com/andreasplesch/x3dom/blob/heightmode/src/Mesh.js#L342 

In this implementation no transformations by parent transform, geolocation or geotransform nodes were applied to the mesh coordinates at the stage when the texture coordinates are generated. This means that two identical shapes would be textured identically even after one is translated vertically by a parent transform.  This is what may work best in most cases but important to keep in mind when using the parameters field to define a custom height range. The height range refers to the local, untransformed height range. 

=== New modes proposal ===

This request for feedback and consideration was distributed and added to web3d Mantis tracker:

<pre style="white-space: pre-wrap; 
white-space: -moz-pre-wrap; 
white-space: -pre-wrap; 
white-space: -o-pre-wrap; 
word-wrap: break-word;">
In data visualization it is often useful to color the y component (height) of a mesh. This is particularly evident for ElevationGrids where contouring is a proven visualization method. Therefore it would be very useful to have a new HEIGHT mode which generates texture coordinates based on the y coordinate. The most useful default would be to automatically scale to the range in height of the mesh. The parameter field could be used to define a custom range in height which corresponds to the 0 to 1 range of the S texture coordinate. T would be set to 0, eg. a 1d texture map would be expected.

Here is an example of the use a height mode:

http://andreasplesch.github.io/x3dom/GeoElevationGrid_texture/terrain_height.xhtml

which was tentatively implemented in a forked x3dom (Mesh.js).

Similary, it is often useful to visualize the spatial gradient of a surface or the slope. A new SLOPE mode for TextureCoordinateGenerator would generate texture coordinates based on the local slope angle ( implementations could derive the slope on the local normal ). By default slopes from 0 to 90 degrees would be scaled to the 0 to 1 range of the S texture coordinate. The  parameter field could be used to define a custom range. T would be set to 0 and a 1d texture map would be expected.

Here are two examples:

http://andreasplesch.github.io/x3dom/GeoElevationGrid_texture/puddle_slope.xhtml

and

http://andreasplesch.github.io/x3dom/GeoElevationGrid_texture/face_slope.xhtml

using a tentative implementation in a forked x3dom (Mesh.js).

One could also imagine (and quite easily implement) another mode "HEIGHT-SLOPE" which uses both attributes as S and T respectively  and a 2d texture map as suggested by Simon Thum on the geospatial list.

These modes would be somewhat similar to the existing VERTEX and SPHERE-LOCAL modes but aimed at 1d texture maps.

Finally, geospatially registered meshes would need equivalent modes using height above the geoid and slope relative to the local tangential plane to the geoid.
</pre>

=== Additional considerations for specification ===

It needs to be decided if height and slope are derived from world or local coordinates, eg. if accumulated parent transformation need to be taken into account. Implementation considerations for both outside and inside of shaders favour local coordinates. GEO-HEIGHT is relative to the ellipsoid defined by the geoSystem used by (coordinates) of the parent mesh. GEO-SLOPE is relative to the local vertical direction at mesh positions.

Another question if it is acceptable to introduce geo-modes to TextureCoordinateGenerator which is otherwise not part of the geospatial component in terms of x3d components and profiles. It may be necessary to introduce a GeoTextureCoordinateGenerator node ?

Above suggests to use degrees as a unit to define a custom range for slopes with the parameter field. However, X3D generally uses radians as a unit for angles. It may be more consistent, though somewhat less intuitive, to use radians for a custom slope range as well.

Looking farther ahead, it may become a suggestion to deprecate the CoordinateTextureGenerator node and favour shader use for dynamic generation of texture coordinates. In this case, a similar node with a name like CoordinateTextureSource which produces static texture coordinates based on a mode may make sense to introduce.

=== Shaded relief effects ===

In map making, relief shading is a standard method and GIS systems often base such shading on a custom sun location and local slope.  http://www.reliefshading.com/ covers this method in depth. Using vertically exaggerated terrain and/or a low altitude of the sun are often used to bring out subtle features in high resolution DEMs. 

It may be possible to replicate this type of relief shading with a slope based texture in another mode of TextureCoordinateGenerator with parameters for the sun location and artificial vertical exaggeration. However, this shading would compete with the regular (light defined) X3D shading. It would be a sort of baked in shading. In many case, a good but more demanding solution may be to have a lower resolution terrain mesh, and a higher resolution image texture showing the detailed relief shading draped on top.

For shaded relief purposes with X3D standard methods, let's think about using a directional light since the sun's rays are effectively parallel.

http://suncalc.net/ shows the sun's position in the sky anywhere, anytime. It uses https://github.com/mourner/suncalc to calculate the sun's position in the sky. It could be quite insightful to use this with geospatial x3dom to predict/reconstruct the lighting situation at some time, perhaps for accident reconstruction and such. This is even more interesting since it turns out that x3dom experimental shadowing works pretty well geospatial terrain.
<!--
Shaded relief shading should be simpler. Since azimuth and elevation of the sun for shaded relief purposes is defined with respect to local north and the local horizontal, it should be possible use a GeoLocation node with a location close the geoelevationgrid in order to rotate the directional light orientation properly with respect to the orientation of the local tangential plane. The directional light orientation would be just azimuth and elevation as a vector.

One could use the NormalInterpolator node to vary the sun light orientation. The node uses a spherical interpolation. Interpolating say from horizontal NE towards SW orientation (-1, 0, -1) to vertical downwards (0, -1, 0) to horizontal SW to NE (1, 0, 1) and routing to the orientation field of the light should produce a nice variation of shading to explore. I may try that.

[Alternatively, it should be also possible to use an OrientationInterpolator node routed to a transform node.]

Another important option for shaded relief purposes is to exaggerate the vertical for more pronounced shading. So it would be nice to have option to do this without actually vertically exaggerating the vertex positions. I suspect the shaders in x3dom use the mesh normals to produce the default shading based on the lights in the scene. If not provided as is often the case, the normals are calculated from the vertex positions. It would be possible to manipulate the normal calculation to use a scaled up Y coordinate of a vertex. However, this would not work for geocentric coordinates. For GeoElevationGrid it may be possible to calculate exaggerated normals, then non-exaggerated normals and positions, and texMode based texcoords, and finally replace the normals with exaggerated normals.


The idea of using a geolocated directional light worked quite well. Here is an animated example along the lines I had described:

http://andreasplesch.github.io/x3dom/GeoElevationGrid_texture/terrain_sun.xhtml

Shaded relief in 3d looks pretty good. It should be possible to restrict lights to certain objects, eg. lights are supposed to be only applied to the objects in their parent group. This way one could have shaded relief on terrain but "normal" lighting for all other objects.

Since this works well, I do not think it is very advantageous to do much about vertical exaggeration for shading purposes.

The last item would be to see if it is possible to use a PixelTexture to define a stepwise color function, eg. to have a limited number of color bands for a striped appearance mimicking actual contour lines. This probably requires the "NEAREST" magFilter of the TextureProperty node.


...
<!--
=== shaded relief effects ===

http://www.reliefshading.com/

For shaded relief purposes, let's think about using a directional light since the sun's rays are effectively parallel.

http://suncalc.net/ shows the sun's position in the sky anywhere, anytime. It uses https://github.com/mourner/suncalc to calculate the sun's position in the sky. It could be fun to use this with geospatial x3dom to predict/reconstruct the lighting situation at some time, perhaps for accident reconstruction and such.

Shaded relief shading should be simpler. Since azimuth and elevation of the sun for shaded relief purposes is defined with respect to local north and the local horizontal, it should be possible use a GeoLocation node with a location close the geoelevationgrid in order to rotate the directional light orientation properly with respect to the orientation of the local tangential plane. The directional light orientation would be just azimuth and elevation as a vector.

One could use the NormalInterpolator node to vary the sun light orientation. The node uses a spherical interpolation. Interpolating say from horizontal NE towards SW orientation (-1, 0, -1) to vertical downwards (0, -1, 0) to horizontal SW to NE (1, 0, 1) and routing to the orientation field of the light should produce a nice variation of shading to explore. I may try that.

[Alternatively, it should be also possible to use an OrientationInterpolator node routed to a transform node.]

Another important option for shaded relief purposes is to exaggerate the vertical for more pronounced shading. So it would be nice to have option to do this without actually vertically exaggerating the vertex positions. I suspect the shaders in x3dom use the mesh normals to produce the default shading based on the lights in the scene. If not provided as is often the case, the normals are calculated from the vertex positions. It would be possible to manipulate the normal calculation to use a scaled up Y coordinate of a vertex. However, this would not work for geocentric coordinates. For GeoElevationGrid it may be possible to calculate exaggerated normals, then non-exaggerated normals and positions, and texMode based texcoords, and finally replace the normals with exaggerated normals.


The idea of using a geolocated directional light worked quite well. Here is an animated example along the lines I had described:

http://andreasplesch.github.io/x3dom/GeoElevationGrid_texture/terrain_sun.xhtml

Shaded relief in 3d looks pretty good. It should be possible to restrict lights to certain objects, eg. lights are supposed to be only applied to the objects in their parent group. This way one could have shaded relief on terrain but "normal" lighting for all other objects.

Since this works well, I do not think it is very advantageous to do much about vertical exaggeration for shading purposes.

The last item would be to see if it is possible to use a PixelTexture to define a stepwise color function, eg. to have a limited number of color bands for a striped appearance mimicking actual contour lines. This probably requires the "NEAREST" magFilter of the TextureProperty node.

-->