Labels

Warning

Pre-implementation. This page describes proposed contracts. Class signatures, parameter types, config field names, and behavior are subject to change before code lands. Once implementation exists, content here will be checked against generated API docs and running tests.

Labels are the supervised targets attached to every generated Record. The label layer reads a composed scene, the receiver’s IQ (in-phase / quadrature) samples, and per-emitter component metadata, then produces the targets needed by downstream training jobs: bounding boxes, segmentation masks, per-emitter rows, and scene-level summaries.

The labeler does not synthesize IQ samples, place emitters, run propagation, or inspect protocol internals. It converts already-composed ground truth into stable training targets. A component is one emission tracked through scene composition; an emitter may contribute one or more components to a scene.

Minimal Example

from rfgen.labels import JointLabeler

# The three inputs come from scene composition.
scene_iq = scene_signal.iq
component_metadata = tuple(c.metadata for c in scene_signal.component_signals)
scene_meta = scene_signal.metadata

labeler = JointLabeler(seg_n_fft=1024, seg_hop=256)
record = labeler.label(iq=scene_iq, emitters=component_metadata, scene=scene_meta)

bboxes = record.bboxes
seg_mask = record.seg_mask
emitters = record.emitters

seg_n_fft and seg_hop configure the short-time Fourier transform (STFT) grid used for segmentation masks. They are measured in samples: seg_n_fft is the analysis-window length and seg_hop is the stride between adjacent windows. The iq argument is a IQ tensor with shape (2, N) for one receiver or (num_rx, 2, N) for a joint multi-receiver record; emitters is a tuple of SignalMetadata objects; scene is SceneMetadata.

The call is a pure function of (iq, emitters, scene). Re-running with the same inputs, labeler configuration, dependency versions, and deterministic backend settings should produce identical labels.

What Gets Labeled

Every generated record can carry four coordinated label modalities:

Modality	Purpose	Source
Bounding boxes	Time-frequency extents for each emitted component.	TorchSig SignalMetadataObject, SigMF annotations, and WRIST [1, 2, 3]
Segmentation	Per-time-frequency-cell occupancy mask: each spectrogram-grid cell records whether an emitter occupies that cell.	DeepSig spectral segmentation and Northeastern I/Q segmentation [4, 5]
Per-emitter metadata	Class, taxonomy path, device identity, signal-to-noise ratio (SNR) in dB, propagation profile, and provenance per component.	TorchSig per-signal fields and multi-task RF characterization [1, 10]
Scene metadata	Dataset-window, receiver, density, and aggregate fields shared by the record.	SigMF capture-level metadata and storage annotations [2]

The default JointLabeler computes these modalities together so they cannot drift. Bboxes, segmentation masks, and per-emitter rows should all describe the same component list in the same order.

Exact fields, dtypes, validation thresholds, and writer-specific encodings live in Reference / Label Schema and Reference / API / rfgen.labels.

Source Of Truth

Labels are derived from the component metadata produced by scene composition, not by running a detector over IQ samples to rediscover where signals are.

• Time placement comes from component start and duration metadata.

• Frequency placement comes from component center frequency and occupied bandwidth metadata.

• Class and taxonomy come from emitter metadata.

• SNR, channel profile, receiver index, and device identity come from the channel and scene records.

• Segmentation uses metadata-derived bbox geometry to decide which STFT cells are occupied.

• The composed IQ samples are used only to validate record axis and capture length, preserve the joint or per-receiver layout, and keep the output tied to the right receiver frame. They do not act as an amplitude or energy detector.

Rasterization means converting analytic time-frequency extents into cells on the segmentation grid. Tie-breaking means choosing which emitter owns a single-label cell when two components overlap. This is why the scene composer must preserve component Signal objects even when the stored IQ is a summed receiver waveform: the receiver IQ is the per-sample sum of all in-band emitter contributions, so individual components are not recoverable from the sum alone. The shipped segmentation labeler is therefore a metadata rasterizer, not a detector over raw IQ or STFT magnitude.

Source. TorchSig and SigMF both model labels as structured metadata attached to known signal components or capture spans; the labeler preserves that generator-side truth instead of rediscovering it from samples [1, 2].

Coordinate Conventions

The framework keeps absolute coordinates as the canonical representation: samples on the time axis and hertz on the frequency axis. Normalized detector formats such as YOLO are derived at write time from the same absolute record.

This avoids two common sources of label drift:

• Normalizing against a signal’s own duration instead of the full dataset window.

• Recomputing detector labels separately from absolute bboxes.

For TorchSig interoperability, the framework follows TorchSig’s bbox vocabulary where practical. TorchSig is the RF machine learning (RFML) detection and classification toolkit used as rfgen’s compatibility target for common modulation datasets. The exact field-by-field conversion rules belong in Reference / TorchSig Interop.

Source. TorchSig supplies the per-signal bbox vocabulary, while SigMF is the interchange format for capture annotations with absolute sample and frequency fields [1, 2].

Overlap And Multi-Receiver Records

RF scenes can contain overlapping emitters and multiple receivers. The label contract handles both explicitly:

• A component keeps one emitter identity even if it overlaps another component in time, frequency, or both.

• Single-label segmentation is the storage-efficient default for ordinary detection datasets.

• Multi-label segmentation is an opt-in mode for overlap-specific research.

• Multi-receiver (multi-RX) records may have receiver-specific SNR, occupancy masks, and channel metadata, but they still share the same component identity model.

• Joint multi-RX bbox-bearing records require one shared receiver center frequency. If receivers use heterogeneous center frequencies, callers must request per-RX records instead of a single joint bbox list.

Storage chooses whether to write per-receiver records or a joint multi-RX record. Labels must match that storage mode; see Concepts / Records And Assets.

Source. SigMF permits overlapping annotations, and segmentation literature motivates multi-label masks for dense or overlapping RF scenes [2, 4, 5].

Custom Labelers

Custom modalities, such as oriented boxes, time-only spans, instance masks, or panoptic maps, should implement the same conceptual contract:

• read only composed IQ samples, component metadata, and scene metadata;

• return deterministic structured labels;

• preserve component ordering;

• expose a schema and validation checks;

• avoid duplicating information already present in another modality unless the storage or training interface requires it.

Implementation details belong in Reference / API / rfgen.labels and task-level recipes belong in the How-to section.

Design Rationale

Why three modalities and not one?

The field has not converged on a single label format. RFML detection benchmarks use bounding boxes (TorchSig, SigMF, WRIST) [1, 2, 3]. Dense-overlap and continuous-emitter scenarios push toward per-cell semantic segmentation (DeepSig 2021, Northeastern 2024) [4, 5]. Spectrum monitoring uses occupancy ratios (NTIA TR-20-548) [6]. Anchor-free per-bin attribute prediction (Li IEEE SPL 2022) and recent foundation-model SSL targets (SpectrumFM 2025, RIS-MAE 2025) are emerging directions [7, 8, 9].

The default JointLabeler ships bboxes, segmentation masks, and per-emitter metadata because those are the three modalities a detection or segmentation training pipeline actually consumes. Each is a separate BaseLabeler subclass under the hood. New modalities (instance segmentation, anchor-free attributes, foundation-model targets, PDW-style track labels) plug in as additional BaseLabeler subclasses without disrupting the default pipeline.

The literature review behind these decisions, with individual citations and field-level evidence, lives in Background / Labeling Survey.

Why one joint labeler?

The main modalities share inputs and consistency checks. Producing them together makes cross-modality validation part of the labeler contract instead of a later storage concern.

Why store labels instead of recomputing them?

The labeler is deterministic, so labels can be regenerated in principle. In practice, regenerating labels for a large dataset is expensive, and stored labels make training reads simple and auditable. The manifest records the schema and labeler configuration so stored labels remain traceable.

What counts as label leakage?

The data generation repository should preserve rich metadata. The training pipeline decides which fields are exposed to a model for a specific task. For example, storing snr_db (signal-to-noise ratio per component, in decibels) is useful for audit and stratified evaluation, but a classifier should not receive it as an input feature unless the experiment explicitly calls for that.

See Also

• Reference / API / rfgen.labels for class signatures, parameters, and return types.

• Reference / Label Schema for exact fields, dtypes, validation rules, and taxonomy tables.

• Reference / TorchSig Interop for conversion guarantees.

• Reference / Storage Layout for how labels sit alongside IQ on disk.

• Concepts / Core Types for Record, Signal, BBox, SignalMetadata, and SceneMetadata.

• Background / Labeling Survey for the field-level evidence behind the multi-modal label design (canonical bbox formats, segmentation alternatives, anchor-free directions, spectrum-monitoring conventions, foundation-model SSL targets, time-evolving track labels).

• Concepts / Scenes for upstream scene composition.

• Concepts / Records And Assets for storage-mode implications.

• Concepts / Annotations for the text layer that consumes label metadata.

References

The label modalities, formats, and design alternatives discussed above follow established RFML-detection, segmentation, spectrum-monitoring, and foundation-model practice. The full literature review with field-level evidence is in Background / Labeling Survey; the citations below are the primary sources behind the inline references on this page.

1. TorchDSP. TorchSig: SignalMetadataObject and dataset toolkit. GitHub. https://github.com/TorchDSP/torchsig. (Per-signal bbox vocabulary; start_in_samples, stop_in_samples, center_freq, bandwidth, class_name fields)

2. SigMF Contributors. Signal Metadata Format (SigMF) Specification. sigmf.org. https://sigmf.org/sigmf-spec.pdf. (Interchange format for core:annotation; supports unlimited overlapping annotations and continuous emitters via omitted sample_count)

3. Hanna, S. et al. WRIST: Wideband RF Inference and Signal Type detection. arXiv:2107.05114, 2021. https://arxiv.org/abs/2107.05114. (~1M emissions, 90 mAP on YOLO/DETR-style spectrogram detection; bbox detection benchmark)

4. West, N., Roy, T., O’Shea, T. Wideband Signal Localization with Spectral Segmentation. arXiv:2110.00583, 2021. https://arxiv.org/abs/2110.00583. (DeepSig U-Net per-frequency-bin segmentation; bboxes via connected components)

5. Uvaydov, D. et al. Stitching the Spectrum: Semantic Segmentation of Wideband I/Q Signals. arXiv:2402.03465, 2024. https://arxiv.org/abs/2402.03465. (Northeastern; 96.7% mIoU over five protocols; critique of bbox granularity for dense overlap)

6. Sanders, F. H. et al. NTIA Technical Report TR-20-548: Spectrum Occupancy Measurements. NTIA, 2020. (Per-(time, frequency)-cell threshold-exceedance occupancy; SigMF + sigmf-ns-ntia extension)

7. Li, Y. et al. Anchor-free framework for per-frequency-bin attribute prediction. IEEE Signal Processing Letters, 2022, doc 9788039. (Center-frequency / shape attributes per frequency bin; addresses anchor-mismatch on slender HF signals)

8. Zhou, F. et al. SpectrumFM: A Foundation Model for Intelligent Spectrum Management. arXiv:2505.06256, 2025. https://arxiv.org/abs/2505.06256. (Masked-IQ-reconstruction pretraining target; downstream AMC, WTC, spectrum sensing, anomaly detection)

9. Liu, S. et al. RIS-MAE: A Self-Supervised Modulation Classification Method Based on Raw IQ Signals and Masked Autoencoder. arXiv:2508.00274, 2025. https://arxiv.org/abs/2508.00274. (Masked-autoencoder over raw IQ patches; amplitude / phase reconstruction)

10. Huang, P. et al. Multi-task Learning for Radar Signal Characterisation. arXiv:2306.13105, 2023. https://arxiv.org/abs/2306.13105. (Joint classification and regression over categorical RF class labels and continuous physical attributes)