Footprint.h

Go to the documentation of this file.

/*
 * LSST Data Management System
 * Copyright 2008-2016  AURA/LSST.
 *
 * 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 <https://www.lsstcorp.org/LegalNotices/>.
 */
#if !defined(LSST_DETECTION_FOOTPRINT_H)
#define LSST_DETECTION_FOOTPRINT_H
 
#include <algorithm>
#include <list>
#include <set>
#include <cmath>
#include <cstdint>
#include <memory>
#include "ndarray.h"
#include "lsst/base.h"
#include "lsst/afw/image/MaskedImage.h"
#include "lsst/afw/detection/Peak.h"
#include "lsst/afw/geom/Span.h"
#include "lsst/afw/geom/SpanSet.h"
#include "lsst/geom/Box.h"
#include "lsst/afw/geom/ellipses.h"
#include "lsst/geom/LinearTransform.h"
#include "lsst/afw/geom/SkyWcs.h"
#include "lsst/afw/geom/Transform.h"
#include "lsst/afw/table/fwd.h"
#include "lsst/afw/table/Schema.h"
#include "lsst/afw/table/Key.h"
#include "lsst/afw/table/io/Persistable.h"
#include "lsst/afw/table/io/InputArchive.h"
 
namespace lsst {
namespace afw {
namespace detection {

class Footprint : public afw::table::io::PersistableFacade<lsst::afw::detection::Footprint>,
                  public afw::table::io::Persistable {
public:
    /*
     * As a note there is no constructor which accepts a unique_ptr to a SpanSet.
     * If someone did have a unique_ptr to a SpanSet it is possible to wrap the
     * unique_ptr in a std::move when calling the constructor of a Footprint and
     * the compiler will implicitly turn the unique_ptr into a shared_ptr and use
     * that to construct the Footprint.
     */

    explicit Footprint(std::shared_ptr<geom::SpanSet> inputSpans,
                       lsst::geom::Box2I const &region = lsst::geom::Box2I());

    explicit Footprint(std::shared_ptr<geom::SpanSet> inputSpans, afw::table::Schema const &peakSchema,
                       lsst::geom::Box2I const &region = lsst::geom::Box2I());

    explicit Footprint()
            : _spans(std::make_shared<geom::SpanSet>()),
              _peaks(PeakTable::makeMinimalSchema()),
              _region(lsst::geom::Box2I()) {}
 
    Footprint(Footprint const &other) = default;
    Footprint(Footprint &&) = default;
 
    Footprint &operator=(Footprint const &other) = default;
    Footprint &operator=(Footprint &&) = default;
 
    ~Footprint() override = default;

    virtual bool isHeavy() const { return false; }

    std::shared_ptr<geom::SpanSet> getSpans() const { return _spans; }

    void setSpans(std::shared_ptr<geom::SpanSet> otherSpanSet);

    PeakCatalog &getPeaks() { return _peaks; }
    const PeakCatalog &getPeaks() const { return _peaks; }

    std::shared_ptr<PeakRecord> addPeak(float fx, float fy, float value);

    void sortPeaks(afw::table::Key<float> const &key = afw::table::Key<float>());

    void setPeakSchema(afw::table::Schema const &peakSchema);

    void setPeakCatalog(PeakCatalog const &otherPeaks);

    std::size_t getArea() const { return _spans->getArea(); }

    lsst::geom::Point2D getCentroid() const { return _spans->computeCentroid(); }

    geom::ellipses::Quadrupole getShape() const { return _spans->computeShape(); }

    void shift(int dx, int dy);

    void shift(lsst::geom::ExtentI const &d) { shift(d.getX(), d.getY()); }

    lsst::geom::Box2I getBBox() const { return _spans->getBBox(); }

    lsst::geom::Box2I getRegion() const { return _region; }

    void setRegion(lsst::geom::Box2I const &region) { _region = region; }

    void clipTo(lsst::geom::Box2I const &bbox);

    bool contains(lsst::geom::Point2I const &pix) const;

    std::shared_ptr<Footprint> transform(std::shared_ptr<geom::SkyWcs> source,
                                         std::shared_ptr<geom::SkyWcs> target,
                                         lsst::geom::Box2I const &region, bool doClip = true) const;

    std::shared_ptr<Footprint> transform(lsst::geom::LinearTransform const &t,
                                         lsst::geom::Box2I const &region, bool doClip = true) const;

    std::shared_ptr<Footprint> transform(lsst::geom::AffineTransform const &t,
                                         lsst::geom::Box2I const &region, bool doClip = true) const;

    std::shared_ptr<Footprint> transform(geom::TransformPoint2ToPoint2 const &t,
                                         lsst::geom::Box2I const &region, bool doClip = true) const;

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

    void dilate(int r, geom::Stencil s = geom::Stencil::CIRCLE);

    void dilate(geom::SpanSet const &other);

    void erode(int r, geom::Stencil s = geom::Stencil::CIRCLE);

    void erode(geom::SpanSet const &other);

    void removeOrphanPeaks();

    void updatePeakSignificance(double sigma);

    void updatePeakSignificance(image::Image<float> const &variance, int polarity);

    bool isContiguous() const { return getSpans()->isContiguous(); };

    std::vector<std::shared_ptr<Footprint>> split() const;

    bool operator==(Footprint const &other) const;
 
protected:
    std::string getPersistenceName() const override;

    inline std::string getPythonModule() const override { return "lsst.afw.detection"; }

    void write(OutputArchiveHandle &handle) const override;
 
    friend class FootprintFactory;

    static std::unique_ptr<Footprint> readSpanSet(afw::table::BaseCatalog const &,
                                                  afw::table::io::InputArchive const &);
    static void readPeaks(afw::table::BaseCatalog const &, Footprint &);
 
private:
    friend class FootprintMerge;
 
    std::shared_ptr<geom::SpanSet> _spans;  
    PeakCatalog _peaks;                     
    lsst::geom::Box2I _region;  
};

std::ostream &operator<<(std::ostream &os, Footprint const &rhs);

std::shared_ptr<Footprint> mergeFootprints(Footprint const &footprint1, Footprint const &footprint2);

std::vector<lsst::geom::Box2I> footprintToBBoxList(Footprint const &footprint);
}  // namespace detection
}  // namespace afw
}  // namespace lsst
 
#endif  // LSST_DETECTION_FOOTPRINT_H