IDetector.h

Go to the documentation of this file.

//  ************************************************************************************************
//
//  BornAgain: simulate and fit reflection and scattering
//
//! @file      Device/Detector/IDetector.h
//! @brief     Defines common detector interface.
//!
//! @homepage  http://www.bornagainproject.org
//! @license   GNU General Public License v3 or higher (see COPYING)
//! @copyright Forschungszentrum Jülich GmbH 2018
//! @authors   Scientific Computing Group at MLZ (see CITATION, AUTHORS)
//
//  ************************************************************************************************
 
#ifndef BORNAGAIN_DEVICE_DETECTOR_IDETECTOR_H
#define BORNAGAIN_DEVICE_DETECTOR_IDETECTOR_H
 
#include "Base/Types/ICloneable.h"
#include "Base/Types/OwningVector.h"
#include "Device/Coord/Tags.h" // enum Coords
#include "Device/Detector/SimulationAreaIterator.h"
#include "Device/Pol/PolFilter.h"
#include <functional>
 
class Beam;
class CoordSystem2D;
class DetectorContext;
class DetectorMask;
class DiffuseElement;
class Direction;
class IAxis;
class ICoordSystem;
class IDetectorResolution;
class IPixel;
class IResolutionFunction2D;
class IShape2D;
 
class Datafield;
 
//! Abstract detector interface.
//!
//! Handles also "region of interest" (ROI). In general, the ROI is the whole
//! detector, and all methods related to ROI work on the whole detector.
//! If a ROI different to the detector size is explicitly set, then ROI-related
//! methods work on this reduced ROI.
//! Therefore, when calling ROI related methods, the distinction between "explicit
//! ROI exists: yes/no" does not have to be made by the caller, but it is handled in here.
//! For access to the whole detector, even if a smaller ROI is explicitly defined, use the
//! non-ROI-related methods like totalSize() or axes().
//! Any method which is not speaking of "explicit ROI" handles the "implicit ROI", i.e. uses
//! an explicitly set ROI or the whole detector if no explicit ROI exists.
//! To access the explicitly set ROI, use the methods which have the explicit in its
//! name, like sizeOfExplicitRegionOfInterest().
//!
//! @ingroup detector
 
class IDetector : public ICloneable, public INode {
public:
    using const_iterator = const SimulationAreaIterator&;
    IDetector();
 
    IDetector* clone() const override = 0;
 
    ~IDetector() override;
 
    //! Inits detector with the beam settings
    virtual void setDetectorNormal(const Direction&) {} // nontrivial only for RectangularDetector
 
    void addDetAxis(const IAxis& axis);
 
    //! Sets the polarization analyzer characteristics of the detector
    void setAnalyzer(R3 direction, double efficiency, double total_transmission);
    //! Sets the detector resolution
    void setDetectorResolution(const IDetectorResolution& p_detector_resolution);
    void setResolutionFunction(const IResolutionFunction2D& resFunc);
 
    //! Resets region of interest making whole detector plane available for the simulation.
    void resetRegionOfInterest();
 
    std::vector<const INode*> nodeChildren() const override;
 
    //! Iterate over all points within "region of interest", no matter whether they are masked or
    //! not. If no region of interest is explicitly defined, then the whole detector is taken as
    //! "region of interest".
    void iterateOverRegionOfInterest(std::function<void(const_iterator)> func) const;
 
    //! Iterate over all non-masked points within "region of interest".
    //! If no region of interest is explicitly defined, then the whole detector is taken as
    //! "region of interest".
    void iterateOverNonMaskedPoints(std::function<void(const_iterator)> func) const;
 
    //! Sets equidistant axes
    void setDetectorParameters(size_t n_x, double x_min, double x_max, size_t n_y, double y_min,
                               double y_max);
 
    const DetectorMask* detectorMask() const;
 
    //! Adds mask of given shape to the stack of detector masks. The mask value 'true' means
    //! that the channel will be excluded from the simulation. The mask which is added last
    //! has priority.
    //! @param shape The shape of mask (Rectangle, Polygon, Line, Ellipse)
    //! @param mask_value The value of mask
    void addMask(const IShape2D& shape, bool mask_value = true);
 
    //! Put the mask for all detector channels (i.e. exclude whole detector from the analysis)
    void maskAll();
 
    //! Sets rectangular region of interest with lower left and upper right corners defined.
    void setRegionOfInterest(double xlow, double ylow, double xup, double yup);
 
    virtual ICoordSystem* offspecCoords(IAxis* beamAxis, const Direction& beamDirection) const = 0;
    virtual CoordSystem2D* scatteringCoords(const Beam& beam) const = 0;
 
    //! Returns vector of unmasked detector indices.
    std::vector<size_t> active_indices() const;
 
    //! Creates an IPixel for the given Datafield object and index
    virtual IPixel* createPixel(size_t index) const = 0;
 
    //! Returns index of pixel that contains the specular wavevector.
    //! If no pixel contains this specular wavevector, the number of pixels is
    //! returned. This corresponds to an overflow index.
    virtual size_t indexOfSpecular(const Beam& beam) const = 0;
 
    //! One axis of the complete detector.
    //! Any region of interest is not taken into account.
    const IAxis& axis(size_t index) const;
 
    //! Returns number of defined axes
    size_t rank() const;
 
    //! Calculate axis index for given global index
    size_t axisBinIndex(size_t index, size_t selected_axis) const;
 
    //! Returns total number of pixels.
    //! Any region of interest is not taken into account.
    size_t totalSize() const;
 
    //! The size of the "Region of Interest". Same as totalSize()
    //! if no region of interest has been explicitly set.
    size_t sizeOfRegionOfInterest() const;
 
    //! True if a region of interest is explicitly set.
    bool hasExplicitRegionOfInterest() const;
 
    //! Returns the axes clipped to the region of interest. If no region of interest is explicitly
    //! defined, then the whole detector is taken as "region of interest".
    OwningVector<IAxis> axesClippedToRegionOfInterest() const;
 
    //! Convert an index of the region of interest to an index of the detector.
    //! If no region of interest is set, then the index stays unmodified (since ROI == detector
    //! area).
    size_t regionOfInterestIndexToDetectorIndex(size_t regionOfInterestIndex) const;
    size_t detectorIndexToRegionOfInterestIndex(size_t detectorIndex) const;
 
    //! Applies the detector resolution to the given intensity maps
    void applyDetectorResolution(Datafield* p_intensity_map) const;
 
    //! Returns a pointer to detector resolution object
    const IDetectorResolution* detectorResolution() const;
 
    //! Returns new intensity map with resolution applied, and cropped to ROI if applicable.
    Datafield*
    createDetectorIntensity(const std::vector<std::unique_ptr<DiffuseElement>>& elements) const;
 
    //! Return default axes units
    virtual Coords defaultCoords() const = 0;
 
    //! Returns number of simulation elements.
    size_t numberOfElements() const;
 
    //! The lower and upper bound of the region of interest. If no region of interest is explicitly
    //! defined, then the whole detector is taken as "region of interest".
    std::pair<double, double> regionOfInterestBounds(size_t iAxis) const;
 
#ifndef SWIG
    std::unique_ptr<DetectorContext> createContext() const;
 
    //! Create begin-iterator to iterate over all points which are not masked and lay
    //! within the "Region of Interest"
    SimulationAreaIterator beginNonMaskedPoints() const;
 
    //! Create end-iterator to iterate over all points which are not masked and lay
    //! within the "Region of Interest"
    SimulationAreaIterator endNonMaskedPoints() const;
 
    //! Create begin-iterator to iterate over all points which lay
    //! within the "Region of Interest". If no region of interest is explicitly
    //! defined, then the whole detector is taken as "region of interest".
    //! No matter whether masked or not.
    SimulationAreaIterator beginRegionOfInterestPoints() const;
 
    //! Create end-iterator to iterate over all points which lay
    //! within the "Region of Interest". If no region of interest is explicitly
    //! defined, then the whole detector is taken as "region of interest".
    //! No matter whether masked or not.
    SimulationAreaIterator endRegionOfInterestPoints() const;
 
    //! Returns empty detector map in given axes units.
    //! This map is a data array limited to the size of the "Region of interest"
    std::unique_ptr<Datafield> createDetectorMap() const;
 
    //! Returns detection properties
    const PolFilter& analyzer() const { return m_polAnalyzer; }
#endif // SWIG
 
protected:
    IDetector(const IDetector& other);
 
    void clear();
 
    //! Returns the name for the axis with given index
    virtual std::string axisName(size_t index) const = 0;
 
    //! Return 0 if no ROI has been explicitly set.
    //! Size means number of data points.
    virtual size_t sizeOfExplicitRegionOfInterest() const;
 
    //! Lower and upper bound of one axis of an explicitly set ROI.
    //! Return 0/0 if no ROI has been explicitly set.
    virtual std::pair<double, double> boundsOfExplicitRegionOfInterest(size_t iAxis) const;
 
    //! Calculate global index from two axis indices
    size_t getGlobalIndex(size_t x, size_t y) const;
 
#ifndef SWIG
    //! Keeps RegionOfInterest (ROI) data of one axis
    struct RoiOfAxis {
        double lower;
        double upper;
 
        // The following values are all pre-computed values. Aim is to speed up repeated
        // calculations.
        size_t lowerIndex;   //!< index corresponding to 'lower'
        size_t upperIndex;   //!< index corresponding to 'upper'
        size_t roiSize;      //!< number of bins on axis of ROI
        size_t detectorSize; //!< number of bins on axis of detector
 
        RoiOfAxis(const IAxis& axis, double lower, double upper);
    };
 
    std::vector<RoiOfAxis> m_explicitROI; //!< an explicitly defined region of interest.
                                          //!< Empty if no ROI has been defined.
                                          //!< Vector index corresponds to axis index in m_axes
 
 
private:
    OwningVector<IAxis> m_axes;
    PolFilter m_polAnalyzer;
    std::unique_ptr<IDetectorResolution> m_detector_resolution;
    std::shared_ptr<DetectorMask> m_detector_mask;
#endif // SWIG
};
 
#endif // BORNAGAIN_DEVICE_DETECTOR_IDETECTOR_H