convert coord btw. UTM and lat/lon

[yunjunz]

Description of proposed changes

• utils.utils0.py: add the following functions to convert coordinates between UTM and lat/lon, as described in Using geocoded SLC input products to mintpy #1016 (comment).

  • utm2latlon()
  • latlon2utm()
  • utm_zone2epsg_code(): bugfix if the latitude letter is not N or S
  • get_lat_lon(): convert UTM to lat/lon to ensure lat/lon output for hyp3 products. Together with hdfeos5: calc/write latitude/longitude if missing in geometry file #1050, this fixes hdfeos5: latitude/longitude missing for hyp3 product #1049

• add utm to the dependency, since 1) it depends on numpy only; and 2) it's available on PyPI and conda-forge

  • requirements.txt
  • setup.py

Reminders

• Pass Pre-commit check (green)
• Pass Codacy code review (green)
• Pass Circle CI test (green)
• Make sure that your code follows our style. Use the other functions/files as a basis.
• If modifying functionality, describe changes to function behavior and arguments in a comment below the function declaration.
• If adding new functionality, add a detailed description to the documentation and/or an example.

[scottstanie]

Is utm_zone[-1].upper() either "S" or "N"? If so, then this is always false:

>>> 'N' < 'N'
False
>>> 'S' < 'N'
False

[scottstanie]

Oh sorry, this is for the "UTM Zone Designators" from here http://www.jaworski.ca/utmzones.htm ? I had only seen them called "Latitude Bands" as part of MGRS https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system#Latitude_bands

[yunjunz]

I should have asked for your review here. The UTM_ZONE attribute is grabbed using gdal here. So I am not sure if the last letter is the zone designator (latitude band), or just N / S. The change here assumes the zone designator.

TBH, I don't like the above two, which can be confusing. After searching gdal, the GetUTMZone() seems like a nice solution, with a negative value for the southern hemisphere, which is enough since the zone designator is not really needed for the coordinate conversion. Shall we use this convention instead for UTM_ZONE attribute? How does OPERA handle this?

[scottstanie]

I think we've been trying to just use EPSG codes, since they are more general than UTM and are just as easy to use with pyproj or gdal to warp coordinates due to the nice from_user_input and from_epsg:

In [1]: from pyproj import CRS
# e.g. the EPSG code 32617 is zone 17N
In [2]: CRS.from_epsg(32617) == CRS.from_user_input("epsg:32617") == CRS.from_user_input("32617")
Out[2]: True

In [3]: CRS.from_epsg(32617)
Out[3]:
<Derived Projected CRS: EPSG:32617>
Name: WGS 84 / UTM zone 17N
Axis Info [cartesian]:
- E[east]: Easting (metre)
- N[north]: Northing (metre)
Area of Use:
- name: Between 84°W and 78°W, northern hemisphere between equator and 84°N, onshore and offshore. Bahamas. Ecuador - north of equator. Canada - Nunavut; Ontario; Quebec. Cayman Islands. Colombia. Costa Rica. Cuba. Jamaica. Nicaragua. Panama. United States (USA).
- bounds: (-84.0, 0.0, -78.0, 84.0)
Coordinate Operation:
- name: UTM zone 17N
- method: Transverse Mercator
Datum: World Geodetic System 1984 ensemble
- Ellipsoid: WGS 84
- Prime Meridian: Greenwich

I'm now seeing how the confusion arose... it's very unfortunate that the utm python package links to http://www.jaworski.ca/utmzones.htm , since I'm >90% sure those "Zone designators" are not part of UTM, but rather MGRS:

https://cove.army.gov.au/article/smart-soldier-understanding-military-grid-reference-system

A UTM coordinate comprises a zone number, a hemisphere (N/S), an easting and a northing. [....]

UTM zones are divided in the same way MGRS zones are divided, although there is no letter designation after the zone number. Instead this letter indicator is replaced with an ‘N’ or ‘S’ depending on which hemisphere the map is within.

MGRS is built on top of UTM, so the initial zones are the same... but there's not the latitude bands, just "north/south". I think MGRS the added extra specifiers as a way to quickly communicate locations on maps.

[yunjunz]

I see, thanks for the examples and links. We should use EPSG code then as the primary metadata; and the UTM_ZONE without the latitude band as the secondary metadata (to calculate EPSG code if missing), while converting coordinates.

I will fix the utm_zone2epsg_code() with a PR right away.

It seems that pyproj may be enough for the coordinate conversion, and we do not really need the utm package (although it seems faster than pyproj, the speed is not our concern here since the conversion will be rare). Converting UTM to lat/lon seems straightforward, as a similar function already exists (utils.utils0.to_latlon()).

I will work on the function to convert lat/lon to UTM without utm package when I find time. utm provides an solution on calculating the UTM zone number given a lat/lon here.