rfgen.labels

Reference surface for the shipped Layer 7 labelers. The module exports metadata-only bbox labeling, STFT-grid segmentation labeling, and the joint labeler that returns a full Record.

Module summary

from rfgen.labels import JointLabeler

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

assert record.bboxes
assert record.seg_mask is not None

Class index

Class

Kind

Notes

BaseLabeler

abc

Common pure-function contract for all labelers.

BBoxLabeler

concrete

Derives one receiver-frame bbox per emitter from metadata only.

SegmentationLabeler

concrete

Rasterizes occupancy onto an STFT grid.

JointLabeler

concrete

Returns a full Record with bbox plus segmentation labels.

class rfgen.labels.BaseLabeler

Abstract base class for shipped and plugin labelers.

class BaseLabeler(ABC):
    name: ClassVar[str]

    @abstractmethod
    def label(
        self,
        iq: torch.Tensor,
        emitters: tuple[SignalMetadata, ...],
        scene: SceneMetadata,
    ) -> Record: ...

    @classmethod
    @abstractmethod
    def schema(cls) -> type[BaseModel]: ...

    @classmethod
    def from_config(cls, config: LabelConfig) -> BaseLabeler: ...

Notes

  • label(...) is the runtime contract. The shipped labelers are pure functions of (iq, emitters, scene).

  • schema() returns the Pydantic constructor schema used by config-driven construction.

  • from_config(...) resolves the configured primary labeler through rfgen.labelers.

Method: label

def label(
    self,
    iq: torch.Tensor,
    emitters: tuple[SignalMetadata, ...],
    scene: SceneMetadata,
) -> Record: ...

Runtime labeler contract. Implementations return a full Record with structured label fields populated from the composed IQ, emitter metadata, and scene metadata.

class rfgen.labels.BBoxLabeler

Metadata-only bbox derivation.

BBoxLabeler()

Method: label

def label(
    self,
    iq: torch.Tensor | None,
    emitters: tuple[SignalMetadata, ...],
    scene: SceneMetadata,
) -> Record

Behavior

  • Does not inspect iq.

  • Returns one BBox per emitter, in emitter order.

  • Resolves bbox frequency bounds in the active receiver frame from scene.extras.

  • Rejects unresolved joint multi-RX scenes when receiver center frequencies are heterogeneous, because one Record.bboxes list can only describe one receiver frequency frame.

  • Raises LabelError on invalid bandwidth, invalid duration, negative start sample, missing receiver center frequency, or bboxes that escape the capture window.

class rfgen.labels.SegmentationLabeler

STFT-grid occupancy rasterization.

SegmentationLabeler(
    *,
    seg_n_fft: int = 1024,
    seg_hop: int = 256,
    mode: SegmentationMode = SegmentationMode.SINGLE_LABEL,
    tie_break: SegmentationTieBreak = SegmentationTieBreak.LOWER_EMITTER_INDEX,
)

Method: label

def label(
    self,
    iq: torch.Tensor,
    emitters: tuple[SignalMetadata, ...],
    scene: SceneMetadata,
) -> Record

Behavior

  • Requires iq.

  • Uses BBoxLabeler to derive the metadata bbox list first, then rasterizes those bboxes.

  • Uses iq only to validate record axis and capture length, preserve the batch axis for joint multi-RX records, and place the output on the input device. Occupancy is not inferred from IQ amplitude or STFT energy.

  • Resolves the active receiver sample rate from scene.extras["receivers"][scene.rx_index]["sample_rate_hz"], scene.extras["rx_sample_rate_hz"], or the emitter metadata fallback.

  • Single-label mode returns torch.int16 shape [F, T] with -1 for background and class_id for occupied cells.

  • Multi-label mode returns torch.uint8 shape [C, F, T], one binary plane per distinct class in sorted class_id order. Emitters with the same class share the same plane.

  • tie_break=LOWER_EMITTER_INDEX is the shipped single-label overlap rule.

class rfgen.labels.JointLabeler

Default shipped labeler.

JointLabeler(
    *,
    seg_n_fft: int = 1024,
    seg_hop: int = 256,
    segmentation_mode: SegmentationMode = SegmentationMode.SINGLE_LABEL,
    segmentation_tie_break: SegmentationTieBreak = SegmentationTieBreak.LOWER_EMITTER_INDEX,
)

Method: label

def label(
    self,
    iq: torch.Tensor,
    emitters: tuple[SignalMetadata, ...],
    scene: SceneMetadata,
) -> Record

Behavior

  • Requires len(emitters) == scene.num_emitters.

  • Requires iq.

  • Reuses the shipped BBoxLabeler and SegmentationLabeler implementations so the two modalities stay aligned.

  • Rejects unresolved joint multi-RX scenes when scene.extras["receivers"] carries heterogeneous center_freq_hz values, because one joint Record.bboxes list cannot represent multiple receiver frequency frames safely.

  • Returns a full Record whose bboxes and emitters remain in the same order.

Helper: build_labeler_suite

def build_labeler_suite(
    config: LabelConfig,
) -> tuple[BaseLabeler, tuple[BaseLabeler, ...]]

Builds the configured primary labeler plus any extra_labelers, applying the shared seg_n_fft, seg_hop, segmentation_mode, and segmentation_tie_break defaults where the target labeler supports them.

Removed rfgen.labels.Labels

The shipped module does not export a Labels datatype. Layer 7 labelers return a full Record, with structured label fields stored on Record.bboxes, Record.seg_mask, Record.emitters, and Record.scene.

See Also