TransformMap.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_TRANSFORMMAP_H)
#define LSST_AFW_CAMERAGEOM_TRANSFORMMAP_H
 
#include <optional>
#include <vector>
#include <unordered_map>
#include <memory>
 
#include "boost/iterator/transform_iterator.hpp"
#include "astshim/FrameSet.h"
 
#include "lsst/afw/table/io/Persistable.h"
#include "lsst/afw/cameraGeom/CameraSys.h"
#include "lsst/geom/Point.h"
#include "lsst/afw/geom/Transform.h"
 
namespace lsst {
namespace afw {
namespace cameraGeom {
 
class DetectorBase;

class TransformMap final : public table::io::PersistableFacade<TransformMap>, public table::io::Persistable {
private:
    // Functor for boost::transform_iterator: given an entry in a std::map or unordered_map, return the key
    struct GetKey {
        CameraSys const &operator()(std::pair<const CameraSys, int> const &p) const { return p.first; };
    };
 
    using CameraSysFrameIdMap = std::unordered_map<CameraSys, int>;
 
public:
    using Transforms = std::unordered_map<CameraSys, std::shared_ptr<geom::TransformPoint2ToPoint2>>;
    using CameraSysIterator = boost::transform_iterator<GetKey, CameraSysFrameIdMap::const_iterator>;

    struct Connection final {
        std::shared_ptr<geom::TransformPoint2ToPoint2 const> transform;
        CameraSys fromSys;
        CameraSys toSys;

        void reverse();
    };

    static std::shared_ptr<TransformMap const> make(CameraSys const &reference, Transforms const &transforms);

    static std::shared_ptr<TransformMap const> make(CameraSys const &reference,
                                                    std::vector<Connection> const &connections);

    TransformMap(TransformMap const &other) = delete;
    TransformMap(TransformMap &&other) = delete;
    TransformMap &operator=(TransformMap const &) = delete;
    TransformMap &operator=(TransformMap &&) = delete;
 
    ~TransformMap() noexcept;

    lsst::geom::Point2D transform(lsst::geom::Point2D const &point, CameraSys const &fromSys,
                                  CameraSys const &toSys) const;

    std::vector<lsst::geom::Point2D> transform(std::vector<lsst::geom::Point2D> const &pointList,
                                               CameraSys const &fromSys, CameraSys const &toSys) const;
 
    CameraSysIterator begin() const { return boost::make_transform_iterator(_frameIds.begin(), GetKey()); }
 
    CameraSysIterator end() const { return boost::make_transform_iterator(_frameIds.end(), GetKey()); }

    bool contains(CameraSys const &system) const noexcept;

    std::shared_ptr<geom::TransformPoint2ToPoint2> getTransform(CameraSys const &fromSys,
                                                                CameraSys const &toSys) const;

    size_t size() const noexcept;

    std::vector<Connection> getConnections() const;

    bool getFocalPlaneParity() const noexcept;

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

    std::unique_ptr<ast::FrameSet> makeFrameSet(
        std::vector<std::shared_ptr<DetectorBase>> const & detectors,
        std::string const & focalPlaneUnit = "mm"
    ) const;
 
private:
    // Helper class used in persistence.
    class Factory;
 
    // Private ctor, only called by `make` static methods and `Factory`.
    explicit TransformMap(std::vector<Connection> &&connections);
 
    /*
     * Return the internal frame ID corresponding to a coordinate system.
     *
     * @param system  The system to convert.
     * @return the ID by which the coordinate system can be found in transforms.
     *
     * @throws lsst::pex::exceptions::InvalidParameterError Thrown if `system`
     *         is not in frameIds.
     *
     * @exceptsafe Provides strong exception guarantee.
     */
    int _getFrame(CameraSys const &system) const;
 
    /*
     * Return ast::Mapping that transforms between two coordinate systems.
     *
     * @param fromSys, toSys  Coordinate systems between which to transform
     * @return an invertible Mapping that converts from `fromSys` to `toSys`
     *
     * @throws lsst::pex::exceptions::InvalidParameterError Thrown if either
     *         `fromSys` or `toSys` is not supported.
     */
    std::shared_ptr<ast::Mapping const> _getMapping(CameraSys const &fromSys, CameraSys const &toSys) const;
 
    std::string getPersistenceName() const override;
 
    std::string getPythonModule() const override;
 
    void write(OutputArchiveHandle &handle) const override;
 
    /*
     * Sequence of connections that define the edges of the graph.
     * Ordered by distance from the reference system.
     */
    std::vector<Connection> _connections;
 
    // Stores information on all relationships between Transforms.
    std::unique_ptr<ast::FrameSet> _frameSet;
 
    /*
     * Translates from LSST coordinate ID to AST frame ID.
     *
     * Must have exactly one mapping for each Frame in `transforms`.
     */
    CameraSysFrameIdMap _frameIds;
 
    bool _focalPlaneParity;
};
 
std::ostream &operator<<(std::ostream &os, TransformMap::Connection const &connection);
 
}  // namespace cameraGeom
}  // namespace afw
}  // namespace lsst
 
#endif