sidescanpy.export.ml.tiles#

Swath tiles for annotation and detection, and boxes drawn on them back to targets.

The round trip a detector workflow needs:

write_swath_tiles() cuts a channel into dual-swath tiles (swath_tiles()), writes each as an 8-bit PNG and records where every tile sits in the sonar data in an index file (tiles.json).
People annotate the tiles, or a detector predicts boxes on them, in any tool that exports COCO (FiftyOne, CVAT, Label Studio, …). read_coco_boxes() reads the boxes per image.
boxes_to_targets() turns the boxes on one tile into Target records: file, ping, side, sample and, on a georeferenced channel, latitude and longitude. They can be rendered as chips with build_target_dataset() or scored against a catalog with sidescanpy.targets.score.match_targets().

2026 rshomberg@uri.edu

Contents

`TILE_INDEX_NAME`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`TileBox`	One box on a tile image, from an annotation or a detector.
`TileRecord`	Where one tile image sits in the sonar data (an entry of `tiles.json`).
`write_swath_tiles`	Write a channel as dual-swath PNG tiles plus an index for mapping boxes back.
`read_tile_index`	Read a `tiles.json` written by `write_swath_tiles()`.
`read_coco_boxes`	Read the boxes of a COCO file, per image file name.
`boxes_to_targets`	Turn boxes drawn on one tile into targets in the sonar data.

sidescanpy.export.ml.tiles.TILE_INDEX_NAME = 'tiles.json'#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

class sidescanpy.export.ml.tiles.TileBox(x, y, w, h, category=None, score=None)#

Bases: object

One box on a tile image, from an annotation or a detector.

Attributes:

x, y, w, hfloat: Box in image pixels: top-left corner and size.
categorystr, optional: Class name.
scorefloat, optional: Detector confidence; None for a human annotation.

class sidescanpy.export.ml.tiles.TileRecord(file_name, ss_h5, freq_key, window)#

Bases: object

Where one tile image sits in the sonar data (an entry of tiles.json).

Attributes:

file_namestr: Image file, relative to the index.
ss_h5str: Stem of the .ss.h5 file the tile was cut from.
freq_keystr: Frequency channel, e.g. "hz_400000".
windowNativeWindow

sidescanpy.export.ml.tiles.write_swath_tiles(ds, out_dir, *, ss_h5, freq_key, tile_m, px_m, overlap_m=0.0, value_var='backscatter_intensity', pct_low=1.0, pct_high=99.0, gamma=1.0)#

Write a channel as dual-swath PNG tiles plus an index for mapping boxes back.

Parameters:

dsxr.Dataset: One frequency channel, usually corrected (TVG, so the tiles are even across range).
out_dirpath: Created if needed. Tiles are written as <ss_h5>_<freq_key>_<n>.png; the index tiles.json there is extended, so several channels and files can share one folder.
ss_h5, freq_keystr: Where ds came from: the .ss.h5 file stem and frequency key. Recorded in the index so boxes can be traced back to the data.
tile_m, px_m, overlap_mfloat: Tile length along track, pixel size and along-track overlap, in metres (see swath_tiles()).
value_varstr, default “backscatter_intensity”
pct_low, pct_high, gammafloat: 8-bit stretch (see to_uint8()), applied per tile.

Returns:

list of TileRecord: The tiles written by this call.

sidescanpy.export.ml.tiles.read_tile_index(path)#

Read a tiles.json written by write_swath_tiles().

Parameters:

pathpath: The index file, or the folder holding it.

Returns:

dict: {file_name: TileRecord}.

sidescanpy.export.ml.tiles.read_coco_boxes(path)#

Read the boxes of a COCO file, per image file name.

Works for annotation exports (FiftyOne, CVAT, Label Studio) and for detector results written in COCO form: an annotation’s score is kept when present.

Parameters:

pathpath: COCO JSON with images, annotations and categories.

Returns:

dict: {file_name: [TileBox, ...]} keyed by the image’s file name without folders. Images with no boxes map to an empty list.

sidescanpy.export.ml.tiles.boxes_to_targets(ds, record, boxes, *, source_format='tile_box', catalog_source='')#

Turn boxes drawn on one tile into targets in the sonar data.

Each box becomes a Target at the box centre: the side under the centre (a dual-swath box crossing nadir is clipped to that side), the ping and sample there, and, when ds is georeferenced (latitude_per_sample), the position of that sample.

Parameters:

dsxr.Dataset: The channel the tile was cut from (record.ss_h5, record.freq_key), with the same pings and samples.
recordTileRecord: The tile (from write_swath_tiles() or read_tile_index()).
boxesiterable of TileBox
source_format, catalog_sourcestr: Recorded on each target (e.g. "detector" and the model path).

Returns:

list of Target: ping and sample are the dataset’s ping and sample coordinates at the box centre (the axes a catalog’s ping and sample refer to). extra_attributes holds ss_h5 and ping_index (so correlate_target() places the target on that exact ping), ping_meters_per_sample, score, tile and the box size in metres (length_m along track, width_m across). position_confidence is "verified" for a box without a score (a person drew it) and "approximate" for a detection.