voxcity.utils.orientation

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

ORIENTATION_NORTH_UP

ORIENTATION_SOUTH_UP

Functions

ensure_orientation(→ numpy.ndarray)

Return grid converted from orientation_in to orientation_out.

Module Contents

voxcity.utils.orientation.ORIENTATION_NORTH_UP: Literal['north_up'] = 'north_up'
voxcity.utils.orientation.ORIENTATION_SOUTH_UP: Literal['south_up'] = 'south_up'
voxcity.utils.orientation.ensure_orientation(grid: numpy.ndarray, orientation_in: Literal['north_up', 'south_up'], orientation_out: Literal['north_up', 'south_up'] = ORIENTATION_NORTH_UP) → numpy.ndarray[source]

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.

Notes

  • This function does not copy when no conversion is needed.

  • Use at data boundaries (read/write, interop) rather than deep in processing code.