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/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 {};
 
using MaskPlaneDict = std::map<std::string, int>;
}  // namespace detail
 
template <typename MaskPixelT = lsst::afw::image::MaskPixel>
class Mask : public ImageBase<MaskPixelT> {
public:
    using MaskPlaneDict = detail::MaskPlaneDict;
 
    using image_category = detail::Mask_tag;
 
    template <typename MaskPT = MaskPixelT>
    struct ImageTypeFactory {
        using type = Mask<MaskPT>;
    };
 
    // 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,
                   daf::base::PropertySet const * metadata = nullptr,
                   std::string const& mode = "w") const;
    [[deprecated("Replaced by a non-shared_ptr overload.  Will be removed after v25.")]]
    void writeFits(std::string const& fileName,
                   std::shared_ptr<daf::base::PropertySet const> metadata,
                   std::string const& mode = "w") const;
 
 
    void writeFits(fits::MemFileManager& manager,
                   daf::base::PropertySet const * metadata = nullptr,
                   std::string const& mode = "w") const;
    [[deprecated("Replaced by a non-shared_ptr overload.  Will be removed after v25.")]]
    void writeFits(fits::MemFileManager& manager,
                   std::shared_ptr<daf::base::PropertySet const> metadata,
                   std::string const& mode = "w") const;
 
 
    void writeFits(fits::Fits& fitsfile, daf::base::PropertySet const * metadata = nullptr) const;
    [[deprecated("Replaced by a non-shared_ptr overload.  Will be removed after v25.")]]
    void writeFits(fits::Fits& fitsfile,
                   std::shared_ptr<daf::base::PropertySet const> metadata) const;
 
 
    void writeFits(std::string const& filename, fits::ImageWriteOptions const& options,
                   std::string const& mode = "w",
                   daf::base::PropertySet const * header = nullptr) const;
    [[deprecated("Replaced by a non-shared_ptr overload.  Will be removed after v25.")]]
    void writeFits(std::string const& filename, fits::ImageWriteOptions const& options,
                   std::string const& mode,
                   std::shared_ptr<daf::base::PropertySet const> header) const;
 
 
    void writeFits(fits::MemFileManager& manager, fits::ImageWriteOptions const& options,
                   std::string const& mode = "w",
                   daf::base::PropertySet const * header = nullptr) const;
    [[deprecated("Replaced by a non-shared_ptr overload.  Will be removed after v25.")]]
    void writeFits(fits::MemFileManager& manager, fits::ImageWriteOptions const& options,
                   std::string const& mode,
                   std::shared_ptr<daf::base::PropertySet const> header) const;
 
 
    void writeFits(fits::Fits& fitsfile, fits::ImageWriteOptions const& options,
                   daf::base::PropertySet const * header = nullptr) const;
    [[deprecated("Replaced by a non-shared_ptr overload.  Will be removed after v25.")]]
    void writeFits(fits::Fits& fitsfile, fits::ImageWriteOptions const& options,
                   std::shared_ptr<daf::base::PropertySet const> header) 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