Oblique and Rotated Mercator (#5548)

* Introduce new coord system classes.

* Add loading code for oblique mercator.

* Fix for azimuth check.

* Add saving code for oblique mercator.

* Fix to rotated repr.

* Scale factor wording fix.

* Tests first pass.

* Temp test disable.

* Temp RotatedMercator test disable.

* Deprecate RotatedMercator.

* Revert "Temp RotatedMercator test disable."

This reverts commit 27c486f.

* First attempted fix for RM test inheritance.

* Revert "Temp test disable."

This reverts commit a81507c.

* Fix warnings doctests.

* Add deprecation test for RotatedMercator.

* Oblique Mercator loading tests.

* Oblique Mercator loading deprecation test.

* Saving test for Oblique Mercator.

* Fix isinstance() check.

* What's New entry.

* Temp test disable.

* More temp test disabling.

* WIP testing.

* WIP testing.

* Revert "More temp test disabling."

This reverts commit ff251b7.

* Revert "Temp test disable."

This reverts commit 77eba55.

* Use RotatedMercator inheritance for isinstance() check.

* Check grid_mapping_name instead of using isinstance().

* Better type hinting.

* Use return over yield in a fixture.

* Duck typing comment.

* Better grid_mapping_name checking.

* Better structure for test parameterisation.

Author: trexfeathers

docs/src/further_topics/filtering_warnings.rst

@@ -47,9 +47,9 @@ Warnings:
 
     >>> my_operation()
     ...
-    iris/coord_systems.py:454: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
+    iris/coord_systems.py:456: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
       warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning)
-    iris/coord_systems.py:821: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
+    iris/coord_systems.py:823: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
       warnings.warn(
 
 Warnings can be suppressed using the Python warnings filter with the ``ignore``
@@ -110,7 +110,7 @@ You can target specific Warning messages, e.g.
     ...     warnings.filterwarnings("ignore", message="Discarding false_easting")
     ...     my_operation()
     ...
-    iris/coord_systems.py:454: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
+    iris/coord_systems.py:456: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
       warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning)
 
 ::
@@ -125,10 +125,10 @@ Or you can target Warnings raised by specific lines of specific modules, e.g.
 .. doctest:: filtering_warnings
 
     >>> with warnings.catch_warnings():
-    ...     warnings.filterwarnings("ignore", module="iris.coord_systems", lineno=454)
+    ...     warnings.filterwarnings("ignore", module="iris.coord_systems", lineno=456)
     ...     my_operation()
     ...
-    iris/coord_systems.py:821: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
+    iris/coord_systems.py:823: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
       warnings.warn(
 
 ::
@@ -188,7 +188,7 @@ module during execution:
     ...     )
     ...     my_operation()
     ...
-    iris/coord_systems.py:454: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
+    iris/coord_systems.py:456: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
       warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning)
 
 ----

docs/src/whatsnew/latest.rst

@@ -34,6 +34,10 @@ This document explains the changes made to Iris for this release
    :class:`UserWarning`\s for richer filtering. The full index of
    sub-categories can be seen here: :mod:`iris.exceptions` . (:pull:`5498`)
 
+#. `@trexfeathers`_ added the :class:`~iris.coord_systems.ObliqueMercator`
+   and :class:`~iris.coord_systems.RotatedMercator` coordinate systems,
+   complete with NetCDF loading and saving. (:pull:`5548`)
+
 
 🐛 Bugs Fixed
 =============

lib/iris/coord_systems.py

@@ -10,11 +10,13 @@
 
 from abc import ABCMeta, abstractmethod
 from functools import cached_property
+import re
 import warnings
 
 import cartopy.crs as ccrs
 import numpy as np
 
+from iris._deprecation import warn_deprecated
 import iris.exceptions
 
 
@@ -1634,3 +1636,197 @@ def as_cartopy_crs(self):
 
     def as_cartopy_projection(self):
         return self.as_cartopy_crs()
+
+
+class ObliqueMercator(CoordSystem):
+    """
+    A cylindrical map projection, with XY coordinates measured in metres.
+
+    Designed for regions not well suited to :class:`Mercator` or
+    :class:`TransverseMercator`, as the positioning of the cylinder is more
+    customisable.
+
+    See Also
+    --------
+    :class:`RotatedMercator`
+
+    """
+
+    grid_mapping_name = "oblique_mercator"
+
+    def __init__(
+        self,
+        azimuth_of_central_line,
+        latitude_of_projection_origin,
+        longitude_of_projection_origin,
+        false_easting=None,
+        false_northing=None,
+        scale_factor_at_projection_origin=None,
+        ellipsoid=None,
+    ):
+        """
+        Constructs an ObliqueMercator object.
+
+        Parameters
+        ----------
+        azimuth_of_central_line : float
+            Azimuth of centerline clockwise from north at the center point of
+            the centre line.
+        latitude_of_projection_origin : float
+            The true longitude of the central meridian in degrees.
+        longitude_of_projection_origin: float
+            The true latitude of the planar origin in degrees.
+        false_easting: float, optional
+            X offset from the planar origin in metres.
+            Defaults to 0.0 .
+        false_northing: float, optional
+            Y offset from the planar origin in metres.
+            Defaults to 0.0 .
+        scale_factor_at_projection_origin: float, optional
+            Scale factor at the central meridian.
+            Defaults to 1.0 .
+        ellipsoid: :class:`GeogCS`, optional
+            If given, defines the ellipsoid.
+
+        Examples
+        --------
+        >>> from iris.coord_systems import GeogCS, ObliqueMercator
+        >>> my_ellipsoid = GeogCS(6371229.0, None, 0.0)
+        >>> ObliqueMercator(90.0, -22.0, -59.0, -25000.0, -25000.0, 1., my_ellipsoid)
+        ObliqueMercator(azimuth_of_central_line=90.0, latitude_of_projection_origin=-22.0, longitude_of_projection_origin=-59.0, false_easting=-25000.0, false_northing=-25000.0, scale_factor_at_projection_origin=1.0, ellipsoid=GeogCS(6371229.0))
+
+        """
+        #: Azimuth of centerline clockwise from north.
+        self.azimuth_of_central_line = float(azimuth_of_central_line)
+
+        #: True latitude of planar origin in degrees.
+        self.latitude_of_projection_origin = float(
+            latitude_of_projection_origin
+        )
+
+        #: True longitude of planar origin in degrees.
+        self.longitude_of_projection_origin = float(
+            longitude_of_projection_origin
+        )
+
+        #: X offset from planar origin in metres.
+        self.false_easting = _arg_default(false_easting, 0)
+
+        #: Y offset from planar origin in metres.
+        self.false_northing = _arg_default(false_northing, 0)
+
+        #: Scale factor at the central meridian.
+        self.scale_factor_at_projection_origin = _arg_default(
+            scale_factor_at_projection_origin, 1.0
+        )
+
+        #: Ellipsoid definition (:class:`GeogCS` or None).
+        self.ellipsoid = ellipsoid
+
+    def __repr__(self):
+        return (
+            "{!s}(azimuth_of_central_line={!r}, "
+            "latitude_of_projection_origin={!r}, "
+            "longitude_of_projection_origin={!r}, false_easting={!r}, "
+            "false_northing={!r}, scale_factor_at_projection_origin={!r}, "
+            "ellipsoid={!r})".format(
+                self.__class__.__name__,
+                self.azimuth_of_central_line,
+                self.latitude_of_projection_origin,
+                self.longitude_of_projection_origin,
+                self.false_easting,
+                self.false_northing,
+                self.scale_factor_at_projection_origin,
+                self.ellipsoid,
+            )
+        )
+
+    def as_cartopy_crs(self):
+        globe = self._ellipsoid_to_globe(self.ellipsoid, None)
+
+        return ccrs.ObliqueMercator(
+            central_longitude=self.longitude_of_projection_origin,
+            central_latitude=self.latitude_of_projection_origin,
+            false_easting=self.false_easting,
+            false_northing=self.false_northing,
+            scale_factor=self.scale_factor_at_projection_origin,
+            azimuth=self.azimuth_of_central_line,
+            globe=globe,
+        )
+
+    def as_cartopy_projection(self):
+        return self.as_cartopy_crs()
+
+
+class RotatedMercator(ObliqueMercator):
+    """
+    :class:`ObliqueMercator` with ``azimuth_of_central_line=90``.
+
+    As noted in CF versions 1.10 and earlier:
+
+        The Rotated Mercator projection is an Oblique Mercator projection
+        with azimuth = +90.
+
+    .. deprecated:: 3.8.0
+        This coordinate system was introduced as already scheduled for removal
+        in a future release, since CF version 1.11 onwards now requires use of
+        :class:`ObliqueMercator` with ``azimuth_of_central_line=90.`` .
+        Any :class:`RotatedMercator` instances will always be saved to NetCDF
+        as the ``oblique_mercator`` grid mapping.
+
+    """
+
+    def __init__(
+        self,
+        latitude_of_projection_origin,
+        longitude_of_projection_origin,
+        false_easting=None,
+        false_northing=None,
+        scale_factor_at_projection_origin=None,
+        ellipsoid=None,
+    ):
+        """
+        Constructs a RotatedMercator object.
+
+        Parameters
+        ----------
+        latitude_of_projection_origin : float
+            The true longitude of the central meridian in degrees.
+        longitude_of_projection_origin: float
+            The true latitude of the planar origin in degrees.
+        false_easting: float, optional
+            X offset from the planar origin in metres.
+            Defaults to 0.0 .
+        false_northing: float, optional
+            Y offset from the planar origin in metres.
+            Defaults to 0.0 .
+        scale_factor_at_projection_origin: float, optional
+            Scale factor at the central meridian.
+            Defaults to 1.0 .
+        ellipsoid: :class:`GeogCS`, optional
+            If given, defines the ellipsoid.
+
+        """
+        message = (
+            "iris.coord_systems.RotatedMercator is deprecated, and will be "
+            "removed in a future release. Instead please use "
+            "iris.coord_systems.ObliqueMercator with "
+            "azimuth_of_central_line=90 ."
+        )
+        warn_deprecated(message)
+
+        super().__init__(
+            90.0,
+            latitude_of_projection_origin,
+            longitude_of_projection_origin,
+            false_easting,
+            false_northing,
+            scale_factor_at_projection_origin,
+            ellipsoid,
+        )
+
+    def __repr__(self):
+        # Remove the azimuth argument from the parent repr.
+        result = super().__repr__()
+        result = re.sub(r"azimuth_of_central_line=\d*\.?\d*, ", "", result)
+        return result

lib/iris/fileformats/_nc_load_rules/actions.py

@@ -156,6 +156,14 @@ def action_default(engine):
         None,
         hh.build_geostationary_coordinate_system,
     ),
+    hh.CF_GRID_MAPPING_OBLIQUE: (
+        None,
+        hh.build_oblique_mercator_coordinate_system,
+    ),
+    hh.CF_GRID_MAPPING_ROTATED_MERCATOR: (
+        None,
+        hh.build_oblique_mercator_coordinate_system,
+    ),
 }
 
 

lib/iris/fileformats/_nc_load_rules/helpers.py

@@ -23,6 +23,7 @@
 import pyproj
 
 import iris
+from iris._deprecation import warn_deprecated
 import iris.aux_factory
 from iris.common.mixin import _get_valid_standard_name
 import iris.coord_systems
@@ -124,6 +125,8 @@
 CF_GRID_MAPPING_TRANSVERSE = "transverse_mercator"
 CF_GRID_MAPPING_VERTICAL = "vertical_perspective"
 CF_GRID_MAPPING_GEOSTATIONARY = "geostationary"
+CF_GRID_MAPPING_OBLIQUE = "oblique_mercator"
+CF_GRID_MAPPING_ROTATED_MERCATOR = "rotated_mercator"
 
 #
 # CF Attribute Names.
@@ -154,6 +157,7 @@
 CF_ATTR_GRID_STANDARD_PARALLEL = "standard_parallel"
 CF_ATTR_GRID_PERSPECTIVE_HEIGHT = "perspective_point_height"
 CF_ATTR_GRID_SWEEP_ANGLE_AXIS = "sweep_angle_axis"
+CF_ATTR_GRID_AZIMUTH_CENT_LINE = "azimuth_of_central_line"
 CF_ATTR_POSITIVE = "positive"
 CF_ATTR_STD_NAME = "standard_name"
 CF_ATTR_LONG_NAME = "long_name"
@@ -893,6 +897,58 @@ def build_geostationary_coordinate_system(engine, cf_grid_var):
     return cs
 
 
+################################################################################
+def build_oblique_mercator_coordinate_system(engine, cf_grid_var):
+    """
+    Create an oblique mercator coordinate system from the CF-netCDF
+    grid mapping variable.
+
+    """
+    ellipsoid = _get_ellipsoid(cf_grid_var)
+
+    azimuth_of_central_line = getattr(
+        cf_grid_var, CF_ATTR_GRID_AZIMUTH_CENT_LINE, None
+    )
+    latitude_of_projection_origin = getattr(
+        cf_grid_var, CF_ATTR_GRID_LAT_OF_PROJ_ORIGIN, None
+    )
+    longitude_of_projection_origin = getattr(
+        cf_grid_var, CF_ATTR_GRID_LON_OF_PROJ_ORIGIN, None
+    )
+    scale_factor_at_projection_origin = getattr(
+        cf_grid_var, CF_ATTR_GRID_SCALE_FACTOR_AT_PROJ_ORIGIN, None
+    )
+    false_easting = getattr(cf_grid_var, CF_ATTR_GRID_FALSE_EASTING, None)
+    false_northing = getattr(cf_grid_var, CF_ATTR_GRID_FALSE_NORTHING, None)
+    kwargs = dict(
+        azimuth_of_central_line=azimuth_of_central_line,
+        latitude_of_projection_origin=latitude_of_projection_origin,
+        longitude_of_projection_origin=longitude_of_projection_origin,
+        scale_factor_at_projection_origin=scale_factor_at_projection_origin,
+        false_easting=false_easting,
+        false_northing=false_northing,
+        ellipsoid=ellipsoid,
+    )
+
+    # Handle the alternative form noted in CF: rotated mercator.
+    grid_mapping_name = getattr(cf_grid_var, CF_ATTR_GRID_MAPPING_NAME)
+    candidate_systems = dict(
+        oblique_mercator=iris.coord_systems.ObliqueMercator,
+        rotated_mercator=iris.coord_systems.RotatedMercator,
+    )
+    if grid_mapping_name == "rotated_mercator":
+        message = (
+            "Iris will stop loading the rotated_mercator grid mapping name in "
+            "a future release, in accordance with CF version 1.11 . Instead "
+            "please use oblique_mercator with azimuth_of_central_line = 90 ."
+        )
+        warn_deprecated(message)
+        del kwargs[CF_ATTR_GRID_AZIMUTH_CENT_LINE]
+
+    cs = candidate_systems[grid_mapping_name](**kwargs)
+    return cs
+
+
 ################################################################################
 def get_attr_units(cf_var, attributes):
     attr_units = getattr(cf_var, CF_ATTR_UNITS, UNKNOWN_UNIT_STRING)