Labels

Labels are the supervised targets attached to every generated LabeledScene. The label layer reads a composed scene, the receiver’s IQ (in-phase / quadrature) samples, and per-event component metadata, then derives the two targets a detection or segmentation pipeline trains against: bounding boxes and a segmentation raster. Per-event and scene-level metadata travel with the record too, but no labeler computes them — they are declared upstream.

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 accepted, placed event tracked through scene composition; a selected generator slot may yield zero, one, or multiple such components.

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)
labels = labeler.label(iq=scene_iq, emitters=component_metadata, scene=scene_meta)

bboxes = labels.bboxes            # one box per emitter, receiver-baseband frame
segmentation = labels.segmentation  # the rasterized occupancy grid, or None

A labeler returns a LabelSet holding those two things and nothing else. The emitters and the scene are what you handed it; it does not hand them back.

seg_n_fft and seg_hop size the segmentation grid, in samples. The grid is shaped like an STFT and is not one: seg_n_fft is the number of frequency bins, spanning [-fs/2, +fs/2), and seg_hop is the width of a time cell, not a stride between overlapping windows. The cells tile the capture, and the last one is clipped to its end. Nothing is transformed — a cell is occupied when a declared box covers at least half its area. See Reference / Label Schema for the exact grid and for how it fails to line up with torch.stft.

The iq argument is a IQ tensor with shape (2, N) for one receiver or (num_rx, 2, N) for an unresolved multi-receiver scene; emitters is a tuple of SignalMetadata objects; scene is SceneMetadata.

emitters is the retained API field name, not a generator-slot count. In a composed record it contains exactly one metadata entry per accepted, placed event, in the same order as LabelSet.bboxes. The generator that produced an event remains identifiable through each entry’s generator_name, family, and class fields.

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

A labeler derives two things:

Modality

Purpose

Source

Bounding boxes

Time-frequency extents for each accepted, placed event.

TorchSig SignalMetadataObject, SigMF annotations, and WRIST [1, 2, 3]

Segmentation

Per-cell occupancy raster: each time-frequency cell records whether an emitter occupies it.

DeepSig spectral segmentation and Northeastern I/Q segmentation [4, 5]

A published record carries two more kinds of label that no labeler computes, because they are declared upstream and merely travel with the record: per-emitter metadata (class, taxonomy, device, SNR, propagation profile) and scene metadata (window, receivers, density, aggregates).

The default JointLabeler derives both of its modalities from one box computation, so the raster can never describe an occupancy the boxes disagree with.

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 grid cells are occupied.

  • The composed IQ samples are used only to validate rank and capture length, preserve the receiver axis for an unresolved multi-receiver scene, and keep the output on the right device. 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.

For a composed scene, the input component list has exactly one metadata entry per accepted, placed event. Its order is the accepted-event order from scene composition, and every bbox, segmentation instance, and per-event row refers to that same ordered list. It is not an emitter-slot list: one selected emitter slot can yield no accepted event (for example, when its schedule has no in-capture start) or multiple accepted events. Emitter class, taxonomy, and device fields remain attributes of each resulting component; they do not imply one component per selected emitter. Scene Capture Boundaries defines the event-fit rule that creates the list, while Coordinate Systems defines how its scene-rate time coordinates map onto a receiver record.

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 unnormalized 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 unnormalized record.

Unnormalized is not absolute. Both axes are receiver-relative: samples are indices at the receiver’s rate, and hertz are offsets from the receiver’s tuned centre. See Coordinate Systems § Label implications.

The two time representations have distinct jobs. Per-event SignalMetadata preserves the accepted placement interval at the scene/channel rate. A bbox and the segmentation derived from it live at the active receiver-record rate, because they must align with the receiver IQ tensor. The exact half-open [start, stop) conversion (flooring the start, ceiling the stop, and rejecting rather than cropping an out-of-capture result) is owned by Coordinate Systems § Component-to-record time mapping. The event already had to fit the scene before this conversion; see Scene Capture Boundaries.

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.

  • A multi-receiver scene has receiver-specific SNR, occupancy rasters, and channel metadata, but every receiver shares the same component identity model.

  • Boxes are declared once per record, in one receiver-baseband frame. A scene whose receivers do not share a centre frequency is refused at label time with a LabelError, so a record that exists has exactly one frame for its boxes to be in.

There is no per-receiver versus joint choice to make: one sample is one record, and its receivers are named subtrees inside it. See Concepts / Records, Receivers, 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 derives both boxes and the raster from one box computation, so the two cannot disagree about occupancy. 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

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)