The StandardPipeline class is a convenience class to work with a predefined processing pipeline for creation of projections. More...

#include <standardpipeline.h>

Inheritance diagram for CTL::StandardPipeline:

[legend]

Collaboration diagram for CTL::StandardPipeline:

[legend]

Classes
class	Settings

class	SettingsAFS

class	SettingsDetectorSaturation

class	SettingsPoissonNoise

class	SettingsRayCaster

class	SettingsSpectralEffects

Public Types
enum	{ Type = 201 }

enum	ApproximationPolicy { No_Approximation, Default_Approximation, Full_Approximation }

Public Types inherited from CTL::AbstractProjector
enum	{ Type = 0 }

Public Types inherited from CTL::SerializationInterface
enum	{ Type = -1, UserType = 65536 }

Public Member Functions
int	type () const override

	StandardPipeline (ApproximationPolicy policy=StandardPipeline::Default_Approximation)

	StandardPipeline (const StandardPipeline &)=delete

StandardPipeline &	operator= (const StandardPipeline &)=delete

	StandardPipeline (StandardPipeline &&other) noexcept

StandardPipeline &	operator= (StandardPipeline &&other) noexcept

void	configure (const AcquisitionSetup &setup) override
	Sets the acquisition setup for the simulation to setup. More...

ProjectionData	project (const VolumeData &volume) override
	Creates projection data from volume. More...

ProjectionData	projectComposite (const CompositeVolume &volume) override
	Creates projection data from the composite volume volume. More...

ProjectionData	projectSparse (const SparseVoxelVolume &volume) override
	Creates projection data from the sparse volume volume. More...

bool	isLinear () const override

ProjectorNotifier *	notifier () override
	Returns a pointer to the notifier of the projector. More...

void	fromVariant (const QVariant &variant) override
	Sets the contents of the object based on the QVariant variant. More...

QVariant	toVariant () const override
	Stores the contents of this instance in a QVariant. More...

void	enableArealFocalSpot (bool enable=true)

void	enableDetectorSaturation (bool enable=true)

void	enablePoissonNoise (bool enable=true)

void	enableSpectralEffects (bool enable=true)

SettingsAFS &	settingsArealFocalSpot ()

SettingsDetectorSaturation &	settingsDetectorSaturation ()

SettingsPoissonNoise &	settingsPoissonNoise ()

SettingsSpectralEffects &	settingsSpectralEffects ()

SettingsRayCaster &	settingsRayCaster ()

Public Member Functions inherited from CTL::AbstractProjector
	AbstractProjector (const AbstractProjector &)=delete

	AbstractProjector (AbstractProjector &&)=default

AbstractProjector &	operator= (const AbstractProjector &)=delete

AbstractProjector &	operator= (AbstractProjector &&)=default

	~AbstractProjector () override=default

ProjectionData	configureAndProject (const AcquisitionSetup &setup, const VolumeData &volume)
	Performs a forward projection with a precedent configuration of the projector. More...

ProjectionData	configureAndProject (const AcquisitionSetup &setup, const CompositeVolume &volume)
	Performs a forward projection with a precedent configuration of the projector. More...

ProjectionData	configureAndProject (const AcquisitionSetup &setup, const SparseVoxelVolume &volume)
	Performs a forward projection with a precedent configuration of the projector. More...

virtual QVariant	parameter () const
	Returns the parameters of this instance as QVariant. More...

virtual void	setParameter (const QVariant &parameter)
	Sets the parameters of this instance based on the passed QVariant parameter. Parameters need to follow the naming convention as described in parameter(). More...

void	connectNotifierToMessageHandler (bool includeProgress=false)
	Connects the notifier to the CTL's MessageHandler. More...

Public Member Functions inherited from CTL::SerializationInterface
virtual	~SerializationInterface ()=default

Private Member Functions
uint	posAFS () const

uint	posDetSat () const

uint	posPoisson () const

uint	posSpectral () const

Private Attributes
ProjectionPipeline	_pipeline
	The pipeline object; owns the projector and all extensions.

OCL::RayCasterProjector *	_projector
	Pointer to the ray caster projector.

ArealFocalSpotExtension *	_extAFS
	Pointer to the ArealFocalSpotExtension.

DetectorSaturationExtension *	_extDetSat
	Pointer to the DetectorSaturationExtension.

PoissonNoiseExtension *	_extPoisson
	Pointer to the PoissonNoiseExtension.

SpectralEffectsExtension *	_extSpectral
	Pointer to the SpectralEffectsExtension.

CTL::StandardPipeline::SettingsRayCaster	_settingsRayCaster

CTL::StandardPipeline::SettingsAFS	_settingsAFS

CTL::StandardPipeline::SettingsDetectorSaturation	_settingsDetSat

CTL::StandardPipeline::SettingsPoissonNoise	_settingsPoisson

CTL::StandardPipeline::SettingsSpectralEffects	_settingsSpectral

ApproximationPolicy	_approxMode
	approximation level for the simulation

bool	_arealFSEnabled = false
	enabled/disabled state variable for areal focal spot

bool	_detSatEnabled = false
	enabled/disabled state variable for detector saturation

bool	_spectralEffEnabled = false
	enabled/disabled state variable for spectral effects

bool	_poissonEnabled = false
	enabled/disabled state variable for Poisson noise

Friends
template<class >
struct	SerializationHelper::RegisterWithSerializationHelper

Additional Inherited Members
Protected Member Functions inherited from CTL::SerializationInterface
	SerializationInterface ()=default

	SerializationInterface (const SerializationInterface &)=default

	SerializationInterface (SerializationInterface &&)=default

SerializationInterface &	operator= (const SerializationInterface &)=default

SerializationInterface &	operator= (SerializationInterface &&)=default

Related Functions inherited from CTL::AbstractProjector
	VolumeData
	Alias name for CTL::SpectralVolumeData. More...

std::unique_ptr< ProjectorType >	makeProjector (ConstructorArguments &&... arguments)

Detailed Description

The StandardPipeline class is a convenience class to work with a predefined processing pipeline for creation of projections.

This class provides a preset arrangement of projector and extensions in a meaningful composition. Individual simulation effects can be simply enabled/disabled using the corresponding methods (default setting in brackets) :

enableArealFocalSpot() - simulation of finite focal spot size [disabled]
enableDetectorSaturation() - simulation of over-/undersaturation effects [disabled]
enablePoissonNoise() - simulation of Poisson noise [enabled]
enableSpectralEffects() - full spectral simulation (energy dependent attenuation and response) [enabled]

Specific settings for all effects can be adjusted using the corresponding setter objects.

The StandardPipeline supports three different options with respect to degree of approximation used in the processing of individual effects:

ApproximationPolicy::No_Approximation
ApproximationPolicy::Default_Approximation
ApproximationPolicy::Full_Approximation

The Default_Approximation setting (default) uses the approximation of processing Poisson noise after the spectral effects. This leads to substantial acceleration with slight loss in accuracy. However, in case a spectral detector response is in use, the use of the Fast setting is strongly discouraged, because it then leads to incorrect results. In addition to the approximation described above, the Full_Approximation also uses the linearized setting for the ArealFocalSpotExtension. This uses sub-sample averaging in extinction domain and leads to further increases in computation speed, but yields inaccurate results in case of strong extinction gradients (e.g. edges) in the projection images. In the No_Approximation setting (most accurate), Poisson noise is processed for each individual energy bin requested by the spectral effects extension. While being most accurate, this option is substatially more time-consuming and not strongly required in many situations. The approximation behavior must be decided in the constructor and cannot be changed afterwards.

StandardPipeline uses OCL::RayCasterProjector as the actual forward projector. Its settings can be adjusted calling the corresponding member methods of settingsRayCaster().

A fully-enabled pipeline is composed as follows:

Volume Data <- OCL::RayCasterProjector <- ArealFocalSpotExtension <- SpectralEffectsExtension <- PoissonNoiseExtension <- DetectorSaturationExtension [Default_Approximation or Full_Approximation]
Volume Data <- OCL::RayCasterProjector <- ArealFocalSpotExtension <- PoissonNoiseExtension <- SpectralEffectsExtension <- DetectorSaturationExtension [No_Approximation]

The StandardPipeline object itself can be used in the same way as any projector; use configure() to pass the AcquisitionSetup for the simulation and then call project() (or projectComposite()) with the volume dataset that shall be projected to create the simulated projections using the full processing pipeline that is managed your StandardPipeline object.

The following code example demonstrates the usage of StandardPipeline for creating projections of a water ball phantom. In addition to its standard settings, we want to also enable the simulation of an areal focal spot (with default sampling of 3x3 sub-samples) and set the energy resolution for spectral effects to 5 keV (i.e. bin width).

// create a water ball
auto volume = SpectralVolumeData::ball(50.0f, 0.5f, 1.0f,
                                       database::attenuationModel(database::Composite::Water));
// create a C-arm CT system and a short scan protocol with 10 views
auto system = CTSystemBuilder::createFromBlueprint(blueprints::GenericCarmCT());
auto setup = AcquisitionSetup(system, 10);
setup.applyPreparationProtocol(protocols::ShortScanTrajectory(750.0));
// create the standard pipeline and adjust the desired settings (focal spot & energy resolution)
StandardPipeline pipe;
pipe.enableArealFocalSpot();
pipe.settingsSpectralEffects().setSamplingResolution(5.0f);
// pass the acquisition setup and run the simulation
pipe.configure(setup);
auto projections = pipe.project(volume);

Member Enumeration Documentation

◆ ApproximationPolicy

enum CTL::StandardPipeline::ApproximationPolicy

Enumeration for the approximation behavior in the standard pipeline. See Detailed Description for more details.

Enumerator
No_Approximation	Configuration with spectral effects simulation wrapping Poisson noise addition for each energy bin. Approximation-free but increased computation effort. Can be used in combination with a spectral detector response.
Default_Approximation	The default setting for the StandardPipeline. Configuration in which Poisson noise addition is applied to final result of the spectral effects simulation. Approximation with substantially increased computation speed. Not suited in combination with a spectral detector response.
Full_Approximation	Same configuration as in Default_Approximation setting. Additionally, a linearized approach is used in the ArealFocalSpotExtension (if enabled). Not suited in combination with a spectral detector response and inaccurate in case of high extinction gradients (e.g. edges of highly absorbing material) in the projection images.

Constructor & Destructor Documentation

◆ StandardPipeline()

CTL::StandardPipeline::StandardPipeline ( ApproximationPolicy policy = StandardPipeline::Default_Approximation )

explicit

Constructs a StandardPipeline object and with the ApproximationPolicy policy.

The default configuration enables spectral effects and Poisson noise simulation.

Member Function Documentation

◆ configure()

void CTL::StandardPipeline::configure ( const AcquisitionSetup & setup )

overridevirtual

Sets the acquisition setup for the simulation to setup.

Sets the acquisition setup for the simulation to setup. This needs to be done prior to calling project().

Implements CTL::AbstractProjector.

◆ enableArealFocalSpot()

void CTL::StandardPipeline::enableArealFocalSpot ( bool enable = true )

Enables/disables the simulation of areal focal spot effects, according to enable.

◆ enableDetectorSaturation()

void CTL::StandardPipeline::enableDetectorSaturation ( bool enable = true )

Enables/disables the simulation of detector saturation effects, according to enable.

This only has an effect on the simulation if the detector component of the system passed with the setup during configure() has a detector response model (see AbstractDetector::setSaturationModel()).

◆ enablePoissonNoise()

void CTL::StandardPipeline::enablePoissonNoise ( bool enable = true )

Enables/disables the simulation of Poisson noise, according to enable.

◆ enableSpectralEffects()

void CTL::StandardPipeline::enableSpectralEffects ( bool enable = true )

Enables/disables the simulation of spectral effects, according to enable.

Spectral effects require full spectral information (see SpectralVolumeData) in the volume data passed to project(). Otherwise, the spectral effects step will be skipped.

Spectral detector response effects will be considered if a corresponding response model has been set to the detector component (see AbstractDetector::setSpectralResponseModel()) of the system passed with the setup during configure(). Note that trying to simulate settings with a spectral response model in combination with volume data without full spectral information is not supported and leads to an exception.

◆ fromVariant()

void CTL::StandardPipeline::fromVariant ( const QVariant & variant )

overridevirtual

Sets the contents of the object based on the QVariant variant.

Implementation of the deserialization interface. This method uses setParameter() to deserialize class members.

Reimplemented from CTL::AbstractProjector.

◆ isLinear()

bool CTL::StandardPipeline::isLinear ( ) const

overridevirtual

Returns true if the application of the full processing pipeline is linear.

Reimplemented from CTL::AbstractProjector.

◆ notifier()

ProjectorNotifier * CTL::StandardPipeline::notifier ( )

overridevirtual

Returns a pointer to the notifier of the projector.

The notifier object can be used to emit the signal ProjectorNotifier::projectionFinished(int) when the calculation of the viewNb'th view has been done.

To receive emitted signals, use Qt's connect() method to connect the notifier object to any receiver object of choice. The notifier can also conveniently be connected to the MessageHandler of the CTL using connectToMessageHandler() or directly from the projector through AbstractProjector::connectNotifierToMessageHandler().

Example - sending simulation progress information to a QProgressBar:

AbstractProjector* myProjector /* = new ActualProjector */;
QProgressBar* myProgressBar = new QProgressBar();
// ... e.g. add the progress bar somewhere in your GUI
connect(myProjector->notifier(), SIGNAL(projectionFinished(int)),
        myProgressBar, SLOT(setValue(int)));

/// Example 2 - forwarding the information text to a QStatusBar

AbstractProjector* myProjector /* = new ActualProjector */;
QStatusBar* myStatusBar = new QStatusBar;
// ... e.g. add the status bar somewhere in your GUI (or take a pointer to an existing one)
QObject::connect(myProjector->notifier(), SIGNAL(information(QString)),
                 myStatusBar, SLOT(showMessage(QString)));

Reimplemented from CTL::AbstractProjector.

◆ posAFS()

uint CTL::StandardPipeline::posAFS ( ) const

private

Returns the position of the areal focal spot extension in the standard pipeline. This is defined to always be the first position (maximum efficiency).

◆ posDetSat()

uint CTL::StandardPipeline::posDetSat ( ) const

private

Returns the position of the detector saturation extension in the standard pipeline. This is defined to always be the last position, as it is only accurate in this spot.

◆ posPoisson()

uint CTL::StandardPipeline::posPoisson ( ) const

private

Returns the position of the Poisson noise extension in the standard pipeline. Depending on whether the mode has been set to StandardPipeline::No_Approximation or not (i.e. StandardPipeline::Full_Approximation or StandardPipeline::Default_Approximation), the Poisson extension is placed before or after the spectral effects extension, respectively.

◆ posSpectral()

uint CTL::StandardPipeline::posSpectral ( ) const

private

Returns the position of the spectral effects extension in the standard pipeline. Depending on whether the mode has been set to StandardPipeline::No_Approximation or not (i.e. StandardPipeline::Full_Approximation or StandardPipeline::Default_Approximation), the spectral effects extension is placed after or before the Poisson noise extension, respectively.

◆ project()

ProjectionData CTL::StandardPipeline::project ( const VolumeData & volume )

overridevirtual

Creates projection data from volume.

Creates projection data from volume using the current processing pipeline configuration of this instance. Uses the last acquisition setup set by configure().

Implements CTL::AbstractProjector.

◆ projectComposite()

ProjectionData CTL::StandardPipeline::projectComposite ( const CompositeVolume & volume )

overridevirtual

Creates projection data from the composite volume volume.

Creates projection data from the composite volume volume using the current processing pipeline configuration of this instance. Uses the last acquisition setup set by configure().

Reimplemented from CTL::AbstractProjector.

◆ projectSparse()

ProjectionData CTL::StandardPipeline::projectSparse ( const SparseVoxelVolume & volume )

overridevirtual

Creates projection data from the sparse volume volume.

Creates projection data from the sparse volume volume using the current processing pipeline configuration of this instance. Uses the last acquisition setup set by configure().

Reimplemented from CTL::AbstractProjector.

◆ settingsArealFocalSpot()

StandardPipeline::SettingsAFS & CTL::StandardPipeline::settingsArealFocalSpot ( )

Returns a handle to the settings for the areal focal spot simulation.

Areal focal spot settings are:

setDiscretization(const QSize& discretization): sets the number of sampling points for the subsampling of the areal focal spot to discretization (width x height) [ default value: {3, 3} ]
enableLowExtinctionApproximation(bool enable): sets the use of the linear approximation to enable. [ default: false (true for StandardPipeline::Full_Approximation) ]

Example:

StandardPipeline pipe;
pipe.enableArealFocalSpot();
pipe.settingsArealFocalSpot().setDiscretization( { 2, 2 } );

See also: ArealFocalSpotExtension::setDiscretization()

◆ settingsDetectorSaturation()

StandardPipeline::SettingsDetectorSaturation & CTL::StandardPipeline::settingsDetectorSaturation ( )

Returns a handle to the settings for the detector saturation simulation.

Detector saturation settings are:

setSpectralSamples(uint nbSamples): sets the number of energy bins used to sample the spectrum when processing intensity saturation to nbSamples [ default value: 0 (i.e. use sampling hint of source component) ]

Example:

StandardPipeline pipe;
pipe.enableDetectorSaturation();
pipe.settingsDetectorSaturation().setSpectralSamples(10);

See also: DetectorSaturationExtension::setIntensitySampling()

◆ settingsPoissonNoise()

StandardPipeline::SettingsPoissonNoise & CTL::StandardPipeline::settingsPoissonNoise ( )

Returns a handle to the settings for the Poisson noise simulation.

Poisson noise settings are:

setFixedSeed(uint seed): sets a fixed seed for the pseudo random number generation [ default value: not used]
setRandomSeedMode(): (re-)enables the random seed mode, any fixed seed set will be ignored until setFixedSeed() is called again [ default: random seed mode used ]
setParallelizationMode(bool enabled): sets the use of parallelization to enabled [ default value: true (i.e. parallelization enabled) ]

Example:

StandardPipeline pipe;
pipe.settingsPoissonNoise().setFixedSeed(1337);
pipe.settingsPoissonNoise().setParallelizationMode(false);

See also: PoissonNoiseExtension::setFixedSeed(), PoissonNoiseExtension::setRandomSeedMode(), PoissonNoiseExtension::setParallelizationEnabled()

◆ settingsRayCaster()

StandardPipeline::SettingsRayCaster & CTL::StandardPipeline::settingsRayCaster ( )

Returns a handle to the settings for the ray caster projector.

Ray caster settings are:

setInterpolation(bool enabled): sets the use of interpolation in the OpenCL kernel to enabled; disable interpolation when your OpenCL device does not have image support [ default value: true (i.e. interpolation enabled) ]
setRaysPerPixel(const QSize& sampling): sets the number of rays cast per pixel to sampling (width x height) [ default value: {1, 1} ]
setRaySampling(float sampling): sets the step length used to traverse the ray to sampling, which is defined as the fraction of the length of a voxel in its shortest dimension [ default value: 0.3 ]
setVolumeUpSampling(uint upSamplingFactor): sets the factor for upsampling of the input volume data to upSamplingFactor [ default value: 1 (i.e. no upsampling) ]

Example:

StandardPipeline pipe;
pipe.settingsRayCaster().setRaysPerPixel( { 2, 2 } );
pipe.settingsRayCaster().setVolumeUpSampling(2);

See also: OCL::RayCasterProjector::settings()

◆ settingsSpectralEffects()

StandardPipeline::SettingsSpectralEffects & CTL::StandardPipeline::settingsSpectralEffects ( )

Returns a handle to the settings for the spectral effects simulation.

Spectral effects settings are:

setSamplingResolution(float energyBinWidth): sets the energy bin width used to sample the spectrum to energyBinWidth (in keV) [ default value: 0 (i.e. resolution determined automatically based on sampling hint of source component) ]

Example:

StandardPipeline pipe;

pipe.settingsSpectralEffects().setSamplingResolution(5.0f);

See also: SpectralEffectsExtension::setSpectralSamplingResolution()

◆ toVariant()

QVariant CTL::StandardPipeline::toVariant ( ) const

overridevirtual

Stores the contents of this instance in a QVariant.

Implementation of the serialization interface. Stores the object's type-id (from SerializationInterface::toVariant()).

This method uses parameter() to serialize class members.

Reimplemented from CTL::AbstractProjector.

◆ type()

int CTL::StandardPipeline::type ( ) const

inlineoverridevirtual

Returns the type-id of the serializable object. Used in deserialization to determine the proper object type.

Add derived classes to the enumeration using the CTL_TYPE_ID macro.

Reimplemented from CTL::AbstractProjector.

The documentation for this class was generated from the following files:

modules/src/projectors/standardpipeline.h
modules/src/projectors/standardpipeline.cpp

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ApproximationPolicy

Constructor & Destructor Documentation

◆ StandardPipeline()

Member Function Documentation

◆ configure()

◆ enableArealFocalSpot()

◆ enableDetectorSaturation()

◆ enablePoissonNoise()

◆ enableSpectralEffects()

◆ fromVariant()

◆ isLinear()

◆ notifier()

◆ posAFS()

◆ posDetSat()

◆ posPoisson()

◆ posSpectral()

◆ project()

◆ projectComposite()

◆ projectSparse()

◆ settingsArealFocalSpot()

◆ settingsDetectorSaturation()

◆ settingsPoissonNoise()

◆ settingsRayCaster()

◆ settingsSpectralEffects()

◆ toVariant()

◆ type()