File acc_trace_core.h¶

FileList > acc_trace > acc_trace_core.h

Go to the source code of this file

AccTrace — per-bin vector trace accumulator. More...

• #include "clib_common.h"
• #include "jm_perf.h"
• #include "dp_state.h"

Classes¶

Public Types¶

Public Functions¶

Macros¶

Detailed Description¶

Folds a stream of equal-length frames into a single running trace using one of four reduction modes: linear mean, exponential moving average (EMA), max-hold, or min-hold. Where the scalar acc_f32 / acc_cf64 accumulators reduce a frame to one running sum, AccTrace keeps a value per bin, which is what spectrum averaging, waterfalls/spectrograms, and video-averaged displays need. Accumulation is done in double precision regardless of the float32 input/output to keep the running mean numerically stable over long captures.

The first frame seeds the trace in every mode; subsequent frames update it: * mean : acc += (p - acc) / count (Welford running mean) * exp : acc = alpha*p + (1-alpha)*acc (EMA) * maxhold : acc = max(acc, p) per bin * minhold : acc = min(acc, p) per bin

Lifecycle: create -> (accumulate / reset)* -> value -> destroy

Public Types Documentation¶

enum acc_trace_mode_t¶

Trace reduction mode. Values match the Python string-enum index order ("mean", "exp", "maxhold", "minhold").

enum acc_trace_mode_t {
    ACC_TRACE_MEAN = 0,
    ACC_TRACE_EXP = 1,
    ACC_TRACE_MAXHOLD = 2,
    ACC_TRACE_MINHOLD = 3
};

Public Functions Documentation¶

function acc_trace_accumulate¶

Fold one length-n frame into the running trace. Frames shorter than n are ignored; ifp_len exceedsn only the firstn samples are used. The first accumulated frame seeds the trace directly (every mode), so a single frame followed by value() returns that frame unchanged.

void acc_trace_accumulate (
    acc_trace_state_t * state,
    const float * p,
    size_t p_len
) 

Parameters:

• state Must be non-NULL.
• p Input frame (float32).
• p_len Number of samples in p; must be >= n to take effect.

>>> import numpy as np
>>> from doppler.accumulator import AccTrace
>>> acc = AccTrace(n=4, mode="mean")
>>> acc.accumulate(np.array([1, 3, 5, 7], dtype=np.float32))
>>> acc.accumulate(np.array([3, 5, 7, 9], dtype=np.float32))
>>> acc.value().tolist()
[2.0, 4.0, 6.0, 8.0]

function acc_trace_create¶

Create a length- n trace accumulator.

acc_trace_state_t * acc_trace_create (
    size_t n,
    int mode,
    double alpha
) 

Parameters:

• n Trace length in bins. Must be > 0; returns NULL otherwise.
• mode Reduction mode index (0=mean, 1=exp, 2=maxhold, 3=minhold).
• alpha EMA smoothing factor used only by exp mode (0 < alpha <= 1).

Returns:

Heap-allocated state, or NULL on invalid argument or OOM.

Note:

Caller must call acc_trace_destroy() when done.

>>> from doppler.accumulator import AccTrace
>>> acc = AccTrace(n=8, mode="mean")
>>> acc.n, acc.count
(8, 0)

function acc_trace_destroy¶

Destroy an AccTrace instance and release all memory.

void acc_trace_destroy (
    acc_trace_state_t * state
) 

Parameters:

• state May be NULL (no-op).

function acc_trace_get_state¶

void acc_trace_get_state (
    const acc_trace_state_t * state,
    void * blob
) 

function acc_trace_reset¶

Discard the running trace; the next accumulate re-seeds it. The mode, alpha, and length are preserved.

void acc_trace_reset (
    acc_trace_state_t * state
) 

Parameters:

• state Must be non-NULL.

>>> import numpy as np
>>> from doppler.accumulator import AccTrace
>>> acc = AccTrace(n=4, mode="mean")
>>> acc.accumulate(np.ones(4, dtype=np.float32))
>>> acc.reset()
>>> acc.count
0

function acc_trace_set_state¶

int acc_trace_set_state (
    acc_trace_state_t * state,
    const void * blob
) 

function acc_trace_state_bytes¶

size_t acc_trace_state_bytes (
    const acc_trace_state_t * state
) 

function acc_trace_value¶

Copy the current averaged trace into out . Writes the full length-n trace and returns n. Returns 0 (which the Python wrapper renders as None) before any frame has been accumulated.

size_t acc_trace_value (
    acc_trace_state_t * state,
    size_t n,
    float * out
) 

Parameters:

• state Must be non-NULL.
• n Caller buffer capacity (ignored; buffer is pre-sized to n).
• out Destination, at least n float32 elements.

Returns:

Number of samples written (n, or 0 if empty).

>>> import numpy as np
>>> from doppler.accumulator import AccTrace
>>> acc = AccTrace(n=3, mode="maxhold")
>>> acc.accumulate(np.array([1, 5, 2], dtype=np.float32))
>>> acc.accumulate(np.array([4, 3, 6], dtype=np.float32))
>>> acc.value().tolist()
[4.0, 5.0, 6.0]

function acc_trace_value_max_out¶

Output capacity hint for value(); equals the trace length n.

size_t acc_trace_value_max_out (
    acc_trace_state_t * state
) 

Macro Definition Documentation¶

define ACC_TRACE_STATE_MAGIC¶

#define ACC_TRACE_STATE_MAGIC `DP_FOURCC ('A','T','R','C')`

define ACC_TRACE_STATE_VERSION¶

#define ACC_TRACE_STATE_VERSION `1u`

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