lsst::afw::cameraGeom::TransformMap::Builder Class Reference

Helper class used to incrementally construct TransformMap instances. More...

#include <TransformMap.h>

Public Member Functions
	Builder (CameraSys const &reference)
	Construct an empty builder with no transforms and only the given coordinate system. More...
	~Builder () noexcept
Builder &	connect (CameraSys const &fromSys, CameraSys const &toSys, std::shared_ptr< geom::TransformPoint2ToPoint2 const > transform)
	Add a new coordinate system to the builder. More...
Builder &	connect (CameraSys const &fromSys, Transforms const &transforms)
	Add multiple connections relative to a single reference CameraSys. More...
Builder &	connect (Transforms const &transforms)
	Add multiple connections relative to a single reference CameraSys. More...
std::shared_ptr< TransformMap const >	build () const
	Construct a TransformMap from the connections in the builder. More...
	Builder (Builder const &)
	Builder (Builder &&)
Builder &	operator= (Builder const &)
Builder &	operator= (Builder &&)

Detailed Description

Helper class used to incrementally construct TransformMap instances.

Definition at line 239 of file TransformMap.h.

Constructor & Destructor Documentation

Builder() [1/3]

lsst::afw::cameraGeom::TransformMap::Builder::Builder ( CameraSys const &  reference )

explicit

Construct an empty builder with no transforms and only the given coordinate system.

Definition at line 252 of file TransformMap.cc.

: _reference(reference) {}

Builder() [2/3]

lsst::afw::cameraGeom::TransformMap::Builder::Builder ( Builder const &  )

default

Builders are copyable, movable, and assignable.

Builder() [3/3]

lsst::afw::cameraGeom::TransformMap::Builder::Builder ( Builder &&  )

default

Builders are copyable, movable, and assignable.

~Builder()

lsst::afw::cameraGeom::TransformMap::Builder::~Builder ( )

defaultnoexcept

Member Function Documentation

build()

std::shared_ptr< TransformMap const > lsst::afw::cameraGeom::TransformMap::Builder::build

(

)

const

Construct a TransformMap from the connections in the builder.

Exceptions

pex::exceptions::InvalidParameterError

Thrown if there is no direct or indirect connection between FOCAL_PLANE and one or more coordinate systems, or there are duplicate connections between any two systems.

Exception Safety

strong

Definition at line 330 of file TransformMap.cc.

                                                                   {

    int nFrames = 0;  // tracks frameSet->getNFrame() to avoid those (expensive) calls
    CameraSysFrameIdMap frameIds;  // mapping from CameraSys to Frame ID (int)
    std::vector<std::pair<int, int>> canonicalConnections;  // remembers the frame IDs we've connected

    // Local helper function that looks up the Frame ID for a CameraSys, with
    // results returned via boost::optional.
    auto findFrameIdForSys = [&frameIds](CameraSys const & sys) -> boost::optional<int> {
        auto iter = frameIds.find(sys);
        if (iter != frameIds.end()) {
            return boost::optional<int>(iter->second);
        } else {
            return boost::none;
        }
    };

    // Local helper function that creates a Frame, updates the nFrames counter,
    // and adds an entry to the frameIds map.  Returns the new Frame.
    // Should always be called in concert with an update to frameSet.
    auto addFrameForSys = [&frameIds, &nFrames](CameraSys const & sys) mutable -> ast::Frame {
        frameIds.emplace(sys, ++nFrames);
        return ast::Frame(2, makeFrameName(sys));
    };

    // FrameSet that manages all transforms; should always be updated in
    // concert with a call to addFrameForSys.
    auto frameSet = std::make_unique<ast::FrameSet>(addFrameForSys(_reference));

    // RAII: make sure all 'processed' fields are reset, no matter how we exit
    auto guard = onScopeExit(
        [this]() noexcept {
            for (auto const & c : _connections) { c.processed = false; }
        }
    );

    std::size_t nProcessedTotal = 0;
    while (nProcessedTotal != _connections.size()) {

        // Loop over all connections, only inserting those that are connected
        // to already-inserted connections.
        std::size_t nProcessedThisPass = 0;
        for (auto const & c : _connections) {
            if (c.processed) continue;
            auto fromId = findFrameIdForSys(c.fromSys);
            auto toId = findFrameIdForSys(c.toSys);
            if (fromId && toId) {  // We've already inserted both fromSys and toSys. That's a problem.
                std::ostringstream buffer;
                buffer << "Duplicate connection from " << c.fromSys << " to " << c.toSys << ".";
                throw LSST_EXCEPT(pex::exceptions::InvalidParameterError, buffer.str());
            } else if (fromId) {  // We've already inserted fromSys (only)
                frameSet->addFrame(*fromId, *c.transform->getMapping(), addFrameForSys(c.toSys));
                canonicalConnections.emplace_back(*fromId, nFrames);
                c.processed = true;
                ++nProcessedThisPass;
            } else if (toId) {  // We've already inserted toSys (only)
                frameSet->addFrame(*toId, *c.transform->inverted()->getMapping(), addFrameForSys(c.fromSys));
                canonicalConnections.emplace_back(*toId, nFrames);
                c.processed = true;
                ++nProcessedThisPass;
            }
            // If we haven't inserted either yet, just continue; hopefully
            // we'll have inserted one in a future pass.
        }

        if (nProcessedThisPass == 0u) {  // We're not making progress, so we must have orphans
            // Use std::set to compile the list of orphaned coordinate systems
            // for a friendlier (unique, predictably-ordered) error message.
            std::set<CameraSys> orphaned;
            for (auto const & c : _connections) {
                if (!c.processed) {
                    orphaned.insert(c.fromSys);
                    orphaned.insert(c.toSys);
                }
            }
            std::ostringstream buffer;
            auto o = orphaned.begin();
            buffer << "Orphaned coordinate system(s) found: " << *o;
            for (++o; o != orphaned.end(); ++o) {
                buffer << ", " << *o;
            }
            buffer << ".";
            throw LSST_EXCEPT(pex::exceptions::InvalidParameterError, buffer.str());
        }

        nProcessedTotal += nProcessedThisPass;
    }

    // We've maintained our own counter for frame IDs for performance and
    // convenience reasons, but it had better match AST's internal counter.
    assert(frameSet->getNFrame() == nFrames);

    // Return the new TransformMap.
    // We can't use make_shared because TransformMap ctor is private.
    return std::shared_ptr<TransformMap>(new TransformMap(std::move(frameSet),
                                                          std::move(frameIds),
                                                          std::move(canonicalConnections)));
}

connect() [1/3]

TransformMap::Builder & lsst::afw::cameraGeom::TransformMap::Builder::connect	(	CameraSys const &	fromSys,
		CameraSys const &	toSys,
		std::shared_ptr< geom::TransformPoint2ToPoint2 const >	transform
	)

Add a new coordinate system to the builder.

Parameters

fromSys	Coordinate system for the arguments to transform->applyForward.
toSys	Coordinate system for the return values of transform->applyForward.
transform	Mapping from fromSys to toSys.

Returns

*this to enable chained calls.

Exceptions

pex::exceptions::InvalidParameterError

Thrown if the transform does not have forward or inverse mapping, or if fromSys and toSys are the same.

Exception Safety

strong

Definition at line 262 of file TransformMap.cc.

  {
    if (fromSys == toSys) {
        std::ostringstream buffer;
        buffer << "Identity connection detected for " << fromSys << ".";
        throw LSST_EXCEPT(pex::exceptions::InvalidParameterError, buffer.str());
    }
    if (!transform->hasForward()) {
        std::ostringstream buffer;
        buffer << "Connection from " << fromSys << " to "
               << toSys << " has no forward transform.";
        throw LSST_EXCEPT(pex::exceptions::InvalidParameterError, buffer.str());
    }
    if (!transform->hasInverse()) {
        std::ostringstream buffer;
        buffer << "Connection from " << fromSys << " to "
               << toSys << " has no inverse transform.";
        throw LSST_EXCEPT(pex::exceptions::InvalidParameterError, buffer.str());
    }
    _connections.push_back(Connection{false, std::move(transform), fromSys, toSys});
    return *this;
}

connect() [2/3]

TransformMap::Builder & lsst::afw::cameraGeom::TransformMap::Builder::connect	(	CameraSys const &	fromSys,
		Transforms const &	transforms
	)

Add multiple connections relative to a single reference CameraSys.

Parameters

fromSys	Coordinate system of the arguments to Transform::applyForward for each transform in the given map.
transforms	A map whose keys are camera coordinate systems, and whose values point to Transforms that convert from fromSys coordinate system to the corresponding key. All Transforms must be invertible.

Returns

*this to enable chained calls.

Exceptions

lsst::pex::exceptions::InvalidParameterError

Thrown if transforms contains fromSys camera system as a key, or if any Transform is not invertible.

Exception Safety

strong

Definition at line 289 of file TransformMap.cc.

  {
    Builder other(_reference);  // temporary for strong exception safety
    for (auto const & item : transforms) {
        other.connect(fromSys, item.first, item.second);
    }
    _connections.insert(_connections.end(), other._connections.begin(), other._connections.end());
    return *this;
}

connect() [3/3]

Builder& lsst::afw::cameraGeom::TransformMap::Builder::connect ( Transforms const &  transforms )

inline

Add multiple connections relative to a single reference CameraSys.

Parameters

transforms

A map whose keys are camera coordinate systems, and whose values point to Transforms that convert from the reference coordinate system (i.e. the one the Builder was originally constructed with) to the corresponding key. All Transforms must be invertible.

Returns

*this to enable chained calls.

Exceptions

lsst::pex::exceptions::InvalidParameterError

Thrown if transforms contains the reference camera system as a key, or if any Transform is not invertible.

Exception Safety

strong

Definition at line 317 of file TransformMap.h.

                                                    {
        return connect(_reference, transforms);
    }

operator=() [1/2]

TransformMap::Builder & lsst::afw::cameraGeom::TransformMap::Builder::operator= ( Builder const &  )

default

Builders are copyable, movable, and assignable.

operator=() [2/2]

TransformMap::Builder & lsst::afw::cameraGeom::TransformMap::Builder::operator= ( Builder &&  )

default

Builders are copyable, movable, and assignable.

---

The documentation for this class was generated from the following files:

• /j/snowflake/release/lsstsw/stack/Linux64/afw/18.1.0/include/lsst/afw/cameraGeom/TransformMap.h
• /j/snowflake/release/lsstsw/stack/Linux64/afw/18.1.0/src/cameraGeom/TransformMap.cc