sidescanpy.grids.raster#

SideScanGriddedRaster: xarray-validated wrapper for gridded backscatter.

A raster is a GridDefinition + 2D backscatter array with xarray schema.

Contents

SideScanGriddedRaster

Georeferenced gridded backscatter data.

class sidescanpy.grids.raster.SideScanGriddedRaster(grid_def, backscatter, channel_name=None, processing_level='raw', units='linear')#

Bases: object

Georeferenced gridded backscatter data.

Wraps a GridDefinition + 2D backscatter array in an xarray Dataset with validated schema (coordinates, variables, attributes).

Attributes:

grid_defGridDefinition: Grid definition (bbox, resolution, CRS).
backscatternp.ndarray: 2D array of shape (num_cells_ns, num_cells_ew).
channel_namestr: Frequency/channel identifier (e.g., “455 kHz”).
processing_levelstr: Processing level: “raw”, “radiometric”, etc.
datasetxr.Dataset: Build and cache xarray Dataset.

property crs#: Coordinate reference system.

property is_geographic#: True for a geographic CRS (e.g. WGS84), False for projected (e.g. UTM).

property y_coord_name#

Name of the north-south position coordinate in dataset.

"latitude" for a geographic CRS, "northing" for a projected one — matches whichever GridDefinition.get_grid_centers() actually returns for this raster’s CRS.

property x_coord_name#

Name of the east-west position coordinate in dataset.

"longitude" for a geographic CRS, "easting" for a projected one.

property y_values#: North-south position array (degrees or meters — see y_coord_name).

property x_values#: East-west position array (degrees or meters — see x_coord_name).

property bbox#: Bounding box (south, west, north, east).

property bounds_dict#: Bounding box as dict.

property resolution_m#: Grid resolution in meters.

property num_cells_ns#: Number of cells in north-south direction.

property num_cells_ew#: Number of cells in east-west direction.

property num_cells_total#: Total number of cells.

property extent_m_ns#: North-south extent in meters.

property extent_m_ew#: East-west extent in meters.

property data_coverage#: Fraction of non-NaN cells.

property dataset#

Build and cache xarray Dataset.

Returns:

xr.Dataset: Dataset with backscatter data variable, lat/lon coordinates, and validated schema attributes.

to_dataset()#

This raster as a plain xr.Dataset on 1-D cell-center axes.

Dims ("y", "x") with 1-D y/x coordinates (northing/ easting in metres for a projected CRS, latitude/longitude in degrees for a geographic one), in this raster’s own row order (south to north). Every data variable of dataset (backscatter, plus n_contributing_samples when present) is carried over with its attrs, and the CRS is stored CF-style in a scalar spatial_ref coordinate (crs_wkt / spatial_ref attrs, referenced from each variable’s grid_mapping), which rioxarray, GDAL and most CF readers recognize. Needs no optional dependency.

The grid’s cell centers are evenly spaced but, because GridDefinition stretches ceil(extent / resolution_m) cells across the bbox (a ratio within float error of a whole number counts as that number), the spacing is only approximately resolution_m (exactly it when the extent is a whole number of cells); x/y hold the real centers.

reproject_to(target_crs)#

Reproject raster to a different CRS.

Parameters:

target_crspyproj.CRS: Target coordinate reference system.

Returns:

SideScanGriddedRaster: New raster in target CRS. Backscatter data preserved (grid bounds transformed).

Notes

This reprojects the grid definition; backscatter values are not resampled. Use resample_channel_to_grid() for resampling. Grid cell count may change slightly due to extent changes; backscatter shape is preserved.

slice_by_bbox(bbox)#

Slice raster by geographic bounding box.

Parameters:

bboxtuple of (south, west, north, east): Bounding box to extract. Must overlap with raster bbox.

Returns:

SideScanGriddedRaster: Subset raster. Cell alignment may cause subset bounds to exceed requested bbox slightly.

Raises:

ValueError: If bbox does not overlap with raster bounds.

slice_by_indices(ns_slice=None, ew_slice=None)#

Slice raster by array indices.

Parameters:

ns_sliceslice, optional: North-south slice (default: all).
ew_sliceslice, optional: East-west slice (default: all).

Returns:

SideScanGriddedRaster: Subset raster.

to_dict(include_data=False)#

Serialize to dict.

Parameters:

include_databool, default False: If True, include backscatter array (as nested list). If False, include only metadata.

Returns:

dict: Serializable dict.

classmethod from_dict(d)#: Reconstruct from dict.