The PoissonNoiseExtension class is an extension for forward projectors that adds Poisson-distributed noise to the projection data. More...

#include <poissonnoiseextension.h>

Inheritance diagram for CTL::PoissonNoiseExtension:

[legend]

Collaboration diagram for CTL::PoissonNoiseExtension:

[legend]

Public Types
enum	{ Type = 103 }

Public Types inherited from CTL::ProjectorExtension
enum	{ Type = 100 }

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

void	configure (const AcquisitionSetup &setup) override
	Configures the projector. More...

	PoissonNoiseExtension (uint fixedSeed, bool useParalellization=true)

bool	isLinear () const override

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

QVariant	parameter () const override

void	setParameter (const QVariant &parameter) override
	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	setFixedSeed (uint seed)

void	setRandomSeedMode ()

void	setParallelizationEnabled (bool enabled)

	ProjectorExtension (AbstractProjector *projector=nullptr)

	ProjectorExtension (std::unique_ptr< AbstractProjector > projector)

Public Member Functions inherited from CTL::ProjectorExtension
int	type () const override

void	configure (const AcquisitionSetup &setup) override

ProjectionData	project (const VolumeData &volume) override

	ProjectorExtension (AbstractProjector *projector=nullptr)

	ProjectorExtension (std::unique_ptr< AbstractProjector > projector)

ProjectionData	projectComposite (const CompositeVolume &volume) override
	Provides the functionality to forward project CompositeVolume data. More...

ProjectionData	projectSparse (const SparseVoxelVolume &volume) override
	Provides the functionality to forward project SparseVoxelVolume data. More...

bool	isLinear () const override
	Returns true if the projection operation is linear. More...

virtual void	use (AbstractProjector *other)

void	use (std::unique_ptr< AbstractProjector > other)

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...

AbstractProjector *	release ()

void	reset ()

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 ProjectorNotifier *	notifier ()
	Returns a pointer to the notifier of the projector. 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

Protected Member Functions
ProjectionData	extendedProject (const MetaProjector &nestedProjector) override

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

Static Private Member Functions
static void	processViewCompact (SingleViewData &view, const std::vector< float > &i_0, uint seed)

Private Attributes
std::mt19937	_rng

AcquisitionSetup	_setup
	A copy of the setup used for acquisition.

bool	_useParallelization { true }

bool	_useFixedSeed { false }

uint	_seed { 0u }

Friends
template<class >
struct	SerializationHelper::RegisterWithSerializationHelper

Additional Inherited Members
Related Functions inherited from CTL::ProjectorExtension
std::unique_ptr< ProjectorExtensionType >	makeExtension (AbstractProjector *projector=nullptr)

std::unique_ptr< ProjectorExtensionType >	makeExtension (std::unique_ptr< AbstractProjector > projector)

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

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

Detailed Description

The PoissonNoiseExtension class is an extension for forward projectors that adds Poisson-distributed noise to the projection data.

This extension performs a postprocessing on the projection data to add Poisson-distributed noise to the projections. For counts larger than 1.0e4. the Poisson distribution is approximated by a normal distribution.

Poisson-distributed random numbers are generated using the Mersenne twister engine (std::mt19937). A fixed seed can be used to create reproducible results (see setFixedSeed()).

The following code example shows how to extend a simple ray caster algorithm to add Poisson noise to the simulated projections:

// define volume and acquisition setup (incl. system)
auto volume = VolumeData::cube(100, 1.0f, 0.02f);
auto system = SimpleCTSystem::fromCTSystem(CTSystemBuilder::createFromBlueprint(blueprints::GenericCarmCT(DetectorBinning::Binning4x4)));
// reduce default radiation output of the source component (-> make noise more prominent)
static_cast<XrayTube*>(system.source())->setMilliampereSeconds(0.001);
AcquisitionSetup acquisitionSetup(system, 10);
acquisitionSetup.applyPreparationProtocol(protocols::ShortScanTrajectory(750.0));
// Core part
auto simpleProjector = new RayCasterProjector; // our simple projector
    // optional parameter settings for the projector
    // e.g. simpleProjector->settings().raySampling = 0.1f;
// this is what you do without extension (i.e. noise-free):
    // simpleProjector->configure(acquisitionSetup);
    // ProjectionData projections = simpleProjector->project(volume);
// instead we now do the following
PoissonNoiseExtension* extension = new PoissonNoiseExtension;
extension->use(simpleProjector);                            // tell the extension to use the ray caster
extension->setFixedSeed(42);                                // setting a fixed seed for random number generation
extension->configure(acquisitionSetup);                     // configure the simulation
ProjectionData projections = extension->project(volume);    // (compute and) get the final (noisy) projections
// visualization (optional, requires 'ctl_qtgui' submodule):
    // gui::ProjectionViewer::plot(projections);

The difference between the projections with and without noise in the example above is shown here:

Simulated projections of a homogeneous water cube without (left) and with Poisson noise (right).

Constructor & Destructor Documentation

◆ PoissonNoiseExtension()

CTL::PoissonNoiseExtension::PoissonNoiseExtension	(	uint	fixedSeed,
		bool	useParalellization = `true`
	)

explicit

Constructs a PoissonNoiseExtension and sets the fixed seed for the random number generator to fixedSeed.

To use PoissonNoiseExtension without fixed seed, use the default constructor instead or reactivate random seeding after construction with setRandomSeedMode().

Optionally, parallelization can be deactivated when passing useParalellization = false.

Member Function Documentation

◆ configure()

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

overridevirtual

Configures the projector.

This method should be used to gather all necessary information to prepare the actual forward projection. This usually contains all geometry and system information, which can be retrieved from setup.

If you intend to call configure() and project() (or projectComposite()) directly after each other, you should use configureAndProject() instead.

Implements CTL::AbstractProjector.

◆ extendedProject()

ProjectionData CTL::PoissonNoiseExtension::extendedProject ( const MetaProjector & nestedProjector )

overrideprotectedvirtual

This protected virtual method can be overridden in a subclass in order to implement a custom ProjectorExtension. An implementation of extendedProject is convenient, because an implementation of the two functions project and projectComposite can be avoided. However, this strategy enables only ProjectorExtensions that perform post-processing of the ProjectionData from the nested projector and/or a modification of the AcquisitionSetup (by calling ProjectorExtension::configure), but no change of the VolumeData.

You can simply obtain the ProjectionData from the nestedProjector via the call nestedProjector.project(), no matter if the client called project or projectComposite. Subsequent processing can be implemented before the data will be returned.

Reimplemented from CTL::ProjectorExtension.

◆ isLinear()

bool CTL::PoissonNoiseExtension::isLinear ( ) const

overridevirtual

Returns false, because addition of Poisson noise is non-linear (it operates on the count domain, which involves exponentiation of the extinction values).

Reimplemented from CTL::AbstractProjector.

◆ parameter()

QVariant CTL::PoissonNoiseExtension::parameter ( ) const

overridevirtual

Returns the parameters of this instance as QVariant.

This returns a QVariantMap with three key-value-pairs:

("Use fixed seed", _useFixedSeed), storing whether fixed seed mode is used or not.
("Use parallelization", _useParallelization), storing whether parallelization is used or not.
("Seed", _seed), storing the seed used for the RNG.

This method is used within toVariant() to serialize the object's settings.

Reimplemented from CTL::AbstractProjector.

◆ processViewCompact()

void CTL::PoissonNoiseExtension::processViewCompact	(	SingleViewData &	view,
		const std::vector< float > &	i_0,
		uint	seed
	)

staticprivate

The actual processing of projection data from a single view view (ie. with all its detector modules).

Transforms data into count domain based on initial counts passed by i_0.

This method approximates the Poisson distribution by a normal distribution for counts larger than 1.0e4.

◆ ProjectorExtension() [1/2]

CTL::ProjectorExtension::ProjectorExtension

explicit

Constructs a ProjectorExtension object and sets the nested projector to projector. A good practice to create a ProjectorExtension on the heap is to use the make function makeExtension(std::unique_ptr<AbstractProjector> projector) which will interally use this constructor.

◆ ProjectorExtension() [2/2]

CTL::ProjectorExtension::ProjectorExtension

explicit

Constructs a ProjectorExtension object and sets the nested projector to projector. The nested projector is internally used as a basis for computing forward projections. Note that the constructed object takes over the ownership of projector.

◆ setFixedSeed()

void CTL::PoissonNoiseExtension::setFixedSeed ( uint seed )

Activates the fixed seed mode and sets the fixed seed to seed.

To reactivate random seeding, use setRandomSeedMode().

◆ setParallelizationEnabled()

void CTL::PoissonNoiseExtension::setParallelizationEnabled ( bool enabled )

Sets the use of parallelization for the processing of multiple projections to enabled.

◆ setParameter()

void CTL::PoissonNoiseExtension::setParameter ( const QVariant & parameter )

overridevirtual

Sets the parameters of this instance based on the passed QVariant parameter. Parameters need to follow the naming convention as described in parameter().

This method is used within fromVariant() to deserialize the object's settings. Direct use of this method is discouraged; consider using dedicated setter methods instead.

Reimplemented from CTL::AbstractProjector.

◆ setRandomSeedMode()

void CTL::PoissonNoiseExtension::setRandomSeedMode ( )

Reactivates random seeding for the random number generator.

Has no effect if fixed seeding has not been enabled before.

◆ toVariant()

QVariant CTL::PoissonNoiseExtension::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::PoissonNoiseExtension::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/poissonnoiseextension.h
modules/src/projectors/poissonnoiseextension.cpp

Public Types

Public Member Functions

Protected Member Functions

Static Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PoissonNoiseExtension()

Member Function Documentation

◆ configure()

◆ extendedProject()

◆ isLinear()

◆ parameter()

◆ processViewCompact()

◆ ProjectorExtension() [1/2]

◆ ProjectorExtension() [2/2]

◆ setFixedSeed()

◆ setParallelizationEnabled()

◆ setParameter()

◆ setRandomSeedMode()

◆ toVariant()

◆ type()