convster.helper
===============

.. py:module:: convster.helper

.. autoapi-nested-parse::

   Array utility functions for the convster package.

   This module provides low-level helper functions for inspecting and manipulating
   NumPy arrays. Currently, it exposes utilities for locating the first and last
   non-zero element along a given axis, which are used internally during filter
   application to determine valid data ranges within raster bands.



Functions
---------

.. autoapisummary::

   convster.helper.first_nonzero
   convster.helper.last_nonzero


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

.. py:function:: first_nonzero(data, axis = 0, no_value = -1)

   Return the index of the first non-zero value along the given axis.

   :param data: Input array to examine.
   :type data: NDArray
   :param axis: Array axis along which to search for the first non-zero. Default is 0.
   :type axis: int
   :param no_value: Value to return when no non-zero entries are found along an axis.
                    Default is -1.
   :type no_value: int

   :returns: Array indices of the first non-zero values along the specified axis.
             If no non-zero is found, returns `no_value` for that slice.
   :rtype: indices

   .. seealso::

      :func:`last_nonzero`
          Return the index of the last non-zero value.

   .. rubric:: Examples

   >>> a = np.array([
   ...     [0, 0, 3, 0],
   ...     [1, 0, 0, 0],
   ...     [0, 2, 0, 0],
   ...     [0, 0, 0, 4]
   ... ])
   >>> first_nonzero(a, axis=1)
   array([2, 0, 1, 3])
   >>> first_nonzero(a, axis=0)
   array([1, 2, 0, 3])


.. py:function:: last_nonzero(data, axis = 0, no_value = -1)

   Return the index of the last non-zero value along the given axis.

   :param data: Input array to examine.
   :type data: NDArray
   :param axis: Array axis along which to search for the last non-zero. Default is 0.
   :type axis: int
   :param no_value: Value to return when no non-zero entries are found along an axis.
                    Default is -1.
   :type no_value: int

   :returns: Array indices of the last non-zero values along the specified axis.
             If no non-zero is found, returns `no_value` for that slice.
   :rtype: indices

   .. seealso::

      :func:`first_nonzero`
          Return the index of the first non-zero value.

   .. rubric:: Examples

   >>> a = np.array([
   ...     [0, 0, 3, 0],
   ...     [1, 0, 0, 0],
   ...     [0, 2, 0, 0],
   ...     [0, 0, 0, 4]
   ... ])
   >>> last_nonzero(a, axis=1)
   array([2, 0, 1, 3])
   >>> last_nonzero(a, axis=0)
   array([1, 2, 2, 3])