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/>.
 */

/*
 * LSST bitmasks
 */

#ifndef LSST_AFW_IMAGE_MASK_H
#define LSST_AFW_IMAGE_MASK_H

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

#include <memory>

#include "lsst/base.h"
#include "lsst/daf/base/Citizen.h"
#include "lsst/daf/base/PropertySet.h"
#include "lsst/pex/exceptions.h"
#include "lsst/afw/image/ImageBase.h"
#include "lsst/afw/image/LsstImageTypes.h"
#include "lsst/afw/fitsDefaults.h"

namespace lsst {
namespace afw {
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;
}  // namespace detail

template <typename MaskPixelT = lsst::afw::image::MaskPixel>
class Mask : public ImageBase<MaskPixelT> {
public:
    typedef detail::MaskPlaneDict MaskPlaneDict;

    typedef detail::Mask_tag image_category;

    template <typename MaskPT = MaskPixelT>
    struct ImageTypeFactory {
        typedef Mask<MaskPT> type;
    };

    // 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(lsst::geom::Extent2I const& dimensions = lsst::geom::Extent2I(),
                  MaskPlaneDict const& planeDefs = MaskPlaneDict());
    explicit Mask(lsst::geom::Extent2I const& dimensions, MaskPixelT initialValue,
                  MaskPlaneDict const& planeDefs = MaskPlaneDict());
    explicit Mask(lsst::geom::Box2I const& bbox, MaskPlaneDict const& planeDefs = MaskPlaneDict());
    explicit Mask(lsst::geom::Box2I const& bbox, MaskPixelT initialValue,
                  MaskPlaneDict const& planeDefs = MaskPlaneDict());

    explicit Mask(std::string const& fileName, int hdu = fits::DEFAULT_HDU,
                  std::shared_ptr<lsst::daf::base::PropertySet> metadata =
                          std::shared_ptr<lsst::daf::base::PropertySet>(),
                  lsst::geom::Box2I const& bbox = lsst::geom::Box2I(), ImageOrigin origin = PARENT,
                  bool conformMasks = false, bool allowUnsafe=false);

    explicit Mask(fits::MemFileManager& manager, int hdu = fits::DEFAULT_HDU,
                  std::shared_ptr<lsst::daf::base::PropertySet> metadata =
                          std::shared_ptr<lsst::daf::base::PropertySet>(),
                  lsst::geom::Box2I const& bbox = lsst::geom::Box2I(), ImageOrigin origin = PARENT,
                  bool conformMasks = false, bool allowUnsafe=false);

    explicit Mask(fits::Fits& fitsfile,
                  std::shared_ptr<lsst::daf::base::PropertySet> metadata =
                          std::shared_ptr<lsst::daf::base::PropertySet>(),
                  lsst::geom::Box2I const& bbox = lsst::geom::Box2I(), ImageOrigin origin = PARENT,
                  bool conformMasks = false, bool allowUnsafe=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(Mask&& src);
    ~Mask() override;
    Mask(const Mask& src, const lsst::geom::Box2I& bbox, ImageOrigin const origin = PARENT,
         const bool deep = false);

    explicit Mask(ndarray::Array<MaskPixelT, 2, 1> const& array, bool deep = false,
                  lsst::geom::Point2I const& xy0 = lsst::geom::Point2I());

    void swap(Mask& rhs);
    // Operators

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

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

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

    Mask subset(lsst::geom::Box2I const & bbox, ImageOrigin origin=PARENT) const {
        return Mask(*this, bbox, origin, false);
    }

    Mask operator[](lsst::geom::Box2I const & bbox) const {
        return subset(bbox);
    }

    using ImageBase<MaskPixelT>::operator[];

    static MaskPixelT getPlaneBitMask(const std::vector<std::string>& names);

    Mask& operator^=(Mask const& rhs);
    Mask& 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& check);
    typename ImageBase<MaskPixelT>::PixelConstReference operator()(int x, int y,
                                                                   CheckIndices const& check) const;
    bool operator()(int x, int y, int plane, CheckIndices const& check) const;

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

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

    void writeFits(fits::Fits& fitsfile, std::shared_ptr<lsst::daf::base::PropertySet const> metadata =
                                                 std::shared_ptr<lsst::daf::base::PropertySet const>()) const;

    void writeFits(std::string const& filename, fits::ImageWriteOptions const& options,
                   std::string const& mode = "w",
                   std::shared_ptr<daf::base::PropertySet const> header = nullptr) const;

    void writeFits(fits::MemFileManager& manager, fits::ImageWriteOptions const& options,
                   std::string const& mode = "w",
                   std::shared_ptr<daf::base::PropertySet const> header = nullptr) const;

    void writeFits(fits::Fits& fitsfile, fits::ImageWriteOptions const& options,
                   std::shared_ptr<daf::base::PropertySet const> header = nullptr) const;

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

    static Mask readFits(fits::MemFileManager& manager, int hdu = fits::DEFAULT_HDU) {
        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(std::shared_ptr<lsst::daf::base::PropertySet const> metadata);
    //
    // 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(std::shared_ptr<lsst::daf::base::PropertySet>);
    //
    // This one isn't static, it fixes up a given Mask's planes
    void conformMaskPlanes(const MaskPlaneDict& masterPlaneDict);

private:

    friend class MaskFitsReader;

    std::shared_ptr<detail::MaskDict> _maskDict;  // our bitplane dictionary

    static std::shared_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);
}  // namespace image
}  // namespace afw
}  // namespace lsst

#endif  // LSST_AFW_IMAGE_MASK_H