Match.h

Go to the documentation of this file.

// -*- lsst-c++ -*-

/*
 * LSST Data Management System
 * Copyright 2008, 2009, 2010 LSST Corporation.
 *
 * This product includes software developed by the
 * LSST Project (http://www.lsst.org/).
 *
 * 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 LSST License Statement and
 * the GNU General Public License along with this program.  If not,
 * see <http://www.lsstcorp.org/LegalNotices/>.
 */

#ifndef LSST_AFW_TABLE_MATCH_H
#define LSST_AFW_TABLE_MATCH_H

#include <vector>

#include "lsst/pex/config.h"
#include "lsst/afw/table/fwd.h"
#include "lsst/afw/table/BaseRecord.h"
#include "lsst/afw/table/Simple.h"
#include "lsst/afw/table/Source.h"
#include "lsst/afw/table/Catalog.h"
#include "lsst/geom/Angle.h"

namespace lsst {
namespace afw {
namespace table {

class MatchControl {
public:
    MatchControl() : findOnlyClosest(true), symmetricMatch(true), includeMismatches(false) {}
    LSST_CONTROL_FIELD(findOnlyClosest, bool,
                       "Return only the closest match if more than one is found "
                       "(default: true)");
    LSST_CONTROL_FIELD(symmetricMatch, bool,
                       "Produce symmetric matches (default: true):\n"
                       "i.e. if (s1, s2, d) is reported, then so is (s2, s1, d)");
    LSST_CONTROL_FIELD(includeMismatches, bool,
                       "Include failed matches (i.e. one 'match' is NULL) "
                       "(default: false)");
};

template <typename Record1, typename Record2>
struct Match final {
    std::shared_ptr<Record1> first;
    std::shared_ptr<Record2> second;
    double distance;  // may be pixels or radians

    Match() : first(), second(), distance(0.0) {}

    Match(std::shared_ptr<Record1> const &r1, std::shared_ptr<Record2> const &r2, double dist)
            : first(r1), second(r2), distance(dist) {}

    template <typename R1, typename R2>
    Match(Match<R1, R2> const &other) : first(other.first), second(other.second), distance(other.distance) {}
};

typedef Match<SimpleRecord, SimpleRecord> SimpleMatch;
typedef Match<SimpleRecord, SourceRecord> ReferenceMatch;
typedef Match<SourceRecord, SourceRecord> SourceMatch;

typedef std::vector<SimpleMatch> SimpleMatchVector;
typedef std::vector<ReferenceMatch> ReferenceMatchVector;
typedef std::vector<SourceMatch> SourceMatchVector;

SourceMatchVector matchXy(
        SourceCatalog const &cat1,  
        SourceCatalog const &cat2,  
        double radius,              
        MatchControl const &mc =
                MatchControl()  
);

SourceMatchVector matchXy(
        SourceCatalog const &cat,  
        double radius,             
        MatchControl const &mc =
                MatchControl()  
);

[[deprecated("Use overloads that take `MatchControl` instead. To be removed after 20.0.0.")]]  // DM-22276
        SourceMatchVector
        matchXy(SourceCatalog const &cat1, SourceCatalog const &cat2, double radius, bool closest);

[[deprecated("Use overloads that take `MatchControl` instead. To be removed after 20.0.0.")]]  // DM-22276
        SourceMatchVector
        matchXy(SourceCatalog const &cat, double radius, bool symmetric);

template <typename Cat1, typename Cat2>
std::vector<Match<typename Cat1::Record, typename Cat2::Record> > matchRaDec(
        Cat1 const &cat1,          
        Cat2 const &cat2,          
        lsst::geom::Angle radius,  
        MatchControl const &mc =
                MatchControl()  
);

/*
 * Compute all tuples (s1,s2,d) where s1 != s2, s1 and s2 both belong to `cat`,
 * and d, the distance between s1 and s2, is at most `radius`. The
 * match is performed in ra, dec space.
 *
 * This is instantiated for Simple and Source catalogs.
 */
template <typename Cat>
std::vector<Match<typename Cat::Record, typename Cat::Record> > matchRaDec(
        Cat const &cat,            
        lsst::geom::Angle radius,  
        MatchControl const &mc =
                MatchControl()  
);

template <typename Cat1, typename Cat2>
[[deprecated("Use overloads that take `MatchControl` instead. To be removed after 20.0.0.")]]  // DM-22276
        std::vector<Match<typename Cat1::Record, typename Cat2::Record> >
        matchRaDec(Cat1 const &cat1, Cat2 const &cat2, lsst::geom::Angle radius, bool closest);

template <typename Cat>
[[deprecated("Use overloads that take `MatchControl` instead. To be removed after 20.0.0.")]]  // DM-22276
        std::vector<Match<typename Cat::Record, typename Cat::Record> >
        matchRaDec(Cat const &cat, lsst::geom::Angle radius, bool symmetric);

template <typename Record1, typename Record2>
BaseCatalog packMatches(std::vector<Match<Record1, Record2> > const &matches);

template <typename Cat1, typename Cat2>
std::vector<Match<typename Cat1::Record, typename Cat2::Record> > unpackMatches(BaseCatalog const &matches,
                                                                                Cat1 const &cat1,
                                                                                Cat2 const &cat2);
}  // namespace table
}  // namespace afw
}  // namespace lsst

#endif  // #ifndef LSST_AFW_TABLE_MATCH_H