sidescanpy.core.target

Target dataclass and pixel-box helpers: the format-agnostic sonar contact model.

A target’s position may be known in the native address space (ping/ channel/sample, lat/lon), the pixel address space (image id + bbox), both, or neither, depending on what the source catalog actually gives up.

Pure Python (no I/O) so that catalog readers in io can build Target without importing a higher layer.

2026 rshomberg@uri.edu

Contents

Target	One sonar target/contact, in native and/or pixel address space.
CONFIDENCE_RANK
clip_bbox	Clip a (x, y, w, h) pixel box to an image's bounds.
bbox_from_center	Build a (x, y, w, h) pixel box of box_size (width, height) centered on (col, row).

class sidescanpy.core.target.Target(target_id, source_format, catalog_source, pick_timestamp=None, ping=None, channel=None, sample=None, latitude=None, longitude=None, image_id=None, bbox=None, position_confidence='unknown', label=None, category=None, extra_attributes=<factory>)

Bases: object

One sonar target/contact, in native and/or pixel address space.

Parameters:

target_idstr

Identifier from the source catalog (e.g. a filename-derived number). Not assumed globally unique across catalogs — see catalog_source for provenance.

source_formatstr

e.g. "jsf_discover", "sdf_sonarwiz".

catalog_sourcestr

Path to the original catalog file this target came from.

pick_timestampfloat, optional

Unix epoch seconds, when trustworthy.

ping, channel, sampleint, optional

Native (ping/sample) address space. channel: 0=port, 1=starboard.

latitude, longitudefloat, optional

Degrees, WGS84.

image_idstr, optional

Pixel address space: identifies the rendered image this target was localized on (populated once a crop/render exists).

bboxtuple[float, float, float, float], optional

(x, y, w, h) in image_id’s pixel space.

position_confidence{“unknown”, “approximate”, “verified”}

Whether the position (native and/or pixel) has been visually validated. Export code should default to filtering on this rather than silently shipping unlocalized or unverified boxes.

labelstr, optional

Free text, passed through, not interpreted.

categorystr, optional

Class name for multi-class annotation export (COCO/YOLO). None (the default) means “uncategorized”: the export writers then use their single default category name.

extra_attributesdict

Format-specific fields that don’t generalize (e.g. JSF’s MutableTag text, or notes about data-quality workarounds applied while reading this target).

sidescanpy.core.target.CONFIDENCE_RANK = {'approximate': 1, 'unknown': 0, 'verified': 2}

sidescanpy.core.target.clip_bbox(bbox, width, height)

Clip a (x, y, w, h) pixel box to an image’s bounds.

Shared by export/ml/coco.py and export/ml/yolo.py so both formats agree on exactly the same clipped box for a given target.

Returns:

(clipped_bbox, was_clipped)

sidescanpy.core.target.bbox_from_center(row, col, box_size)

Build a (x, y, w, h) pixel box of box_size (width, height) centered on (col, row).

Shared by box-drawing QA visualization and COCO export so both agree on exactly the same box for a given target. box_size is either a catalog’s real measured extent already converted to this window’s pixels (extra_attributes["bbox_size_px"], set by sidescan-export chip when the target carries a bbox) or, for center-only catalogs (JSF/Discover picks), a caller-supplied placeholder.