LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
ImageBase.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  * Support for 2-D images
27  *
28  * This file contains the basic 2-d image support for LSST
29  */
30 #ifndef LSST_AFW_IMAGE_IMAGEBASE_H
31 #define LSST_AFW_IMAGE_IMAGEBASE_H
32 
33 #include <string>
34 #include <utility>
35 #include <functional>
36 
37 #include <memory>
38 
39 #include "lsst/geom.h"
40 #include "lsst/afw/image/lsstGil.h"
42 #include "lsst/afw/math/Function.h"
43 #include "lsst/pex/exceptions.h"
44 #include "ndarray.h"
45 
46 namespace lsst {
47 namespace afw {
48 
49 namespace fits {
50 class Fits;
51 class MemFileManager;
52 struct ImageWriteOptions;
53 } // namespace fits
54 
55 namespace image {
56 namespace detail {
57 //
58 // Traits for image types
59 //
61 struct basic_tag {};
63 struct Image_tag : public basic_tag {};
65 template <typename ImageT>
66 struct image_traits {
67  using image_category = typename ImageT::image_category;
68 };
69 //
70 std::string const wcsNameForXY0 = "A"; // the name of the WCS to use to save (X0, Y0) to FITS files; e.g. "A"
71 } // namespace detail
72 
74 class CheckIndices {
75 public:
76  explicit CheckIndices(bool check = true) : _check(check) {}
77  operator bool() const { return _check; }
78 
79 private:
80  bool _check;
81 };
82 
84 template <typename PixelT>
85 struct Reference {
86  using type = typename boost::gil::channel_traits<PixelT>::reference;
87 };
89 template <typename PixelT>
91  using type = typename boost::gil::channel_traits<PixelT>::const_reference;
92 };
93 
95 
97 //
98 // You are not expected to use this class directly in your own code; use one of the
99 // specialised subclasses
100 //
101 template <typename PixelT>
102 class ImageBase {
103 private:
104  using _view_t = typename lsst::afw::image::detail::types_traits<PixelT>::view_t;
105  using _const_view_t = typename lsst::afw::image::detail::types_traits<PixelT>::const_view_t;
106 
107  using Manager = ndarray::Manager;
108 
109 public:
111 
115  using Pixel = PixelT;
121  using xy_locator = typename _view_t::xy_locator;
123  using const_xy_locator = typename _view_t::xy_locator::const_t;
125  using iterator = typename _view_t::iterator;
127  using const_iterator = typename _const_view_t::iterator;
129  using reverse_iterator = typename _view_t::reverse_iterator;
131  using const_reverse_iterator = typename _const_view_t::reverse_iterator;
133  using x_iterator = typename _view_t::x_iterator;
139  using xy_x_iterator = typename _view_t::x_iterator;
141  using const_x_iterator = typename _const_view_t::x_iterator;
143  using y_iterator = typename _view_t::y_iterator;
145  using xy_y_iterator = typename _view_t::y_iterator;
147  using const_y_iterator = typename _const_view_t::y_iterator;
149  using Array = typename ndarray::Array<PixelT, 2, 1>;
151  using ConstArray = typename ndarray::Array<const PixelT, 2, 1>;
152 
153  template <typename OtherPixelT>
154  friend class ImageBase; // needed by generalised copy constructors
155 
157  template <typename SinglePixelT>
158  static SinglePixel PixelCast(SinglePixelT rhs) {
159  return SinglePixel(rhs);
160  }
161  //
162  // DecoratedImage needs enough access to ImageBase to read data from disk; we might be able to design
163  // around this
164  //
165  template <typename>
166  friend class DecoratedImage;
167  template <typename, typename, typename>
168  friend class MaskedImage;
181  explicit ImageBase(const lsst::geom::Box2I& bbox);
192  ImageBase(const ImageBase& src, const bool deep = false);
208  explicit ImageBase(const ImageBase& src, const lsst::geom::Box2I& bbox, const ImageOrigin origin = PARENT,
209  const bool deep = false);
216  template <typename OtherPixelT>
217  ImageBase(const ImageBase<OtherPixelT>& rhs, const bool deep) {
218  if (!deep) {
220  "Only deep copies are permitted for ImageBases with different pixel types");
221  }
222 
223  ImageBase<PixelT> tmp(rhs.getBBox());
224  copy_and_convert_pixels(rhs._gilView, tmp._gilView); // from boost::gil
225 
226  using std::swap; // See Meyers, Effective C++, Item 25
227  ImageBase<PixelT>::swap(tmp); // See Meyers, Effective C++, Items 11 and 43
228  }
229 
239  explicit ImageBase(Array const& array, bool deep = false,
241 
242  virtual ~ImageBase() = default;
251  ImageBase& operator=(const ImageBase& rhs);
252  ImageBase& operator=(ImageBase&& rhs);
254  ImageBase& operator=(const PixelT rhs);
255 
267  void assign(ImageBase const& rhs, lsst::geom::Box2I const& bbox = lsst::geom::Box2I(),
268  ImageOrigin origin = PARENT);
269 
270  // TODO: should deprecate these, but the replacement should take two ints
271  // rather than a Point2I, to keep C++ loops simple
273  PixelReference operator()(int x, int y);
275  PixelReference operator()(int x, int y, CheckIndices const&);
277  PixelConstReference operator()(int x, int y) const;
279  PixelConstReference operator()(int x, int y, CheckIndices const&) const;
280 
282  PixelReference get(lsst::geom::Point2I const& index, ImageOrigin origin);
283 
285  PixelConstReference get(lsst::geom::Point2I const& index, ImageOrigin origin) const;
286 
288  PixelReference operator[](lsst::geom::Point2I const& index) { return get(index, PARENT); }
289 
291  PixelConstReference operator[](lsst::geom::Point2I const& index) const { return get(index, PARENT); }
292 
294  int getWidth() const { return _gilView.width(); }
296  int getHeight() const { return _gilView.height(); }
298  int getArea() const { return getWidth()*getHeight(); }
306  int getX0() const { return _origin.getX(); }
314  int getY0() const { return _origin.getY(); }
315 
323  lsst::geom::Point2I getXY0() const { return _origin; }
324 
331  double const pos,
332  lsst::afw::image::xOrY const xy
333  ) const {
334  double const fullIndex = pos - PixelZeroPos - (xy == X ? getX0() : getY0());
335  int const roundedIndex = static_cast<int>(fullIndex + 0.5);
336  double const residual = fullIndex - roundedIndex;
337  return std::pair<int, double>(roundedIndex, residual);
338  }
339 
349  inline double indexToPosition(double ind,
350  lsst::afw::image::xOrY const xy
351  ) const {
352  return ind + PixelZeroPos + (xy == X ? getX0() : getY0());
353  }
354 
357 
358  void swap(ImageBase& rhs);
359 
362  //
363  // Iterators and Locators
364  //
370  iterator begin() const;
372  iterator end() const;
374  reverse_iterator rbegin() const;
376  reverse_iterator rend() const;
378  iterator at(int x, int y) const;
379 
387  fast_iterator begin(bool contiguous) const;
395  fast_iterator end(bool contiguous) const;
396 
401  x_iterator row_begin(int y) const { return _gilView.row_begin(y); }
402 
404  x_iterator row_end(int y) const { return _gilView.row_end(y); }
405 
407  x_iterator x_at(int x, int y) const { return _gilView.x_at(x, y); }
408 
413  y_iterator col_begin(int x) const { return _gilView.col_begin(x); }
414 
416  y_iterator col_end(int x) const { return _gilView.col_end(x); }
417 
419  y_iterator y_at(int x, int y) const { return _gilView.y_at(x, y); }
420 
425  xy_locator xy_at(int x, int y) const { return xy_locator(_gilView.xy_at(x, y)); }
434  void setXY0(lsst::geom::Point2I const origin) { _origin = origin; }
443  void setXY0(int const x0, int const y0) { setXY0(lsst::geom::Point2I(x0, y0)); }
444 
446  if (origin == PARENT) {
447  return lsst::geom::Box2I(_origin, getDimensions());
448  } else
450  }
451 
452 private:
453  lsst::geom::Point2I _origin;
454  Manager::Ptr _manager;
455  _view_t _gilView;
456 
457  // oring of ImageBase in some larger image as returned to and manipulated
458  // by the user
459 
460 protected:
461  static _view_t _allocateView(lsst::geom::Extent2I const& dimensions, Manager::Ptr& manager);
462  static _view_t _makeSubView(lsst::geom::Extent2I const& dimensions, lsst::geom::Extent2I const& offset,
463  const _view_t& view);
464 
465  _view_t _getRawView() const { return _gilView; }
466 
467  inline bool isContiguous() const { return begin() + getWidth() * getHeight() == end(); }
468 };
469 
470 template <typename PixelT>
471 void swap(ImageBase<PixelT>& a, ImageBase<PixelT>& b);
472 
473 // Inline template definitions
474 
475 template <typename PixelT>
477  int rowStride = 1;
478  PixelT * data = nullptr;
479  if (getArea() > 0) {
480  data = reinterpret_cast<PixelT*>(row_begin(0));
481  }
482  if (getHeight() > 1) {
483  rowStride = reinterpret_cast<PixelT*>(row_begin(1)) - reinterpret_cast<PixelT*>(row_begin(0));
484  }
485  return ndarray::external(data,
486  ndarray::makeVector(getHeight(), getWidth()), ndarray::makeVector(rowStride, 1),
487  this->_manager);
488 }
489 
490 template <typename PixelT>
492  int rowStride = 1;
493  PixelT * data = nullptr;
494  if (getArea() > 0) {
495  data = reinterpret_cast<PixelT*>(row_begin(0));
496  }
497  if (getHeight() > 1) {
498  rowStride = reinterpret_cast<PixelT*>(row_begin(1)) - reinterpret_cast<PixelT*>(row_begin(0));
499  }
500  return ndarray::external(data,
501  ndarray::makeVector(getHeight(), getWidth()), ndarray::makeVector(rowStride, 1),
502  this->_manager);
503 }
504 
505 } // namespace image
506 } // namespace afw
507 } // namespace lsst
508 
509 #endif
AmpInfoBoxKey bbox
Definition: Amplifier.cc:117
char * data
Definition: BaseRecord.cc:61
double x
#define LSST_EXCEPT(type,...)
Create an exception with a given type.
Definition: Exception.h:48
Fits * fits
Definition: FitsWriter.cc:90
afw::table::PointKey< int > dimensions
Definition: GaussianPsf.cc:48
std::shared_ptr< RecordT > src
Definition: Match.cc:48
int y
Definition: SpanSet.cc:48
table::Key< int > b
table::Key< int > a
A class used to request that array accesses be checked.
Definition: ImageBase.h:74
CheckIndices(bool check=true)
Definition: ImageBase.h:76
A container for an Image and its associated metadata.
Definition: Image.h:397
The base class for all image classed (Image, Mask, MaskedImage, ...)
Definition: ImageBase.h:102
y_iterator col_begin(int x) const
Return an y_iterator to the start of the y'th row.
Definition: ImageBase.h:413
iterator end() const
Return an STL compliant iterator to the end of the image.
Definition: Image.cc:255
void setXY0(lsst::geom::Point2I const origin)
Set the ImageBase's origin.
Definition: ImageBase.h:434
y_iterator y_at(int x, int y) const
Return an y_iterator to the point (x, y) in the image.
Definition: ImageBase.h:419
int getX0() const
Return the image's column-origin.
Definition: ImageBase.h:306
PixelT Pixel
A pixel in this ImageBase.
Definition: ImageBase.h:115
xy_locator xy_at(int x, int y) const
Return an xy_locator at the point (x, y) in the image.
Definition: ImageBase.h:425
iterator begin() const
Return an STL compliant iterator to the start of the image.
Definition: Image.cc:250
typename _view_t::xy_locator xy_locator
An xy_locator.
Definition: ImageBase.h:121
void setXY0(int const x0, int const y0)
Set the ImageBase's origin.
Definition: ImageBase.h:443
typename _const_view_t::x_iterator const_x_iterator
A const iterator for traversing the pixels in a row.
Definition: ImageBase.h:141
static _view_t _allocateView(lsst::geom::Extent2I const &dimensions, Manager::Ptr &manager)
Definition: Image.cc:45
typename _const_view_t::iterator const_iterator
An STL compliant const iterator.
Definition: ImageBase.h:127
typename Reference< PixelT >::type PixelReference
A Reference to a PixelT.
Definition: ImageBase.h:117
std::pair< int, double > positionToIndex(double const pos, lsst::afw::image::xOrY const xy) const
Convert image position to index (nearest integer and fractional parts)
Definition: ImageBase.h:330
typename _view_t::iterator iterator
An STL compliant iterator.
Definition: ImageBase.h:125
PixelReference operator()(int x, int y)
Return a reference to the pixel (x, y) in LOCAL coordinates.
Definition: Image.cc:171
static _view_t _makeSubView(lsst::geom::Extent2I const &dimensions, lsst::geom::Extent2I const &offset, const _view_t &view)
Definition: Image.cc:65
int getWidth() const
Return the number of columns in the image.
Definition: ImageBase.h:294
typename _view_t::xy_locator::const_t const_xy_locator
A const_xy_locator.
Definition: ImageBase.h:123
typename _const_view_t::y_iterator const_y_iterator
A const iterator for traversing the pixels in a column.
Definition: ImageBase.h:147
lsst::geom::Box2I getBBox(ImageOrigin origin=PARENT) const
Definition: ImageBase.h:445
typename ndarray::Array< const PixelT, 2, 1 > ConstArray
An immutable ndarray representation of the image.
Definition: ImageBase.h:151
typename _const_view_t::reverse_iterator const_reverse_iterator
An STL compliant const reverse iterator.
Definition: ImageBase.h:131
PixelReference operator[](lsst::geom::Point2I const &index)
Return a reference to a single pixel in PARENT coordinates (with no bounds check).
Definition: ImageBase.h:288
int getY0() const
Return the image's row-origin.
Definition: ImageBase.h:314
int getArea() const
Return the area of the image.
Definition: ImageBase.h:298
x_iterator x_at(int x, int y) const
Return an x_iterator to the point (x, y) in the image.
Definition: ImageBase.h:407
lsst::geom::Extent2I getDimensions() const
Return the image's size; useful for passing to constructors.
Definition: ImageBase.h:356
typename ndarray::Array< PixelT, 2, 1 > Array
A mutable ndarray representation of the image.
Definition: ImageBase.h:149
void assign(ImageBase const &rhs, lsst::geom::Box2I const &bbox=lsst::geom::Box2I(), ImageOrigin origin=PARENT)
Copy pixels from another image to a specified subregion of this image.
Definition: Image.cc:153
x_iterator fast_iterator
A fast STL compliant iterator for contiguous images N.b.
Definition: ImageBase.h:137
typename _view_t::reverse_iterator reverse_iterator
An STL compliant reverse iterator.
Definition: ImageBase.h:129
int getHeight() const
Return the number of rows in the image.
Definition: ImageBase.h:296
y_iterator col_end(int x) const
Return an y_iterator to the start of the y'th row.
Definition: ImageBase.h:416
ImageBase & operator=(const ImageBase &rhs)
Shallow assignment operator.
Definition: Image.cc:140
iterator at(int x, int y) const
Return an STL compliant iterator at the point (x, y)
Definition: Image.cc:270
typename _view_t::y_iterator xy_y_iterator
An iterator for traversing the pixels in a row, created from an xy_locator.
Definition: ImageBase.h:145
PixelT SinglePixel
A single Pixel of the same type as those in the ImageBase.
Definition: ImageBase.h:113
ImageBase(const ImageBase< OtherPixelT > &rhs, const bool deep)
generalised copy constructor
Definition: ImageBase.h:217
double indexToPosition(double ind, lsst::afw::image::xOrY const xy) const
Convert image index to image position.
Definition: ImageBase.h:349
x_iterator row_begin(int y) const
Return an x_iterator to the start of the y'th row.
Definition: ImageBase.h:401
x_iterator row_end(int y) const
Return an x_iterator to the end of the y'th row.
Definition: ImageBase.h:404
typename _view_t::x_iterator x_iterator
An iterator for traversing the pixels in a row.
Definition: ImageBase.h:133
reverse_iterator rbegin() const
Return an STL compliant reverse iterator to the start of the image.
Definition: Image.cc:260
virtual ~ImageBase()=default
_view_t _getRawView() const
Definition: ImageBase.h:465
ConstArray getArray() const
Definition: ImageBase.h:491
PixelReference get(lsst::geom::Point2I const &index, ImageOrigin origin)
Return a reference to a single pixel (with no bounds check).
Definition: Image.cc:209
typename _view_t::y_iterator y_iterator
An iterator for traversing the pixels in a column.
Definition: ImageBase.h:143
lsst::geom::Point2I getXY0() const
Return the image's origin.
Definition: ImageBase.h:323
void swap(ImageBase &rhs)
Definition: Image.cc:233
typename ConstReference< PixelT >::type PixelConstReference
A ConstReference to a PixelT.
Definition: ImageBase.h:119
static SinglePixel PixelCast(SinglePixelT rhs)
Convert a type to our SinglePixel type.
Definition: ImageBase.h:158
typename _view_t::x_iterator xy_x_iterator
An iterator for traversing the pixels in a row, created from an xy_locator.
Definition: ImageBase.h:139
PixelConstReference operator[](lsst::geom::Point2I const &index) const
Return a reference to a single pixel in PARENT coordinates (with no bounds check).
Definition: ImageBase.h:291
reverse_iterator rend() const
Return an STL compliant reverse iterator to the end of the image.
Definition: Image.cc:265
A class to manipulate images, masks, and variance as a single object.
Definition: MaskedImage.h:73
An integer coordinate rectangle.
Definition: Box.h:55
Reports invalid arguments.
Definition: Runtime.h:66
std::string const wcsNameForXY0
Definition: ImageBase.h:70
Backwards-compatibility support for depersisting the old Calib (FluxMag0/FluxMag0Err) objects.
const double PixelZeroPos
position of center of pixel 0
Definition: ImageUtils.h:44
void swap(Image< PixelT > &a, Image< PixelT > &b)
Definition: Image.cc:442
Extent< int, 2 > Extent2I
Definition: Extent.h:397
A base class for image defects.
metafunction to extract const reference type from PixelT
Definition: ImageBase.h:90
typename boost::gil::channel_traits< PixelT >::const_reference type
const reference type
Definition: ImageBase.h:91
metafunction to extract reference type from PixelT
Definition: ImageBase.h:85
typename boost::gil::channel_traits< PixelT >::reference type
reference type
Definition: ImageBase.h:86
traits class for image categories
Definition: ImageBase.h:66
typename ImageT::image_category image_category
Definition: ImageBase.h:67
T swap(T... args)