priority_flow.init_queue
========================

.. py:module:: priority_flow.init_queue

.. autoapi-nested-parse::

   Initialize queue for topographic processing.

   Line-by-line translation of Init_Queue.R from the R PriorityFlow package.
   R uses 1-based indexing and column-major (Fortran) order; we use 0-based
   and NumPy Fortran order so queue and behaviour match R.



Functions
---------

.. autoapisummary::

   priority_flow.init_queue.init_queue


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

.. py:function:: init_queue(dem: numpy.ndarray, initmask: Optional[numpy.ndarray] = None, domainmask: Optional[numpy.ndarray] = None, border: Optional[numpy.ndarray] = None, d4: Tuple[int, int, int, int] = (1, 2, 3, 4)) -> Dict[str, numpy.ndarray]

   Initialize queue for topographic processing.

   Sets up a queue and initializes marked and step matrices for DEM processing

   This function is a port of the R function ``InitQueue`` from the
   PriorityFlow package. It sets up the initial queue of cells, along
   with ``marked``, ``step``, ``basin`` and ``direction`` matrices used
   during DEM processing.

   :param dem: 2D array of elevations for the domain in HydroFrame orientation (nx by ny).
   :type dem: np.ndarray
   :param initmask: Mask with the same shape as ``dem`` indicating the subset of
                    cells to be considered for the initial queue (for example, only
                    river cells). If ``None``, all border cells in the domain are
                    eligible to be added to the queue.
   :type initmask: np.ndarray, optional
   :param domainmask: Mask defining the domain extent to be considered. If ``None``,
                      the entire rectangular extent of ``dem`` is used as the domain.
   :type domainmask: np.ndarray, optional
   :param border: Optional pre-computed border mask. If ``None``, the border is
                  derived from ``domainmask`` (cells on the outer edge of the
                  domain and internal boundaries).
   :type border: np.ndarray, optional
   :param d4: Direction numbering system for the D4 neighbors, given as
              ``(down, left, up, right)``. Defaults to ``(1, 2, 3, 4)`` to
              match the original R implementation.
   :type d4: tuple of int, optional

   :returns: Dictionary containing:

             - ``"mask"``: the effective initialization mask used to define
               candidate outlet cells (``initmask`` after any defaults).
             - ``"queue"``: 2D array of outlet cells with columns
               ``(row, col, elevation)`` in column-major order, suitable for
               use with ``d4_traverse_b``.
             - ``"marked"``: 2D array indicating which cells were added to
               the initial queue (1 for queue cells, 0 otherwise).
             - ``"basins"``: 2D array assigning a unique basin number to
               each outlet cell (queue entry).
             - ``"direction"``: 2D array of flow directions at outlet
               points, pointing out of the domain, using the ``d4`` numbering
               scheme.
   :rtype: Dict[str, np.ndarray]