The AbstractSubsetGenerator class is the abstract base class for subset generators. More...
#include <abstractsubsetgenerator.h>
Public Types | |
| enum | { Type = 1000 } |
 Public Types inherited from CTL::SerializationInterface | |
| enum | { Type = -1, UserType = 65536 } |
Public Member Functions | |
| int | type () const override |
| void | fromVariant (const QVariant &variant) override |
| QVariant | toVariant () const override |
| virtual void | setSetup (const AcquisitionSetup &) |
| Sets the AcquisitionSetup that belongs to the projection data to setup. More... | |
| virtual void | setProjections (ProjectionDataView projections) |
| Sets the projections that this instance shall operate on to projections. More... | |
| void | setData (ProjectionDataView projections, const AcquisitionSetup &setup) |
| Sets the projections to projections and the corresponding acquisition setup to setup. More... | |
| std::vector< ProjectionDataView > | generateSubsets (uint iteration) const |
| Generates the subsets for iteration iteration. More... | |
| virtual std::vector< std::vector< ProjectionDataView > > | generateAllSubsets (uint nbIterations) |
| Convenience method to generate subsets for a certain number of iterations. More... | |
| bool | isSubsetPermutationEnabled () const |
Returns true if subset permutation is enabled; false otherwise. | |
| const ProjectionDataView & | projections () const |
| Returns the ProjectionDataView that has been set via setProjections(). | |
| uint | randomGeneratorSeed () const |
| Returns the seed that has been used to seed the RNG of this instance. More... | |
| void | setRandomGeneratorSeed (uint seed=std::random_device{}()) |
| Sets the seed of the RNG to seed and actually seeds the RNG. | |
| void | setSubsetPermutationEnabled (bool enabled) |
| Sets the use of subset permutation to enabled. More... | |
| Public Member Functions inherited from CTL::SerializationInterface | |
| virtual | ~SerializationInterface ()=default |
Protected Member Functions | |
| virtual std::vector< ProjectionDataView > | generateSubsetsImpl (uint iteration) const =0 |
| Implementation of the generation algorithm for subsets in the iteration -th iteration. More... | |
| AbstractSubsetGenerator () | |
| Constructs an AbstractSubsetGenerator. More... | |
| AbstractSubsetGenerator (const AbstractSubsetGenerator &)=default | |
| AbstractSubsetGenerator (AbstractSubsetGenerator &&)=default | |
| AbstractSubsetGenerator & | operator= (const AbstractSubsetGenerator &)=default |
| AbstractSubsetGenerator & | operator= (AbstractSubsetGenerator &&)=default |
| virtual void | shuffleSubsets (std::vector< ProjectionDataView > &subsets) const |
| Randomly permutes the order of the subsets in subsets. More... | |
| 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 |
Protected Attributes | |
| ProjectionDataView | _fullProjections = ProjectionDataView::invalidView() |
| The projection data view this instance operates on. | |
| std::mt19937 | _rng |
| random number generator (RNG) instance | |
| uint | _rngSeed = 42 |
| value used to seed the RNG | |
| bool | _permuteSubsets = true |
| state variable if subset permutation is enabled | |
Friends | |
| template<class > | |
| struct | SerializationHelper::RegisterWithSerializationHelper |
Detailed Description
The AbstractSubsetGenerator class is the abstract base class for subset generators.
This class provides the interface for subset generator implementations. The public interface provides the options to generate the subsets for a particular iteration through generateSubsets() and generation of the entirety of all subsets for a given number of iterations (see generateAllSubsets()). Before subsets can be generated, projections must be set by passing a view to the data (see ProjectionDataView) through setProjections(). Depending on the specific algorithm, sub-classes may also require the acquisition setup that corresponds to the projection data. This can be passed to setSetup(). For convenience, setData() can be used as a simultaneous setter for both projection data and setup.
By default, the list of generated subsets will be shuffled - i.e. the order of subsets will be permuted randomly before they are returned; uses the std::mt19937 RNG engine for that purpose. The permutation procedure can be configured through:
- setSubsetPermutationEnabled() - enable/disable subset permutation
- setRandomGeneratorSeed() - set a seed for the RNG used to perform the permutation
- isSubsetPermutationEnabled() - query if subset permutation is enabled/disabled
- randomGeneratorSeed() - returns the current RNG seed (default is 42)
If necessary, the current ProjectionDataView can be queried through projections().
Sub-classing: Sub-classes need to implement generateSubsetsImpl(), which is the routine to generate the subsets for a particular iteration. Depending on the specific subset generation algorithm, it might be required to have access to information about the acquisition. If required, re-implement setSetup() and extract all relevant data (or copy the passed setup). This class already provides a random number generator (std::mt19937); i.e., if random number generation becomes necessary in sub-classes, it is strongly advised to use this class' RNG to allow end-users to provide a global seed for all RNG processes through the base-class interface (see setRandomGeneratorSeed()). Here, the RNG is used to permute the order of subsets after generation. It might be necessary to change this behavior in sub-classes; for example to avoid multiple shuffle steps. Re-implement shuffleSubsets() to change the shuffling procedure in sub-classes.
To enable de-/serialization of objects of the new sub-class, reimplement the toVariant() and fromVariant() methods. These should take care of all newly introduced information of the sub-class. Additionally, call the macro DECLARE_SERIALIZABLE_TYPE(YourNewClassName) within the .cpp file of your new class (substitute "YourNewClassName" with the actual class name). Objects of the new class can then be de-/serialized with any of the serializer classes (see also AbstractSerializer). Remember to also register the new component in the enumeration using the CTL_TYPE_ID(newIndex) macro. Subset generators use the miscellaneous object category in the index range from 1000 to 1999. It is required to specify a value for newIndex that is not already in use.
Constructor & Destructor Documentation
◆ AbstractSubsetGenerator()
|
protected |
Constructs an AbstractSubsetGenerator.
This ctor is protected. Seeds the RNG with the default seed (i.e. 42).
Member Function Documentation
◆ fromVariant()
|
overridevirtual |
Interface to read all member variables from the QVariant variant.
Reimplement this method such that it reads all newly introduced content when sub-classing. A typical reimplementation in sub-classes might look like this:
Reimplemented from CTL::SerializationInterface.
Reimplemented in CTL::AbstractFixedSizeSubsetGenerator, CTL::TransitionSchemeExtension, and CTL::SimpleSubsetGenerator.
◆ generateAllSubsets()
|
virtual |
Convenience method to generate subsets for a certain number of iterations.
This is a convenience wrapper method that executes generateSubsets() for all iteration numbers from zero to nbIterations-1 and appends the resulting subsets to a std::vector.
This is a virtual method and as such, it can be re-implemented in sub-classes if a more appropriate (or more efficient) way of generating multiple sets of subsets is available. However, it is strongly recommended, not to change the general behavior of the method, i.e. the elements of the returned vector should always contain the subsets of the corresponding iteration as if they would have been created from an isolated call to generateSubsets() with the particular iteration number.
◆ generateSubsets()
| std::vector< ProjectionDataView > CTL::AbstractSubsetGenerator::generateSubsets | ( | uint | iteration | ) | const |
Generates the subsets for iteration iteration.
This calls generateSubsetsImpl() with the passed iteration and executes shuffleSubsets() on the generated subsets if isSubsetPermutationEnabled() == true. In its default implementation, this randomly permutes the order of the subsets.
Note that data must have been set earlier. This refers to a ProjectionDataView to operate on (see setProjections()) and potentially - if required by the specific sub-class - a corresponding AcquisitionSetup (see setSetup()).
◆ generateSubsetsImpl()
|
protectedpure virtual |
Implementation of the generation algorithm for subsets in the iteration -th iteration.
This (pure virtual) method must be implemented in sub-classes to generate the subsets that shall be used in iteration number iteration. The specific algorithm may also be independent of the actual iteration number.
The returned std::vector<ProjectionDataView> must contain one ProjectionDataView for each subset, where each ProjectionDataView element must contain the ids of the projections that have been selected for that particular subset. Note that random permutation of the subsets does not need to be done in this implementation, as it is provided by shuffleSubsets().
This method relies on data previously set through setProjections(), so consider adding a check whether or not appropriate data is available. In case that your subset generation routine also requires information about the acquisition - and thus, setSetup() must have been called with appropriate data earlier - you should consider checking for consistency (i.e. between setup and projcetions) here as well.
Implemented in CTL::TransitionSchemeExtension, CTL::OrthogonalSubsetGenerator, and CTL::SimpleSubsetGenerator.
◆ randomGeneratorSeed()
| uint CTL::AbstractSubsetGenerator::randomGeneratorSeed | ( | ) | const |
Returns the seed that has been used to seed the RNG of this instance.
Note that this only returns the original seed. The internal state of the RNG might be different from the point it was seeded. For that reason, the full state of the RNG will be serialized in toVariant() for the purpose of later restoration (i.e. deserialization).
◆ setData()
| void CTL::AbstractSubsetGenerator::setData | ( | ProjectionDataView | projections, |
| const AcquisitionSetup & | setup | ||
| ) |
Sets the projections to projections and the corresponding acquisition setup to setup.
This is a convenience method that combines the calls to setProjections() and setSetup() into a single call. Pay attention that both passed parameter need to be correctly related to each other, i.e. setup must be the AcquisitionSetup that describes the acquisition of the projection data that projections contains.
Please note that setup must always represent the full ProjectionData that is managed by projections. That means if projections is already a subset, the setup passed here must still refer to the full ProjectionData the view belongs to.
- See also
- setProjections(), setSetup().
◆ setProjections()
|
virtual |
Sets the projections that this instance shall operate on to projections.
This takes a ProjectionDataView to efficiently create subsets without overhead of data copies. Note that the underlying ProjectionData (i.e. the ones the view refers to) must remain valid throughout the entire use time of this instance. That means that all subsets created by this instance (w.r.t. the data from projections) are valid only as long as the ProjectionData projections refers to is valid.
Reimplemented in CTL::TransitionSchemeExtension.
◆ setSetup()
|
inlinevirtual |
Sets the AcquisitionSetup that belongs to the projection data to setup.
setup must be the AcquisitionSetup that describes the acquisition of the projection data passed to setProjections(). Please note that setup must always represent the full ProjectionData that is managed by the view passed to setProjections(). That means if the ProjectionDataView passed to setProjections() is already a subset, the setup passed here must still refer to the full ProjectionData the view belongs to.
Reimplemented in CTL::TransitionSchemeExtension, and CTL::OrthogonalSubsetGenerator.
◆ setSubsetPermutationEnabled()
| void CTL::AbstractSubsetGenerator::setSubsetPermutationEnabled | ( | bool | enabled | ) |
Sets the use of subset permutation to enabled.
This enables/disables subset permutation. To be more precise, if enabled=true, the method shuffleSubsets() will be applied to the generated subset when generateSubsets() is called. In its default implementation, shuffleSubsets() randomly permutes the order of the subsets.
◆ shuffleSubsets()
|
protectedvirtual |
Randomly permutes the order of the subsets in subsets.
This permutes the order in which subsets appear in subsets. Uses std::shuffle in combination with the RNG member of this class.
Shuffling subset order may be beneficial in iterative reconstructions to avoid image artifacts as a result of (overly) structured update schemes.
Reimplemented in CTL::TransitionSchemeExtension.
◆ toVariant()
|
overridevirtual |
Interface to store all member variables in a QVariant.
Stores the object's type-id.
Reimplement this method such that it stores all newly introduced object data when sub-classing. This needs to cover everything that is necessary to fully determine the state of an object. Best practice is to invoke the base class version of this method to take care of all content originating from underlying base classes.
A typical reimplementation in sub-classes might look like this:
Reimplemented from CTL::SerializationInterface.
Reimplemented in CTL::AbstractFixedSizeSubsetGenerator, CTL::TransitionSchemeExtension, and CTL::SimpleSubsetGenerator.
◆ type()
|
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::SerializationInterface.
Reimplemented in CTL::DefaultSubsetGenerator, CTL::AbstractFixedSizeSubsetGenerator, CTL::TransitionSchemeExtension, CTL::OrthogonalSubsetGenerator, and CTL::SimpleSubsetGenerator.
The documentation for this class was generated from the following files:
- modules/src/recon/abstractsubsetgenerator.h
- modules/src/recon/abstractsubsetgenerator.cpp
