File detector_core.h¶

FileList > detector > detector_core.h

Go to the source code of this file

1-D streaming signal detector with FFT-based correlation, integrate-and-dump, and configurable noise-referenced threshold. More...

• #include "buffer/buffer.h"
• #include "corr/corr_core.h"
• #include "dp_state.h"

Classes¶

Public Types¶

Public Functions¶

Macros¶

Detailed Description¶

Wraps a corr_state_t (FFT correlator + coherent int-dump) behind a double-mapped ring buffer so that arbitrary-length sample streams can be fed in any chunk size. After every int-dump a test statistic is computed:

test_stat = peak_mag / noise_est

where peak_mag = max|R[τ]| and noise_est is an aggregate (mean, median, min, or max) of |R[τ]| over a user-supplied bin range [noise_lo, noise_hi]. A detection event is emitted when test_stat > threshold (or whenever threshold == 0.0, which means "always fire").

The detector operates as a single-threaded object; do not call detector_push() concurrently from multiple threads.

Lifecycle:

float complex ref[N] = { ... };
detector_state_t *det = detector_create(ref, N, 1,
    1, N-1, DET_NOISE_MEAN, 0.0f, 1);
det_result_t results[64];
// stream loop
while (recv(chunk, CHUNK_SZ)) {
    size_t n = detector_push(det, chunk, CHUNK_SZ, results, 64);
    for (size_t i = 0; i < n; i++)
        printf("lag=%zu stat=%.2f\n", results[i].lag, results[i].test_stat);
}
detector_destroy(det);

Public Types Documentation¶

enum det_noise_mode_t¶

enum det_noise_mode_t {
    DET_NOISE_MEAN = 0,
    DET_NOISE_MEDIAN = 1,
    DET_NOISE_MIN = 2,
    DET_NOISE_MAX = 3
};

Public Functions Documentation¶

function detector_create¶

Allocate a 1-D streaming signal detector backed by an FFT correlator. Combines a corr_state_t with a double-mapped ring buffer so that arbitrary chunk sizes can be pushed. After every int-dump the peak-to-noise test statistic is compared againstthreshold ; adet_result_t is emitted when it passes. Settingthreshold to 0.0 unconditionally fires on every dump. The ring capacity is next_pow2(max(n, 512)) complex samples.

detector_state_t * detector_create (
    const float complex * ref,
    size_t n,
    size_t dwell,
    size_t noise_lo,
    size_t noise_hi,
    det_noise_mode_t noise_mode,
    float threshold,
    int nthreads
) 

Parameters:

• ref Reference signal, CF32 ndarray of length n.
• n Reference / FFT length in complex samples.
• dwell Int-dump depth; must be >= 1.
• noise_lo Lower noise bin index (inclusive, 0-based).
• noise_hi Upper noise bin index (inclusive, < n).
• noise_mode Noise aggregation: "mean", "median", "min", or "max".
• threshold Test-stat gate; 0.0 = always emit.
• nthreads Accepted for API compatibility; ignored.

Returns:

Heap-allocated state, or NULL on allocation failure.

>>> from doppler.spectral import Detector
>>> import numpy as np
>>> ref = np.zeros(8, dtype=np.complex64); ref[0] = 1.0
>>> det = Detector(ref=ref, dwell=1, noise_lo=1, noise_hi=7,
...                noise_mode="mean", threshold=0.0)
>>> det.n, det.dwell, det.ring_cap
(8, 1, 512)

function detector_destroy¶

Destroy and free a detector instance.

void detector_destroy (
    detector_state_t * state
) 

Parameters:

• state May be NULL.

function detector_get_state¶

void detector_get_state (
    const detector_state_t * state,
    void * blob
) 

function detector_push¶

Stream an arbitrary-length CF32 chunk through the detector pipeline. Writes samples into the ring buffer, drains complete n-sample frames through the correlator, and on every int-dump computes the test statistic peak_mag / noise_est. Detections that pass the threshold are appended to the Python return list as (lag, peak_mag, noise_est, test_stat) tuples. In Python the result is always a list, even when empty.

size_t detector_push (
    detector_state_t * state,
    const float complex * in,
    size_t n_in,
    det_result_t * result,
    size_t max_results
) 

Parameters:

• state Allocated detector (non-NULL).
• in CF32 input chunk of arbitrary length.
• n_in Number of input samples in in.
• result Caller-supplied array of at least max_results det_result_t structs; filled on return.
• max_results Capacity of result (maximum detections to emit).

Returns:

Number of det_result_t entries written to result.

>>> from doppler.spectral import Detector
>>> import numpy as np
>>> ref = np.zeros(8, dtype=np.complex64); ref[0] = 1.0
>>> det = Detector(ref=ref, dwell=1, noise_lo=1, noise_hi=7,
...                noise_mode="mean", threshold=0.0)
>>> results = det.push(np.ones(8, dtype=np.complex64))
>>> len(results)
1
>>> lag, peak, noise, stat = results[0]
>>> lag, round(peak, 4), round(noise, 4), round(stat, 4)
(0, 1.0, 1.0, 1.0)

function detector_reset¶

Reset the correlator, ring buffer, and last-corr flag. Discards any partial frame buffered in the ring and zeroes the coherent accumulator. Equivalent to starting fresh from the same reference without rebuilding any internal object.

void detector_reset (
    detector_state_t * state
) 

>>> from doppler.spectral import Detector
>>> import numpy as np
>>> ref = np.zeros(8, dtype=np.complex64); ref[0] = 1.0
>>> det = Detector(ref=ref, dwell=1, noise_lo=1, noise_hi=7,
...                noise_mode="mean", threshold=0.0)
>>> _ = det.push(np.ones(8, dtype=np.complex64))
>>> det.reset()
>>> det.count
0

function detector_set_ref¶

Replace the reference signal and recompute conj(FFT(ref)).

void detector_set_ref (
    detector_state_t * state,
    const float complex * ref
) 

Also resets (see detector_reset()). The new reference must have the same length n that was passed to detector_create().

Parameters:

• state Must be non-NULL.
• ref New reference, CF32, length state->n.

function detector_set_state¶

int detector_set_state (
    detector_state_t * state,
    const void * blob
) 

function detector_set_threshold¶

Change the threshold without rebuilding the object.

void detector_set_threshold (
    detector_state_t * state,
    float threshold
) 

Parameters:

• state Must be non-NULL.
• threshold New threshold; 0.0 = always fire.

function detector_state_bytes¶

size_t detector_state_bytes (
    const detector_state_t * state
) 

Macro Definition Documentation¶

define DETECTOR_STATE_MAGIC¶

#define DETECTOR_STATE_MAGIC `DP_FOURCC ('D','E','T','1')`

define DETECTOR_STATE_VERSION¶

#define DETECTOR_STATE_VERSION `1u`

define DET_NOISE_MODE_T_DEFINED¶

Selects how noise power is estimated from the correlation magnitude vector over bins [noise_lo, noise_hi].

#define DET_NOISE_MODE_T_DEFINED 

The test statistic is peak_mag / noise_est. A zero noise_est (e.g., when all bins in the range are zero) yields test_stat = 0.

The documentation for this class was generated from the following file native/inc/detector/detector_core.h