Thursday, January 6, 2022

Tips to interact with Astro’s WMS maps

update from the original 2014 post:

For years we have supported our live mapping services (called Web Mapping Services, WMS) for use within our own web mapping tools but also for the community to use. For example, these available WMS layers are viewable from our Planetary Nomenclature, PILOT, CartoCosmo viewer, etc (example Aram Chaos on Mars). Thus they are ideal for use in web mapping apps like OpenLayers and Leaflet and also GISs like QGIS, ArcMap, or ENVI. And you can even build custom images from a simple browser call or using apps like GDAL (gdal_translate). Fortunately, most bases used for our WMS services are available for download from Astropedia https://astrogeology.usgs.gov/search. And for direct use in ArcGIS Pro and ArcMap, many are also listed from the Esri GIS portal. Note that many of the latest WMS Tiled layers in the ESRI portal, as served by ESRI, are appropriately tagged for the body they represent (no projection workarounds as described next).


Projection quirks. Because of the original limitations for WM* services as defined by the Open Geospatial Consortium (OGC), most services we support are tagged as EPSG:4326. This code defines Earth (specifically WGS84) in degrees. Fortunately for mapping services, degrees are degrees on most mapped bodies. This is our current (unfortunate) workaround to support these services across as many applications as possible for interoperability. 

So to use these correctly for measures, not just for viewing, it will require the user to know how to override this EPSG code in the application. Generally, using these services in packages like ArcMap or QGIS simply requires the user to first set a correct planetary-based map projection and the WMS layer will be "automagically" project correctly (see more below). Also for OpenLayers, Cesium, or Leaflet, you can override the internal definition of EPSG:4326 to define the correct radius. For example, see CartoCosmo or an updated version of Cesium.

The community has been working on this issue for a while. In 2021, we revised a new set of OGC codes (IAU2015) for the planetary domain (see this abstract). These are now available as built into the PROJ library (and GDAL) and will hopefully be pushed out into some other applications (e.g. Mapserver, QGIS, etc.). You can see these newer codes in action here. The original IAU2000 codes, as proposed in 2006 (abstract), were even incorporated in Lunaserv (and also a fork of MapServer but it never pushed back into to main).

For Polar map-projected services (in meters), you will also need to make sure your application correctly overrides the service using a Polar Stereographic projection (making sure body (radius) is defined correctly). All our polar WMS services are correctly using meters on the defined planetary body (even if the code is defined as Earth).
  

Example uses:

For a simple interactive image request, again from any layer listed above you can type this into any browser and modify it at will. HTML example (just click to test):
http://planetarymaps.usgs.gov/cgi-bin/mapserv?map=/maps/mars/mars_simp_cyl.map&SERVICE=WMS&VERSION=1.1.1&SRS=EPSG:4326&STYLES=&REQUEST=GetMap&FORMAT=image%2Fjpeg&LAYERS=MDIM21&BBOX=221,15,231,25&WIDTH=1000&HEIGHT=1000
To change the request, pay attention to these keywords:
  • LAYERS: use listing from the page above
  • BBOX: for LonMin, LatMin, LonMax, LatMax
  • WIDTH and HEIGHT for number for the number of pixels (equates to final resolution).
  • more examples: Mars THEMIS DayMars MOLA, Lunar WAC, Io Galileo SSI ,Mercury Messenger
  • Nomenclature layers were changed from a deafult "0 to 360" Longitude system to a "-180 to 180" Longitude system in Jan. 2023. Let us know if is a problem. 
  • Nomenclature -180 to 180 Longitude: example Mars (&LAYERS=NOMENCLATURE_180) 


For GDAL see our tips page for installing and the GDAL wms page for more (also related). See the xml text below (or on Git) for a Mars MDIM21 example (again customize the address and layer names from the listing above). Using the XML block you can run this below:
> gdal_translate -of PNG gdal_MDIM21.xml mdim21_out.png

File: gdal_MDIM21.xml
<GDAL_WMS>
  <Service name="WMS">
    <Version>1.1.1</Version>
    <ServerUrl>http://planetarymaps.usgs.gov/cgi-bin/mapserv?map=/maps/mars/mars_simp_cyl.map</ServerUrl>
    <SRS>EPSG:4326</SRS>
    <ImageFormat>image/jpeg</ImageFormat>
    <Layers>MDIM21</Layers>
  </Service>
  <DataWindow>
    <UpperLeftX>150</UpperLeftX>
    <UpperLeftY>45</UpperLeftY>
    <LowerRightX>160</LowerRightX>
    <LowerRightY>35</LowerRightY>
     <SizeX>1000</SizeX>
     <SizeY>1000</SizeY>
  </DataWindow>
  <Projection>EPSG:4326</Projection>
  <BandsCount>3</BandsCount>
  <DataType>Byte</DataType>
</GDAL_WMS>

Using IAU_2015 codes in PROJ (for GDAL 3.4+), override the projection (so it is correct).
> gdal_translate -of PNG -a_srs IAU_2015:49900 gdal_MDIM21.xml mdim21_out.png

Note code 49900 is a spherical Mars in degrees. To expand it, type: gdalsrsinfo IAU_2015:49900

In QGIS v2.x you can add a "WMS" layer and copy this example "get capabilities" linked in from the page above. Then you can pick one or more of the available layers:
http://planetarymaps.usgs.gov/cgi-bin/mapserv?map=/maps/earth/moon_simp_cyl.map&service=WMS&request=GetCapabilities


By default, if added first, these layers will think they are on Earth. But if you define the QGIS project using the built-in planetary projections for the Moon, Mars, or other and allow projection-on-the-fly, they will behave appropriately.


For QGIS v3.x, there are newer projection checks so you must override the original EPSG:4326. First, add in the layer accepting the incorrect EPSG:4326 code. Once loaded, open the WMS's layer Properties and you can override the projection. In the Properties window, under the Source tab, type in Mars or Moon, etc., and override the projection. It should now be correctly defined and usable. See the image below. Another tip is to define a custom map projection in meters (under Project Properties, CRS tab). For example, 


Another QGIS v3.x tip is to define a custom map projection in meters for the project. Under Settings, Custom Projections, define a new planetary projection you want to use (see next image). Now under Project Properties, CRS tab, set this project with your newly defined custom projection. Using a meters projection in QGIS v3.x can help with calculated measurements (e.g. Ellipsoidal measurement tool).



ArcMap and ArcGIS Pro are actually more forgiving with projections. But it is still best to first add a layer or image that is correctly defined. This will set the current project (or view) to that planetary projection. Now once you add in a WMS layer, it will (usually) conform to that defined map projection set in the view. For our polar WMS services, you will want to set the map projection to match Polar Stereographic (+-90 central lat, in meters) on the body you are using.

Lastly, using our planetary extensions within OpenLayers, you can easily make your own web maps using these same services. Copy and edit this example html document with the layers from above which uses our own planetary-ready version of Open Layers. There is also CartoCosmo, which is a student-created planetary-ready version of Leaflet (based on code from our original OpenLayers version). Once tweaked, feel free to host on your own website.


Hope this helps,
Trent