Scene Importer
The Aerial Omniverse Digital Twin is built on NVIDIA Omniverse. As such, it requires scene geometries to be in OpenUSD format. Geospatial information, however, is often available and distributed in other formats. To bridge the gap, the Aerial Omniverse Digital Twin offers a pipeline to import geospatial data from CityGML format as well as OpenStreetMap OSM.
One way of running the GIS processing tools is through the AODT UI. To set up your container for this use case, the GIS container must have a data folder mounted at the container location /src/aodt_gis/data. The channel listener script must also be running.
Container setup
As first thing, we need to log into the nvcr.io container registry using the $oauthtoken username and the NGC API Key:
docker login nvcr.io
Username: $oauthtoken
Password: <NGC_CLI_API_KEY>
More information about NGC_CLI_API_KEY can be found at NGC - User’s Guide.
Next, we run the container and mount <local data>, which is the local folder where the source data is stored:
docker run --rm -it -v <local data>:/src/aodt_gis/data --pull=always nvcr.io/esee5uzbruax/aodt-gis:1.1.0 /bin/bash
Now that we are inside the container, we start up the channel listener using:
cd /src/aodt_gis/aodt_py/aodt_ui_gis/channel_listener.py --nucleus <Nucleus server IP> --broadcast <unique broadcast channel name here>
The broadcast channel listed here will be the same one used in the UI GIS tab. The container is now ready to connect to the UI.
AODT UI setup
Connecting to a GIS worker
Once the GIS container is set up on the host machine, you are now able to attach a worker from the UI. The worker allows the UI to trigger GIS jobs in the host machine, and for the GIS container to communicate progress and data back to the UI. Attaching the worker takes place in the GIS Channel Configuration section.
The Server path is the URL for the Omniverse Nucleus server. The Broadcast Channel Name is the name of the private channel that will be created between the UI and the GIS worker. Once established, the UI and GIS worker will communicate exclusively on this channel. The server path and broadcast channel name should be the same ones used to start up the channel listener in the GIS container.
Note: The Broadcast Channel Name must be different from the EM worker broadcast channel name. The connection won’t be allowed otherwise. This is to avoid interference when an EM worker and a GIS worker is attached at the same time.
Once set, click Attach Worker to attach to an available GIS worker.
Once the server is validated and a worker is attached successfully, a confirmation window should appear:
If there are no workers available, the connection can’t be established, or the server is invalid, an error window will appear. In that case, check the server connection, validity, and that the channel listener is running on the GIS container.
Starting GIS Processing from the UI
Once a worker is attached, we are able to trigger GML or OSM jobs. The progress bar below will communicate the status and progress of each job. Only one job can be run at once. Any logs generated by the UI or the GIS container will be in the Console tab of the UI with the Info filter enabled. Below are more details on how to start processing for each job type.
OpenStreetMap (OSM)
An explanation of the parameters available through the graphical interface can be found in the previous section of this document.
Assuming a worker is attached, once parameters are set, we can click the Start OSM Processing button. The progress bar below will reflect progress from the GIS container, along with status logs.
When the job completes successfully, the status will read Completed successfully, and the USD file will be in the path specified in the Output stage field. The console will contain additional information regarding the job generated by the attached worker. If the job fails, the status will read Failed (check console for more info). The console will contain more information about why the job failed.
CityGML
An explanation of the parameters available through the graphical interface can be found in the previous section of this document.
Assuming a worker is attached, once the parameters are set, we can click the Start GML Processing button to produce the scene we want to analyze. The progress bar below will reflect progress of the GIS container in generating the scene, along with status logs.
When the job completes successfully, the status will read Completed successfully, and the USD file will be in the path specified in the Output stage field. If the job fails, the status will read Failed (check console for more info) and the console will contain more information.
We may also use the CityGML and OSM import tools using the CLI directly. To do so, as in other setup steps, we boot up the container by running
docker run --rm -it -v <local_path>:/src/aodt_gis/data --pull=always nvcr.io/esee5uzbruax/aodt-gis:1.1.0 /bin/bash
where <local_data> is the folder where the GIS data is contained.
CityGML Import
The GML import script can be accessed directly at
cd /src/aodt_gis/aodt_py/aodt_ui_gis
python3 gis_jobs/gml_job.py
and it has following parameters:
Parameter |
Required |
Description |
|---|---|---|
--output |
Yes | This argument specifies the URL where the USD scene needs to be saved. |
--logging |
N️o | Set logging verbosity between [info , warning , debug] |
--epsg_in --epsg_out |
N️o | If set, the pipeline will perform a conversion between input and output coordinate reference systems, as defined by their EPSG codes. Currently, only the transform from geographic coordinate systems (angular units) to projected coordinate systems (linear units) is supported. For example, a transform from EPSG:6697 to EPSG:32654 would be expressed as --epsg_in EPSG:6697 --epsg_out EPSG:32654. |
--scaling |
N️o | A scaling factor may be necessary if the target EPSG is in units other than meters. This argument can be used to specify the number of centimeters contained in the unit of measurement used in the geospatial data. E.g., 100 for meters (default) and 30.48 for feet. |
--textures |
N️o | If present, colocated with the input files and referenced therein, the textures will be copied to the destination specified by --output. We can use --textures False to ensure that this does not occur. |
--textures_out_prefix |
No | Explicitly set the texture directory. |
--flatten |
N️o | If a digital elevation data (DEM) is available, it may be included in the input files argument. If a DEM is not available, all buildings may be adjusted to a flat ground plane using the --flatten argument. |
--adjust_height_threshold |
No | Depending on the data source, there may be a discrepancy between a CityGML building bldg:measuredHeight and its rendered height. Where this is a cause for concern and better geospatial data cannot be obtained, --adjust_height_threshold can be used to ensure that the building footprints are extruded to bld:measuredHeight. |
--mobility_scale |
N️o | This flag defines the maximum size that an edge is allowed to have in the mobility domain mesh generated by the pipeline (default = 400 in target units of measurements, i.e., centimeters). In large scenes, this may be used to improve performance. A warning will be generated in those cases where there are excessive triangles in the resulting mobility mesh. |
--force_mobility |
N️o | In particularly large maps with excessive triangle sizes, the mobility generation may be automatically disabled. Override this behavior. |
--disable_mobility |
N️o | Disable the mobility mesh generation. This is useful when debugging visual issues in the map quickly. |
--max_lod |
N️o | Limit the LOD present in the map to the selected value or lower, depending on what is available in the CityGML. |
For example, suppose we would like to import a portion of Tokyo from PLATEAU.
First, run a script to download the Tokyo CityGML bundle to our data folder. Note, this may take some time.
cp /src/aodt_gis/samples/get_tokyo.bash /src/aodt_gis/data
sh /src/aodt_gis/samples/get_tokyo.bash
rm -r /src/aodt_gis/data/get_tokyo.bash
Next, we can run the command
python3 gis_jobs/gml_job.py --in_gmls /src/aodt_gis/data/13100_tokyo23-ku_2022_citygml_1_2_op/13100_tokyo23-ku_2022_citygml_1_2_op/udx/dem/533936_dem_6697_op.gml /src/aodt_gis/data/13100_tokyo23-ku_2022_citygml_1_2_op/13100_tokyo23-ku_2022_citygml_1_2_op/udx/dem/533935_dem_6697_op.gml /src/aodt_gis/data/13100_tokyo23-ku_2022_citygml_1_2_op/13100_tokyo23-ku_2022_citygml_1_2_op/udx/bldg/53393599_bldg_6697_2_op.gml /src/aodt_gis/data/13100_tokyo23-ku_2022_citygml_1_2_op/13100_tokyo23-ku_2022_citygml_1_2_op/udx/bldg/53393690_bldg_6697_2_op.gml /src/aodt_gis/data/13100_tokyo23-ku_2022_citygml_1_2_op/13100_tokyo23-ku_2022_citygml_1_2_op/udx/bldg/53393589_bldg_6697_2_op.gml /src/aodt_gis/data/13100_tokyo23-ku_2022_citygml_1_2_op/13100_tokyo23-ku_2022_citygml_1_2_op/udx/bldg/53393680_bldg_6697_2_op.gml -o /src/aodt_gis/data/cli_japan_sample.usd -ei EPSG:6697 -eo EPSG:32654 -s 100
The parameters
-ei EPSG:6697 -eo EPSG:32654
indicate that we are projecting from the source coordinate reference system (EPSG 6697) to the UTM (Universal Transverse Mercator) zone 54N.
Unless otherwise configured, textures will be moved to the destination folder where the generated USD file resides.
Note: for the Stadt Zuerich map bundled with AODT, it is worth mentioning that the procedure to regenerate the map requires the use of the --force_mobility flat. Specifically, after extracting the sample data
cp /src/aodt_gis/samples/get_zurich.bash /src/aodt_gis/data
sh /src/aodt_gis/samples/get_zurich.bash
rm -r /src/aodt_gis/data/get_zurich.bash
we need to run
python3 gis_jobs/gml_job.py --in_gmls /src/aodt_gis/data/Zurich_LoD2_CityGML/*.gml -o /src/aodt_gis/data/zurich_sample.usd --flatten True --force_mobility True
to obtain a map having the mobility domain included.
OpenStreetMap (OSM) import
The OSM import script can be accessed directly at
cd /src/aodt_gis/aodt_py/aodt_ui_gis/
python3 gis_jobs/osm_job.py
and it has the following parameters:
Parameter |
Required |
Description |
|---|---|---|
--output_stage |
Yes | This argument specifies the URL where the USD scene needs to be saved. |
-coords |
Yes | This argument specifies the bounding box of the area of interest in decimal degrees and in the following order <minLon> <minLat> <maxLon> <maxLat>. The bounding box can be at most 100 sq km. |
For example, to import a map of the area around the University of Texas - Austin, we would run the following command:
python3 gis_jobs/osm_job.py -o /src/aodt_gis/data/ut_austin.usd -c -97.74384 30.27690 -97.72444 30.29416