Hook Reference

Hook Summary

Hook	Mode	Description
detect_format	firstresult	Identify a sonar file’s format
extract_nav	firstresult	Extract lat/lon track from a file
get_format_signatures	historic	Contribute magic byte signatures
get_extension_map	historic	Contribute extension-to-format mappings
export_data	firstresult	Export data to a specific format
get_export_formats	historic	List available export formats
register_web_routes	historic	Add routes to the Flask web app

---

detect_format

Mode: firstresult (first non-None result wins)

Identify the sonar format of a file based on its header bytes and/or extension.

Parameters

Parameter	Type	Description
file_path	str	Absolute path to the file
header	bytes	First 32 bytes of the file
extension	str	File extension (lowercase, with dot)

Returns

str — Format name (e.g., "xtf", "jsf"), or None to pass.

Example

def detect_my_format(file_path=None, header=None, extension=None, **kw):
    if header and header[:2] == b"\xAB\xCD":
        return "my_format"
    return None

---

extract_nav

Mode: firstresult

Extract navigation (lat/lon) track data from a sonar file.

Parameters

Parameter	Type	Description
file_path	str	Absolute path to the file
sonar_format	str	Detected format name
sidecar_config	list[dict]	Sidecar file patterns from config

Returns

NavResult — with .track (list of [lat, lon] pairs) and .source (string identifier), or None.

from sonar_catalog.extractors.base import NavResult

def extract_my_nav(file_path=None, sonar_format=None, **kw):
    if sonar_format != "my_format":
        return None
    track = parse_my_file(file_path)
    return NavResult(track=track, source="my_format_nav")

---

get_format_signatures

Mode: historic (all plugins contribute)

Return magic byte signatures and extension mappings for format detection.

Parameters

None (called with no arguments).

Returns

dict with optional keys:

{
    "signatures": [
        {
            "format": "my_format",
            "hex_bytes": "abcd",
            "byte_length": 2,
            "offset": 0,
        }
    ],
    "extensions": {
        ".myf": "my_format",
    },
}

---

get_extension_map

Mode: historic

Return a mapping of file extensions to format names.

Returns

dict[str, str] — e.g., {".myf": "my_format", ".myformat": "my_format"}

---

export_data

Mode: firstresult

Export catalog data to a specific file format.

Parameters

Parameter	Type	Description
data	list[dict]	Rows from the catalog
format_name	str	Target format (e.g., "csv", "geojson")
output_path	str or None	Output file path (None = return as string)

Returns

str — The output (file path or string content), or None to pass.

---

get_export_formats

Mode: historic

List the export formats this plugin provides.

Returns

list[dict] — Format descriptors:

[
    {
        "name": "my_export",
        "description": "My custom export format",
        "extension": ".myexp",
    }
]

---

register_web_routes

Mode: historic

Register additional routes on the Flask web application.

Parameters

Parameter	Type	Description
app	Flask	The Flask application instance

Example

def register_my_routes(app=None, **kw):
    @app.route("/my-plugin/status")
    def plugin_status():
        return {"status": "ok"}