#include <roibin_split_stage.h>

Inheritance diagram for fz::ROIBinSplitStage< TData >:

Public Member Functions
void	setPeaksFile (const std::string &path)

void	setPeaks (const std::vector< RoiPeak > &peaks)
	Supply peaks directly (used by tests).

void	setRoiHalfWidth (uint32_t hw)
	ROI box half-width in pixels; the box is `(2*hw+1)^2`. Default 4 → 9x9.

void	setBinFactor (uint32_t b)

void	setDims (const std::array< size_t, 3 > &dims) override

double	getRoiOverlapFraction () const

void	setInverse (bool inv) override

bool	isGraphCompatible () const override

std::vector< std::string >	getOutputNames () const override

std::string	getName () const override

uint16_t	getStageTypeId () const override

uint8_t	getOutputDataType (size_t output_index) const override

uint8_t	getInputDataType (size_t input_index) const override

void	execute (fz::stream_t stream, MemoryPool pool, const std::vector< void > &inputs, const std::vector< void * > &outputs, const std::vector< size_t > &sizes) override

void	onFinalize (size_t estimated_inlen, MemoryPool *pool) override

size_t	estimateDeviceFootprintBytes (size_t) const override

std::vector< size_t >	estimateOutputSizes (const std::vector< size_t > &input_sizes) const override

std::unordered_map< std::string, size_t >	getActualOutputSizesByName () const override

size_t	getActualOutputSize (int index) const override

std::vector< std::string >	getRunNotes () const override

size_t	serializeHeader (size_t, uint8_t *buf, size_t max_size) const override

void	deserializeHeader (const uint8_t *buf, size_t size) override

size_t	getMaxHeaderSize (size_t) const override

void	saveState () override

void	restoreState () override

Public Member Functions inherited from fz::Stage
virtual size_t	getRequiredInputAlignment () const

int	getOutputIndex (const std::string &name) const

virtual size_t	estimatePinnedFootprintBytes (size_t) const

virtual void	postStreamSync (fz::stream_t stream)

virtual size_t	estimateScratchBytes (const std::vector< size_t > &input_sizes) const

Additional Inherited Members
Static Public Member Functions inherited from fz::Stage
static constexpr bool	isSupportedOnBackend ()

Detailed Description

template<typename TData>
class fz::ROIBinSplitStage< TData >

Region-of-interest / background split stage.

TData is the field element type (float or double).

Member Function Documentation

◆ setPeaksFile()

template<typename TData >

void fz::ROIBinSplitStage< TData >::setPeaksFile ( const std::string & path )

Load the peak list from a .roi file (compress side only). Throws on a malformed file or on peaks that fall outside the configured dimensions.

◆ setBinFactor()

template<typename TData >

void fz::ROIBinSplitStage< TData >::setBinFactor ( uint32_t b )

inline

Background binning factor; 1 disables binning. See the header note on what binning does and does not bound.

◆ setDims()

template<typename TData >

void fz::ROIBinSplitStage< TData >::setDims ( const std::array< size_t, 3 > & dims )

inlineoverridevirtual

Pipeline-driven dims push, at addStage and again at finalize.

Ignored once the dims came from the archive (deserializeHeader) and ignored for a degenerate push. On the decompress path the pipeline is rebuilt from the FZM header and its global dims are not repopulated, so finalize() pushes {0,0,1} to every stage; taking that would erase the geometry this stage just read from its own header and leave the inverse pass unable to place a single ROI box.

Reimplemented from fz::Stage.

◆ getRoiOverlapFraction()

template<typename TData >

double fz::ROIBinSplitStage< TData >::getRoiOverlapFraction ( ) const

inline

Fraction of ROI slots that are duplicates of an already-covered pixel. Computed on the host at finalize; reported as a run note so the redundancy the design trades for an exact output size stays visible.

◆ setInverse()

template<typename TData >

void fz::ROIBinSplitStage< TData >::setInverse ( bool inverse )

inlineoverridevirtual

Switch between forward (compression) and inverse (decompression) mode. Affects getNumInputs()/getNumOutputs() for stages with asymmetric port counts.

Reimplemented from fz::Stage.

◆ isGraphCompatible()

template<typename TData >

bool fz::ROIBinSplitStage< TData >::isGraphCompatible ( ) const

inlineoverridevirtual

Plain kernel launches and a stream-ordered H2D upload of the peak table that happens once at finalize, not per execute → capturable.

Reimplemented from fz::Stage.

◆ getOutputNames()

template<typename TData >

std::vector< std::string > fz::ROIBinSplitStage< TData >::getOutputNames ( ) const

inlineoverridevirtual

Output port names in order. Default: single port named "output". Multi-output stages (e.g. Lorenzo: "codes", "outliers") override this.

Reimplemented from fz::Stage.

◆ getName()

template<typename TData >

std::string fz::ROIBinSplitStage< TData >::getName ( ) const

inlineoverridevirtual

Human-readable name used in error messages and debug output.

Implements fz::Stage.

◆ getStageTypeId()

template<typename TData >

uint16_t fz::ROIBinSplitStage< TData >::getStageTypeId ( ) const

inlineoverridevirtual

Stage type identifier written into the FZM file header.

Implements fz::Stage.

◆ getOutputDataType()

template<typename TData >

uint8_t fz::ROIBinSplitStage< TData >::getOutputDataType ( size_t output_index ) const

inlineoverridevirtual

DataType enum of the given output port.

Implements fz::Stage.

◆ getInputDataType()

template<typename TData >

uint8_t fz::ROIBinSplitStage< TData >::getInputDataType ( size_t ) const

inlineoverridevirtual

Expected DataType of the given input port.

Used by Pipeline::finalize() to detect type mismatches between connected stages before any execution. Return DataType::UNKNOWN to opt out of checking — byte-transparent stages (Bitshuffle, RZE, RRE) and mock stages must return UNKNOWN; finalize() skips any connection where either side is UNKNOWN.

Reimplemented from fz::Stage.

◆ execute()

template<typename TData >

void fz::ROIBinSplitStage< TData >::execute	(	fz::stream_t	stream,
		MemoryPool *	pool,
		const std::vector< void * > &	inputs,
		const std::vector< void * > &	outputs,
		const std::vector< size_t > &	sizes
	)

overridevirtual

Execute the stage. Inputs, outputs, and sizes are device pointers/bytes.

Stages may call cudaStreamSynchronize(stream) or issue blocking D2H copies when the algorithm requires it (e.g. Huffman histogram readback for codebook construction, ANS renormalization tables). Such stages must return false from isGraphCompatible() and must document the sync points.

Note: the DAG dispatches sibling nodes (same topological level) via a sequential CPU loop, each enqueuing to its own stream. A sync inside execute() blocks the CPU from dispatching subsequent siblings until the synced stream is idle — this delays parallel branches in wide DAGs. In a linear pipeline there are no siblings and no extra cost.

Implements fz::Stage.

◆ onFinalize()

template<typename TData >

void fz::ROIBinSplitStage< TData >::onFinalize	(	size_t	estimated_inlen,
		MemoryPool *	pool
	)

overridevirtual

Uploads the peak table to a stage-private persistent device buffer so the forward pass never does a per-execute H2D copy.

Reimplemented from fz::Stage.

◆ estimateDeviceFootprintBytes()

template<typename TData >

size_t fz::ROIBinSplitStage< TData >::estimateDeviceFootprintBytes ( size_t ) const

inlineoverridevirtual

Estimated persistent device memory this stage allocates outside the pool (via pool->allocatePersistentDevice). Used for total footprint reporting. Default: 0.

Reimplemented from fz::Stage.

◆ estimateOutputSizes()

template<typename TData >

std::vector< size_t > fz::ROIBinSplitStage< TData >::estimateOutputSizes ( const std::vector< size_t > & input_sizes ) const

inlineoverridevirtual

Estimate output buffer sizes given input sizes. Used for buffer allocation planning in PREALLOCATE mode — must be a safe upper bound; under-estimation causes buffer overruns.

Implements fz::Stage.

◆ getActualOutputSizesByName()

template<typename TData >

std::unordered_map< std::string, size_t > fz::ROIBinSplitStage< TData >::getActualOutputSizesByName ( ) const

inlineoverridevirtual

Actual output sizes after execute(), keyed by output port name.

Implements fz::Stage.

◆ getActualOutputSize()

template<typename TData >

size_t fz::ROIBinSplitStage< TData >::getActualOutputSize ( int index ) const

inlineoverridevirtual

Actual size of a single output by index after execute(). Avoids constructing the map for the common single-output case. Default delegates to getActualOutputSizesByName(); override to return directly from an internal field.

Reimplemented from fz::Stage.

◆ getRunNotes()

template<typename TData >

std::vector< std::string > fz::ROIBinSplitStage< TData >::getRunNotes ( ) const

overridevirtual

Notes about what this stage actually did on the last run, when that differs from what was configured in a way that affects comparability.

Motivating case: HuffmanStage silently falls back to an Adaptive book when a PerBlock/Fixed build drives a symbol past the 27-bit code field. The fallback is correct — it does not relax the error bound — but a field encoded with a different codebook is not compression-ratio comparable to one that was not, and getBookSource() deliberately keeps reporting what was asked for. Without a channel like this, a benchmark row records the two cases identically and the difference is unrecoverable after the fact.

Returns short stable machine-readable tokens (e.g. "adaptive_fallback"), not prose — these are meant to land in a benchmark row and be grouped on. Empty by default; a stage that never surprises its caller need not implement it.

Reimplemented from fz::Stage.

◆ serializeHeader()

template<typename TData >

size_t fz::ROIBinSplitStage< TData >::serializeHeader	(	size_t	output_index,
		uint8_t *	header_buffer,
		size_t	max_size
	)		const

inlineoverridevirtual

Serialize stage config into header_buffer (max 128 bytes) for the FZM file. Return the number of bytes written, or 0 if the stage has no config.

Reimplemented from fz::Stage.

◆ deserializeHeader()

template<typename TData >

void fz::ROIBinSplitStage< TData >::deserializeHeader	(	const uint8_t *	header_buffer,
		size_t	size
	)

inlineoverridevirtual

Restore stage config from header_buffer during decompression.

Reimplemented from fz::Stage.

◆ getMaxHeaderSize()

template<typename TData >

size_t fz::ROIBinSplitStage< TData >::getMaxHeaderSize ( size_t output_index ) const

inlineoverridevirtual

Maximum bytes this stage writes into its per-output FZM header slot.

Reimplemented from fz::Stage.

◆ saveState()

template<typename TData >

void fz::ROIBinSplitStage< TData >::saveState ( )

inlineoverridevirtual

Save/restore config state around a decompression pass. deserializeHeader() overwrites the stage's forward-pass config; saveState() is called before and restoreState() after so the stage returns to its original configuration.

Reimplemented from fz::Stage.

◆ restoreState()

template<typename TData >

void fz::ROIBinSplitStage< TData >::restoreState ( )

inlineoverridevirtual

Restoring is a no-op until saveState() has actually run. decompressMulti() brackets each inverse execute() with save/restore, but the pipeline may call restore first; without this guard that would write the default {0,0,1} over the geometry deserializeHeader() just recovered and the inverse pass would fail with "dimensions not set".

Reimplemented from fz::Stage.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ setPeaksFile()

◆ setBinFactor()

◆ setDims()

◆ getRoiOverlapFraction()

◆ setInverse()

◆ isGraphCompatible()

◆ getOutputNames()

◆ getName()

◆ getStageTypeId()

◆ getOutputDataType()

◆ getInputDataType()

◆ execute()

◆ onFinalize()

◆ estimateDeviceFootprintBytes()

◆ estimateOutputSizes()

◆ getActualOutputSizesByName()

◆ getActualOutputSize()

◆ getRunNotes()

◆ serializeHeader()

◆ deserializeHeader()

◆ getMaxHeaderSize()

◆ saveState()

◆ restoreState()