LSST Applications  21.0.0+04719a4bac,21.0.0-1-ga51b5d4+f5e6047307,21.0.0-11-g2b59f77+a9c1acf22d,21.0.0-11-ga42c5b2+86977b0b17,21.0.0-12-gf4ce030+76814010d2,21.0.0-13-g1721dae+760e7a6536,21.0.0-13-g3a573fe+768d78a30a,21.0.0-15-g5a7caf0+f21cbc5713,21.0.0-16-g0fb55c1+b60e2d390c,21.0.0-19-g4cded4ca+71a93a33c0,21.0.0-2-g103fe59+bb20972958,21.0.0-2-g45278ab+04719a4bac,21.0.0-2-g5242d73+3ad5d60fb1,21.0.0-2-g7f82c8f+8babb168e8,21.0.0-2-g8f08a60+06509c8b61,21.0.0-2-g8faa9b5+616205b9df,21.0.0-2-ga326454+8babb168e8,21.0.0-2-gde069b7+5e4aea9c2f,21.0.0-2-gecfae73+1d3a86e577,21.0.0-2-gfc62afb+3ad5d60fb1,21.0.0-25-g1d57be3cd+e73869a214,21.0.0-3-g357aad2+ed88757d29,21.0.0-3-g4a4ce7f+3ad5d60fb1,21.0.0-3-g4be5c26+3ad5d60fb1,21.0.0-3-g65f322c+e0b24896a3,21.0.0-3-g7d9da8d+616205b9df,21.0.0-3-ge02ed75+a9c1acf22d,21.0.0-4-g591bb35+a9c1acf22d,21.0.0-4-g65b4814+b60e2d390c,21.0.0-4-gccdca77+0de219a2bc,21.0.0-4-ge8a399c+6c55c39e83,21.0.0-5-gd00fb1e+05fce91b99,21.0.0-6-gc675373+3ad5d60fb1,21.0.0-64-g1122c245+4fb2b8f86e,21.0.0-7-g04766d7+cd19d05db2,21.0.0-7-gdf92d54+04719a4bac,21.0.0-8-g5674e7b+d1bd76f71f,master-gac4afde19b+a9c1acf22d,w.2021.13
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  typedef typename ImageT::image_category 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  typedef typename boost::gil::channel_traits<PixelT>::reference type;
87 };
89 template <typename PixelT>
91  typedef typename boost::gil::channel_traits<PixelT>::const_reference type;
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  typedef typename lsst::afw::image::detail::types_traits<PixelT>::view_t _view_t;
105  typedef typename lsst::afw::image::detail::types_traits<PixelT>::const_view_t _const_view_t;
106 
107  typedef ndarray::Manager Manager;
108 
109 public:
111 
115  typedef PixelT Pixel;
121  typedef typename _view_t::xy_locator xy_locator;
123  typedef typename _view_t::xy_locator::const_t const_xy_locator;
125  typedef typename _view_t::iterator iterator;
127  typedef typename _const_view_t::iterator const_iterator;
129  typedef typename _view_t::reverse_iterator reverse_iterator;
131  typedef typename _const_view_t::reverse_iterator const_reverse_iterator;
133  typedef typename _view_t::x_iterator x_iterator;
139  typedef typename _view_t::x_iterator xy_x_iterator;
141  typedef typename _const_view_t::x_iterator const_x_iterator;
143  typedef typename _view_t::y_iterator y_iterator;
145  typedef typename _view_t::y_iterator xy_y_iterator;
147  typedef typename _const_view_t::y_iterator const_y_iterator;
149  typedef typename ndarray::Array<PixelT, 2, 1> Array;
151  typedef typename ndarray::Array<PixelT const, 2, 1> ConstArray;
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:62
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:49
std::shared_ptr< RecordT > src
Definition: Match.cc:48
int y
Definition: SpanSet.cc:49
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:404
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:268
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
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
PixelT Pixel
A pixel in this ImageBase.
Definition: ImageBase.h:115
iterator begin() const
Return an STL compliant iterator to the start of the image.
Definition: Image.cc:263
_const_view_t::x_iterator const_x_iterator
A const iterator for traversing the pixels in a row.
Definition: ImageBase.h:141
void setXY0(int const x0, int const y0)
Set the ImageBase's origin.
Definition: ImageBase.h:443
static _view_t _allocateView(lsst::geom::Extent2I const &dimensions, Manager::Ptr &manager)
Definition: Image.cc:58
_const_view_t::reverse_iterator const_reverse_iterator
An STL compliant const reverse iterator.
Definition: ImageBase.h:131
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
_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
_view_t::xy_locator xy_locator
An xy_locator.
Definition: ImageBase.h:121
Reference< PixelT >::type PixelReference
A Reference to a PixelT.
Definition: ImageBase.h:117
PixelReference operator()(int x, int y)
Return a reference to the pixel (x, y) in LOCAL coordinates.
Definition: Image.cc:184
static _view_t _makeSubView(lsst::geom::Extent2I const &dimensions, lsst::geom::Extent2I const &offset, const _view_t &view)
Definition: Image.cc:78
int getWidth() const
Return the number of columns in the image.
Definition: ImageBase.h:294
_view_t::reverse_iterator reverse_iterator
An STL compliant reverse iterator.
Definition: ImageBase.h:129
x_iterator fast_iterator
A fast STL compliant iterator for contiguous images N.b.
Definition: ImageBase.h:137
lsst::geom::Box2I getBBox(ImageOrigin origin=PARENT) const
Definition: ImageBase.h:445
detail::basic_tag image_category
trait class to identify type of image
Definition: ImageBase.h:110
ndarray::Array< PixelT, 2, 1 > Array
A mutable ndarray representation of the image.
Definition: ImageBase.h:149
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
_const_view_t::y_iterator const_y_iterator
A const iterator for traversing the pixels in a column.
Definition: ImageBase.h:147
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:166
int getHeight() const
Return the number of rows in the image.
Definition: ImageBase.h:296
_view_t::iterator iterator
An STL compliant iterator.
Definition: ImageBase.h:125
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:153
PixelT SinglePixel
A single Pixel of the same type as those in the ImageBase.
Definition: ImageBase.h:113
iterator at(int x, int y) const
Return an STL compliant iterator at the point (x, y)
Definition: Image.cc:283
ConstReference< PixelT >::type PixelConstReference
A ConstReference to a PixelT.
Definition: ImageBase.h:119
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
_view_t::xy_locator::const_t const_xy_locator
A const_xy_locator.
Definition: ImageBase.h:123
_view_t::y_iterator y_iterator
An iterator for traversing the pixels in a column.
Definition: ImageBase.h:143
reverse_iterator rbegin() const
Return an STL compliant reverse iterator to the start of the image.
Definition: Image.cc:273
virtual ~ImageBase()=default
ndarray::Array< PixelT const, 2, 1 > ConstArray
An immutable ndarray representation of the image.
Definition: ImageBase.h:151
_view_t _getRawView() const
Definition: ImageBase.h:465
_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
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:222
_const_view_t::iterator const_iterator
An STL compliant const iterator.
Definition: ImageBase.h:127
_view_t::x_iterator x_iterator
An iterator for traversing the pixels in a row.
Definition: ImageBase.h:133
lsst::geom::Point2I getXY0() const
Return the image's origin.
Definition: ImageBase.h:323
void swap(ImageBase &rhs)
Definition: Image.cc:246
static SinglePixel PixelCast(SinglePixelT rhs)
Convert a type to our SinglePixel type.
Definition: ImageBase.h:158
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:278
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:456
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
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
boost::gil::channel_traits< PixelT >::reference type
reference type
Definition: ImageBase.h:86
traits class for image categories
Definition: ImageBase.h:66
ImageT::image_category image_category
Definition: ImageBase.h:67
T swap(T... args)