Footprint.h

Go to the documentation of this file.

/*
 * LSST Data Management System
 * Copyright 2008-2015 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/>.
 */

#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/pex/policy/Policy.h"
#include "lsst/afw/image/MaskedImage.h"
#include "lsst/afw/image/Wcs.h"
#include "lsst/afw/detection/Peak.h"
#include "lsst/afw/geom.h"
#include "lsst/afw/geom/ellipses.h"
#include "lsst/afw/table/fwd.h"
#include "lsst/afw/table/io/Persistable.h"

namespace lsst { namespace afw { namespace detection {

using geom::Span;

/************************************************************************************************************/
class Footprint : public lsst::daf::base::Citizen,
                  public afw::table::io::PersistableFacade<lsst::afw::detection::Footprint>,
                  public afw::table::io::Persistable
{
public:
    typedef std::shared_ptr<Footprint> Ptr;
    typedef std::shared_ptr<const Footprint> ConstPtr;

    typedef std::vector<Span::Ptr> SpanList;

    explicit Footprint(int nspan = 0, geom::Box2I const & region=geom::Box2I());

    explicit Footprint(afw::table::Schema const & peakSchema, int nspan=0,
                       geom::Box2I const & region=geom::Box2I());

    explicit Footprint(geom::Box2I const & bbox, geom::Box2I const & region=geom::Box2I());
    Footprint(geom::Point2I const & center, double const radius, geom::Box2I const & = geom::Box2I());
    explicit Footprint(geom::ellipses::Ellipse const & ellipse, geom::Box2I const & region=geom::Box2I());

    explicit Footprint(SpanList const & spans, geom::Box2I const & region=geom::Box2I());

    Footprint(Footprint const & other);

    virtual ~Footprint();

    virtual bool isHeavy() const { return false; }

    int getId() const { return _fid; }

    SpanList& getSpans() { return _spans; }

    const SpanList& getSpans() const { return _spans; }

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

    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) {
        if (!getPeaks().empty()) {
            throw LSST_EXCEPT(
                pex::exceptions::LogicError,
                "Cannot change the PeakCatalog schema unless it is empty"
            );
        }
        // this syntax doesn't work in Python, which is why this method has to exist
        getPeaks() = PeakCatalog(peakSchema);
    }

    size_t getNpix() const { return _area; }
    size_t getArea() const { return _area; }

    geom::Point2D getCentroid() const;

    geom::ellipses::Quadrupole getShape() const;

    const Span& addSpan(const int y, const int x0, const int x1);
    const Span& addSpan(Span const& span);
    const Span& addSpan(Span const& span, int dx, int dy);

    const Span& addSpanInSeries(const int y, const int x0, const int x1);

    void shift(int dx, int dy);
    void shift(geom::ExtentI d) {shift(d.getX(), d.getY());}

    geom::Box2I getBBox() const { return _bbox; }

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

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

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

    template<typename PixelT>
    void clipToNonzero(lsst::afw::image::Image<PixelT> const& img);

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

    void normalize();
    bool isNormalized() const {return _normalized;}

    template<typename MaskT>
    MaskT overlapsMask(typename image::Mask<MaskT> const& mask 
        ) const;

    template<typename PixelT>
    void insertIntoImage(typename lsst::afw::image::Image<PixelT>& idImage,
                         std::uint64_t const id,
                         geom::Box2I const& region=geom::Box2I()
    ) const;

    template<typename PixelT>
    void insertIntoImage(typename lsst::afw::image::Image<PixelT>& idImage,
                         std::uint64_t const id,
                         bool const overwriteId, long const idMask,
                         typename std::set<std::uint64_t> *oldIds,
                         geom::Box2I const& region=geom::Box2I()
    ) const;

    Footprint & operator=(Footprint & other);

    template <typename MaskPixelT>
    void intersectMask(
        image::Mask<MaskPixelT> const & mask,
        MaskPixelT bitmask=~0x0
    );

    PTR(Footprint) transform(
        image::Wcs const & source,
        image::Wcs const & target,
        geom::Box2I const & region,
        bool doClip=true
    ) const;

    PTR(Footprint) findEdgePixels() const;

    void include(std::vector<PTR(Footprint)> const & children, bool ignoreSelf=false);

    bool isPersistable() const { return true; }

protected:

    virtual std::string getPersistenceName() const;

    virtual std::string getPythonModule() const;

    virtual void write(OutputArchiveHandle & handle) const;

    void readSpans(afw::table::BaseCatalog const & spanCat);
    void readPeaks(afw::table::BaseCatalog const & peakCat);

    friend class FootprintFactory;

private:

    friend class FootprintMerge;

    static int id;
    mutable int _fid;                    
    size_t _area;                           

    SpanList _spans;                     
    geom::Box2I _bbox;                   
    PeakCatalog _peaks;                     
    mutable geom::Box2I _region;         
    bool _normalized;                    
};

void nearestFootprint(std::vector<PTR(Footprint)> const& foots,
                      lsst::afw::image::Image<std::uint16_t>::Ptr argmin,
                      lsst::afw::image::Image<std::uint16_t>::Ptr dist);

PTR(Footprint) mergeFootprints(Footprint const& foot1, Footprint const& foot2);

PTR(Footprint) mergeFootprints(Footprint& foot1, Footprint& foot2);

PTR(Footprint) shrinkFootprint(Footprint const& foot, int nGrow, bool isotropic);

PTR(Footprint) growFootprint(Footprint const& foot, int nGrow, bool isotropic=true);

PTR(Footprint) growFootprint(PTR(Footprint) const& foot, int nGrow, bool isotropic=true);

PTR(Footprint) growFootprint(Footprint const& foot, int nGrow,
                             bool left, bool right, bool up, bool down);

std::vector<lsst::afw::geom::Box2I> footprintToBBoxList(Footprint const& foot);

template<typename ImageT>
typename ImageT::Pixel setImageFromFootprint(ImageT *image,
                                             Footprint const& footprint,
                                             typename ImageT::Pixel const value);

template<typename ImageT>
typename ImageT::Pixel setImageFromFootprintList(ImageT *image,
                                                 CONST_PTR(std::vector<PTR(Footprint)>) footprints,
                                                 typename ImageT::Pixel  const value);

template<typename ImageT>
typename ImageT::Pixel setImageFromFootprintList(ImageT *image,
                                                 std::vector<PTR(Footprint)> const& footprints,
                                                 typename ImageT::Pixel  const value);

template<typename MaskT>
MaskT setMaskFromFootprint(lsst::afw::image::Mask<MaskT> *mask,
                           Footprint const& footprint,
                           MaskT const bitmask);

template<typename MaskT>
MaskT clearMaskFromFootprint(lsst::afw::image::Mask<MaskT> *mask,
                             Footprint const& footprint,
                             MaskT const bitmask);

template <typename ImageOrMaskedImageT>
void copyWithinFootprint(Footprint const& foot,
                         PTR(ImageOrMaskedImageT) const input,
                         PTR(ImageOrMaskedImageT) output);

/************************************************************************************************************/
template<typename MaskT>
MaskT setMaskFromFootprintList(lsst::afw::image::Mask<MaskT> *mask,
                               std::vector<PTR(Footprint)> const& footprints,
                               MaskT const bitmask);

template<typename MaskT>
MaskT setMaskFromFootprintList(lsst::afw::image::Mask<MaskT> *mask,
                               CONST_PTR(std::vector<PTR(Footprint)>) const& footprints,
                               MaskT const bitmask);

template<typename MaskT>
PTR(Footprint) footprintAndMask(PTR(Footprint) const& foot,
                                typename image::Mask<MaskT>::Ptr const& mask,
                                MaskT const bitmask);

/************************************************************************************************************/

}}} // namespace lsst::afw::detection

#endif