LSSTApplications  20.0.0
LSSTDataManagementBasePackage
Mask.h
Go to the documentation of this file.
1 // -*- lsst-c++ -*-
2 
3 /*
4  * LSST Data Management System
5  * Copyright 2008, 2009, 2010 LSST Corporation.
6  *
7  * This product includes software developed by the
8  * LSST Project (http://www.lsst.org/).
9  *
10  * This program is free software: you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation, either version 3 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the LSST License Statement and
21  * the GNU General Public License along with this program. If not,
22  * see <http://www.lsstcorp.org/LegalNotices/>.
23  */
24 
25 /*
26  * LSST bitmasks
27  */
28 
29 #ifndef LSST_AFW_IMAGE_MASK_H
30 #define LSST_AFW_IMAGE_MASK_H
31 
32 #include <list>
33 #include <map>
34 #include <string>
35 
36 #include <memory>
37 
38 #include "lsst/base.h"
40 #include "lsst/pex/exceptions.h"
43 #include "lsst/afw/fitsDefaults.h"
44 
45 namespace lsst {
46 namespace afw {
47 namespace image {
48 
49 namespace detail {
50 class MaskDict; // forward declaration
51 }
52 
53 // all masks will initially be instantiated with the same pixel type
54 namespace detail {
56 struct Mask_tag : public detail::basic_tag {};
57 
59 } // namespace detail
60 
76 template <typename MaskPixelT = lsst::afw::image::MaskPixel>
77 class Mask : public ImageBase<MaskPixelT> {
78 public:
80 
82 
84  template <typename MaskPT = MaskPixelT>
87  typedef Mask<MaskPT> type;
88  };
89 
90  // Constructors
98  explicit Mask(unsigned int width, unsigned int height, MaskPlaneDict const& planeDefs = MaskPlaneDict());
107  explicit Mask(unsigned int width, unsigned int height, MaskPixelT initialValue,
108  MaskPlaneDict const& planeDefs = MaskPlaneDict());
116  MaskPlaneDict const& planeDefs = MaskPlaneDict());
124  explicit Mask(lsst::geom::Extent2I const& dimensions, MaskPixelT initialValue,
125  MaskPlaneDict const& planeDefs = MaskPlaneDict());
132  explicit Mask(lsst::geom::Box2I const& bbox, MaskPlaneDict const& planeDefs = MaskPlaneDict());
140  explicit Mask(lsst::geom::Box2I const& bbox, MaskPixelT initialValue,
141  MaskPlaneDict const& planeDefs = MaskPlaneDict());
142 
163  explicit Mask(std::string const& fileName, int hdu = fits::DEFAULT_HDU,
167  bool conformMasks = false, bool allowUnsafe = false);
168 
189  explicit Mask(fits::MemFileManager& manager, int hdu = fits::DEFAULT_HDU,
193  bool conformMasks = false, bool allowUnsafe = false);
194 
212  explicit Mask(fits::Fits& fitsfile,
216  bool conformMasks = false, bool allowUnsafe = false);
217 
218  // generalised copy constructor
219  template <typename OtherPixelT>
220  Mask(Mask<OtherPixelT> const& rhs, const bool deep)
221  : image::ImageBase<MaskPixelT>(rhs, deep), _maskDict(rhs._maskDict) {}
222 
229  Mask(const Mask& src, const bool deep = false);
230  Mask(Mask&& src);
231  ~Mask() override;
240  Mask(const Mask& src, const lsst::geom::Box2I& bbox, ImageOrigin const origin = PARENT,
241  const bool deep = false);
242 
243  explicit Mask(ndarray::Array<MaskPixelT, 2, 1> const& array, bool deep = false,
245 
246  void swap(Mask& rhs);
247  // Operators
248 
249  Mask& operator=(MaskPixelT const rhs);
250  Mask& operator=(const Mask& rhs);
251  Mask& operator=(Mask&& rhs);
252 
254  Mask& operator|=(Mask const& rhs);
256  Mask& operator|=(MaskPixelT const rhs);
257 
259  Mask& operator&=(Mask const& rhs);
261  Mask& operator&=(MaskPixelT const rhs);
262 
277  return Mask(*this, bbox, origin, false);
278  }
279 
281  Mask operator[](lsst::geom::Box2I const& bbox) const { return subset(bbox); }
282 
284 
290  static MaskPixelT getPlaneBitMask(const std::vector<std::string>& names);
291 
293  Mask& operator^=(Mask const& rhs);
295  Mask& operator^=(MaskPixelT const rhs);
296 
310  typename ImageBase<MaskPixelT>::PixelConstReference operator()(int x, int y) const;
318  bool operator()(int x, int y, int plane) const;
326  typename ImageBase<MaskPixelT>::PixelReference operator()(int x, int y, CheckIndices const& check);
335  CheckIndices const& check) const;
344  bool operator()(int x, int y, int plane, CheckIndices const& check) const;
345 
353  void writeFits(std::string const& fileName,
356  std::string const& mode = "w") const;
357 
368  std::string const& mode = "w") const;
369 
378 
387  void writeFits(std::string const& filename, fits::ImageWriteOptions const& options,
388  std::string const& mode = "w",
389  std::shared_ptr<daf::base::PropertySet const> header = nullptr) const;
390 
400  std::string const& mode = "w",
401  std::shared_ptr<daf::base::PropertySet const> header = nullptr) const;
402 
410  void writeFits(fits::Fits& fitsfile, fits::ImageWriteOptions const& options,
411  std::shared_ptr<daf::base::PropertySet const> header = nullptr) const;
412 
421  static Mask readFits(std::string const& filename, int hdu = fits::DEFAULT_HDU) {
422  return Mask<MaskPixelT>(filename, hdu);
423  }
424 
433  static Mask readFits(fits::MemFileManager& manager, int hdu = fits::DEFAULT_HDU) {
434  return Mask<MaskPixelT>(manager, hdu);
435  }
436 
438  static std::string interpret(MaskPixelT value);
439  std::string getAsString(int x, int y) { return interpret((*this)(x, y)); }
440 
441  // Mask Plane ops
442 
444  void clearAllMaskPlanes();
446  void clearMaskPlane(int plane);
450  void setMaskPlaneValues(const int plane, const int x0, const int x1, const int y);
458  //
459  // Operations on the mask plane dictionary
460  //
462  static void clearMaskPlaneDict();
463  static int addMaskPlane(const std::string& name);
464  static void removeMaskPlane(const std::string& name);
474  void removeAndClearMaskPlane(const std::string& name, bool const removeFromDefault = false);
475 
481  static int getMaskPlane(const std::string& name);
487  static MaskPixelT getPlaneBitMask(const std::string& name);
488 
489  static int getNumPlanesMax() { return 8 * sizeof(MaskPixelT); }
490  static int getNumPlanesUsed();
494  MaskPlaneDict const& getMaskPlaneDict() const;
496  void printMaskPlanes() const;
497 
502  //
503  // This one isn't static, it fixes up a given Mask's planes
518  void conformMaskPlanes(const MaskPlaneDict& masterPlaneDict);
519 
520 private:
521  friend class MaskFitsReader;
522 
523  std::shared_ptr<detail::MaskDict> _maskDict; // our bitplane dictionary
524 
525  static std::shared_ptr<detail::MaskDict> _maskPlaneDict();
526  static int _setMaskPlaneDict(MaskPlaneDict const& mpd);
527  static const std::string maskPlanePrefix;
528 
537  static int addMaskPlane(std::string name, int plane);
538 
540  static int getMaskPlaneNoThrow(const std::string& name);
542  static MaskPixelT getBitMaskNoThrow(int plane);
548  static MaskPixelT getBitMask(int plane);
549 
553  void _initializePlanes(MaskPlaneDict const& planeDefs); // called by ctors
554 
555  //
556  // Make names in templatized base class visible (Meyers, Effective C++, Item 43)
557  //
560 
566  void checkMaskDictionaries(Mask const& other);
567 };
568 
569 template <typename PixelT>
570 void swap(Mask<PixelT>& a, Mask<PixelT>& b);
571 } // namespace image
572 } // namespace afw
573 } // namespace lsst
574 
575 #endif // LSST_AFW_IMAGE_MASK_H
y
int y
Definition: SpanSet.cc:49
lsst::afw::image::MaskFitsReader
A FITS reader class for Masks.
Definition: MaskFitsReader.h:39
lsst::afw::image
Backwards-compatibility support for depersisting the old Calib (FluxMag0/FluxMag0Err) objects.
Definition: imageAlgorithm.dox:1
lsst::afw::image::Mask::writeFits
void writeFits(fits::MemFileManager &manager, fits::ImageWriteOptions const &options, std::string const &mode="w", std::shared_ptr< daf::base::PropertySet const > header=nullptr) const
Write a mask to a FITS RAM file.
std::string
STL class.
std::shared_ptr< lsst::daf::base::PropertySet >
lsst::afw::image::Mask
Represent a 2-dimensional array of bitmask pixels.
Definition: Mask.h:77
lsst::afw::image::detail::MaskPlaneDict
std::map< std::string, int > MaskPlaneDict
Definition: Mask.h:58
lsst::afw::image::Mask::Mask
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)
Construct a Mask by reading a regular FITS file.
lsst::afw::image::Mask::interpret
static std::string interpret(MaskPixelT value)
Interpret a mask value as a comma-separated list of mask plane names.
Definition: Mask.cc:252
lsst::afw::image::Mask::Mask
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)
Construct a Mask from an already-open FITS object.
lsst::afw::fits::DEFAULT_HDU
const int DEFAULT_HDU
Specify that the default HDU should be read.
Definition: fitsDefaults.h:18
lsst::afw::image::Mask::readFits
static Mask readFits(std::string const &filename, int hdu=fits::DEFAULT_HDU)
Read a Mask from a regular FITS file.
Definition: Mask.h:421
lsst::afw::image::Mask::getNumPlanesMax
static int getNumPlanesMax()
Definition: Mask.h:489
lsst::afw::image::Mask::operator&=
Mask & operator&=(Mask const &rhs)
AND a Mask into a Mask.
Definition: Mask.cc:532
lsst::afw::image::Mask::writeFits
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
Write a mask to a regular FITS file.
lsst::afw::fits::Fits
A simple struct that combines the two arguments that must be passed to most cfitsio routines and cont...
Definition: fits.h:297
std::vector< std::string >
lsst::afw::image::Mask::ImageTypeFactory::type
Mask< MaskPT > type
Return the desired type.
Definition: Mask.h:87
lsst::afw::image::Mask::operator=
Mask & operator=(MaskPixelT const rhs)
Definition: Mask.cc:159
ImageBase.h
lsst::afw::image::Mask::writeFits
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
Write a mask to a FITS RAM file.
lsst::afw::image::Mask::parseMaskPlaneMetadata
static MaskPlaneDict parseMaskPlaneMetadata(std::shared_ptr< lsst::daf::base::PropertySet const > metadata)
Given a PropertySet that contains the MaskPlane assignments, setup the MaskPlanes.
Definition: Mask.cc:604
lsst::afw::image::Mask::Mask
Mask(Mask< OtherPixelT > const &rhs, const bool deep)
Definition: Mask.h:220
lsst::afw::image::Mask::operator[]
Mask operator[](lsst::geom::Box2I const &bbox) const
Return a subimage corresponding to the given box (interpreted as PARENT coordinates).
Definition: Mask.h:281
lsst::afw
Definition: imageAlgorithm.dox:1
lsst::afw::image::Mask::clearAllMaskPlanes
void clearAllMaskPlanes()
Clear all the pixels.
Definition: Mask.cc:398
lsst::afw::image::Mask::readFits
static Mask readFits(fits::MemFileManager &manager, int hdu=fits::DEFAULT_HDU)
Read a Mask from a FITS RAM file.
Definition: Mask.h:433
lsst::afw::fits::MemFileManager
Lifetime-management for memory that goes into FITS memory files.
Definition: fits.h:121
lsst::afw::geom.transform.transformContinued.name
string name
Definition: transformContinued.py:32
lsst::afw::image::Mask::getNumPlanesUsed
static int getNumPlanesUsed()
Definition: Mask.cc:388
lsst::afw::image::Mask::getMaskPlane
static int getMaskPlane(const std::string &name)
Return the mask plane number corresponding to a plane name.
Definition: Mask.cc:357
lsst::afw::image::Mask::Mask
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)
Construct a Mask by reading a FITS image in memory.
lsst::afw::image::Mask::Mask
Mask(unsigned int width, unsigned int height, MaskPlaneDict const &planeDefs=MaskPlaneDict())
Construct a Mask initialized to 0x0.
Definition: Mask.cc:69
lsst::afw::image::Mask::MaskPlaneDict
detail::MaskPlaneDict MaskPlaneDict
Definition: Mask.h:79
lsst::afw::fits::ImageWriteOptions
Options for writing an image to FITS.
Definition: fits.h:219
lsst::afw::image::Mask::addMaskPlanesToMetadata
static void addMaskPlanesToMetadata(std::shared_ptr< lsst::daf::base::PropertySet >)
Given a PropertySet, replace any existing MaskPlane assignments with the current ones.
Definition: Mask.cc:576
src
std::shared_ptr< RecordT > src
Definition: Match.cc:48
lsst::afw::image::Mask::operator|=
Mask & operator|=(Mask const &rhs)
OR a Mask into a Mask.
Definition: Mask.cc:512
lsst::afw::image::Mask::removeAndClearMaskPlane
void removeAndClearMaskPlane(const std::string &name, bool const removeFromDefault=false)
Clear all pixels of the specified mask and remove the plane from the mask plane dictionary; optionall...
Definition: Mask.cc:316
lsst::afw::image::Mask::clearMaskPlaneDict
static void clearMaskPlaneDict()
Reset the maskPlane dictionary.
Definition: Mask.cc:393
lsst::afw::image::Mask::getPlaneBitMask
static MaskPixelT getPlaneBitMask(const std::vector< std::string > &names)
Return the bitmask corresponding to a vector of plane names OR'd together.
Definition: Mask.cc:379
lsst::afw::image::Mask::swap
void swap(Mask &rhs)
Definition: Mask.cc:133
lsst::afw::image::detail::Mask_tag
tag for a Mask
Definition: Mask.h:56
lsst::afw::image::ImageBase::PixelReference
Reference< PixelT >::type PixelReference
A Reference to a PixelT.
Definition: ImageBase.h:117
x
double x
Definition: ChebyshevBoundedField.cc:277
fitsDefaults.h
other
ItemVariant const * other
Definition: Schema.cc:56
PropertySet.h
lsst::afw::image::Mask::operator^=
Mask & operator^=(Mask const &rhs)
XOR a Mask into a Mask.
Definition: Mask.cc:553
dimensions
afw::table::PointKey< int > dimensions
Definition: GaussianPsf.cc:49
lsst::afw::image::Mask::getAsString
std::string getAsString(int x, int y)
Definition: Mask.h:439
lsst::afw::image::Mask::writeFits
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
Write a mask to a regular FITS file.
std::map< std::string, int >
lsst::afw::image::CheckIndices
A class used to request that array accesses be checked.
Definition: ImageBase.h:74
lsst::afw::image::Mask::writeFits
void writeFits(fits::Fits &fitsfile, fits::ImageWriteOptions const &options, std::shared_ptr< daf::base::PropertySet const > header=nullptr) const
Write a mask to an open FITS file object.
b
table::Key< int > b
Definition: TransmissionCurve.cc:467
base.h
lsst
A base class for image defects.
Definition: imageAlgorithm.dox:1
lsst::afw::image::Mask::printMaskPlanes
void printMaskPlanes() const
print the mask plane dictionary to std::cout
Definition: Mask.cc:645
lsst::afw::image::Mask::ImageTypeFactory
A templated class to return this classes' type (present in Image/Mask/MaskedImage)
Definition: Mask.h:85
lsst::afw::image::Mask::conformMaskPlanes
void conformMaskPlanes(const MaskPlaneDict &masterPlaneDict)
Adjust this mask to conform to the standard Mask class's mask plane dictionary, adding any new mask p...
Definition: Mask.cc:408
LsstImageTypes.h
lsst::afw::image::Mask::addMaskPlane
static int addMaskPlane(const std::string &name)
Definition: Mask.cc:267
lsst::afw::image::Mask::removeMaskPlane
static void removeMaskPlane(const std::string &name)
Definition: Mask.cc:305
lsst::afw::image::Mask::subset
Mask subset(lsst::geom::Box2I const &bbox, ImageOrigin origin=PARENT) const
Return a subimage corresponding to the given box.
Definition: Mask.h:276
a
table::Key< int > a
Definition: TransmissionCurve.cc:466
lsst::geom::Point< int, 2 >
lsst::afw::image::Mask::writeFits
void writeFits(fits::Fits &fitsfile, std::shared_ptr< lsst::daf::base::PropertySet const > metadata=std::shared_ptr< lsst::daf::base::PropertySet const >()) const
Write a mask to an open FITS file object.
lsst::afw::image::Mask::~Mask
~Mask() override
lsst::geom::Box2I
An integer coordinate rectangle.
Definition: Box.h:55
lsst::afw::image::PARENT
@ PARENT
Definition: ImageBase.h:94
lsst::afw::image::swap
void swap(Image< PixelT > &a, Image< PixelT > &b)
Definition: Image.cc:456
lsst::afw::image::Mask::getMaskPlaneDict
MaskPlaneDict const & getMaskPlaneDict() const
Return the Mask's maskPlaneDict.
Definition: Mask.cc:300
lsst::afw::image::Mask::operator()
ImageBase< MaskPixelT >::PixelReference operator()(int x, int y)
get a reference to the specified pixel
Definition: Mask.cc:464
lsst::afw::image::ImageOrigin
ImageOrigin
Definition: ImageBase.h:94
lsst::afw::image::ImageBase::PixelConstReference
ConstReference< PixelT >::type PixelConstReference
A ConstReference to a PixelT.
Definition: ImageBase.h:119
lsst::afw::image::detail::basic_tag
Base image tag.
Definition: ImageBase.h:61
lsst::afw::image::ImageBase
The base class for all image classed (Image, Mask, MaskedImage, ...)
Definition: ImageBase.h:102
lsst::afw::image::Mask::clearMaskPlane
void clearMaskPlane(int plane)
Clear the specified bit in all pixels.
Definition: Mask.cc:403
lsst::geom::Extent< int, 2 >
lsst::afw::image::Mask::setMaskPlaneValues
void setMaskPlaneValues(const int plane, const int x0, const int x1, const int y)
Set the bit specified by "planeId" for pixels (x0, y) ...
Definition: Mask.cc:567
lsst::afw::image::Mask::image_category
detail::Mask_tag image_category
Definition: Mask.h:81
exceptions.h
bbox
AmpInfoBoxKey bbox
Definition: Amplifier.cc:117