Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dfki-ric/uxo-dataset2024/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The aris_definitions module provides essential constants, enumerations, and helper functions for working with ARIS sonar data files. It defines the binary structure of ARIS file and frame headers, beam angle configurations, and utility functions for interpreting sonar parameters. Module Path: scripts/common/aris_definitions.py

​
Header Format Definitions

​
File Header

The file header structure is defined using Python’s struct format string: 
FileHeaderDefinition = '< IIIII f II ff II 32s 256s iiii IIIIIIIIIIIIIIIIII QQQ II 568x'
This defines a little-endian (<) packed binary structure containing version information, frame counts, sample rates, and recording parameters. The structure includes 568 bytes of padding at the end.

​
Frame Header

The frame header structure contains metadata for each individual sonar frame: 
FrameHeaderDefinition = '< I Q II Q IIIIII ff I i IIIIII ffffffffffffffffffff dd f I fff IIII f I fffffffff d f III fff IIIIIII ffffff 16f ffff IIIIII ff IIIIII Q IIIIII ffff IIIIIIIIIIIIIIIII fff III ffffffffffff IIIIII HH Q fff II 288x'
This structure includes timestamp information, sensor readings (temperature, humidity, battery), positioning data (GPS, compass, depth), and system status flags. It ends with 288 bytes of padding.

​
Enumerations

​
FileHeaderFields

Enum defining all fields available in the ARIS file header. 
class FileHeaderFields(str, Enum):
    version = "Version"
    frame_count = "FrameCount"
    frame_rate = "FrameRate"
    high_resolution = "HighResolution"
    num_raw_beams = "NumRawBeams"
    # ... additional fields
​
version
str
File format version number
​
frame_count
str
Total number of frames in the file
​
frame_rate
str
Recording frame rate in frames per second
​
high_resolution
str
High resolution mode flag
​
num_raw_beams
str
Number of acoustic beams
​
sample_rate
str
Sample rate in Hz
​
samples_per_channel
str
Number of samples per channel
​
receiver_gain
str
Receiver gain setting
​
window_start
str
Start of acquisition window
​
window_length
str
Length of acquisition window
​
reverse
str
Reverse orientation flag
​
sn
str
Serial number
​
str_date
str
Recording date string
​
str_header_id
str
Header identifier string
​
water_temp
str
Water temperature in Celsius
​
salinity
str
Water salinity
​
pulse_length
str
Acoustic pulse length
​
file_size
str
Total file size in bytes

​
FrameHeaderFields

Enum defining all fields available in each ARIS frame header. 
class FrameHeaderFields(str, Enum):
    frame_index = "FrameIndex"
    frame_time = "FrameTime"
    version = "Version"
    status = "Status"
    # ... additional fields
​
frame_index
str
Sequential frame number
​
frame_time
str
Frame timestamp in microseconds since epoch (PC time)
​
sonar_time_stamp
str
Frame timestamp in microseconds since epoch (sonar time)
​
ping_mode
str
Ping mode identifier (determines beam count)
​
sample_rate
str
Sample rate for this frame
​
samples_per_beam
str
Number of samples per acoustic beam
​
sound_speed
str
Speed of sound in water (m/s)
​
latitude
str
GPS latitude
​
longitude
str
GPS longitude
​
depth
str
Water depth
​
altitude
str
Sonar altitude above bottom
​
pitch
str
Sonar pitch angle
​
roll
str
Sonar roll angle
​
heading
str
Sonar heading angle
​
water_temp
str
Water temperature in Celsius
​
salinity
str
Water salinity
​
battery_voltage
str
Battery voltage level

​
Functions

​
get_beamcount_from_pingmode

Determines the number of acoustic beams based on the ping mode setting. 
def get_beamcount_from_pingmode(pingmode: int) -> int
​
pingmode
int
required
The ping mode identifier from the frame header
​
beam_count
int
Number of beams for the given ping mode:
  • Modes 1-2: 48 beams
  • Modes 3-5: 96 beams
  • Modes 6-8: 64 beams
  • Modes 9-12: 128 beams
  • Unknown modes: 0

​
Example

from scripts.common.aris_definitions import get_beamcount_from_pingmode

# Get beam count for ping mode 10
beam_count = get_beamcount_from_pingmode(10)
print(f"Ping mode 10 uses {beam_count} beams")  # Output: 128 beams

​
Beam Angle Definitions

​
BeamWidthsAris3000_64

Defines the angular coverage for 64-beam ARIS 3000 configuration. Each entry is a tuple of (center_angle, left_angle, right_angle) in degrees. 
BeamWidthsAris3000_64 = [
    (-14.8872, -15.1175, -14.6569),
    (-14.4266, -14.6569, -14.1952),
    # ... 64 total beams
    (14.8872, 14.6569, 15.1175),
]
Total Coverage: Approximately -15° to +15° (30° total field of view)

​
BeamWidthsAris3000_128

Defines the angular coverage for 128-beam ARIS 3000 configuration. Each entry is a tuple of (center_angle, left_angle, right_angle) in degrees. 
BeamWidthsAris3000_128 = [
    (-15.0068, -15.1218, -14.8918),
    (-14.7768, -14.8918, -14.6615),
    # ... 128 total beams
    (15.0156, 14.9003, 15.1306),
]
Total Coverage: Approximately -15° to +15° (30° total field of view with finer resolution)

​
Usage Example

import struct
from scripts.common.aris_definitions import (
    FileHeaderDefinition,
    FrameHeaderDefinition,
    FileHeaderFields,
    FrameHeaderFields,
    get_beamcount_from_pingmode,
    BeamWidthsAris3000_128
)

# Parse file header
with open('recording.aris', 'rb') as f:
    header_bytes = f.read(struct.calcsize(FileHeaderDefinition))
    header_data = struct.unpack(FileHeaderDefinition, header_bytes)
    
    # Access specific fields
    version_idx = list(FileHeaderFields).index(FileHeaderFields.version)
    version = header_data[version_idx]
    
# Determine beam configuration
ping_mode = 10  # from frame header
beam_count = get_beamcount_from_pingmode(ping_mode)
print(f"Using {beam_count} beams")

# Get beam angles for 128-beam configuration
if beam_count == 128:
    for i, (center, left, right) in enumerate(BeamWidthsAris3000_128):
        print(f"Beam {i}: {center:.2f}° (±{(right-left)/2:.2f}°)")

Build docs developers (and LLMs) love

Get started for freeTalk to us