voxcity.utils.orientation
=========================

.. py:module:: voxcity.utils.orientation

.. autoapi-nested-parse::

   Grid orientation helpers.

   Contract:
   - Core Phase 3 processing uses uv_m/SOUTH_UP: axis 0 = u/north (row 0 = southern origin edge),
     increasing row index moves north. Columns increase eastward: column 0 is
     west/left and indices increase toward the east/right. All processing functions
     accept and return 2D grids in this orientation unless explicitly documented
     otherwise.
   - Visualization utilities may flip vertically for display purposes only.
   - 3D indexing follows (row, col, z) = (north→south, west→east, ground→up).

   Utilities here are intentionally minimal to avoid introducing hidden behavior.
   They can be used at I/O boundaries (e.g., when reading rasters with south_up
   conventions) to normalize to the internal orientation.

   Coordinate-frame vocabulary (see also voxcity.utils.projector):
     uv cell — cell index (i, j) in uv_m/SOUTH_UP (Phase 3); row 0 is south/origin.
     legacy ij_south — same layout as uv_m/SOUTH_UP; kept for backward compatibility.
     ensure_orientation() is the only legitimate place to convert between the two.



Attributes
----------

.. autoapisummary::

   voxcity.utils.orientation.ORIENTATION_NORTH_UP
   voxcity.utils.orientation.ORIENTATION_SOUTH_UP


Functions
---------

.. autoapisummary::

   voxcity.utils.orientation.ensure_orientation


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

.. py:data:: ORIENTATION_NORTH_UP
   :type:  Literal['north_up']
   :value: 'north_up'


.. py:data:: ORIENTATION_SOUTH_UP
   :type:  Literal['south_up']
   :value: 'south_up'


.. py:function:: ensure_orientation(grid: numpy.ndarray, orientation_in: Literal['north_up', 'south_up'], orientation_out: Literal['north_up', 'south_up'] = ORIENTATION_NORTH_UP) -> numpy.ndarray

   Return ``grid`` converted from ``orientation_in`` to ``orientation_out``.

   Both orientations are defined for 2D arrays as:
   - north_up: row 0 = north/top, last row = south/bottom
   - south_up: row 0 = south/bottom, last row = north/top

   If orientations match, the input array is returned unchanged. When converting
   between north_up and south_up, a vertical flip is applied using ``np.flipud``.

   .. rubric:: Notes

   - This function does not copy when no conversion is needed.
   - Use at data boundaries (read/write, interop) rather than deep in processing code.