bounds
======

.. py:module:: bounds


Classes
-------

.. autoapisummary::

   bounds.BoundingBox


Module Contents
---------------

.. py:class:: BoundingBox(x_min, x_max, y_min, y_max, crs=coordinate_reference_systems.DEFAULT_CRS)

   .. py:method:: contains_point(point, crs=None)

      Determine whether or not a point lies within this bounding box.

      :param point: An x, y tuple representing the coordinates of the point.
      :type point: tuple
      :param crs: The coordinate reference system on which the x and y coordinates of
                  the given point are defined. If `None` (default), assumes the input
                  point uses the same coordinate reference system as this bounding
                  box.
      :type crs: cartopy.crs.CRS, optional

      :rtype: bool



   .. py:attribute:: crs


   .. py:property:: east

      Convenience property to access this bbox's furthest east point.


   .. py:method:: from_bbox(bbox, source_crs=None, target_crs=None)
      :classmethod:


      Generate a bounding box which completely contains another bounding box.

      The intended use case of this method is to generate a bounding box on
      a different coordinate reference system to an input bounding box,
      ensuring that the entire input bounding box is countained.

      :param bbox: The bounding box around which to generate a new bounding box. If a
                   list, mus
      :type bbox: list or earthkit.plots.geo.bounds.BoundingBox
      :param source_crs: The coordinate reference system of the source bounding box.  If
                         `None` (default), assumes a cylindrical lat-lon CRS, unless the
                         source bounding box is an `earthkit.plots.geo.bounds.BoundingBox`
                         with its own CRS.
      :type source_crs: cartopy.crs.CRS, optional
      :param target_crs: The coordinate reference system in which to generate a new bounding
                         box which entriely contains the input bounding box. If `None`
                         (default), attempts to find an "optimised" target CRS based on the
                         domain extents.
      :type target_crs: cartopy.crs.CRS, optional

      :rtype: earthkit.plots.geo.bounds.BoundingBox



   .. py:method:: from_geometry(geometry, source_crs=coordinate_reference_systems.DEFAULT_CRS, target_crs=None)
      :classmethod:


      Generate a tight bounding box around a geometry.

      :param geometry: A shapely geometry around which the bounding box should be drawn.
      :type geometry: shapely.geometry
      :param source_crs: The coordinate reference system on which the geometry's coordinates
                         are defined. If `None`, assumes a cylindrical lat-lon CRS.
      :type source_crs: cartopy.crs.CRS, optional
      :param target_crs: The target coordinate reference system for the generated bounding
                         box.
      :type target_crs: cartopy.crs.CRS, optional

      :rtype: earthkit.plots.geo.bounds.BoundingBox



   .. py:property:: north

      Convenience property to access this bbox's furthest north point.


   .. py:property:: south

      Convenience property to access this bbox's furthest south point.


   .. py:method:: to_bbox(target_crs)

      Convert bounding box onto a new coordinate reference system.

      Paratemers
      ----------
      target_crs : cartopy.crs.CRS
          The coordinate reference system to use for the new bounding box.

      :rtype: earthkit.plots.geo.BoundingBox



   .. py:method:: to_cartopy_bounds()

      Convert bounding box to a cartopy-compatible list of bounds.

      :rtype: tuple



   .. py:method:: to_latlon_bbox()

      Generate a tight bounding box around a geometry.

      :param geometry: A shapely geometry around which the bounding box should be drawn.
      :type geometry: shapely.geometry
      :param source_crs: The coordinate reference system on which the geometry's coordinates
                         are defined. If `None`, assumes a cylindrical lat-lon CRS.
      :type source_crs: cartopy.crs.CRS, optional
      :param target_crs: The target coordinate reference system for the generated bounding
                         box.
      :type target_crs: cartopy.crs.CRS, optional

      :rtype: earthkit.plots.geo.bounds.BoundingBox



   .. py:method:: to_optimised_bbox()

      Generate a new bounding box using the "optimised" CRS for these extents.

      The method for choosing an optimised CRS is as follows:
          - If the area of the map is greater than 60% of the globe, use a
            global equirectangular CRS.
          - If the central latitude is within ±25 degrees, use an
            equirectangular CRS.
          - If the central latitude is greater (less) than +(-)75 degrees, use
            a North (South) Polar Stereo CRS.
          - If the central latitude falls between ±25 and ±75 degrees and the
            aspect ratio is > 0.8, use an Albers Equal Area CRS.
          - If the central latitude falls between ±25 and ±75 degrees and the
            aspect ratio is < 0.8, use a Transverse Mercator CRS.

      This method is adapted from the method used by
      https://projectionwizard.org,
      which is discussed in the following article:
      Šavrič, B., Jenny, B. and Jenny, H. (2016). Projection Wizard – An
      online map projection selection tool. The Cartographic Journal, 53–2, p.
      177–185.
      Doi: 10.1080/00087041.2015.1131938.

      :param bounds: The latitude and longitude extents of the bounding box, given as
                     `[min_longitude, max_longitude, min_latitude, max_latitude]`.
      :type bounds: list

      :rtype: cartopy.crs.CRS



   .. py:property:: west

      Convenience property to access this bbox's furthest west point.


   .. py:attribute:: x_max


   .. py:attribute:: x_min


   .. py:attribute:: y_max


   .. py:attribute:: y_min