File detector2d_core.h¶

FileList > detector2d > detector2d_core.h

Go to the source code of this file

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

• #include "buffer/buffer.h"
• #include "corr2d/corr2d_core.h"
• #include "dp_state.h"

Classes¶

Public Types¶

Public Functions¶

Macros¶

Detailed Description¶

Two-dimensional extension of detector_core. The input stream is chunked into ny×nx frames (flat row-major CF32). The test statistic and threshold semantics are identical to the 1-D variant; the only difference is that the peak index maps to a (row, col) pair instead of a single lag.

Detection events: det_result2d_t = { row, col, peak_mag, noise_est, test_stat }

Lifecycle:

float complex ref[NY * NX] = { ... };
detector2d_state_t *det = detector2d_create(ref, NY, NX, 1,
    0, NY*NX-1, DET_NOISE_MEAN, 0.0f, 1);
det_result2d_t results[64];
while (recv(chunk, CHUNK_SZ)) {
    size_t n = detector2d_push(det, chunk, CHUNK_SZ, results, 64);
    for (size_t i = 0; i < n; i++)
        printf("row=%zu col=%zu stat=%.2f\n",
               results[i].row, results[i].col, results[i].test_stat);
}
detector2d_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 detector2d_create¶

Allocate a 2-D streaming signal detector backed by a 2-D correlator. Two-dimensional extension of detector_create() . Input frames are flat row-major CF32 arrays of length ny*nx streamed through a ring buffer. On every int-dump the peak flat index is decomposed into (row, col) and adet_result2d_t is emitted when test_stat > threshold. The Python wrapper accepts a (ny, nx) CF32 ndarray for bothref and the push input.

detector2d_state_t * detector2d_create (
    const float complex * ref,
    size_t ny,
    size_t nx,
    size_t dwell,
    size_t noise_lo,
    size_t noise_hi,
    det_noise_mode_t noise_mode,
    float threshold,
    int nthreads
) 

Parameters:

• ref 2-D reference image, (ny, nx) CF32 ndarray in Python.
• ny Number of rows in the reference and input frames.
• nx Number of columns in the reference and input frames.
• dwell Int-dump depth; must be >= 1.
• noise_lo Lower flat-index noise bin (inclusive, 0-based).
• noise_hi Upper flat-index noise bin (inclusive, < ny*nx).
• 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 Detector2D
>>> import numpy as np
>>> ref = np.zeros((4, 4), dtype=np.complex64); ref[0, 0] = 1.0
>>> det = Detector2D(ref=ref, dwell=1, noise_lo=1, noise_hi=15,
...                  noise_mode="mean", threshold=0.0)
>>> det.ny, det.nx, det.n, det.dwell
(4, 4, 16, 1)

function detector2d_destroy¶

Destroy and free.

void detector2d_destroy (
    detector2d_state_t * state
) 

Parameters:

• state May be NULL.

function detector2d_get_state¶

void detector2d_get_state (
    const detector2d_state_t * state,
    void * blob
) 

function detector2d_push¶

Stream an arbitrary-length CF32 chunk through the 2-D detector. Identical to detector_push() except frames are ny*nx complex samples and each detection event carries (row, col) for the peak location instead of a single lag index. In Python the result is always a list of (row, col, peak_mag, noise_est, test_stat) tuples.

size_t detector2d_push (
    detector2d_state_t * state,
    const float complex * in,
    size_t n_in,
    det_result2d_t * result,
    size_t max_results
) 

Parameters:

• state Allocated 2-D 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_result2d_t structs; filled on return.
• max_results Capacity of result (maximum detections to emit).

Returns:

Number of det_result2d_t entries written to result.

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

function detector2d_reset¶

Reset the 2-D correlator, ring buffer, and last-corr flag. Discards any partial frame buffered in the ring and zeroes the coherent accumulator. The reference spectrum and FFT plans are preserved.

void detector2d_reset (
    detector2d_state_t * state
) 

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

function detector2d_set_ref¶

Replace the reference image and recompute conj(FFT2(ref)).

void detector2d_set_ref (
    detector2d_state_t * state,
    const float complex * ref
) 

Also resets. The new reference must have the same ny*nx total size.

Parameters:

• state Must be non-NULL.
• ref New reference, flat row-major CF32, length ny*nx.

function detector2d_set_state¶

int detector2d_set_state (
    detector2d_state_t * state,
    const void * blob
) 

function detector2d_set_threshold¶

Change threshold without rebuilding.

void detector2d_set_threshold (
    detector2d_state_t * state,
    float threshold
) 

Parameters:

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

function detector2d_state_bytes¶

size_t detector2d_state_bytes (
    const detector2d_state_t * state
) 

Macro Definition Documentation¶

define DETECTOR2D_STATE_MAGIC¶

#define DETECTOR2D_STATE_MAGIC `DP_FOURCC ('D','E','T','2')`

define DETECTOR2D_STATE_VERSION¶

#define DETECTOR2D_STATE_VERSION `1u`

define DET_NOISE_MODE_T_DEFINED¶

#define DET_NOISE_MODE_T_DEFINED 

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