LSSTApplications  17.0+11,17.0+34,17.0+56,17.0+57,17.0+59,17.0+7,17.0-1-g377950a+33,17.0.1-1-g114240f+2,17.0.1-1-g4d4fbc4+28,17.0.1-1-g55520dc+49,17.0.1-1-g5f4ed7e+52,17.0.1-1-g6dd7d69+17,17.0.1-1-g8de6c91+11,17.0.1-1-gb9095d2+7,17.0.1-1-ge9fec5e+5,17.0.1-1-gf4e0155+55,17.0.1-1-gfc65f5f+50,17.0.1-1-gfc6fb1f+20,17.0.1-10-g87f9f3f+1,17.0.1-11-ge9de802+16,17.0.1-16-ga14f7d5c+4,17.0.1-17-gc79d625+1,17.0.1-17-gdae4c4a+8,17.0.1-2-g26618f5+29,17.0.1-2-g54f2ebc+9,17.0.1-2-gf403422+1,17.0.1-20-g2ca2f74+6,17.0.1-23-gf3eadeb7+1,17.0.1-3-g7e86b59+39,17.0.1-3-gb5ca14a,17.0.1-3-gd08d533+40,17.0.1-30-g596af8797,17.0.1-4-g59d126d+4,17.0.1-4-gc69c472+5,17.0.1-6-g5afd9b9+4,17.0.1-7-g35889ee+1,17.0.1-7-gc7c8782+18,17.0.1-9-gc4bbfb2+3,w.2019.22
LSSTDataManagementBasePackage
MaskDict.h
Go to the documentation of this file.
1 /*
2  * Developed for the LSST Data Management System.
3  * This product includes software developed by the LSST Project
4  * (https://www.lsst.org).
5  * See the COPYRIGHT file at the top-level directory of this distribution
6  * for details of code ownership.
7  *
8  * This program is free software: you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation, either version 3 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program. If not, see <https://www.gnu.org/licenses/>.
20  */
21 
22 #ifndef LSST_AFW_IMAGE_DETAIL_MASKDICT_H
23 #define LSST_AFW_IMAGE_DETAIL_MASKDICT_H
24 
25 #include <memory>
26 #include <map>
27 #include "lsst/afw/image/Mask.h"
28 
29 namespace lsst { namespace afw { namespace image { namespace detail {
30 
31 /*
32  * MaskDict is the internal object that relates Mask's string plane names
33  * to bit IDs.
34  *
35  * The Mask public API only uses MaskPlaneDict, which is just a typedef
36  * to std::map. A MaskDict holds this MaskPlaneDict, limiting non-const
37  * access to just the add() and erase() methods in order to maintain
38  * a hash of the full dictionary for fast comparison between MaskDicts.
39  *
40  * In order to maximize consistency of mask plane definitions across different
41  * Mask instances, MaskDict also maintains a global list of all active
42  * MaskDict instances. When a plane is added to Mask, it is typically
43  * automatically added to *all* active Mask instances that do not already use
44  * that bit (via MaskDict::addMaskPlane) as well as a default MaskDict that is
45  * used when constructing future Mask instances. In contrast, when a plane is
46  * removed, it typically only affects that Mask, and if that Mask is currently
47  * using the default MaskDict, the default is redefined to a copy prior to
48  * the plane's removal (via detachDefault).
49  *
50  * To maintain that global state, all MaskDicts must be held by shared_ptr,
51  * and hence MaskDict's constructors are private, and static or instance
52  * methods that return shared_ptr are provided to replace them.
53  *
54  * MaskDict is an implementation detail (albeit and important one) and hence
55  * its "documentation" is intentionally in the form of regular comments
56  * rather than Doxygen-parsed blocks. It is also not available from Python.
57  *
58  * With the exception of addMaskPlane, all MaskDict methods provide strong
59  * exception safety.
60  */
61 class MaskDict final {
62 public:
63 
64  typedef MaskPlaneDict::value_type value_type;
65  typedef MaskPlaneDict::const_iterator const_iterator;
66 
67  // Return a new MaskDict with the same plane definitions as the given
68  // MaskPlaneDict, or return the default mask dict if it is empty.
70 
71  // Return the default MaskDict to be used for new Mask instances.
73 
74  // Set the default MaskDict.
75  static void setDefault(std::shared_ptr<MaskDict> dict);
76 
77  /*
78  * Set the default MaskDict to a copy of the current one, returning the
79  * new default.
80  */
82 
83  /*
84  * Add the given mask plane to all active MaskDicts for which there is
85  * no conflict, including the default MaskDict.
86  *
87  * MaskDicts that already have a plane with the same name or bit ID
88  * are not affected.
89  *
90  * Provides basic exception safety: mask planes may be added to some
91  * MaskDict instances even if an exception is raised while adding
92  * the mask plane to later ones (though the only exception that could
93  * be thrown in practice is std::bad_alloc).
94  */
95  static void addAllMasksPlane(std::string const & name, int bitId);
96 
97  // Assignment is disabled; we don't need it.
98  MaskDict & operator=(MaskDict const &) = delete;
99  MaskDict & operator=(MaskDict &&) = delete;
100 
101  ~MaskDict() noexcept;
102 
103  // Return a deep copy of the MaskDict.
104  std::shared_ptr<MaskDict> clone() const;
105 
106  /*
107  * Return an integer bit ID that is not currently used in this MaskDict.
108  *
109  * Always succeeds in returning a new plane (except in the extraordinarily
110  * unlikely case that int overflows), but is is the responsibility of the
111  * caller to check that the Mask pixel size has enough bits for it.
112  */
113  int getUnusedPlane() const;
114 
115  /*
116  * Return the bit ID associated with the given mask plane name.
117  *
118  * Returns -1 if no such plane is found.
119  */
120  int getMaskPlane(std::string const & name) const;
121 
122  // Write a description of the MaskDict to stdout.
123  void print() const;
124 
125  // Fast comparison of MaskDicts, using the hash (and assuming there are
126  // no unlucky collisions).
127  bool operator==(MaskDict const& rhs) const;
128  bool operator!=(MaskDict const& rhs) const { return !(*this == rhs); }
129 
130  // Iterators over MaskDict items (yields std::pair<std::string, int>).
131  const_iterator begin() const noexcept { return _dict.begin(); }
132  const_iterator end() const noexcept { return _dict.end(); }
133 
134  // Return an iterator to the item with the given name, or end().
135  const_iterator find(std::string const & name) const { return _dict.find(name); }
136 
137  // Return the number of planes in this MaskDict.
138  std::size_t size() const noexcept { return _dict.size(); }
139 
140  // Return true if the MaskDict contains no mask planes.
141  bool empty() const noexcept { return _dict.empty(); }
142 
143  // Return the internal MaskPlaneDict.
144  MaskPlaneDict const & getMaskPlaneDict() const noexcept { return _dict; }
145 
146  // Add a mask plane to just this MaskDict.
147  // If a plane with the given name already exists, it is overridden.
148  // Caller is responsible for ensuring that the bit is not in use; if it is,
149  // the MaskDict will be in a corrupted state.
150  void add(std::string const & name, int bitId);
151 
152  // Remove the plane with the given name from just this MaskDict.
153  // Does nothing if no such plane exists.
154  void erase(std::string const & name);
155 
156  // Remove all planes from this MaskDict.
157  void clear();
158 
159 private:
160 
161  class GlobalState;
162 
163  // Add mask planes that should be present on all Masks that don't
164  // explicitly remove them. Called exactly once, when initalizing
165  // GlobalState.
166  void _addInitialMaskPlanes();
167 
168  // ALL MaskDict constructors should only be from GlobalState,
169  // in order to ensure the global set of active dictionaries
170  // is kept up-to-date.
171 
172  MaskDict();
173 
174  explicit MaskDict(MaskPlaneDict const & dict);
175 
176  MaskDict(MaskDict const &) = default;
177  MaskDict(MaskDict &&) = default;
178 
179  MaskPlaneDict _dict;
180  std::size_t _hash;
181 };
182 
183 }}}} // namespace lsst::afw::image::detail
184 
185 #endif // !LSST_AFW_IMAGE_DETAIL_MASKDICT_H
static std::shared_ptr< MaskDict > getDefault()
Definition: MaskDict.cc:115
void add(std::string const &name, int bitId)
Definition: MaskDict.cc:191
T empty(T... args)
static void setDefault(std::shared_ptr< MaskDict > dict)
Definition: MaskDict.cc:119
MaskDict & operator=(MaskDict const &)=delete
static std::shared_ptr< MaskDict > detachDefault()
Definition: MaskDict.cc:123
STL namespace.
int getMaskPlane(std::string const &name) const
Definition: MaskDict.cc:176
T end(T... args)
static void addAllMasksPlane(std::string const &name, int bitId)
Definition: MaskDict.cc:127
MaskPlaneDict::value_type value_type
Definition: MaskDict.h:64
STL class.
MaskPlaneDict const & getMaskPlaneDict() const noexcept
Definition: MaskDict.h:144
const_iterator begin() const noexcept
Definition: MaskDict.h:131
void erase(std::string const &name)
Definition: MaskDict.cc:196
const_iterator end() const noexcept
Definition: MaskDict.h:132
A base class for image defects.
const_iterator find(std::string const &name) const
Definition: MaskDict.h:135
bool empty() const noexcept
Definition: MaskDict.h:141
T find(T... args)
T size(T... args)
static std::shared_ptr< MaskDict > copyOrGetDefault(MaskPlaneDict const &dict)
Definition: MaskDict.cc:111
T begin(T... args)
std::shared_ptr< MaskDict > clone() const
Definition: MaskDict.cc:146
MaskPlaneDict::const_iterator const_iterator
Definition: MaskDict.h:65
Backwards-compatibility support for depersisting the old Calib (FluxMag0/FluxMag0Err) objects...
std::size_t size() const noexcept
Definition: MaskDict.h:138