Signal Hound Converter (#136)

* Add Signal Hound to SigMF conversion functionality

Implement converter for Signal Hound files to SigMF format with metadata extraction and IQ data handling.

* Add Signal Hound file support to conversion script

Integrate Signal Hound file conversion into the main script, updating magic byte checks and handling for new file type.

* Update sigmf/convert/signalhound.py

Co-authored-by: Teque5 <teque5@gmail.com>

* Made code updates based on PR input. Still need to work on returning SigMF object instead of dictionary

Updated the last modified date and refactored comments for clarity.

* This version of the Signal Hound to SigMF conversion uses more of the SigMF File Object, but is not working.

Implement converter for Signal Hound files to SigMF format, including metadata extraction and IQ data conversion.

* add parity tests for signal hound processing

* refactor signalhound, add tests, add docs

* revert change to init to resolve conflict temporarily

* unified detect_converter function & better signalhound conversion

* basic tests for signalhound without external repo

* increment to v1.8.0

* switch to safe XML parsing

* code deduplication

* fix for python3.13

---------

Co-authored-by: Teque5 <teque5@gmail.com>
Co-authored-by: Kyle A Logue <kyle.a.logue@aero.org>

Author: 3 people

README.md

@@ -32,6 +32,7 @@ sample_rate = meta.sample_rate  # get sample rate
 # read other formats containing RF time series as SigMF
 meta = sigmf.fromfile("recording.wav")   # WAV
 meta = sigmf.fromfile("recording.cdif")  # BLUE / Platinum
+meta = sigmf.fromfile("recording.xml")   # Signal Hound Spike
 ```
 
 ### Docs

docs/requirements.txt

@@ -1,3 +1,2 @@
-# pinned 2025-01-15
-sphinx==8.1.3
-sphinx-rtd-theme==3.0.2
+sphinx>=8.0
+sphinx-rtd-theme>=3.0

docs/source/converters.rst

@@ -12,6 +12,7 @@ Conversion is available for:
 
 * **BLUE files** - MIDAS Blue and Platinum BLUE RF recordings (usually ``.cdif``)
 * **WAV files** - Audio recordings (``.wav``)
+* **Signal Hound Spike files** - Signal Hound zero-span recordings (``.xml`` + ``.iq``)
 
 All converters return a :class:`~sigmf.SigMFFile` object with converted metadata.
 
@@ -29,6 +30,7 @@ formats and reads without writing any output files:
     # auto-detect and create NCD for any supported format
     meta = sigmf.fromfile("recording.cdif")  # BLUE file
     meta = sigmf.fromfile("recording.wav")   # WAV file
+    meta = sigmf.fromfile("recording.xml")   # Signal Hound Spike file
     meta = sigmf.fromfile("recording.sigmf")  # SigMF archive
 
     all_samples = meta.read_samples()
@@ -44,13 +46,17 @@ For programmatic access, use the individual converter functions directly:
 
     from sigmf.convert.wav import wav_to_sigmf
     from sigmf.convert.blue import blue_to_sigmf
+    from sigmf.convert.signalhound import signalhound_to_sigmf
 
     # convert WAV to SigMF archive
     _ = wav_to_sigmf(wav_path="recording.wav", out_path="recording", create_archive=True)
 
     # convert BLUE to SigMF pair and return metadata for new files
     meta = blue_to_sigmf(blue_path="recording.cdif", out_path="recording")
 
+    # convert Signal Hound Spike to SigMF pair
+    meta = signalhound_to_sigmf(signalhound_path="recording.xml", out_path="recording")
+
 
 Command Line Usage
 ~~~~~~~~~~~~~~~~~~
@@ -65,8 +71,9 @@ Converters are accessed through a unified command-line interface that automatica
     # examples
     sigmf_convert recording.cdif recording.sigmf
     sigmf_convert recording.wav recording.sigmf
+    sigmf_convert recording.xml recording.sigmf
 
-The converter uses magic byte detection to automatically identify BLUE and WAV file formats.
+The converter uses magic byte detection to automatically identify BLUE, WAV, and Signal Hound Spike file formats.
 No need to remember format-specific commands!
 
 
@@ -168,4 +175,40 @@ Examples
 
     # access standard SigMF data & metadata
     all_samples = meta.read_samples()
-    sample_rate_hz = meta.sample_rate
+    sample_rate_hz = meta.sample_rate
+
+
+Signal Hound Spike Converter
+-----------------------------
+
+The Signal Hound Spike converter handles recordings from Signal Hound devices.
+These recordings consist of two files: an XML metadata file (``.xml``) and a binary IQ data file (``.iq``).
+The converter extracts metadata from the XML file and references the IQ data file, storing Signal Hound-specific
+fields in the ``spike:`` namespace extension.
+
+.. autofunction:: sigmf.convert.signalhound.signalhound_to_sigmf
+
+Examples
+~~~~~~~~
+
+.. code-block:: python
+
+    from sigmf.convert.signalhound import signalhound_to_sigmf
+
+    # standard conversion (provide path to XML file)
+    meta = signalhound_to_sigmf(signalhound_path="recording.xml", out_path="recording")
+
+    # create NCD automatically (metadata-only, references original .iq file)
+    meta = signalhound_to_sigmf(signalhound_path="recording.xml")
+
+    # access standard SigMF data & metadata
+    all_samples = meta.read_samples()
+    sample_rate = meta.sample_rate
+    center_freq = meta.get_captures()[0]["core:frequency"]
+
+    # access Signal Hound-specific metadata in spike: namespace
+    reference_level_dbm = meta.get_global_field("spike:reference_level_dbm")
+    scale_factor_mw = meta.get_global_field("spike:scale_factor_mw")
+    if_bandwidth_hz = meta.get_global_field("spike:if_bandwidth_hz")
+    iq_filename = meta.get_global_field("spike:iq_filename")  # original IQ file name
+    preview_trace = meta.get_global_field("spike:preview_trace")  # max-hold trace

docs/source/developers.rst

@@ -60,6 +60,7 @@ To build the docs and host locally:
 .. code-block:: console
 
    $ cd docs
+   $ pip install -r requirements.txt
    $ make clean
    $ make html
    $ python3 -m http.server --directory build/html/

pyproject.toml

@@ -24,6 +24,7 @@ requires-python = ">=3.7"
 dependencies = [
     "numpy",        # for vector math
     "jsonschema",   # for spec validation
+    "defusedxml",   # for safe XML parsing (XXE protection)
 ]
     [project.urls]
     repository = "https://github.com/sigmf/sigmf-python"

sigmf/__init__.py

@@ -5,7 +5,7 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
 # version of this python module
-__version__ = "1.7.2"
+__version__ = "1.8.0"
 # matching version of the SigMF specification
 __specification__ = "1.2.6"
 

sigmf/convert/__init__.py

@@ -0,0 +1,91 @@
+# Copyright: Multiple Authors
+#
+# This file is part of sigmf-python. https://github.com/sigmf/sigmf-python
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Convert non-SigMF recordings to SigMF format"""
+
+from pathlib import Path
+
+from ..error import SigMFConversionError
+
+
+def get_magic_bytes(file_path: Path, count: int = 4, offset: int = 0) -> bytes:
+    """
+    Get magic bytes from a file to help identify file type.
+
+    Parameters
+    ----------
+    file_path : Path
+        Path to the file to read magic bytes from.
+    count : int, optional
+        Number of bytes to read. Default is 4.
+    offset : int, optional
+        Byte offset to start reading from. Default is 0.
+
+    Returns
+    -------
+    bytes
+        Magic bytes from the file.
+
+    Raises
+    ------
+    SigMFConversionError
+        If file cannot be read or is too small.
+    """
+    try:
+        with open(file_path, "rb") as handle:
+            handle.seek(offset)
+            magic_bytes = handle.read(count)
+            if len(magic_bytes) < count:
+                raise SigMFConversionError(f"File {file_path} too small to read {count} magic bytes at offset {offset}")
+            return magic_bytes
+    except (IOError, OSError) as err:
+        raise SigMFConversionError(f"Cannot read magic bytes from {file_path}: {err}") from err
+
+
+def detect_converter(file_path: Path):
+    """
+    Detect the appropriate converter for a non-SigMF file.
+
+    Parameters
+    ----------
+    file_path : Path
+        Path to the file to detect.
+
+    Returns
+    -------
+    str
+        The converter name: "wav", "blue", or "signalhound"
+
+    Raises
+    ------
+    SigMFConversionError
+        If the file format is not supported or cannot be detected.
+    """
+    magic_bytes = get_magic_bytes(file_path, count=4, offset=0)
+
+    if magic_bytes == b"RIFF":
+        return "wav"
+
+    elif magic_bytes == b"BLUE":
+        return "blue"
+
+    elif magic_bytes == b"<?xm":  # <?xml version="1.0" encoding="UTF-8"?>
+        # Check if it's a Signal Hound Spike file
+        # Skip XML declaration (40 bytes) and check for SignalHoundIQFile root element
+        expanded_magic_bytes = get_magic_bytes(file_path, count=17, offset=40)
+        if expanded_magic_bytes == b"SignalHoundIQFile":
+            return "signalhound"
+        else:
+            raise SigMFConversionError(
+                f"Unsupported XML file format. Root element: {expanded_magic_bytes}. "
+                f"Expected SignalHoundIQFile for Signal Hound Spike files."
+            )
+
+    else:
+        raise SigMFConversionError(
+            f"Unsupported file format. Magic bytes: {magic_bytes}. "
+            f"Supported formats for conversion are WAV, BLUE/Platinum, and Signal Hound Spike."
+        )

sigmf/convert/__main__.py

@@ -13,8 +13,9 @@
 
 from .. import __version__ as toolversion
 from ..error import SigMFConversionError
-from ..utils import get_magic_bytes
+from . import detect_converter
 from .blue import blue_to_sigmf
+from .signalhound import signalhound_to_sigmf
 from .wav import wav_to_sigmf
 
 
@@ -60,8 +61,8 @@ def main() -> None:
     exclusive_group.add_argument(
         "--ncd", action="store_true", help="Output .sigmf-meta only and process as a Non-Conforming Dataset (NCD)"
     )
-    parser.add_argument("--overwrite", action="store_true", help="Overwrite existing output files")
     parser.add_argument("--version", action="version", version=f"%(prog)s v{toolversion}")
+
     args = parser.parse_args()
 
     level_lut = {
@@ -85,33 +86,16 @@ def main() -> None:
     if output_path.is_dir():
         raise SigMFConversionError(f"Output path must be a filename, not a directory: {output_path}")
 
-    # detect file type using magic bytes (same logic as fromfile())
-    magic_bytes = get_magic_bytes(input_path, count=4, offset=0)
-
-    if magic_bytes == b"RIFF":
-        # WAV file
-        _ = wav_to_sigmf(
-            wav_path=input_path,
-            out_path=output_path,
-            create_archive=args.archive,
-            create_ncd=args.ncd,
-            overwrite=args.overwrite,
-        )
-
-    elif magic_bytes == b"BLUE":
-        # BLUE file
-        _ = blue_to_sigmf(
-            blue_path=input_path,
-            out_path=output_path,
-            create_archive=args.archive,
-            create_ncd=args.ncd,
-            overwrite=args.overwrite,
-        )
+    # detect file type using magic bytes
+    converter_type = detect_converter(input_path)
 
-    else:
-        raise SigMFConversionError(
-            f"Unsupported file format. Magic bytes: {magic_bytes}. "
-            f"Supported formats for conversion are WAV and BLUE/Platinum."
+    if converter_type == "wav":
+        _ = wav_to_sigmf(wav_path=input_path, out_path=output_path, create_archive=args.archive, create_ncd=args.ncd)
+    elif converter_type == "blue":
+        _ = blue_to_sigmf(blue_path=input_path, out_path=output_path, create_archive=args.archive, create_ncd=args.ncd)
+    elif converter_type == "signalhound":
+        _ = signalhound_to_sigmf(
+            signalhound_path=input_path, out_path=output_path, create_archive=args.archive, create_ncd=args.ncd
         )
 
 

sigmf/convert/blue.py

@@ -25,7 +25,6 @@
 import numpy as np
 from packaging.version import InvalidVersion, Version
 
-from .. import __version__ as toolversion
 from ..error import SigMFConversionError
 from ..sigmffile import SigMFFile, fromfile, get_sigmf_filenames
 from ..utils import SIGMF_DATETIME_ISO8601_FMT