rsqsim_api.io.array_operations

Raster and grid I/O utilities for GeoTIFF and GMT NetCDF formats.

Functions

read_grid(raster_file[, nan_threshold, window, ...])

Read a raster file into coordinate and value arrays.

read_tiff(tiff[, x_correct, y_correct, nan_threshold, ...])

Read a GeoTIFF file into coordinate and value arrays.

read_gmt_grid(grd_file)

Read a GMT-compatible NetCDF4 grid file.

write_tiff(filename, x, y, z[, epsg, reverse_y, ...])

Write coordinate and data arrays to a GeoTIFF file.

write_gmt_grd(x_array, y_array, mesh, grid_name)

Write coordinate and data arrays to a GMT-compatible NetCDF4 grid file.

tiff2grd(tiff, grd[, x_correct, y_correct, window, buffer])

Convert a GeoTIFF to a GMT NetCDF4 grid file.

grd2tiff(grd, tiff[, x_correct, y_correct])

Convert a GMT NetCDF4 grid file to a GeoTIFF.

array_to_gmt(array, out_file)

Write a NumPy array to a plain-text GMT-compatible file.

clip_tiff(in_tiff, out_tiff, window[, buffer])

Clip a GeoTIFF to a spatial window and write the result.

reproject_tiff(in_raster, out_raster[, dst_epsg, ...])

Reproject a raster to a different coordinate reference system.

Module Contents

rsqsim_api.io.array_operations.read_grid(raster_file, nan_threshold=100, window=None, buffer=100, return_meta=False)[source]

Read a raster file into coordinate and value arrays.

Supports optional spatial windowing by bounding box or shapefile extent. Values with absolute magnitude above nan_threshold are replaced with NaN.

Parameters:

  • raster_file (str) – Path to the raster file (any format supported by rasterio).

  • nan_threshold (float | int) – Values with |z| > nan_threshold are set to NaN. Defaults to 100.

  • window (str | list | tuple | numpy.ndarray) – Optional spatial subset. May be a path to a vector file (whose bounding box is used), or a 4-element sequence [x_min, y_min, x_max, y_max] in the raster’s CRS.

  • buffer (float | int) – Extra margin (in CRS units) added around the window bounds. Defaults to 100.

  • return_meta (bool) – If True, also return the rasterio metadata dict updated to reflect the windowed read.

Returns:

  • x (numpy.ndarray) – 1-D array of easting (column-centre) coordinates.

  • y (numpy.ndarray) – 1-D array of northing (row-centre) coordinates.

  • z (numpy.ndarray of shape (len(y), len(x))) – Data values with out-of-range entries set to NaN.

  • geo_meta (dict, optional) – Rasterio metadata dict (only returned when return_meta=True).

Raises:

AssertionError – If raster_file does not exist, the window sequence does not have exactly 4 elements, or x_max <= x_min / y_max <= y_min.

rsqsim_api.io.array_operations.read_tiff(tiff, x_correct=None, y_correct=None, nan_threshold=9000, make_y_ascending=False, window=None, buffer=100, return_meta=False)[source]

Read a GeoTIFF file into coordinate and value arrays.

Thin wrapper around read_grid() with GeoTIFF-specific defaults and optional coordinate offset correction.

Parameters:

  • tiff (str) – Path to the GeoTIFF file.

  • x_correct (float) – Offset added to x coordinates to correct for pixel vs. gridline registration differences (GMT convention).

  • y_correct (float) – Offset added to y coordinates (same purpose as x_correct).

  • nan_threshold (float | int) – Values with |z| > nan_threshold are set to NaN. Defaults to 9000 (suitable for elevation data in metres).

  • make_y_ascending (bool) – If True and y[0] > y[-1], reverse y and the corresponding rows of z so that y increases monotonically.

  • window (str | list | tuple | numpy.ndarray) – Optional spatial subset passed to read_grid().

  • buffer (float | int) – Buffer added around the window bounds in CRS units.

  • return_meta (bool) – If True, also return the rasterio metadata dict.

Returns:

  • x (numpy.ndarray) – 1-D easting coordinate array.

  • y (numpy.ndarray) – 1-D northing coordinate array.

  • z (numpy.ndarray of shape (len(y), len(x))) – Data values.

  • geo_meta (dict, optional) – Rasterio metadata (only returned when return_meta=True).

Raises:

AssertionError – If tiff does not exist.

rsqsim_api.io.array_operations.read_gmt_grid(grd_file)[source]

Read a GMT-compatible NetCDF4 grid file.

Reads variables named x, y, and z from the file and fills any masked values with NaN. Faster than using rasterio for NetCDF grids.

Parameters:

grd_file (str) – Path to the GMT .grd NetCDF4 file.

Returns:

  • x (numpy.ndarray) – 1-D array of x (easting) coordinate values.

  • y (numpy.ndarray) – 1-D array of y (northing) coordinate values.

  • z (numpy.ndarray of shape (len(y), len(x))) – Grid data values; masked values replaced with NaN.

Raises:

AssertionError – If grd_file does not exist or if the file does not contain variables named x, y, and z.

rsqsim_api.io.array_operations.write_tiff(filename, x, y, z, epsg=2193, reverse_y=False, compress_lzw=True)[source]

Write coordinate and data arrays to a GeoTIFF file.

Parameters:

  • filename (str) – Output GeoTIFF file path.

  • x (numpy.ndarray) – 1-D array of easting coordinates (column centres).

  • y (numpy.ndarray) – 1-D array of northing coordinates (row centres).

  • z (numpy.ndarray of shape (len(y), len(x))) – Data values to write to band 1.

  • epsg (int) – EPSG code for the output coordinate reference system. Defaults to 2193 (NZTM2000).

  • reverse_y (bool) – If True, write the GeoTIFF with y decreasing (top-to-bottom), as preferred by some GIS applications.

  • compress_lzw (bool) – If True (default), apply LZW compression.

Raises:

AssertionError – If x or y are not 1-D, or if z.shape != (len(y), len(x)).

rsqsim_api.io.array_operations.write_gmt_grd(x_array, y_array, mesh, grid_name)[source]

Write coordinate and data arrays to a GMT-compatible NetCDF4 grid file.

Parameters:

  • x_array (numpy.ndarray) – 1-D array of x (easting) coordinate values.

  • y_array (numpy.ndarray) – 1-D array of y (northing) coordinate values.

  • mesh (numpy.ndarray of shape (len(y_array), len(x_array))) – Data values (z) to store in the z variable.

  • grid_name (str) – Output file path, typically ending in .grd.

Raises:

AssertionError – If x_array or y_array are not 1-D, or if mesh.shape != (len(y_array), len(x_array)).

rsqsim_api.io.array_operations.tiff2grd(tiff, grd, x_correct=None, y_correct=None, window=None, buffer=100)[source]

Convert a GeoTIFF to a GMT NetCDF4 grid file.

Parameters:

  • tiff (str) – Path to the input GeoTIFF file.

  • grd (str) – Path for the output GMT .grd file.

  • x_correct (float) – Offset applied to x coordinates to correct for pixel vs. gridline registration differences.

  • y_correct (float) – Offset applied to y coordinates (same purpose as x_correct).

  • window (list | tuple | int) – Optional spatial subset passed to read_tiff().

  • buffer (float | int) – Buffer added around the window bounds in CRS units.

Raises:

AssertionError – If tiff does not exist.

rsqsim_api.io.array_operations.grd2tiff(grd, tiff, x_correct=None, y_correct=None)[source]

Convert a GMT NetCDF4 grid file to a GeoTIFF.

Parameters:

  • grd (str) – Path to the input GMT .grd file.

  • tiff (str) – Path for the output GeoTIFF file.

  • x_correct (float) – Offset applied to x coordinates after reading.

  • y_correct (float) – Offset applied to y coordinates after reading.

Raises:

AssertionError – If grd does not exist.

rsqsim_api.io.array_operations.array_to_gmt(array, out_file)[source]

Write a NumPy array to a plain-text GMT-compatible file.

Each row of array is written as a space-separated line of values formatted to 4 decimal places.

Parameters:

  • array (numpy.ndarray) – 1-D or 2-D array to write. Must have at least 2 elements or columns.

  • out_file (str) – Output file path.

Raises:

AssertionError – If the last dimension of array has fewer than 2 elements.

rsqsim_api.io.array_operations.clip_tiff(in_tiff, out_tiff, window, buffer=100)[source]

Clip a GeoTIFF to a spatial window and write the result.

Parameters:

  • in_tiff (str) – Path to the input GeoTIFF file.

  • out_tiff (str) – Path for the output clipped GeoTIFF.

  • window (str | list | tuple | int) – Spatial subset specifier: a path to a vector file or a 4-element sequence [x_min, y_min, x_max, y_max].

  • buffer (float | int) – Extra margin added around the window bounds in CRS units. Defaults to 100.

Raises:

AssertionError – If in_tiff does not exist.

rsqsim_api.io.array_operations.reproject_tiff(in_raster, out_raster, dst_epsg=4326, window=None, buffer=100, out_format='tiff')[source]

Reproject a raster to a different coordinate reference system.

Reads the input raster, reprojects it to the target CRS using nearest-neighbour resampling, and writes the result as a GeoTIFF or GMT grid.

Parameters:

  • in_raster (str) – Path to the input raster file.

  • out_raster (str) – Path for the output reprojected file.

  • dst_epsg (int) – Target EPSG code. Defaults to 4326 (WGS84 geographic).

  • window (str | list | tuple | int) – Optional spatial subset applied before reprojection.

  • buffer (float | int) – Buffer added around the window bounds in CRS units.

  • out_format – Output format: "tiff" (default) or "grd".

Raises:

AssertionError – If out_format is not "tiff" or "grd".

Notes

Based on the rasterio reprojection example from the rasterio documentation.