Detector.h

Go to the documentation of this file.

// -*- lsst-c++ -*-
/*
 * Developed for the LSST Data Management System.
 * This product includes software developed by the LSST Project
 * (https://www.lsst.org).
 * See the COPYRIGHT file at the top-level directory of this distribution
 * for details of code ownership.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

#if !defined(LSST_AFW_CAMERAGEOM_DETECTOR_H)
#define LSST_AFW_CAMERAGEOM_DETECTOR_H

#include <string>
#include <vector>
#include <unordered_map>
#include "lsst/base.h"
#include "lsst/afw/geom/Transform.h"
#include "lsst/afw/cameraGeom/Amplifier.h"
#include "lsst/afw/cameraGeom/CameraSys.h"
#include "lsst/afw/cameraGeom/Orientation.h"
#include "lsst/afw/cameraGeom/TransformMap.h"
#include "lsst/afw/typehandling/Storable.h"

namespace lsst {
namespace afw {
namespace cameraGeom {

enum class DetectorType {
    SCIENCE,
    FOCUS,
    GUIDER,
    WAVEFRONT,
};


class DetectorBase {
public:

    using CrosstalkMatrix = ndarray::Array<float const, 2>;

    virtual ~DetectorBase() noexcept = default;

    std::string getName() const { return getFields().name; }

    int getId() const { return getFields().id; }

    DetectorType getType() const { return getFields().type; }

    std::string getSerial() const { return getFields().serial; }

    std::string getPhysicalType() const { return getFields().physicalType; }

    lsst::geom::Box2I getBBox() const { return getFields().bbox; }

    Orientation getOrientation() const { return getFields().orientation; }

    lsst::geom::Extent2D getPixelSize() const { return getFields().pixelSize; }

    bool hasCrosstalk() const {
        return !(getFields().crosstalk.isEmpty() ||
                 getFields().crosstalk.getShape() == ndarray::makeVector(0, 0));
    }

    CrosstalkMatrix getCrosstalk() const { return getFields().crosstalk; }

    CameraSys makeCameraSys(CameraSys const &cameraSys) const { return cameraSys; }

    CameraSys makeCameraSys(CameraSysPrefix const &cameraSysPrefix) const {
        return CameraSys(cameraSysPrefix, getFields().name);
    }

    CameraSys getNativeCoordSys() const { return CameraSys(PIXELS, getName()); }

protected:

    // Simple struct containing all simple fields (everything not related
    // to coordinate systems/transforms or associated with an Amplifier).
    // See docs for corresponding getters (each field has one) for
    // descriptions.
    struct Fields {
        std::string name = "";
        int id = 0;
        DetectorType type = DetectorType::SCIENCE;
        std::string serial = "";
        lsst::geom::Box2I bbox;
        Orientation orientation;
        lsst::geom::Extent2D pixelSize;
        CrosstalkMatrix crosstalk;
        std::string physicalType;
    };


    DetectorBase() = default;
    DetectorBase(DetectorBase const &) = default;
    DetectorBase(DetectorBase &&) = default;
    DetectorBase & operator=(DetectorBase const &) = default;
    DetectorBase & operator=(DetectorBase &&) = default;

    virtual Fields const & getFields() const = 0;

};


class Detector final :
    public DetectorBase,
    public table::io::PersistableFacade<Detector>,
    public typehandling::Storable
{
public:

    class Builder;
    class PartialRebuilder;
    class InCameraBuilder;

    std::shared_ptr<PartialRebuilder> rebuild() const;

    std::vector<lsst::geom::Point2D> getCorners(CameraSys const &cameraSys) const;

    std::vector<lsst::geom::Point2D> getCorners(CameraSysPrefix const &cameraSysPrefix) const;

    lsst::geom::Point2D getCenter(CameraSys const &cameraSys) const;

    lsst::geom::Point2D getCenter(CameraSysPrefix const &cameraSysPrefix) const;

    bool hasTransform(CameraSys const &cameraSys) const;

    bool hasTransform(CameraSysPrefix const &cameraSysPrefix) const;

    template <typename FromSysT, typename ToSysT>
    std::shared_ptr<afw::geom::TransformPoint2ToPoint2> getTransform(FromSysT const &fromSys,
                                                                     ToSysT const &toSys) const;

    template <typename FromSysT, typename ToSysT>
    lsst::geom::Point2D transform(lsst::geom::Point2D const &point, FromSysT const &fromSys,
                                  ToSysT const &toSys) const;

    template <typename FromSysT, typename ToSysT>
    std::vector<lsst::geom::Point2D> transform(std::vector<lsst::geom::Point2D> const &points,
                                               FromSysT const &fromSys, ToSysT const &toSys) const;


    std::shared_ptr<TransformMap const> getTransformMap() const { return _transformMap; }

    std::vector<std::shared_ptr<Amplifier const>> const & getAmplifiers() const { return _amplifiers; }


    auto begin() const { return _amplifiers.begin(); }
    auto end() const { return _amplifiers.end(); }
    //}

    std::shared_ptr<Amplifier const> operator[](size_t i) const { return _amplifiers.at(i); }

    std::shared_ptr<Amplifier const> operator[](std::string const &name) const;

    std::size_t size() const { return _amplifiers.size(); }

    bool isPersistable() const noexcept override { return true; }

protected:

    Fields const & getFields() const override { return _fields; }

private:

    class Factory;

    // Pass fields by value to move when we can and copy when we can't;
    // pass amplifiers by rvalue ref because we always move those.
    Detector(Fields fields, std::shared_ptr<TransformMap const> transformMap,
             std::vector<std::shared_ptr<Amplifier const>> && amplifiers);

    std::string getPersistenceName() const override;

    std::string getPythonModule() const override;

    void write(OutputArchiveHandle& handle) const override;

    Fields const _fields;
    std::shared_ptr<TransformMap const> _transformMap;
    // Given that the number of amplifiers in a detector is generally quite
    // small (even LSST only has 16), we just use a vector and do linear
    // searches for name lookups, as adding a map of some kind is definitely
    // more storage and code complexity, without necessarily being any faster.
    std::vector<std::shared_ptr<Amplifier const>> _amplifiers;
};


class Detector::Builder : public DetectorBase {
public:

    // Builder's current subclasses have no need for copy or assignment, and
    // the hierarchy should be considered closed.
    Builder(Builder const &) = delete;
    Builder(Builder &&) = delete;
    Builder & operator=(Builder const &) = delete;
    Builder & operator=(Builder &&) = delete;

    ~Builder() noexcept override = 0;

    void setBBox(lsst::geom::Box2I const & bbox) { _fields.bbox = bbox; }

    void setType(DetectorType type) { _fields.type = type; }

    void setSerial(std::string const & serial) { _fields.serial = serial; }

    void setPhysicalType(std::string const & physicalType) { _fields.physicalType = physicalType; }

    void setCrosstalk(CrosstalkMatrix const & crosstalk) { _fields.crosstalk = crosstalk; }

    void unsetCrosstalk() { _fields.crosstalk = CrosstalkMatrix(); }

    // We return non-const Amplifier::Builder objects by shared_ptr, via const
    // methods.  That's a bit counterintuitive, but there's no solution to the
    // problem of constness in containers of pointers in C++ that *is*
    // intuitive. The alternative would be to have const methods that return
    // pointer-to-const and non-const methods that return
    // pointer-to-not-const.  The only gain from that would be that it'd be
    // possible to have a const reference to a Detector::Builder that would
    // prevent modifications to its amplifiers.  That's a lot more code
    // (writing the iterators would be especially unpleasant) for essentially
    // no gain, because users who want to prevent changes to the amplifiers
    // essentially always Detector itself, not Detector::Builder.

    std::vector<std::shared_ptr<Amplifier::Builder>> const & getAmplifiers() const { return _amplifiers; }


    auto begin() { return _amplifiers.begin(); }
    auto end() { return _amplifiers.end(); }

    std::shared_ptr<Amplifier::Builder> operator[](size_t i) const { return _amplifiers.at(i); }

    std::shared_ptr<Amplifier::Builder> operator[](std::string const &name) const;

    void append(std::shared_ptr<Amplifier::Builder> builder);

    void clear() { _amplifiers.clear(); }

    std::size_t size() const { return _amplifiers.size(); }

protected:

    static std::vector<std::shared_ptr<Amplifier::Builder>> rebuildAmplifiers(Detector const & detector);

    Builder(std::string const & name, int id);

    Builder(Fields fields, std::vector<std::shared_ptr<Amplifier::Builder>> && amplifiers) :
        _fields(std::move(fields)),
        _amplifiers(std::move(amplifiers))
    {}

    Fields const & getFields() const override { return _fields; }

    std::vector<std::shared_ptr<Amplifier const>> finishAmplifiers() const;

    void setOrientation(Orientation const & orientation) { _fields.orientation = orientation; }

    void setPixelSize(lsst::geom::Extent2D const & pixelSize) { _fields.pixelSize = pixelSize; }

private:
    Fields _fields;
    std::vector<std::shared_ptr<Amplifier::Builder>> _amplifiers;
};


class Detector::PartialRebuilder final : public Detector::Builder {
public:

    PartialRebuilder(Detector const & detector);

    std::shared_ptr<Detector const> finish() const;

private:
    std::shared_ptr<TransformMap const> _transformMap;
};

class Detector::InCameraBuilder final : public Detector::Builder {
public:

    void setOrientation(Orientation const & orientation) { Detector::Builder::setOrientation(orientation); }

    void setPixelSize(lsst::geom::Extent2D const & pixelSize) { Detector::Builder::setPixelSize(pixelSize); }

    void setTransformFromPixelsTo(
        CameraSysPrefix const & toSys,
        std::shared_ptr<afw::geom::TransformPoint2ToPoint2 const> transform
    );

    void setTransformFromPixelsTo(
        CameraSys const & toSys,
        std::shared_ptr<afw::geom::TransformPoint2ToPoint2 const> transform
    );

    bool discardTransformFromPixelsTo(CameraSysPrefix const & toSys);

    bool discardTransformFromPixelsTo(CameraSys const & toSys);

    void clearTransforms() { _connections.clear(); }

private:

    // We'd really like to friend Camera::Builder, but can't forward declare
    // an inner class.  So instead we friend Camera, and it has static members
    // that make the needed functionality accessible to Camera::Builder.
    friend class Camera;

    // Construct from an existing Detector.  For use only by Camera.
    InCameraBuilder(Detector const & detector);

    // Construct a completely new detector.  For use only by Camera.
    InCameraBuilder(std::string const & name, int id);

    // Construct a Detector from the builder.  For use only by Camera.
    //
    // @param[in] transformMap  All transforms known to the entire Camera.
    //
    std::shared_ptr<Detector const> finish(std::shared_ptr<TransformMap const> transformMap) const;

    // Transforms and coordinate systems that are specific to this detector.
    // This does not include the FOCAL_PLANE<->PIXELS connection, as that's
    // derived from the orientation and pixel size.
    std::vector<TransformMap::Connection> _connections;
};

}  // namespace cameraGeom
}  // namespace afw
}  // namespace lsst

#endif