processing Namespace Reference

Namespaces
namespace	pipeline

Classes
struct	FixedFullscaleIqSample
	One complex Cartesian IQ sample scaled for VITA-style signed 16-bit transport. More...
struct	FixedFullscaleScalingResult
	Result of fixed-fullscale IQ scaling. More...

Functions
core::OutputFileMetadata	buildStreamingOutputMetadata (const radar::Receiver *receiver, const std::string &output_path, std::size_t total_samples, const std::vector< core::ActiveStreamingSource > &streaming_sources, RealType output_sample_rate)
	Builds HDF5 file metadata for a streaming receiver result emitted through the output sink.
core::ReceiverStreamDescriptor	buildReceiverStreamDescriptor (const radar::Receiver *receiver, RealType sample_rate, std::span< const core::ActiveStreamingSource > streaming_sources={})
	Builds the receiver stream descriptor used by output sinks.
core::ReceiverSampleBlock	buildReceiverSampleBlock (const radar::Receiver *receiver, RealType first_sample_time, RealType sample_rate, std::span< const ComplexType > samples, std::uint64_t sample_start, std::shared_ptr< const core::OutputFileMetadata > file_metadata=nullptr)
	Builds a non-owning output sample block over contiguous processed complex samples.
core::ReceiverSampleBlock	buildReceiverSampleBlock (const radar::Receiver *receiver, RealType first_sample_time, RealType sample_rate, std::span< const ComplexType > samples, std::uint64_t sample_start, std::span< const core::ActiveStreamingSource > streaming_sources, std::shared_ptr< const core::OutputFileMetadata > file_metadata)
	Builds a sample block with active streaming-source context for VITA Context packets.
void	runPulsedFinalizer (radar::Receiver *receiver, const std::vector< std::unique_ptr< radar::Target > > *targets, const std::shared_ptr< core::ProgressReporter > &reporter, const std::string &output_dir, const std::shared_ptr< core::OutputMetadataCollector > &metadata_collector=nullptr, core::ReceiverOutputSink *output_sink=nullptr)
	The main function for a dedicated pulsed-mode receiver finalizer thread.
void	renderWindow (std::vector< ComplexType > &window, RealType length, RealType start, RealType fracDelay, std::span< const std::unique_ptr< serial::Response > > responses)
	Renders a time-window of I/Q data from a collection of raw radar responses.
void	applyThermalNoise (std::span< ComplexType > window, RealType noiseTemperature, std::mt19937 &rngEngine)
	Applies thermal (Johnson-Nyquist) noise to a window of I/Q samples.
void	applyThermalNoiseAtSampleRate (std::span< ComplexType > window, RealType noiseTemperature, std::mt19937 &rngEngine, RealType sampleRateHz)
	Applies circular complex thermal noise using a caller-specified complex-baseband sample rate.
RealType	quantizeAndScaleWindow (std::span< ComplexType > window)
	Simulates ADC quantization and scales a window of complex I/Q samples.
FixedFullscaleScalingResult	scaleToInt16FixedFullscale (std::span< const ComplexType > samples, RealType fullscale)
	Scales complex samples against a fixed full-scale to signed int16 IQ.

Function Documentation

applyThermalNoise()

void processing::applyThermalNoise	(	std::span< ComplexType >	window,
		RealType	noiseTemperature,
		std::mt19937 &	rngEngine
	)

Applies thermal (Johnson-Nyquist) noise to a window of I/Q samples.

Simulates the addition of white Gaussian noise based on the receiver's noise temperature and the simulation bandwidth.

Parameters

window	A span of I/Q data to which noise will be added.
noiseTemperature	The effective noise temperature in Kelvin.
rngEngine	A random number generator engine to use for noise generation.

Definition at line 142 of file signal_processor.cpp.

    {
        if (noiseTemperature == 0)
        {
            return;
        }
 
        const RealType b = params::rate() / (2.0 * params::oversampleRatio());
        const RealType total_power = params::boltzmannK() * noiseTemperature * b;
 
        // Split total power equally between the I and Q channels
        const RealType per_channel_power = total_power / 2.0;
        const RealType stddev = std::sqrt(per_channel_power);
 
        noise::WgnGenerator generator(rngEngine, stddev);
        for (auto& sample : window)
        {
            sample += ComplexType(generator.getSample(), generator.getSample());
        }
    }

References b, params::boltzmannK(), max, params::oversampleRatio(), and params::rate().

Here is the call graph for this function:

applyThermalNoiseAtSampleRate()

void processing::applyThermalNoiseAtSampleRate	(	std::span< ComplexType >	window,
		const RealType	noiseTemperature,
		std::mt19937 &	rngEngine,
		const RealType	sampleRateHz
	)

Applies circular complex thermal noise using a caller-specified complex-baseband sample rate.

Definition at line 163 of file signal_processor.cpp.

    {
        if (noiseTemperature == 0 || sampleRateHz <= 0.0)
        {
            return;
        }
 
        const RealType complex_power = params::boltzmannK() * noiseTemperature * sampleRateHz;
        const RealType per_channel_power = complex_power / 2.0;
        const RealType stddev = std::sqrt(per_channel_power);
 
        noise::WgnGenerator generator(rngEngine, stddev);
        for (auto& sample : window)
        {
            sample += ComplexType(generator.getSample(), generator.getSample());
        }
    }

References params::boltzmannK(), and max.

Referenced by runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

buildReceiverSampleBlock() [1/2]

core::ReceiverSampleBlock processing::buildReceiverSampleBlock	(	const radar::Receiver *	receiver,
		const RealType	first_sample_time,
		const RealType	sample_rate,
		const std::span< const ComplexType >	samples,
		const std::uint64_t	sample_start,
		std::shared_ptr< const core::OutputFileMetadata >	file_metadata
	)

Builds a non-owning output sample block over contiguous processed complex samples.

Definition at line 702 of file finalizer.cpp.

    {
        return buildReceiverSampleBlock(receiver, first_sample_time, sample_rate, samples, sample_start,
                                        std::span<const core::ActiveStreamingSource>{}, std::move(file_metadata));
    }

References buildReceiverSampleBlock(), and receiver.

Referenced by buildReceiverSampleBlock(), and runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

buildReceiverSampleBlock() [2/2]

core::ReceiverSampleBlock processing::buildReceiverSampleBlock	(	const radar::Receiver *	receiver,
		const RealType	first_sample_time,
		const RealType	sample_rate,
		const std::span< const ComplexType >	samples,
		const std::uint64_t	sample_start,
		const std::span< const core::ActiveStreamingSource >	streaming_sources,
		std::shared_ptr< const core::OutputFileMetadata >	file_metadata
	)

Builds a sample block with active streaming-source context for VITA Context packets.

Definition at line 713 of file finalizer.cpp.

    {
        return core::ReceiverSampleBlock{.stream =
                                             buildReceiverStreamDescriptor(receiver, sample_rate, streaming_sources),
                                         .first_sample_time = first_sample_time,
                                         .sample_rate = sample_rate,
                                         .samples = samples,
                                         .sample_start = sample_start,
                                         .valid_data = true,
                                         .calibrated_time = true,
                                         .reference_lock = true,
                                         .file_metadata = std::move(file_metadata)};
    }

References buildReceiverStreamDescriptor(), max, receiver, core::ReceiverStreamDescriptor::sample_rate, and core::ReceiverSampleBlock::stream.

Here is the call graph for this function:

buildReceiverStreamDescriptor()

core::ReceiverStreamDescriptor processing::buildReceiverStreamDescriptor	(	const radar::Receiver *	receiver,
		const RealType	sample_rate,
		const std::span< const core::ActiveStreamingSource >	streaming_sources
	)

Builds the receiver stream descriptor used by output sinks.

Definition at line 679 of file finalizer.cpp.

    {
        core::ReceiverStreamDescriptor descriptor{.receiver_id = receiver->getId(),
                                                  .receiver_name = receiver->getName(),
                                                  .mode = receiverModeToken(receiver),
                                                  .sample_rate = sample_rate,
                                                  .bandwidth = sample_rate > 0.0 ? sample_rate / 2.0 : 0.0,
                                                  .dechirped = receiver->isDechirpEnabled(),
                                                  .if_resampled = receiver->getFmcwIfResamplerPlan().has_value(),
                                                  .adc_bits = params::adcBits(),
                                                  .coordinate = buildCoordinateContext(),
                                                  .initial_platform_state = buildInitialPlatformState(receiver),
                                                  .pulsed = buildPulsedContext(receiver),
                                                  .cw = buildCwContext(receiver),
                                                  .fmcw = buildFmcwContext(receiver, streaming_sources)};
        if (const auto timing = receiver->getTiming(); timing)
        {
            descriptor.reference_frequency = timing->getFrequency();
        }
        return descriptor;
    }

References params::adcBits(), max, receiver, and core::ReceiverStreamDescriptor::receiver_id.

Referenced by buildReceiverSampleBlock(), and runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

buildStreamingOutputMetadata()

core::OutputFileMetadata processing::buildStreamingOutputMetadata	(	const radar::Receiver *	receiver,
		const std::string &	output_path,
		const std::size_t	total_samples,
		const std::vector< core::ActiveStreamingSource > &	streaming_sources,
		const RealType	output_sample_rate
	)

Builds HDF5 file metadata for a streaming receiver result emitted through the output sink.

Definition at line 668 of file finalizer.cpp.

    {
        const auto dechirp_time_spans =
            receiver->isDechirpEnabled() ? dechirpActiveTimeSpans(receiver) : std::vector<TimeSpan>{};
        return buildStreamingMetadata(receiver, output_path, total_samples, streaming_sources, output_sample_rate,
                                      dechirp_time_spans);
    }

References max, and receiver.

quantizeAndScaleWindow()

RealType processing::quantizeAndScaleWindow

(

std::span< ComplexType >

window

)

Simulates ADC quantization and scales a window of complex I/Q samples.

This function first finds the maximum absolute value in the I/Q data to determine the full-scale range. It then simulates the quantization process based on the configured number of ADC bits. If no quantization is specified (adc_bits=0), it normalizes the data to a maximum amplitude of 1.0.

Parameters

window

The window of complex I/Q samples to quantize and scale.

Returns

The full-scale value used for quantization/normalization.

Definition at line 182 of file signal_processor.cpp.

    {
        RealType max_value = 0;
        for (const auto& sample : window)
        {
            const RealType real_abs = std::fabs(sample.real());
            const RealType imag_abs = std::fabs(sample.imag());
 
            max_value = std::max({max_value, real_abs, imag_abs});
        }
 
        if (const auto adc_bits = params::adcBits(); adc_bits > 0)
        {
            adcSimulate(window, adc_bits, max_value);
        }
        else if (max_value != 0)
        {
            for (auto& sample : window)
            {
                sample /= max_value;
            }
        }
        return max_value;
    }

References params::adcBits(), and max.

Referenced by processing::pipeline::applyDownsamplingAndQuantization(), serial::Hdf5OutputSink::Impl::closeStreamingStream(), and serial::Hdf5OutputSink::Impl::writePulsedBlock().

Here is the call graph for this function:

Here is the caller graph for this function:

renderWindow()

void processing::renderWindow	(	std::vector< ComplexType > &	window,
		RealType	length,
		RealType	start,
		RealType	fracDelay,
		std::span< const std::unique_ptr< serial::Response > >	responses
	)

Renders a time-window of I/Q data from a collection of raw radar responses.

This function orchestrates the process of converting abstract Response objects into a concrete vector of complex I/Q samples for a specific time window. It handles the superposition of multiple signals arriving at the receiver during the window and can use a thread pool for parallel processing.

Parameters

window	The output vector where the rendered I/Q samples will be added.
length	The duration of the time window in seconds.
start	The start time of the window in seconds.
fracDelay	A fractional sample delay to apply for fine-grained timing.
responses	A span of unique pointers to the Response objects to be rendered.

Definition at line 110 of file signal_processor.cpp.

    {
        const RealType end = start + length;
        std::queue<serial::Response*> work_list;
 
        for (const auto& response : responses)
        {
            if (response->startTime() <= end && response->endTime() >= start)
            {
                work_list.push(response.get());
            }
        }
 
        const RealType rate = params::rate() * params::oversampleRatio();
        const auto local_window_size = static_cast<std::size_t>(std::ceil(length * rate));
 
        std::vector local_window(local_window_size, ComplexType{});
 
        while (!work_list.empty())
        {
            const auto* resp = work_list.front();
            work_list.pop();
            processResponse(resp, local_window, rate, start, fracDelay, local_window_size);
        }
 
        for (std::size_t i = 0; i < local_window_size; ++i)
        {
            window[i] += local_window[i];
        }
    }

References max, params::oversampleRatio(), and params::rate().

Referenced by runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

runPulsedFinalizer()

void processing::runPulsedFinalizer	(	radar::Receiver *	receiver,
		const std::vector< std::unique_ptr< radar::Target > > *	targets,
		const std::shared_ptr< core::ProgressReporter > &	reporter,
		const std::string &	output_dir,
		const std::shared_ptr< core::OutputMetadataCollector > &	metadata_collector = nullptr,
		core::ReceiverOutputSink *	output_sink = nullptr
	)

The main function for a dedicated pulsed-mode receiver finalizer thread.

This function runs in a loop, dequeuing and processing RenderingJobs for a specific receiver. It handles all expensive rendering, signal processing, and I/O for that receiver's data.

Parameters

receiver	A pointer to the pulsed-mode receiver to process.
targets	A pointer to the world's list of targets for interference calculation.
reporter	Shared pointer to the progress reporter for status updates.
output_dir	Output directory for the simulation files.

Definition at line 731 of file finalizer.cpp.

    {
        (void)output_dir;
        (void)metadata_collector;
        if (output_sink == nullptr)
        {
            throw std::invalid_argument("runPulsedFinalizer requires a receiver output sink");
        }
 
        const auto timing_model = receiver->getTiming()->clone();
        if (!timing_model)
        {
            LOG(logging::Level::FATAL, "Failed to clone timing model for receiver '{}'", receiver->getName());
            return;
        }
 
        const auto sink_stream_id =
            output_sink->registerStream(buildReceiverStreamDescriptor(receiver, params::rate()));
        bool sink_stream_open = false;
        std::uint64_t sink_sample_start = 0;
 
        unsigned chunk_index = 0;
 
        LOG(logging::Level::INFO, "Finalizer thread started for receiver '{}'. Routing to output sink.",
            receiver->getName());
 
        auto last_report_time = std::chrono::steady_clock::now();
        const auto report_interval = std::chrono::milliseconds(100);
        const RealType rate = params::rate() * params::oversampleRatio();
        const RealType dt = 1.0 / rate;
        core::ReceiverTrackerCache streaming_tracker_cache;
 
        while (true)
        {
            core::RenderingJob job;
            if (!receiver->waitAndDequeueFinalizerJob(job))
            {
                break; // Shutdown signal received
            }
 
            const auto window_samples = static_cast<unsigned>(std::ceil(job.duration * rate));
            std::vector pnoise(window_samples, 0.0);
 
            RealType actual_start = job.ideal_start_time;
            RealType frac_delay = 0.0;
 
            if (timing_model->isEnabled())
            {
                pipeline::advanceTimingModel(timing_model.get(), receiver, rate);
                std::ranges::generate(pnoise, [&] { return timing_model->getNextSample(); });
                std::tie(actual_start, frac_delay) = pipeline::calculateJitteredStart(
                    job.ideal_start_time, pnoise[0], timing_model->getFrequency(), rate);
            }
 
            std::vector<ComplexType> window_buffer(window_samples);
 
            pipeline::applyStreamingInterference(window_buffer, actual_start, dt, receiver,
                                                 job.active_streaming_sources, targets, streaming_tracker_cache);
 
            renderWindow(window_buffer, job.duration, actual_start, frac_delay, job.responses);
 
            if (timing_model->isEnabled())
            {
                pipeline::addPhaseNoiseToWindow(pnoise, window_buffer);
            }
 
            pipeline::applyDownsampling(window_buffer);
            applyThermalNoiseAtSampleRate(window_buffer,
                                          receiver->getNoiseTemperature(receiver->getRotation(actual_start)),
                                          receiver->getRngEngine(), params::rate());
            if (!sink_stream_open)
            {
                output_sink->openStream(sink_stream_id, actual_start);
                sink_stream_open = true;
            }
            const auto block =
                buildReceiverSampleBlock(receiver, actual_start, params::rate(), window_buffer, sink_sample_start);
            output_sink->submitBlock(block);
            sink_sample_start += static_cast<std::uint64_t>(window_buffer.size());
            ++chunk_index;
 
            if (reporter)
            {
                const auto now = std::chrono::steady_clock::now();
                if ((now - last_report_time) >= report_interval)
                {
                    reporter->report(std::format("Exporting {}: Chunk {}", receiver->getName(), chunk_index),
                                     static_cast<int>(chunk_index), 0);
                    last_report_time = now;
                }
            }
        }
 
        if (sink_stream_open)
        {
            output_sink->closeStream(sink_stream_id);
        }
 
        if (reporter)
        {
            reporter->report(std::format("Finished Exporting {}", receiver->getName()), 100, 100);
        }
        LOG(logging::Level::INFO, "Finalizer thread for receiver '{}' finished.", receiver->getName());
    }

References processing::pipeline::addPhaseNoiseToWindow(), processing::pipeline::advanceTimingModel(), processing::pipeline::applyDownsampling(), processing::pipeline::applyStreamingInterference(), applyThermalNoiseAtSampleRate(), buildReceiverSampleBlock(), buildReceiverStreamDescriptor(), processing::pipeline::calculateJitteredStart(), logging::FATAL, logging::INFO, LOG, max, params::oversampleRatio(), params::rate(), receiver, and renderWindow().

Here is the call graph for this function:

scaleToInt16FixedFullscale()

FixedFullscaleScalingResult processing::scaleToInt16FixedFullscale	(	std::span< const ComplexType >	samples,
		RealType	fullscale
	)

Scales complex samples against a fixed full-scale to signed int16 IQ.

This helper is intended for real-time receiver-output sinks, where scanning a complete future window to derive full-scale would change hardware-like behavior.

Parameters

samples	Input complex samples in physical units.
fullscale	Positive fixed full-scale magnitude for both I and Q channels.

Returns

Scaled int16 IQ samples and a count of complex samples that clipped on either channel.

Exceptions

std::invalid_argument

when fullscale is not positive.

Definition at line 207 of file signal_processor.cpp.

    {
        if (fullscale <= 0.0 || !std::isfinite(fullscale))
        {
            throw std::invalid_argument("Fixed full-scale must be positive and finite.");
        }
 
        FixedFullscaleScalingResult result;
        result.samples.reserve(samples.size());
        for (const auto& sample : samples)
        {
            bool clipped = false;
            const auto i = scaleComponentToInt16(sample.real(), fullscale, clipped);
            const auto q = scaleComponentToInt16(sample.imag(), fullscale, clipped);
            if (clipped)
            {
                ++result.clipped_sample_count;
            }
            result.samples.push_back(FixedFullscaleIqSample{.i = i, .q = q});
        }
        return result;
    }

References processing::FixedFullscaleIqSample::i, and max.