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.

_images/open-geospatial-consortium-extension_image_extension-window.png
  1. Navigate to Window > Extensions.

_images/OGC-Ext_0_Open_Window_For_Ext.png
  1. Search for and enable the OGC Map Tile Loader Extension.

_images/OGC-Ext_1_Search_for_ogc.png
  1. Navigate to Window > OGC Map Tile Loader to open the extension window.

_images/OGC-Ext_2_Select_extension.png
  1. Click on the OGC Map Tile Loader (Beta) tab.

_images/OGC-Ext_3_Ogc_ext_startup.png

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

_images/OGC-Ext_4_Filled_url.png

Note

Providing a relative path will causes errors. Some paths may be invalid due to user read-write permissions and whether the folder exists.

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

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

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

_images/OGC-Ext_5_Imagery_presets.png _images/OGC-Ext_7_Imagery_api_empty.png _images/OGC-Ext_8_Imagery_custom_empty.png

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

_images/OGC-Ext_6_Imagery_preset_outputs.png
  1. 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.

_images/OGC-Ext_9_elevation_preset.png _images/OGC-Ext_10_elevation_api_empty.png

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


_images/OGC-Ext_11_elevation_custom_empty.png

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.

  1. When inputs have been provided and ready, click on the Generate Tiles button.

_images/OGC-Ext_12_ready_generate.png

Note

The terrain mesh generation may take some time to load.

_images/OGC-Ext_13_Generated_output_stage.png

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.

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

_images/OGC-Ext_14_Generated_output_hierarchy_2023-1-0.png _images/OGC-Ext_13_Generated_output_stage.png

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.

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

_images/OGC-Ext_16_perspective_camera.png
  1. (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”).

_images/OGC-Ext_15_increase_far_clipping_range_add_0.png
  1. (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.

_images/OGC-Ext_16_USD-attributes_elev-corners_2023-1-0.png

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" = {}
  1. In your Python script, import the helper class

from omni.kit.converter.ogc import OgcHelper
  1. 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()
  1. 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>
  1. List the extension as a dependency after the above lines:

CARB_PLUGIN_IMPL_DEPS(omni::kit::converter::ogc::OgcMapConverter)
  1. To access the interface, use the following line:

auto iOgcMapConverter = carb::getCachedInterface<omni::kit::converter::ogc::OgcMapConverter>();
  1. 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

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