sidescanpy.io.xtf.structs

XTF binary structures as numpy structured dtypes.

Field names, order and sizes follow the eXtended Triton Format specification, revision 42 (Exail), and agree field for field with the ctypes structures in pyxtf 1.5.0 (checked by the unit tests). All structures are little-endian and packed (no alignment padding); each dtype’s itemsize is asserted at import.

Structures

• CHAN_INFO_DTYPE (128 bytes): one channel description in the file header (CHANINFO).

• FILE_HEADER_DTYPE (1024 bytes): the file header (XTFFILEHEADER) including its first six ChanInfo blocks.

• PACKET_START_DTYPE (14 bytes): the fields every packet starts with (magic 0xFACE, header type, sub-channel, channels to follow, reserved, total packet byte count).

• PING_HEADER_DTYPE (256 bytes): the sonar ping header (XTFPINGHEADER); its first 14 bytes are the packet start fields.

• PING_CHAN_HEADER_DTYPE (64 bytes): the per-channel header (XTFPINGCHANHEADER) that precedes each channel’s samples.

Units as given by the specification (the reader does not convert): times in seconds, ranges in metres, SensorDepth / SensorPrimaryAltitude in metres, angles in degrees, ShipAltitude / ShipDepth in decimetres, coordinates in the units named by the file header’s NavUnits (0 = projected metres, 3 = degrees with X = longitude, Y = latitude). Sound-velocity fields may hold half the true value (some recorders store the one-way factor c / 2).

2026 rshomberg@uri.edu

Contents

PACKET_MAGIC	Magic number at the start of every packet.
FILE_FORMAT_XTF	Value of FileFormat (first byte of the file) for XTF files.
FILE_HEADER_BLOCK_BYTES	Size of one file-header block; files with more than six channels append further blocks holding the remaining ChanInfo entries.
CHAN_INFO_IN_FIRST_BLOCK	Number of ChanInfo entries inside the first file-header block.
HEADER_TYPE_SONAR	int([x]) -> integer int(x, base=10) -> integer
HEADER_TYPE_NOTES	int([x]) -> integer int(x, base=10) -> integer
HEADER_TYPE_NAMES	Names of the packet header types defined by the specification.
CHANNEL_TYPE_SUBBOTTOM	int([x]) -> integer int(x, base=10) -> integer
CHANNEL_TYPE_PORT	int([x]) -> integer int(x, base=10) -> integer
CHANNEL_TYPE_STBD	int([x]) -> integer int(x, base=10) -> integer
CHANNEL_TYPE_BATHY	int([x]) -> integer int(x, base=10) -> integer
NAV_UNITS_METERS	int([x]) -> integer int(x, base=10) -> integer
NAV_UNITS_LATLON	int([x]) -> integer int(x, base=10) -> integer
SAMPLE_FORMAT_DTYPES	SampleFormat (ChanInfo, added in X41) to sample dtype.
KNOWN_SAMPLE_FORMATS	SampleFormat values the XTF specification defines (0-8).
LEGACY_SAMPLE_DTYPES	BytesPerSample to sample dtype for legacy (SampleFormat 0) data.
CHAN_INFO_DTYPE	VoidDType(length, /)
FILE_HEADER_DTYPE	VoidDType(length, /)
PACKET_START_DTYPE	VoidDType(length, /)
PING_HEADER_DTYPE	VoidDType(length, /)
PING_CHAN_HEADER_DTYPE	VoidDType(length, /)
sample_dtype	Return the sample dtype described by one ChanInfo record.

sidescanpy.io.xtf.structs.PACKET_MAGIC = 64206

Magic number at the start of every packet.

sidescanpy.io.xtf.structs.FILE_FORMAT_XTF = 123

Value of FileFormat (first byte of the file) for XTF files.

sidescanpy.io.xtf.structs.FILE_HEADER_BLOCK_BYTES = 1024

Size of one file-header block; files with more than six channels append further blocks holding the remaining ChanInfo entries.

sidescanpy.io.xtf.structs.CHAN_INFO_IN_FIRST_BLOCK = 6

Number of ChanInfo entries inside the first file-header block.

sidescanpy.io.xtf.structs.HEADER_TYPE_SONAR = 0

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

sidescanpy.io.xtf.structs.HEADER_TYPE_NOTES = 1

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

sidescanpy.io.xtf.structs.HEADER_TYPE_NAMES

Names of the packet header types defined by the specification.

sidescanpy.io.xtf.structs.CHANNEL_TYPE_SUBBOTTOM = 0

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

sidescanpy.io.xtf.structs.CHANNEL_TYPE_PORT = 1

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

sidescanpy.io.xtf.structs.CHANNEL_TYPE_STBD = 2

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

sidescanpy.io.xtf.structs.CHANNEL_TYPE_BATHY = 3

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

sidescanpy.io.xtf.structs.NAV_UNITS_METERS = 0

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

sidescanpy.io.xtf.structs.NAV_UNITS_LATLON = 3

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

sidescanpy.io.xtf.structs.SAMPLE_FORMAT_DTYPES

SampleFormat (ChanInfo, added in X41) to sample dtype. Format 0 (“legacy”) means “use BytesPerSample”, see LEGACY_SAMPLE_DTYPES. Formats 1 (IBM float), 4, 6 and 7 are not supported.

sidescanpy.io.xtf.structs.KNOWN_SAMPLE_FORMATS = frozenset({0, 1, 2, 3, 4, 5, 6, 7, 8})

SampleFormat values the XTF specification defines (0-8). Any other value is treated as unset, i.e. as 0 (legacy, BytesPerSample): some KleinXlt 3.0 files have 0xFF in the ChanInfo reserved bytes, which include SampleFormat.

sidescanpy.io.xtf.structs.LEGACY_SAMPLE_DTYPES

BytesPerSample to sample dtype for legacy (SampleFormat 0) data. Samples are read as unsigned integers, as pyxtf does.

sidescanpy.io.xtf.structs.CHAN_INFO_DTYPE

VoidDType(length, /) –

DType class corresponding to the numpy.void scalar type.

Warning

np.dtypes.VoidDType cannot be instantiated directly. Use np.dtype("void[{unit}]") instead.

See numpy.dtype for the typical way to create dtype instances and Data type objects (dtype) for additional information.

sidescanpy.io.xtf.structs.FILE_HEADER_DTYPE

VoidDType(length, /) –

DType class corresponding to the numpy.void scalar type.

Warning

np.dtypes.VoidDType cannot be instantiated directly. Use np.dtype("void[{unit}]") instead.

See numpy.dtype for the typical way to create dtype instances and Data type objects (dtype) for additional information.

sidescanpy.io.xtf.structs.PACKET_START_DTYPE = dtype([('MagicNumber', '<u2'), ('HeaderType', 'u1'), ('SubChannelNumber', 'u1'), ('NumChansToFollow', '<u2'), ('Reserved1', '<u2', (2,)), ('NumBytesThisRecord', '<u4')])

VoidDType(length, /) –

DType class corresponding to the numpy.void scalar type.

Warning

np.dtypes.VoidDType cannot be instantiated directly. Use np.dtype("void[{unit}]") instead.

See numpy.dtype for the typical way to create dtype instances and Data type objects (dtype) for additional information.

sidescanpy.io.xtf.structs.PING_HEADER_DTYPE

VoidDType(length, /) –

DType class corresponding to the numpy.void scalar type.

Warning

np.dtypes.VoidDType cannot be instantiated directly. Use np.dtype("void[{unit}]") instead.

See numpy.dtype for the typical way to create dtype instances and Data type objects (dtype) for additional information.

sidescanpy.io.xtf.structs.PING_CHAN_HEADER_DTYPE

VoidDType(length, /) –

DType class corresponding to the numpy.void scalar type.

Warning

np.dtypes.VoidDType cannot be instantiated directly. Use np.dtype("void[{unit}]") instead.

See numpy.dtype for the typical way to create dtype instances and Data type objects (dtype) for additional information.

sidescanpy.io.xtf.structs.sample_dtype(chan_info)

Return the sample dtype described by one ChanInfo record.

SampleFormat (X41 and later) takes precedence; format 0 (legacy) falls back to BytesPerSample. A format that disagrees with BytesPerSample is used as given. A value outside KNOWN_SAMPLE_FORMATS (such as 255) is treated as unset, like 0; this logs at DEBUG only, and read_xtf_pings() warns once per file.

Parameters:

chan_infonumpy.void

One record of CHAN_INFO_DTYPE.

Returns:

numpy.dtype

Raises:

ValueError

If the sample format or byte width is not supported (IBM float, formats 4, 6 and 7, or a legacy width other than 1, 2 or 4 bytes).