Custom Formats

Learning Magic Bytes from a Sample File

The easiest way to add a custom format is to let Sonar Catalog read the magic bytes from a sample file:

sonar-catalog add-magic-byte /path/to/sample.myformat \
  --format-name my_sonar \
  --length 4 \
  --description "My proprietary sonar format"

This reads the first 4 bytes from the sample file and registers them as the signature for my_sonar.

Options

Flag	Description
--format-name	Name for the format (defaults to file extension)
--length	Number of magic bytes to read (default: 4)
--offset	Byte offset to start reading from (default: 0)
--description	Human-readable description
--no-extension	Don’t associate the file extension with this format
--force	Replace an existing format with the same name

With offset

Some formats have magic bytes at a non-zero offset:

sonar-catalog add-magic-byte /path/to/sample.dat \
  --format-name sonar_v2 \
  --length 4 \
  --offset 8 \
  --description "SonarV2 format (magic at offset 8)"

Custom Extension Mappings

Add extension-to-format mappings in the config file:

{
  "metadata": {
    "custom_extension_map": {
      ".myformat": "my_sonar",
      ".dat": "proprietary_sonar",
      ".xyz": "bathymetry_export"
    }
  }
}

Config-Based Magic Bytes

You can also add magic byte signatures directly in the config file:

{
  "metadata": {
    "custom_magic_bytes": [
      {
        "format": "my_sonar",
        "hex_bytes": "cafebabe",
        "byte_length": 4,
        "offset": 0,
        "extension": ".myformat",
        "description": "My custom sonar format"
      }
    ]
  }
}

Field	Description
format	Format name
hex_bytes	Hex-encoded magic bytes
byte_length	Number of bytes
offset	Byte offset in file
extension	Associated file extension
description	Human-readable description

Plugin-Based Format Detection

For more complex format detection logic (e.g., checking internal structures beyond magic bytes), write a plugin that implements the detect_format hook. See Writing a Plugin.