Mask.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_IMAGE_MASK_H
#define LSST_AFW_IMAGE_MASK_H

#include <list>
#include <map>
#include <string>

#include "boost/cstdint.hpp"
#include "boost/shared_ptr.hpp"

#include "lsst/base.h"
#include "lsst/daf/base/Citizen.h"
#include "lsst/daf/base/Persistable.h"
#include "lsst/daf/base/PropertySet.h"
#include "lsst/pex/exceptions.h"
#include "lsst/afw/formatters/ImageFormatter.h"
#include "lsst/afw/image/Image.h"
#include "lsst/afw/image/LsstImageTypes.h"

namespace lsst {
namespace afw {
    namespace formatters {
        template<typename> class MaskFormatter;
    }
namespace image {

namespace detail {
    class MaskDict;                     // forward declaration
}

// all masks will initially be instantiated with the same pixel type
namespace detail {
    struct Mask_tag : public detail::basic_tag { };

    typedef std::map<std::string, int> MaskPlaneDict;
}

template<typename MaskPixelT=lsst::afw::image::MaskPixel>
class Mask : public ImageBase<MaskPixelT> {
public:
    typedef boost::shared_ptr<Mask> Ptr;
    typedef boost::shared_ptr<const Mask> ConstPtr;
    typedef detail::MaskPlaneDict MaskPlaneDict;
    
    typedef detail::Mask_tag image_category;

#if !defined(SWIG)
    template<typename MaskPT=MaskPixelT>
    struct ImageTypeFactory {
        typedef Mask<MaskPT> type;
    };
#endif

    // Constructors        
    explicit Mask(
        unsigned int width, unsigned int height,
        MaskPlaneDict const& planeDefs=MaskPlaneDict()
    );
    explicit Mask(
        unsigned int width, unsigned int height,
        MaskPixelT initialValue, 
        MaskPlaneDict const& planeDefs=MaskPlaneDict()
    );
    explicit Mask(
        geom::Extent2I const & dimensions=geom::Extent2I(),
        MaskPlaneDict const& planeDefs=MaskPlaneDict()
    );
    explicit Mask(
        geom::Extent2I const & dimensions, 
        MaskPixelT initialValue, 
        MaskPlaneDict const& planeDefs=MaskPlaneDict()
    );
    explicit Mask(geom::Box2I const & bbox,
                  MaskPlaneDict const& planeDefs=MaskPlaneDict());
    explicit Mask(geom::Box2I const & bbox, MaskPixelT initialValue,
                  MaskPlaneDict const& planeDefs=MaskPlaneDict());

    explicit Mask(
        std::string const & fileName, int hdu=0,
        PTR(lsst::daf::base::PropertySet) metadata=PTR(lsst::daf::base::PropertySet)(),
        geom::Box2I const & bbox=geom::Box2I(),
        ImageOrigin origin=PARENT,
        bool conformMasks=false
    );

    explicit Mask(
        fits::MemFileManager & manager, int hdu=0,
        PTR(lsst::daf::base::PropertySet) metadata=PTR(lsst::daf::base::PropertySet)(),
        geom::Box2I const & bbox=geom::Box2I(),
        ImageOrigin origin=PARENT,
        bool conformMasks=false
    );

    explicit Mask(
        fits::Fits & fitsfile,
        PTR(lsst::daf::base::PropertySet) metadata=PTR(lsst::daf::base::PropertySet)(),
        geom::Box2I const & bbox=geom::Box2I(),
        ImageOrigin origin=PARENT,
        bool conformMasks=false
    );

    // generalised copy constructor
    template<typename OtherPixelT>
    Mask(Mask<OtherPixelT> const& rhs, const bool deep) :
        image::ImageBase<MaskPixelT>(rhs, deep),
        _maskDict(rhs._maskDict) {}

    Mask(const Mask& src, const bool deep=false);
    Mask(
        const Mask& src, 
        const geom::Box2I & bbox,  
        ImageOrigin const origin=PARENT, 
        const bool deep=false
    );
    
    explicit Mask(ndarray::Array<MaskPixelT,2,1> const & array, bool deep=false,
                  geom::Point2I const & xy0=geom::Point2I());

    void swap(Mask& rhs);
    // Operators

    Mask& operator=(MaskPixelT const rhs);
    Mask& operator=(const Mask& rhs);

    void operator|=(Mask const& rhs);
    void operator|=(MaskPixelT const rhs);

    void operator&=(Mask const& rhs);
    void operator&=(MaskPixelT const rhs);
        static MaskPixelT getPlaneBitMask(const std::vector<std::string> &names);

    void operator^=(Mask const& rhs);
    void operator^=(MaskPixelT const rhs);

    typename ImageBase<MaskPixelT>::PixelReference operator()(int x, int y);
    typename ImageBase<MaskPixelT>::PixelConstReference operator()(int x, int y) const;
    bool operator()(int x, int y, int plane) const;
    typename ImageBase<MaskPixelT>::PixelReference operator()(int x, int y, CheckIndices const&);
    typename ImageBase<MaskPixelT>::PixelConstReference operator()(int x, int y,
                                                                   CheckIndices const&) const;
    bool operator()(int x, int y, int plane, CheckIndices const&) const;

    void writeFits(
        std::string const& fileName,
        CONST_PTR(lsst::daf::base::PropertySet) metadata=PTR(lsst::daf::base::PropertySet)(),
        std::string const& mode="w"
    ) const;

    void writeFits(
        fits::MemFileManager & manager,
        CONST_PTR(lsst::daf::base::PropertySet) metadata=PTR(lsst::daf::base::PropertySet)(),
        std::string const& mode="w"
    ) const;

    void writeFits(
        fits::Fits & fitsfile,
        CONST_PTR(lsst::daf::base::PropertySet) metadata=CONST_PTR(lsst::daf::base::PropertySet)()
    ) const;

    static Mask readFits(std::string const & filename, int hdu=0) {
        return Mask<MaskPixelT>(filename, hdu);
    }

    static Mask readFits(fits::MemFileManager & manager, int hdu=0) {
        return Mask<MaskPixelT>(manager, hdu);
    }

    static std::string interpret(MaskPixelT value);
    std::string getAsString(int x, int y) { return interpret((*this)(x, y)); }

    // Mask Plane ops
    
    void clearAllMaskPlanes();
    void clearMaskPlane(int plane);
    void setMaskPlaneValues(const int plane, const int x0, const int x1, const int y);
    static MaskPlaneDict parseMaskPlaneMetadata(CONST_PTR(lsst::daf::base::PropertySet));
    //
    // Operations on the mask plane dictionary
    //
    static void clearMaskPlaneDict();
    static int addMaskPlane(const std::string& name);
    static void removeMaskPlane(const std::string& name);
    void removeAndClearMaskPlane(const std::string& name, bool const removeFromDefault=false);
    
    static int getMaskPlane(const std::string& name);
    static MaskPixelT getPlaneBitMask(const std::string& name);

    static int getNumPlanesMax()  { return 8*sizeof(MaskPixelT); }
    static int getNumPlanesUsed();
    MaskPlaneDict const& getMaskPlaneDict() const;
    void printMaskPlanes() const;

    static void addMaskPlanesToMetadata(PTR(lsst::daf::base::PropertySet));
    //
    // This one isn't static, it fixes up a given Mask's planes
    void conformMaskPlanes(const MaskPlaneDict& masterPlaneDict);
        
private:
    //LSST_PERSIST_FORMATTER(lsst::afw::formatters::MaskFormatter)
    PTR(detail::MaskDict) _maskDict;    // our bitplane dictionary
    
    static PTR(detail::MaskDict) _maskPlaneDict();
    static int _setMaskPlaneDict(MaskPlaneDict const& mpd);
    static const std::string maskPlanePrefix;
    
    static int addMaskPlane(std::string name, int plane);

    static int getMaskPlaneNoThrow(const std::string& name);
    static MaskPixelT getBitMaskNoThrow(int plane);
    static MaskPixelT getBitMask(int plane);

    void _initializePlanes(MaskPlaneDict const& planeDefs); // called by ctors

    //
    // Make names in templatized base class visible (Meyers, Effective C++, Item 43)
    //
    using ImageBase<MaskPixelT>::_getRawView;
    using ImageBase<MaskPixelT>::swap;

    void checkMaskDictionaries(Mask const& other);
};

template<typename PixelT>
void swap(Mask<PixelT>& a, Mask<PixelT>& b);
    
}}}  // lsst::afw::image
        
#endif // LSST_AFW_IMAGE_MASK_H