Adding a New Location to AUV Workbench

This is an advanced task for AUV Workbench developers. Discussion of details is welcome on the mailing list. The NPS team will help ensure that this integration proceeds correctly.

Adding GIS data to web server

If usable GIS data for your location is already available, you are all done with this step.

• Build a set of GIS files for the location of interest, typically ArcView .shp shape files.
  (TODO: more information from Arlene about this task, including standalone testing in ArcView and OpenMap prior to integration.)
• Collect the GIS data in a single LocationNameGIS.zip file, with all contents located in a contained LocationNameGIS subdirectory.
• A server administrator can add it to the appropriate online archives at
  • https://savage.nps.edu/AuvWorkbench/datasets/OpenMap or
  • https://savagedefense.nps.navy.mil/AuvWorkbench/datasets/OpenMap

Building and integrating an X3D model

• Create or convert an X3D Earth model for the location, scaled in meters. Task guidelines are found in Byounghyun Yoo's X3D Terrain Tile Production course notes and web page.
• Add the new X3D Earth model in the appropriate Savage or SavageDefense subdirectory. Usually a new subdirectory is created under the Locations directory, e.g.
  • https://savage.nps.edu/Savage/Locations
  • https://SavageDefense.nps.navy.mil/SavageDefense/Locations
• Add a simple Operating Area (OpArea) scene that points to the new X3D terrain or bathymetry for this location. This since needs to be geospatially referenced, as are the other examples. Put it in the Savage/AuvWorkbench/OperatingAreas directory. Good example scene to pattern after: MontereyBayOpArea.x3d (html).
• Further guidance on X3D authoring details can be found in the X3D Scene Authoring Hints.
• Update Savage/Locations (or SavageDefense/Locations) version control with this change.
• Generate and update Savage (or SavageDefense) examples archive, including updated catalog, scene files and .zip results.
• Also build and deploy the corresponding AUV Workbench excerpt using Savage/buildSavageAuvWorkbenchModelDistribution.xml to build and deploy X3dExamplesSavageAuvWorkbenchExcerpt.zip.
• Once again, the NPS team can help ensure that this integration proceeds correctly.

Adding the location to list of geographic origins (anchor points)

• Pick an anchor point location that is a convenient center reference for any robot missions in this area.
• Add an appropriate latitude-longitude geolocation entry in templates file AuvWorkbench/configuration/templates/c_geo.xml. Example:
  

  <geolocation units="decimalDegrees">
   <!-- make sure to escape commas in these handles -->
   <handle>Hampton Roads\, Virginia</handle>
   <latitude>37</latitude>
   <longitude>-76.3</longitude>
   <scale>1600000</scale>
   <X3Dscene type="path">${SavageRoot}Savage/AuvWorkbench/OperatingAreas/HamptonRoadsOpArea.x3d</X3Dscene>
</geolocation>

• Be sure that you edit and check in the persistent file in the AuvWorkbench/configuration/templates/ directory. The parent directory contains only a user's local copies.
• Clean, build, and then test AUV Workbench to confirm that the location name, latitude and longitude are listed by the menu Geospatial > Select Geographic Origin. Developers must clean when rebuilding in order to copy data files to the run-time build directory.
• Update AUV Workbench version control with this change.

Configuration to download and display GIS data

• Create a corresponding catalog (layer) file for OpenMap to load the GIS information into AUV Workbench. To accomplish this stem, copy and edit one of the example configuration/templates/c_om_LocationName.xml files, such as
  AuvWorkbench/configuration/templates/c_om_monterey_tiger.xml
  

  <openmap description="LocationName layer definition file for AUV workbench">
   <layer prettyname="LocationName GIS information title" type="esrishape" visible="true">
      <datapath>datasets/OpenMap/LocationName</datapath>
      <props key="lineColor" value="80000000"/>
      <props key="fillColor" value="80BDDE83"/>
   </layer>
</openmap>

• As highlighted above, ensure attribute visible="true" for each layer, otherwise it is hidden by default. To make a hidden layer visible, in the upper left-hand corner of the OpenGis tab and select the OpenMap Layer Controls button. Then select/deselect the visibility buttons (light-bulb icons) corresponding to layers of interest. Once a layer is visible, you can also go to the lower right-hand corner of the OpenGis tab and use the small green/red layer hide/unhide buttons. Also note that hiding or making layers invisible can sometimes speed up redraw performance.
• Add an entry pointing to this new layer file in AuvWorkbench/configuration/templates/projectCommonsConfig.xml. Example excerpt:
  

  <additional>
   <!-- c_om_layersroot.xml is mandatory -->
   <xml fileName="c_om_layersroot.xml"/>
   <!-- OpenMap dataset files defined in AUVW installation: -->

   <xml fileName="c_om_LocationName.xml" at="gis">

   <xml fileName="c_om_monterey_tiger.xml" at="gis">
   <!-- ...additional layer files... -->
</additional>

• Add a new target task for zip retrieval online.getLocationNameGIS in Ant build file build_downloads.xml. To get this step right, copy and modify an existing task (such as online.getMontereyBayCaliforniaGIS).
• Add a checkbox to launch this ant task within the Updates > Geospatial Datasets Download panel. To accomplish this, modify Java source for the GUI panel in workbench.util.GeoUtils.java (javadoc).
• Clean, build, and then test that AUV Workbench offers the new location under the Geospatial > Select Geographic Origin menu, and that it works properly.
• Update AUV Workbench version control with all changes.

Additional considerations

• Long-term integration of all new AUV Workbench content is performed by checking it into the appropriate version-control archive. Further details can be found at Savage Developers Guide: Subversion.
• Use the XMSF Issue Tracker for bug reports and feature requests.
• Current research is working to integrate X3D Earth globes into the AUV Workbench. X3D for Advanced Modeling slidesets include further details about the X3D Geospatial Component and X3D Earth.
• TODO: confirm proper handling of configuration/OpenMapConfigs configuration files for downloaded datasets? Ensure that absence of downloaded assets doesn't prevent running, provide warning if asset for selected geographic origin is not available, etc.

Back to the Help page index, the AUV Workbench: Introduction page, or online to AUV Workbench home page.