Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Tutorial
Demonstra'ng X3D Geospa'al with
oceanographic data
Mike McCann
mccann@mbari.org
Monterey Bay Aquarium Research Ins'tute

Heraklion, Crete, Greece 18 - 21 June 2015
Hands on par'cipa'on
• Watch YouTube video about STOQS:
hMps://www.youtube.com/watch?v=E8wO3qMevV8
• Install your own STOQS server on your laptop
– best done in advance of the tutorial (it takes
a couple of hours with a good Internet
connec'on):
hMps://github.com/stoqs/stoqs/tree/django17upgrade
2

Heraklion, Crete, Greece 18 - 21 June 2015
Tutorial Outline
1. Oceanographic data and X3D Geospa'al
2. Geospa'al Component
3. Browser-database data flow
4. Exercises
3

Heraklion, Crete, Greece 18 - 21 June 2015
Oceanographic data and X3D
Geospa'al
• Ocean: 'me varying 3 dimensional structure
– Spa'al: 1 cm to 100 km
– Temporal: seconds to months
• Datasets: mul'ple feature types
– Point observa'ons: ~30 million measurements
– Geospa'al databases needed
4

Heraklion, Crete, Greece 18 - 21 June 2015
Oceanographic data and X3D
Geospa'al
• X3D: general 3D solu'on
– True mapping of 3D Geospa'al coordinates to
X3D’s Cartesian X, Y, Z coordinates
– Able to exaggerate the ver'cal coordinate
– Cen'meter scale accuracies in geospa'al context
– Support for modern web framework (X3DOM)
– Run'me interac'on – routed events
5

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• ISO Specifica'on
• Mul'ple Implementa'ons
• Geospa'al working group

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
Mul'ple coordinate systems
• Geographic (la'tude, longitude, eleva'on)*
• Geocentric – Cartesian, “ECEF”, “GCC”
• Local X3D – may be offset, may be rotated
* X3D supports other other spa'al reference systems via the
geoSystem aMribute, e.g. “UTM”
7

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
8

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
Makes it easy to use Geo in X3D
• Geo content provided in lat, lon, elev
• X3D browser works in X, Y, Z
• Numerical precision issues
• Naviga'on, e.g. “fly” expects +Y to be “up”
9

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
Handles all the
transforma'ons and precision
calcula'ons needed to work
with geographic data
10

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
X3D Geospa=al Node set
1. GeoCoordinate
2. GeoEleva=onGrid
3. GeoLoca=on
4. GeoLOD
5. GeoMetadata
6. GeoOrigin
X3DOM supported
X3DOM experimental
7. GeoPosi=onInterpolator
8. GeoProximitySensor
9. GeoTouchSensor
10. GeoTransform
11. GeoViewpoint
12. GeoOriginTransform
13. GeoWebMap
11

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
Simplicity of use
• Can build Geometry from GeoCoordinate
nodes and use just like Coordinate nodes
• GeoCoordinates may be specified using
familiar la'tude, longitude, depth numbers
• Nodes like GeoEleva=onGrid work just like
Eleva=onGrid but with lat, lon, depth/elev
12

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
Each node in detail
(building blocks for crea'ng awesomeness)
13

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Specify a list of geographic coordinates
• Usage
– Can use a GeoCoordinate node anywhere an X3D
Coordinate node can go, e.g. PointSet, IndexedFaceSet,
IndexedLineSet, ….
• Uses
– Build models in terms of lat, lon, depth. For example, a
road line segment, a GPS track, a cloud.
1. GeoCoordinate
14

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
<Shape>
<IndexedLineSet colorPerVertex="false”
coordIndex="0 1 2 . . .”
<GeoCoordinate
point="21.316258 -157.886202 0.0,
21.316262 -157.8862 0.0,
21.31626 -157.886193 0.0, . . .”
geoSystem="GD">
<GeoOrigin USE="ORIGIN"/>
</GeoCoordinate>
<Color color="1.0 0.0 0.0"/>
</IndexedLineSet>
</Shape>
1. GeoCoordinate
15

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Define a height field using geographic coordinates
• Usage
– Can use a GeoEleva'onGrid node anywhere an X3D
Eleva'onGrid can go, e.g. the geometry field of a Shape
node
• Uses
– Create terrain models for local or large areas
(automa'cally introduces correct earth curvature)
2. GeoEleva'onGrid
16

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
<Shape>
<Appearance>
<ImageTexture
url="NEPacific50.jpg"/>
</Appearance>
<GeoElevationGrid
geoGridOrigin="15.0 -165.0 0.0"
height="-5416.0, -5496.0, …
xDimension="113" xSpacing="0.5380962885"
zDimension="66" zSpacing="0.5415395186”
yScale="10.0”/>
<TextureCoordinate
point="0.0 0.0, 0.00892857 0.0, ... />
</GeoElevationGrid>
</Shape>
2. GeoEleva'onGrid
17

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Georeference a vanilla X3D model
• Usage
– The GeoLoca'on node is a grouping node that affects the
loca'on of its children. It also sets the orienta'on so that
+Y is “up” for that loca'on.
• Uses
– Place a non-georeferenced model at its correct loca'on
and orienta'on, place an X3D Viewpoint or Eleva'onGrid
at a geographic loca'on
3. GeoLoca'on
18

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
<GeoLocation
containerField="children"
geoSystem="GD"
geoCoords="37.45855
-122.172997 6.5">
<inline url="building.x3dv"/>
</GeoLocation>
3. GeoLoca'on
19

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Level of detail management for mul'-resolu'on terrains
• Usage
– The GeoLOD node is a grouping node that switches
between two resolu'on levels of a quad-tree based upon
distance from a point
• Uses
– Build massive 'led, mul'-resolu'on terrain models where
the browser progressively loads higher resolu'on detail as
you fly into the terrain
4. GeoLOD
20

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
GeoLOD {
center 36.5 -122.4 -2054.4
child1Url "../../trees/2/p0p0.x3dv"
child2Url "../../trees/2/p1p0.x3dv"
child3Url "../../trees/2/p0p1.x3dv"
child4Url "../../trees/2/p1p1.x3dv"
geoOrigin USE ORIGIN
geoSystem "GD"
range 72673.5
rootNode Shape {
appearance Appearance {
texture ImageTexture {
url "../../images/1/p0p0.jpg"
}
}
}
..
}
4. GeoLOD
21

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Include a generic subset of metadata about the geographic
data
• Usage
– Can be thought of as a WorldInfo node, but specifically
designed for describing geographic informa'on
• Uses
– Provide a subset of metadata informa'on about one or
more geographic elements in a scene, and provide links to
full metadata and source files
5. GeoMetadata
22

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
GeoMetadata {
summary [
“title”, “SAN FRANCISCO NORTH, CA”
“description”, “DEM GENERATED FROM 1/24,000 DLG-
SOURCE”
“coordinate-system”, “UTM Z10”
“extent”, “555060.99 4177990.30 543974.53 4191924.61”
“resolution”, “30”
“originator”, “United States Geological Survey (USGS)”
“data-format”, “USGS 7.5 min DEM”
]
data USE GEOEG
url “sanfranciscon.dem”
}
5. GeoMetadata
23

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Offset GCC coordinates to increase floa'ng point precision
• Usage
– You can use a GeoOrigin node only as the value for a
geoOrigin field in another X3D node. Only one GeoOrigin
per scene. Use DEF/USE to provide the same GeoOrigin
node to all GeoVRML nodes. Also, Rotate +Y “up”.
• Uses
– Remove floa'ng point rounding ar'facts for ground-level
models such as quan'za'on of ver'ces and camera jiMer
during naviga'on
6. GeoOrigin
24

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
<GeoOrigin DEF="ORIGIN"
containerField="children"
geoSystem="GD"
geoCoords="30.0 -5.0 0.0"/>
<GeoCoordinate
geoSystem="GD"
point="31.31834 -5.886202 0.0"
<GeoOrigin USE="ORIGIN"/>
</GeoCoordinate>
6. GeoOrigin
25

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Special notes
– A scene may contain only 1 GeoOrigin
– Content with different GeoOrigins cannot be combined
– Advice is to avoid GeoOrigin as it prevents “mashing up” content
– In some cases it is useful:
• Some graphics pipelines require it for high precision scenes
• Use for rotateYUp to help support for different naviga'on modes
First the GeoOrigin coordinates are subtracted. Then, if rotateYUp is
requested, a rota'on matrix is computed based on how a GeoLoca'on
node would transform geometry with the GeoOrigin posi'on as the
GeoLoca'on posi'on. Finally, the calculated rota'on matrix is inverted
and applied to each vertex of the node.
6. GeoOrigin
26

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Animate objects within a geographic coordinate system
• Usage
– Can use a GeoPosi'onInterpolator node anywhere that an
X3D Posi'onInterpolator node can go
• Uses
– Perform fly-throughs of X3D content by anima'ng the
camera, animate objects based upon GPS data or key
frame loca'ons
7. GeoPosi'onInterpolator
27

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
<GeoPositionInterpolator
DEF="ROV_Pos_Interpolator">
<IS>
<connect nodeField="key"
protoField="rovKeys"/>
<connect nodeField="keyValue"
protoField="rovLocation"/>
</IS>
<GeoOrigin USE="ORIGIN"/>
</GeoPositionInterpolator>
7. GeoPosi'onInterpolator
28

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Report geographic loca'on of the viewer's posi'on
• Usage
– Can use a GeoProximitySensor node anywhere that an X3D
ProximitySensor node can go
• Uses
– Specify proximity sensors in GeoSpa'al reference frame
– Route GeoCoordinate values of viewpoint loca'on
8. GeoProximitySensor
29

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
DEF PROX GeoProximitySensor {
geoOrigin USE ORIGIN
geoSystem [ "GD" ]
geoCenter IS diveMidpoint
size 1.e6 1.e6 1.e6
}
.
.
.
ROUTE PROX.geoCoord_changed TO
PROX_script.set_geoCoord
ROUTE PROX_script.locationString TO
DepthDisplay.set_string
8. GeoProximitySensor
30

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Report geographic loca'on of the mouse posi'on on an
object
• Usage
– Can use a GeoTouchSensor node anywhere that an X3D
Touch Sensor node can go
• Uses
– Route GeoCoordinate values of mouse posi'on and act on
mouse clicks
9. GeoTouchSensor
31

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
Group {
children [
DEF GTS GeoTouchSensor {
geoOrigin USE ORIGIN
}
geometry GeoElevationGrid
{
. . .
}
]
}
.
.
.
ROUTE GTS.hitGeoCoord_changed TO
TEXTSCRIPT.set_value
9. GeoTouchSensor
32

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Translate and rotate GeoCoordinate geometry rela've to
ellipsoidal tangent plane
• Usage
– Grouping node like Transform, but for GeoCoordinates
• Uses
– Provides transla'on and rota'on routable aMributes for
moving GeoCoordinate constructed geometry rela've to a
local tangent plane on the globe.
– Alternate applica'on of GeoOrigin
10. GeoTransform
33

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
DEF DiveLocation GeoTransform {
geoOrigin USE ORIGIN
geoCenter IS diveMidpoint
children [
Transform {
children [
DEF ROVTrackShape Shape {
geometry IndexedLineSet {
coord GeoCoordinate {
geoOrigin USE ORIGIN
point IS rovLocation
}
]
}
]
}
.
ROUTE DepthSliderEvents.translation_changed TO
DiveLocation.set_translation
10. GeoTransform
34

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Specify a viewpoint using geographic coordinates
• Usage
– Can use a GeoViewpoint anywhere an X3D Viewpoint node
can go. The viewpoint orienta'on is rela've to the up
vector at that loca'on.
• Uses
– Place the camera at a geographic coordinate, setup
sensible naviga'on op'ons such as height-based velocity
and near/far clipping planes
11. GeoViewpoint
35

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
GeoViewpoint {
position "51.5 -0.1 1000000"
orientation 1 0 0 -1.57
geoSystem "GD"
navType "EXAMINE"
description "View1"
headlight TRUE
jump TRUE
}
11. GeoViewpoint
36

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Bring “slippy” map image in as texture to 3D scene
• Usage
– Build upon exis'ng 2D web mapping infrastructure
• Uses
– Web applica'on can 'e together 2D and 3D maps
– OpenStreetMap layers brought into X3D scenes
– Build stand-alone systems on private networks
12. GeoWebMap (X3DOM Experimental)
37

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
12. GeoWebMap
<div id="map" style="…"></div>
<GeoWebMap id="x3dmap" src="map"
geosystem="WM" render="true">
</GeoWebMap>
38

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
• Purpose
– Apply GeoOrigin to non-geospa'al X3D geometry
• Usage
– Transform ECEF data into local GeoOrigin system
• Uses
– Build terrain mesh in geocentric coordinates
– Apply offset and rota'on for high precision uses
13. GeoOriginTransform (X3DOM Experimental)
39

Heraklion, Crete, Greece 18 - 21 June 2015
Geospa'al Component
12. GeoOriginTransform
<GeoOriginTransform>
<inline id="mp-x3d-terrain1”
url="http://dods.mbari.org/
terrain/x3d/
MontereyCanyonBeds_1m+5m_1x/
MontereyCanyonBeds_1m
+5m_1x_scene.x3d>
</inline>
<GeoOrigin geoSystem="GD"
geoCoords="36.4 -122.2 0"/>
</GeoOriginTransform>
40

Heraklion, Crete, Greece 18 - 21 June 2015
Browser-database data flow
How X3D Geospa'al is used in
prac'ce

Heraklion, Crete, Greece 18 - 21 June 2015
Browser-database data flow
• Browser makes HTTP request
• Server sovware translates to SQL request
• Server responds with XHR as JSON structure
• JavaScript updates DOM elements
• Scene updates with selected data
42

Heraklion, Crete, Greece 18 - 21 June 2015
Browser-database data flow
X3D Scene Graph DOM
43

Heraklion, Crete, Greece 18 - 21 June 2015
Browser-database data flow
XML HTTP Response (XHR) containing JSON
44

Heraklion, Crete, Greece 18 - 21 June 2015
Browser-database data flow
JavaScript (jQuery) code to update the scene
graph with data from the database
45

Heraklion, Crete, Greece 18 - 21 June 2015
Exercise 1
• Launch your STOQS development server:
cd ~/dev/stoqsgit!
source venv-stoqs/bin/activate!
export DJANGO_SECRET_KEY='SET_YOUR_OWN_IMPOSSIBLE_TO_GUESS_SECRET_KEY’!
export DATABASE_URL="postgis://stoqsadm:CHANGEME@127.0.0.1:5432/stoqs”!
stoqs/manage.py runserver 0.0.0.0:8000 --settings=config.vagrant!
• Open in Chrome:
localhost:8000
• Ini'al Test
Database !
• Make a 3D
data plot
46

Heraklion, Crete, Greece 18 - 21 June 2015
Exercise 1
1. In Chrome, launch “Developer Tools”:
View -> Developer -> Developer Tools
2. Click “Network”, “XHR”, and reload page
3. Find JSON response for summary data
4. Find <shape> element with id=“mp-x3d-track”
5. Find JavaScript that updates “mp-x3d-track”
47

Heraklion, Crete, Greece 18 - 21 June 2015
Exercise 2
1. Edit file:
stoqs/stoqs/templates/stoqs/stoqsquery.html!
2. Add a <GeoLoca'on> node
3. Use: <inline url=“/stoqs/static/x3d/ESPMooring/
esp_base_scene.x3d”></inline> or another model!
4. Place it at “36.6396,-121.8785,-10”!
5. Scale it by 200 or more to make it easy to see
48