sidescanpy.export.windows.native#

Native slant-range windows that are square in metres.

Sidescan pings are often much further apart along track than samples are across track (e.g. 24 cm between pings, 2.4 cm between samples). Resampling such data onto a fine metric grid repeats or smears pings; cropping a square of native pixels squashes shapes by the same ratio. The windows here cut a region that is square (chip) or a fixed length (tile) in metres from the native ping x sample grid and resize it with linear interpolation, so the native detail is kept and shapes have their true proportions.

native_chip() – one side, centred on a target, size_m square.
swath_tiles() – the whole survey as consecutive dual-swath tiles (port mirrored on the left, starboard on the right), e.g. for annotating every object.
NativeWindow – where an image sits in native (ping, sample, channel) space, with conversions both ways, so boxes drawn on an image can be turned back into sonar coordinates and re-cut at another scale.

Ping and sample arguments are positions along the dataset’s ping and sample axes. Values are taken from value_var as stored (dB after the tvg step); convert to an image with sidescanpy.export.image.to_uint8().

2026 rshomberg@uri.edu

Contents

`along_track_spacing_m`	Mean distance between consecutive pings (m), from the per-ping positions.
`NativeWindow`	Placement of an image in native (ping, sample, channel) space.
`native_chip`	A `size_m` x `size_m` window around a target, as a `size_px` square image.
`swath_tiles`	Cut the whole channel into consecutive dual-swath tiles.

sidescanpy.export.windows.native.along_track_spacing_m(ds)#

Mean distance between consecutive pings (m), from the per-ping positions.

Repeated navigation fixes (several pings sharing one fix) do not bias the result: the summed track length is divided by the number of ping steps.

Raises:

ValueError: Fewer than two pings with a position, or a stationary track.

class sidescanpy.export.windows.native.NativeWindow(layout, channel, ping_start, ping_stop, sample_start, sample_stop, px_per_ping, px_per_sample, width, height, side_width, m_per_ping, m_per_sample)#

Bases: object

Placement of an image in native (ping, sample, channel) space.

Pixel coordinates are continuous, with (0, 0) at the image’s top-left corner; native cell (ping, sample) covers [ping, ping + 1) x [sample, sample + 1). layout is "chip" (one channel, samples increasing to the right) or "dual" (port mirrored left of side_width, starboard right of it, samples increasing outward).

Attributes:

layout{“chip”, “dual”}
channelint or None: The chip’s side (0 port, 1 starboard); None for dual.
ping_start, ping_stop, sample_start, sample_stopint: Native extent (half-open). A chip’s extent can reach outside the dataset (padded with NaN) so the target stays centred.
px_per_ping, px_per_samplefloat: Image pixels per native ping / sample.
width, height, side_widthint: Image size; side_width is the width of one side in "dual".
m_per_ping, m_per_samplefloat: Native spacing used.

to_pixel(ping, sample, channel)#: Image (x, y) of native position (ping, sample) on channel.

to_native(x, y)#: Native (ping, sample, channel) of image position (x, y).

box_to_native(x, y, w, h)#

Native extent of an image box (x, y, w, h) (top-left corner, size).

The side is the one under the box centre; a dual-swath box crossing the centre line is clipped to that side.

sidescanpy.export.windows.native.native_chip(ds, *, ping, channel, sample, size_m, size_px, value_var='backscatter_intensity', m_per_ping=None)#

A size_m x size_m window around a target, as a size_px square image.

Parameters:

dsxr.Dataset: One frequency channel (loaded or lazy).
ping, channel, sampleint: Target position (positions along ping/sample; channel 0 port, 1 starboard).
size_mfloat: Window side in metres, both along and across track (slant range).
size_pxint: Output side in pixels.
value_varstr, default “backscatter_intensity”
m_per_pingfloat, optional: Along-track spacing; default along_track_spacing_m() over the pings around the target.

Returns:

imagenp.ndarray: float32 (size_px, size_px), NaN where there is no data (outside the dataset or already NaN); rows are pings, columns samples.
windowNativeWindow

sidescanpy.export.windows.native.swath_tiles(ds, *, tile_m, px_m, overlap_m=0.0, value_var='backscatter_intensity', m_per_ping=None)#

Cut the whole channel into consecutive dual-swath tiles.

Each tile spans tile_m along track (the last one may be shorter) and the full recorded range on both sides, resized so one pixel is px_m metres both ways. Port is mirrored on the left, starboard on the right, nadir in the middle.

Parameters:

dsxr.Dataset: One frequency channel.
tile_mfloat: Tile length along track (m).
px_mfloat: Pixel size (m) in both directions.
overlap_mfloat, default 0: Along-track overlap between consecutive tiles, so an object on a tile edge appears whole in one of them.
value_varstr, default “backscatter_intensity”
m_per_pingfloat, optional: Default: along_track_spacing_m() over the whole channel.

Returns:

list of (image, NativeWindow): float32 images (NaN where there is no data).