Open Geospatial Consortium (OGC) Map Tile Loader
Overview
The Open Geospatial Consortium (OGC) Map Tile Loader Extension queries geospatial data following open geospatial consortium (OGC) standards and generates map tiles given user input for coordinates (latitude, longitude) and tile size. When enabled in Omniverse USD Composer, the OGC Map Tile Loader provides users a user interface (UI) to provide inputs to define map tiles to be queried and generated on the USD stage.
Users also have access to the extension’s C++- and Python-based API to make queries for raster images for map imagery and elevation data as .png and .tiff files, respectively. Information on the API is provided in the API section. The API is still in beta development.
Features
Tile Information Setup - Use user-defined inputs to determine bounding box of map tiles
Image Query - Make requests to download images for tile’s area
Geospatial Information - Read .tiff file for GeoTiff tags, image size, elevation per pixel
Terrain Mesh Generation - Given latitude and longitude from .tiff file, create and place USD meshes in georeferenced locations and manipulate mesh’s vertices to match elevation data
Create materials with textures using map imagery for map tile’s bounding box
Note
The tool is currently able to convert data following the WGS84 coordinate system
Note
Meshes do not curve and do not create a ellipsoidal Earth.
Generating Map Tiles in Omniverse USD Composer
This tutorial provides the steps to generate map tiles as meshes in Omniverse USD Composer. The OGC Map Tile Loader extension is not enabled by default in USD Composer and will need to be enabled for use.
Open Omniverse USD Composer.
Navigate to Window > Extensions.
Search for and enable the OGC Map Tile Loader Extension.
Navigate to Window > OGC Map Tile Loader to open the extension window.
Click on the OGC Map Tile Loader (Beta) tab.
The window is split into two settings menus: “Global Map Settings” and “Map Tile Settings.” These menus provide settings for all generated map tiles and parameters for the next tile to be generated, respectively. Below is a description of each field.
Fields |
Description |
---|---|
Global Map Settings |
|
Image Download URL |
(string) directory path for downloaded images
|
Map Tile Settings |
|
Tile Latitude (deg) |
(string) Latitude coordinate of map
tile center in degrees.
|
Tile Longitude (deg) |
(string) Longitude coordinate of map
tile center in degrees.
|
Latitude Distance (km) |
(string) Latitude distance of map
tile center in kilometers.
|
Longitude Distance (km) |
(string) Longitude distance of map
tile center in kilometers.
|
Map Imagery Selection |
|
Map Imagery Preset |
(menu) Available Web Map Server providers.
- terrestris - provides topology and OpenStreetMap
overlays for road and building features
- mundialis - provides topology and OpenStreetMap
overlays for road and building features
- Gebco - provides topology
- USGS-NationalMap - provides Satelliate imagery
|
OGC API |
User option to query a server following OGC API queries
for map imagery and elevation data
|
Base URL |
(string) Base URL of the server to query from
|
collectionID |
(string) ID of the collection to query from
|
Advanced Settings |
Parameters that are included but have default values
available for the user
|
transparent |
(bool) transparent background for image
|
bgColor |
(string) background color in hex format
|
credentials |
optional - (string) credentials provided for access of server
this is dependent on how the server conducts
authentication (API key, username and password, etc.)
|
Custom Server |
User option to query a server of choice
for map imagery and elevation data
|
Base URL |
(string) Base URL of the server to query from
|
credentials |
optional - (string) credentials provided for access of server
this is dependent on how the server conducts
authentication (API key, username and password, etc.)
|
Elevation Data Selection |
|
Elevation Data Preset |
(menu) Available Web Map Server providers.
- National Oceanic and Atmospheric Administration -
elevation data source
|
Base URL |
(string) Base URL of the server to query from
|
credentials |
optional - (string) credentials provided for access of server
this is dependent on how the server conducts
authentication (API key, username and password, etc.)
|
In the “Global Map Settings” menu, for the “Image Download URL” field add the absolute path for the folder you wish to save map imagery and elevation data images to. An example URL is “C:users/jdoe/appdata/local/ov/pkg/create-2022.3.0” which is the installation folder of USD Composer.
Note
Providing a relative path will causes errors. Some paths may be invalid due to user read-write permissions and whether the folder exists.
In the “Map Tile Settings” menu, provide latitude (Lat) and longitude (Long) coordinates’ values.
Note
The extension supports the ESPG:4326 / WGS84 coordinate reference system (CRS). They are used to determine the bounding box with the northing and easting distances. Accepted values for latitude are [-90.0, 90.0] and for latitude are [-180.0, 180.0]. Both are in units of degrees.
In the “Map Tile Settings” menu, provide northing and easting distances.
Note
These distances are the north-to-south and east-to-west distances, respectively. They are used to determine the bounding box with the latitude and longitude coordinates. Accepted values for variables are [0.0, 12741.9811]. The units are in kilometers.
In the “Map Tile Settings” menu, for the “Map Imagery Selection” group you can select from either the presets, an OGC API-compliant server, or a custom server to query from.
Note
The extension currently supports Portable Network Graphics (.png) raster file format for map imagery.
Example outputs of presets (top row, from left to right: terrestris, mundialis; bottom row, from left to right: Gebco, USGS-NationalMap):
In the “Map Tile Settings” menu, for the “Elevation Data Selection” group you can select from either the presets, an OGC API-compliant server, or a custom server to query from.
Example values for API:
Fields |
Example Values |
---|---|
Map Imagery |
|
Base URL |
|
collectionID |
blueMarble
|
transparent |
true
|
bgColor |
0xFFFFFF
|
credentials |
|
Elevation Data |
|
Base URL |
|
collectionID |
SRTM_ViewFinderPanorama
|
credentials |
Note
The extension currently supports digital elevation model (DEM) files of the Tagged Image File Format (.tiff) raster file format for elevation data. The extension supports both tiled and scanline TIFF files.
When inputs have been provided and ready, click on the Generate Tiles button.
Note
The terrain mesh generation may take some time to load.
Note
Generating a tile at the same latitude and longitude coordinates of an existing tile will resize the map tile, but not update its image texture.
Verify your tile has been created in the stage by navigating to the Stage tab, clicking on the Geospatial prim, and hitting the F-key to focus on the tile.
Note
You may not be able to see the tile, so try to zoom in and out. To help with rendering, follow the following steps.
(Optional) In your viewport, select the Perspective camera and select the three-slider icon to the right of Perspective.
(Optional) In the Properties tab, increase the far clipping range value. You can multiply the value by inserting a zero (0) before the decimal (.) point (i.e., “100000000.0” becomes “1000000000.0”).
(Optional) Map tiles now contain custom USD Attributes for their elevation points (stored as a GfVec3d array) and their corner coordinates (stored as a Double2 array). They can be found under the Property Window’s Raw USD Properties group in USD Composer.
USD Attribute: |
Attribute description |
---|---|
GfVec3d[] omni:kit:converter:ogc:elevation_points |
an array of pxr::GfVec3d objects; each stores each point as longitude (WGS84 degree), altitude (meters), and latitude (WGS84 degree) to match the translation in a y-up stage
|
Double2[] omni:kit:converter:ogc:tile_corners |
an array of size two (2) containing the south-west [0][…] and the north-east [1][…] corners’ coordinates (lat as […][0], long as […][1]) of the map tile; the coordinates are in WGS84 degrees
|
Here is an example of accessing the attributes:
pxr::VtArray<pxr::GfVec3d> readElevation;
pxr::UsdAttribute readElevationAttr = my_prim.GetAttribute( pxr::TfToken("omni:kit:converter:ogc:elevation_points") );
readElevationAttr.Get( &readElevation );
std::cout << "Elevation first coordinate: lat=" << std::to_string(readElevation[0][0]) << ", alt=" << std::to_string(readElevation[0][1]) << ", long=" << readElevation[0][2] << std::endl;
pxr::VtArray<pxr::GfVec2d> readCorners;
pxr::UsdAttribute readCornersAttr = my_prim.GetAttribute( pxr::TfToken("omni:kit:converter:ogc:tile_corners") );
readCornersAttr.Get( &readCorners );
std::cout << "South-West coordinate: lat=" << std::to_string(readCorners[0][0]) << ", long=" << std::to_string(readCorners[0][1]) << std::endl;
std::cout << "North-East coordinate: lat=" << std::to_string(readCorners[1][0]) << ", long=" << std::to_string(readCorners[1][1]) << std::endl;
You can also view how to get the value of an attribute in Python from the Omniverse documentation here: https://docs.omniverse.nvidia.com/prod_kit/prod_kit/programmer_ref/usd/properties/get-attribute-value.html
Congratulations! You have generated a map tile!
Using the Map Tile Loader API (beta)
This section covers the available methods available for use with the extension.
The methods are separated into “Query”, “Path”, and “Verify” methods.
“Query” methods result in outputs of 0 (success) and -1 (errors) when querying for data.
“Path” methods return the expected file name of your query: Raster image format: Format: {file_name_prefix}_{center_lat}_{center_long}_{northing}_{easting}_{service}_{tile_dim}.{file_format} Example: imagery_N37p30_W121p90_100p00_100p00_wms_256.png Raster image (tiled) format: Format: {prefix}_{z}_{x}_{y}_{service}_{tile_dim}.{file_format} Example: imagery_8_72_98_wms_256.png
“Verify” methods return a boolean value whether the file exists.
Python Synchronous Methods
query_raster_image
Behavior Summary: Users can call this method to query for geospatial data stored as a single raster image. The user provides the center latitude and longitude coordinates as well as the Northing and Easting distances
Input Parameters and type: |
Parameter description |
---|---|
str file_name_prefix |
prefix for file name to help with user identification; example inputs “imagery”, “elevation”
|
str download_path |
folder path to save imagery to
|
float center_lat |
latitude coordinate in WGS84 coordinate reference system for center of map tile
|
float center_long |
longitude coordinate in WGS84 coordinate reference system for center of map tile
|
float northing |
south-to-north distance covered by the map tile, in kilometers
|
float easting |
west-to-east distance covered by the map tile, in kilometers
|
str query_url |
URL of server to query geospatial data from
|
str service |
OGC service to determine whether to query map imagery or elevation data; accepted inputs “wms”, “wcs”
|
str bbox_order |
order for bounding box coordinates; accepted inputs “wsen” or “swne”
|
str size_parameter |
used to determine the image size parameter name for the query; accepted inputs “size”, “widthheight”
|
str file_format |
used for defining the file format for saving the data; example inputs “png”, “tiff”
|
int tile_dim |
image resolution for the map tile; example values “512”, “1024”
|
Output Parameters and type: |
Parameter description |
---|---|
int |
success status of method; expected values: 0 (Pass), -1 (Error, did not query successfully)
|
get_image_path
Behavior Summary: Users can call this method to get the path of the queried raster image as requested through the “i_query_raster_image” method.
Input Parameters and type: |
Parameter description |
---|---|
str file_name_prefix |
prefix for file name to help with user identification; example inputs “imagery”, “elevation”
|
str download_path |
folder path to save imagery to
|
float center_lat |
latitude coordinate in WGS84 coordinate reference system for center of map tile
|
float center_long |
longitude coordinate in WGS84 coordinate reference system for center of map tile
|
float northing |
south-to-north distance covered by the map tile, in kilometers
|
float easting |
west-to-east distance covered by the map tile, in kilometers
|
str query_url |
URL of server to query geospatial data from
|
str service |
OGC service to determine whether to query map imagery or elevation data; accepted inputs “wms”, “wcs”
|
str bbox_order |
order for bounding box coordinates; accepted inputs “wsen” or “swne”
|
str size_parameter |
used to determine the image size parameter name for the query; accepted inputs “size”, “widthheight”
|
str file_format |
used for defining the file format for saving the data; example inputs “png”, “tiff”
|
int tile_dim |
image resolution for the map tile; example values “512”, “1024”
|
Output Parameters and type: |
Parameter description |
---|---|
char* |
absolute file path to queried file
|
verify_raster_image
Behavior Summary: Users can call this method to verify image file was saved through the “i_query_raster_image” method
Input Parameters and type: |
Parameter description |
---|---|
str file_path |
absolute file path to queried file
|
Output Parameters and type: |
Parameter description |
---|---|
bool |
true if file exists, else false
|
query_raster_tile_image
Behavior Summary: Users can call this method to query for geospatial data stored as a single raster image using OGC tile-style for zoom level, tile row/column (this is closer to what you said matches your use case with
Input Parameters and type: |
Parameter description |
---|---|
str file_name_prefix |
prefix for file name to help with user identification; example inputs “imagery”, “elevation”
|
str download_path |
folder path to save imagery to
|
float center_lat |
latitude coordinate in WGS84 coordinate reference system for center of map tile; used as backup if z/x/y-values are not known
|
float center_long |
longitude coordinate in WGS84 coordinate reference system for center of map tile; used as backup if z/x/y-values are not known
|
int z |
zoom level to determine which tile matrix to access; defaults to 8
|
int x |
row of tile matrix at zoom level z
|
int y |
column of tile matrix at zoom level z
|
str query_url |
URL of server to query geospatial data from
|
str service |
OGC service to determine whether to query map imagery or elevation data; accepted inputs “wms”, “wcs”
|
str bbox_order |
order for bounding box coordinates; accepted inputs “wsen” or “swne”
|
str size_parameter |
used to determine the image size parameter name for the query; accepted inputs “size”, “widthheight”
|
str file_format |
used for defining the file format for saving the data; example inputs “png”, “tiff”
|
int tile_dim |
image resolution for the map tile; example values “512”, “1024”
|
Output Parameters and type: |
Parameter description |
---|---|
int |
success status of method; expected values: 0 (Pass), -1 (Error, did not query successfully)
|
get_tile_image_path
Behavior Summary: Users can call this method to get the path of the queried raster image as requested through the “i_query_raster_tile_image” method
Input Parameters and type: |
Parameter description |
---|---|
str file_name_prefix |
prefix for file name to help with user identification; example inputs “imagery”, “elevation”
|
str download_path |
folder path to save imagery to
|
float center_lat |
latitude coordinate in WGS84 coordinate reference system for center of map tile; used as backup if z/x/y-values are not known
|
float center_long |
longitude coordinate in WGS84 coordinate reference system for center of map tile; used as backup if z/x/y-values are not known
|
int z |
zoom level to determine which tile matrix to access; defaults to 8
|
int x |
row of tile matrix at zoom level z
|
int y |
column of tile matrix at zoom level z
|
str query_url |
URL of server to query geospatial data from
|
str service |
OGC service to determine whether to query map imagery or elevation data; accepted inputs “wms”, “wcs”
|
str bbox_order |
order for bounding box coordinates; accepted inputs “wsen” or “swne”
|
str size_parameter |
used to determine the image size parameter name for the query; accepted inputs “size”, “widthheight”
|
str file_format |
used for defining the file format for saving the data; example inputs “png”, “tiff”
|
int tile_dim |
image resolution for the map tile; example values “512”, “1024”
|
Output Parameters and type: |
Parameter description |
---|---|
char* |
absolute file path to queried file
|
verify_raster_tile_image
Behavior Summary: Users can call this method to verify image file was saved through the “i_query_raster_tile_image” method
Input Parameters and type: |
Parameter description |
---|---|
str file_path |
absolute file path to queried file
|
Output Parameters and type: |
Parameter description |
---|---|
bool |
true if file exists, else false
|
Python Asynchronous Methods
The extension also includes asynchronous versions of the above methods with the “_async” suffix (e.g., query_raster_image’s counterpart is query_raster_image_async). These methods have two additional input parameters.
Input Parameters and type: |
Parameter description |
---|---|
Function successCallback |
method to call upon success of the asynchronous call
|
Function errorCallback |
method to call upon error of the asynchronous call
|
How to use Python Methods
This section’s intended audience is for users developing kit extensions that need to query geospatial data. The follow methods are available for Python extensions.
In your extension’s extension.toml file, add a [dependencies] block with OGC Map Tile Loader extension as a dependency
[dependencies]
"omni.kit.converter.ogc" = {}
In your Python script, import the helper class
from omni.kit.converter.ogc import OgcHelper
To set up, add an object set to the helper class (this can be done in your class or in a set up method)
self._ogc_helper = OgcHelper()
Using the functions
4.1. Synchronous functions
4.1.1. Raster Images
result = self._ogc_helper.query_raster_image("imagery","./",38.5517,-78.3158,100.0,100.0,"https://maps.ecere.com/ogcapi/collections/SRTM_ViewFinderPanorama/map?f=png&bgcolor=0xFFFFFF&transparent=true","wms","swne","widthheight","png",128)
path = self._ogc_helper.get_image_path("imagery","./",38.5517,-78.3158,100.0,100.0,"https://maps.ecere.com/ogcapi/collections/SRTM_ViewFinderPanorama/map?f=png&bgcolor=0xFFFFFF&transparent=true","wms","swne","widthheight","png",128)
file_exists = self._ogc_helper.verify_raster_image(path)
4.1.2. Raster Images (Tiled)
result = self._ogc_helper.query_raster_tile_image("imagery","./",38.5517,-78.3158,-1,-1,-1,"https://maps.ecere.com/ogcapi/collections/SRTM_ViewFinderPanorama/map?f=png&bgcolor=0xFFFFFF&transparent=true","wms","swne","widthheight","png",128)
path = self._ogc_helper.get_tile_image_path("imagery","./",38.5517,-78.3158,-1,-1,-1,"https://maps.ecere.com/ogcapi/collections/SRTM_ViewFinderPanorama/map?f=png&bgcolor=0xFFFFFF&transparent=true","wms","swne","widthheight","png",128)
file_exists = self._ogc_helper.verify_raster_tile_image(path)
result = self._ogc_helper.query_raster_tile_image("imagery","./",0,0,8,41,99,"https://maps.ecere.com/ogcapi/collections/SRTM_ViewFinderPanorama/map?f=png&bgcolor=0xFFFFFF&transparent=true","wms","swne","widthheight","png",128)
path = self._ogc_helper.get_tile_image_path("imagery","./",0,0,8,41,99,"https://maps.ecere.com/ogcapi/collections/SRTM_ViewFinderPanorama/map?f=png&bgcolor=0xFFFFFF&transparent=true","wms","swne","widthheight","png",128)
file_exists = self._ogc_helper.verify_raster_tile_image(path)
4.2. Asynchronous functions - the asynchronous functions have a suffix (“_async”). To use them, add callbacks upon success and errors of the asynchronous methods calls.
result = self._ogc_helper.query_raster_tile_image("imagery","./",0,0,8,41,99,"https://maps.ecere.com/ogcapi/collections/SRTM_ViewFinderPanorama/map?f=png&bgcolor=0xFFFFFF&transparent=true","wms","swne","widthheight","png",128)
How to use C++ Carbonite Interface Methods
This section’s intended audience is for users developing kit extensions that need to query geospatial data. The follow methods are available for C++ extensions. The names of methods available are the same as the above Python methods but have the “i_” prefix (e.g., “query_raster_image” becomes “i_query_raster_image”). There are no asynchronous methods yet in the C++ Carbonite interface.
Add the carbonite library for your extension by adding its include and linking its library directories.
Add the following lines to your source code to access the extension:
#include <carb/Interface.h>
#include <carb/InterfaceUtils.h>
#include <omni/kit/converter/ogc/ogc_converter_interface.h>
List the extension as a dependency after the above lines:
CARB_PLUGIN_IMPL_DEPS(omni::kit::converter::ogc::OgcMapConverter)
To access the interface, use the following line:
auto iOgcMapConverter = carb::getCachedInterface<omni::kit::converter::ogc::OgcMapConverter>();
Use the following line to call the interface’s functions:
auto result = iOgcMapConverter->i_query_raster_image("imagery","./",38.5517,-78.3158,100.0,100.0,"https://maps.ecere.com/ogcapi/collections/SRTM_ViewFinderPanorama/map?f=png&bgcolor=0xFFFFFF&transparent=true","wms","swne","widthheight","png",128)
Release Notes
1.1.17
Added USD Attributes to store map tile corners (Double2Array) and elevation data (GfVec3d Array)
1.1.16
Updates to packages for Kit 105, USD 22.11, Python 3.10
1.1.15
C++, Python interface for querying for raster files
1.1.8
Bug fixes for file formats for geospatial data queries
1.1.7
Updating to Kit SDK 104.1 for Create 2022.3.1
1.1.5
Bug fix for file path access
1.1.1
Custom URL - added fields for imagery and elevation for the user to query from desired servers and provide authentication
Scaling of map tiles - scaled up by 100,100,100 to convert meters to units to match scale of Omniverse assets
UI update, styles - default button and lat/long and northing/easting labels’ styles
UI bug, vertical scrolling - when scrolling downward window will “bounce back” upwards when trying to scroll downward to
File and tile naming - add increments as old convention of creating a new tile with same lat/long coordinates as an existing one will cause the old tile to be overwritten
1.0.9
Linux build code merges and switch to Kit SDK 104.0
1.0.8
Updated UI for beta release in Omniverse Create 2022.2.1; user definitions of OGC API compliant servers
1.0.5
Extension beta release for Omniverse Create 2022.2.0
Attributions
Map Imagery
Mundialis - https://www.mundialis.de/en/ows-mundialis/
Terrestris - https://www.terrestris.de/en/openstreetmap-wms/
Gebco - https://www.gebco.net/data_and_products/gebco_web_services/
USGS NationalMap - https://basemap.nationalmap.gov/arcgis/rest/services
Elevation Data
Known issues
Map Tile Issues
Using relative file paths for the Image Download Directory field causes errors. Workaround is to provide an absolute path of an existing folder with user read-write permissions.
Generating small tiles (about 1km by 1km) will cause a “drooping” effect.
Future Work
Query for vector tiles for imagery, elevation, and features (e.g., buildings)
Auto-generation of map tiles based on position of camera
Curvature of map tiles
Swapping between Levels of Detail (LODs) for map tiles as user zooms in