riogrande.prepare
=================

.. py:module:: riogrande.prepare

.. autoapi-nested-parse::

   Functions used to create windows/ views for parallelization processes in 2D raster maps.



Functions
---------

.. autoapisummary::

   riogrande.prepare.create_views
   riogrande.prepare.get_view
   riogrande.prepare.relative_view
   riogrande.prepare.update_view


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

.. py:function:: create_views(view_size, border, size)

   Returns a set of views on which an operation can be applied independently

   :param view_size: The size (width, height) in pixels of a single view (excluding borders)
   :type view_size: tuple[int, int]
   :param border: The border size (width, height) in number of pixels along each axis
   :type border: tuple[int, int]
   :param size: The total size of the map in number of pixels (width, height)
   :type size: tuple[int, int]

   :returns: The first element is a list of tuples (x, y, width, height) defining each
             view on which to apply an operation.
             The second element is a list of tuples (x, y, width, height) defining for
             each view the usable region.
             A region is usable if it does not contain any artificial border effects
             that were introduced from splitting up a bigger view into smaller chunks
   :rtype: tuple

   .. rubric:: Notes

   - Handles cases where the region cannot be divided evenly by `view_size`.
     The last row/column of views may be smaller (`leftovers`) and are still included.
     Uses :func:`math.floor` to compute the number of full blocks.
   - Borders on the outer edges are reduced to fit within the total size.

   .. seealso::

      :func:`~riogrande.prepare.update_view`
          Write a block into a view of an array.
      
      :func:`~riogrande.prepare.get_view`
          Read a rectangular view from an array.
      
      :func:`~riogrande.prepare.relative_view`
          Express an inner view relative to an outer view.

   .. rubric:: Examples

   >>> views, usable = create_views((5, 5), (1, 1), (9, 9))
   >>> len(views), len(usable)
   (4, 4)
   >>> views
   [(0, 0, 6, 6), (3, 0, 6, 5), (0, 3, 6, 6), (3, 3, 6, 6)]
   >>> usable
   [(0, 0, 4, 4), (4, 0, 5, 4), (0, 4, 4, 5), (4, 4, 5, 5)]


.. py:function:: get_view(data, view)

   Return a recatangular view of the data array

   .. note::
     data.shape == height, width!

   :param data: np.array to return the view from
   :type data: NDArray
   :param view: tuple (x, y, width, height) defining the view
   :type view: tuple[int, int, int, int]

   :returns: A view (slice) of `data` with shape `(height, width)` as specified
             by the `view` tuple.
   :rtype: NDArray

   .. seealso::

      :func:`~riogrande.prepare.update_view`
          Write a block into a view of an array.
      
      :func:`~riogrande.prepare.create_views`
          Generate a set of views covering an array.

   .. rubric:: Examples

   >>> arr = np.arange(16).reshape(4, 4)
   >>> arr
   array([[ 0,  1,  2,  3],
          [ 4,  5,  6,  7],
          [ 8,  9, 10, 11],
          [12, 13, 14, 15]])
   >>> get_view(arr, (1, 1, 2, 2))
   array([[ 5,  6],
          [ 9, 10]])


.. py:function:: relative_view(view, inner_view)

   Return the `inner_view` relative to `view`

   Given two rectangular regions defined as `(x, y, width, height)`,
   this function returns the coordinates of `inner_view` relative
   to the origin of `view`.

   :param view: A 4-tuple `(x, y, width, height)` defining the outer view.
   :type view: tuple[int, int, int, int]
   :param inner_view: A 4-tuple `(x, y, width, height)` defining a subregion inside `view`.
   :type inner_view: tuple[int, int, int, int]

   :returns: A 4-tuple `(x, y, width, height)` giving the position and size of
             `inner_view` relative to `view`. The width and height are unchanged.
   :rtype: tuple

   .. seealso::

      :func:`~riogrande.prepare.create_views`
          Generate outer and inner view pairs.

   .. rubric:: Examples

   >>> outer = (10, 20, 100, 50)
   >>> inner = (15, 30, 20, 10)
   >>> outer
   (10, 20, 100, 50)
   >>> inner
   (15, 30, 20, 10)
   >>> relative_view(outer, inner)
   (5, 10, 20, 10)


.. py:function:: update_view(data, view, block)

   Update a view from the data array with a block

   The block must exactly match the shape of the view:
   `block.shape == (view[3], view[2])`, where
   `view = (x, y, width, height)`.

   :param data: The array that we want to update
   :type data: NDArray
   :param view: tuple (x, y, width, height) defining the view of the data array to update
   :type view: tuple[int, int, int, int]
   :param block: np.array with the updated values.
   :type block: ArrayLike

   :rtype: None

   .. seealso::

      :func:`~riogrande.prepare.get_view`
          Read a rectangular view from an array.
      
      :func:`~riogrande.prepare.create_views`
          Generate a set of views covering an array.

   .. rubric:: Examples

   >>> data = np.zeros((5, 5))
   >>> block = np.ones((2, 3))
   >>> update_view(data, (1, 2, 3, 2), block)
   >>> data
   array([[0., 0., 0., 0., 0.],
          [0., 0., 0., 0., 0.],
          [0., 1., 1., 1., 0.],
          [0., 1., 1., 1., 0.],
          [0., 0., 0., 0., 0.]])