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.

1. Open Omniverse USD Composer.

2. Navigate to Window > Extensions.

3. Search for and enable the OGC Map Tile Loader Extension.

4. Navigate to Window > OGC Map Tile Loader to open the extension window.

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

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

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

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

9. 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):

10. 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	https://maps.ecere.com/ogcapi
collectionID	blueMarble
transparent	true
bgColor	0xFFFFFF
credentials
Elevation Data
Base URL	https://maps.ecere.com/ogcapi
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.

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

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

13. (Optional) In your viewport, select the Perspective camera and select the three-slider icon to the right of Perspective.

14. (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”).

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

1. 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" = {}

2. In your Python script, import the helper class

from omni.kit.converter.ogc import OgcHelper

3. 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()

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

1. Add the carbonite library for your extension by adding its include and linking its library directories.

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

3. List the extension as a dependency after the above lines:

CARB_PLUGIN_IMPL_DEPS(omni::kit::converter::ogc::OgcMapConverter)

4. To access the interface, use the following line:

auto iOgcMapConverter = carb::getCachedInterface<omni::kit::converter::ogc::OgcMapConverter>();

5. 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 downwards window will “bounce back” upwards when trying to scroll downwards 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

• NOAA - https://gis.ngdc.noaa.gov/arcgis/rest/services

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