Image.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/>.
 */
 
/*
 * 2-D images
 *
 * This file contains the 2-d image support for LSST
 */
#ifndef LSST_AFW_IMAGE_IMAGE_H
#define LSST_AFW_IMAGE_IMAGE_H
 
#include <string>
 
#include <climits>
#include <memory>
 
#include "lsst/geom.h"
#include "lsst/afw/image/ImageBase.h"
#include "lsst/afw/image/Mask.h"
#include "lsst/afw/math/Function.h"
#include "lsst/daf/base/PropertySet.h"
#include "ndarray.h"
 
namespace lsst {
namespace afw {
namespace image {
 
template <typename PixelT>
class Image : public ImageBase<PixelT> {
public:
    template <typename, typename, typename>
    friend class MaskedImage;
 
    using image_category = detail::Image_tag;
 
    template <typename ImagePT = PixelT>
    struct ImageTypeFactory {
        using type = Image<ImagePT>;
    };
    template <typename OtherPixelT>
    friend class Image;  // needed by generalised copy constructors
 
    explicit Image(unsigned int width, unsigned int height, PixelT initialValue = 0);
    explicit Image(lsst::geom::Extent2I const& dimensions = lsst::geom::Extent2I(), PixelT initialValue = 0);
    explicit Image(lsst::geom::Box2I const& bbox, PixelT initialValue = 0);
 
    explicit Image(Image const& rhs, lsst::geom::Box2I const& bbox, ImageOrigin const origin = PARENT,
                   const bool deep = false);
    Image(const Image& rhs, const bool deep = false);
    Image(Image&& rhs);
 
    explicit Image(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 allowUnsafe = false);
 
    explicit Image(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 allowUnsafe = false);
 
    explicit Image(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 allowUnsafe = false);
 
    // generalised copy constructor
    template <typename OtherPixelT>
    Image(Image<OtherPixelT> const& rhs, const bool deep) : image::ImageBase<PixelT>(rhs, deep) {}
 
    explicit Image(ndarray::Array<PixelT, 2, 1> const& array, bool deep = false,
                   lsst::geom::Point2I const& xy0 = lsst::geom::Point2I())
            : image::ImageBase<PixelT>(array, deep, xy0) {}
 
    ~Image() override = default;
    //
    // Assignment operators are not inherited
    //
    Image& operator=(const PixelT rhs);
    Image& operator=(const Image& rhs);
    Image& operator=(Image&& rhs);
 
    Image subset(lsst::geom::Box2I const& bbox, ImageOrigin origin = PARENT) const {
        return Image(*this, bbox, origin, false);
    }
 
    Image operator[](lsst::geom::Box2I const& bbox) const { return subset(bbox); }
 
    using ImageBase<PixelT>::operator[];
 
 
    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,
                   Mask<MaskPixel> const * mask = 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,
                   std::shared_ptr<Mask<MaskPixel> const> mask = nullptr) const;
 
 
    void writeFits(fits::MemFileManager& manager, fits::ImageWriteOptions const& options,
                   std::string const& mode = "w",
                   daf::base::PropertySet const * header = nullptr,
                   Mask<MaskPixel> const *mask = 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,
                   std::shared_ptr<Mask<MaskPixel> const> mask = nullptr) const;
 
 
    void writeFits(fits::Fits& fitsfile, fits::ImageWriteOptions const& options,
                   daf::base::PropertySet const * header = nullptr,
                   Mask<MaskPixel> const * mask = 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,
                   std::shared_ptr<Mask<MaskPixel> const> mask = nullptr) const;
 
    static Image readFits(std::string const& filename, int hdu = fits::DEFAULT_HDU) {
        return Image<PixelT>(filename, hdu);
    }
 
    static Image readFits(fits::MemFileManager& manager, int hdu = fits::DEFAULT_HDU) {
        return Image<PixelT>(manager, hdu);
    }
 
    void swap(Image& rhs);
    //
    // Operators etc.
    //
    Image& operator+=(PixelT const rhs);
    virtual Image& operator+=(Image<PixelT> const& rhs);
    Image& operator+=(lsst::afw::math::Function2<double> const& function);
    void scaledPlus(PixelT const c, Image<PixelT> const& rhs);
    Image& operator-=(PixelT const rhs);
    Image& operator-=(Image<PixelT> const& rhs);
    Image& operator-=(lsst::afw::math::Function2<double> const& function);
    void scaledMinus(PixelT const c, Image<PixelT> const& rhs);
    Image& operator*=(PixelT const rhs);
    Image& operator*=(Image<PixelT> const& rhs);
    void scaledMultiplies(PixelT const c, Image<PixelT> const& rhs);
    Image& operator/=(PixelT const rhs);
    Image& operator/=(Image<PixelT> const& rhs);
    void scaledDivides(PixelT const c, Image<PixelT> const& rhs);
 
    // In-place per-pixel sqrt().  Useful when handling variance planes.
    void sqrt();
 
protected:
    using ImageBase<PixelT>::_getRawView;
};
 
template <typename LhsPixelT, typename RhsPixelT>
Image<LhsPixelT>& operator+=(Image<LhsPixelT>& lhs, Image<RhsPixelT> const& rhs);
template <typename LhsPixelT, typename RhsPixelT>
Image<LhsPixelT>& operator-=(Image<LhsPixelT>& lhs, Image<RhsPixelT> const& rhs);
template <typename LhsPixelT, typename RhsPixelT>
Image<LhsPixelT>& operator*=(Image<LhsPixelT>& lhs, Image<RhsPixelT> const& rhs);
template <typename LhsPixelT, typename RhsPixelT>
Image<LhsPixelT>& operator/=(Image<LhsPixelT>& lhs, Image<RhsPixelT> const& rhs);
 
template <typename PixelT>
void swap(Image<PixelT>& a, Image<PixelT>& b);
 
template <typename PixelT>
class DecoratedImage {
public:
    explicit DecoratedImage(const lsst::geom::Extent2I& dimensions = lsst::geom::Extent2I());
    explicit DecoratedImage(const lsst::geom::Box2I& bbox);
    explicit DecoratedImage(std::shared_ptr<Image<PixelT>> rhs);
    DecoratedImage(DecoratedImage const& rhs, const bool deep = false);
    explicit DecoratedImage(std::string const& fileName, const int hdu = fits::DEFAULT_HDU,
                            lsst::geom::Box2I const& bbox = lsst::geom::Box2I(),
                            ImageOrigin const origin = PARENT, bool allowUnsafe = false);
 
    DecoratedImage& operator=(const DecoratedImage& image);
 
    std::shared_ptr<lsst::daf::base::PropertySet> getMetadata() const { return _metadata; }
    void setMetadata(std::shared_ptr<lsst::daf::base::PropertySet> metadata) { _metadata = metadata; }
 
    int getWidth() const { return _image->getWidth(); }
    int getHeight() const { return _image->getHeight(); }
 
    int getX0() const { return _image->getX0(); }
    int getY0() const { return _image->getY0(); }
 
    const lsst::geom::Extent2I getDimensions() const { return _image->getDimensions(); }
 
    void swap(DecoratedImage& rhs);
 
 
    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(std::string const& fileName, fits::ImageWriteOptions const& options,
                   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, fits::ImageWriteOptions const& options,
                   std::shared_ptr<daf::base::PropertySet const> metadata,
                   std::string const& mode = "w") const;
 
    std::shared_ptr<Image<PixelT>> getImage() { return _image; }
    std::shared_ptr<Image<PixelT> const> getImage() const { return _image; }
 
    double getGain() const { return _gain; }
    void setGain(double gain) { _gain = gain; }
 
private:
    std::shared_ptr<Image<PixelT>> _image;
    std::shared_ptr<lsst::daf::base::PropertySet> _metadata;
 
    double _gain;
 
    void init();
};
 
template <typename PixelT>
void swap(DecoratedImage<PixelT>& a, DecoratedImage<PixelT>& b);
 
lsst::geom::Box2I bboxFromMetadata(daf::base::PropertySet& metadata);
 
template <typename T1, typename T2>
bool imagesOverlap(ImageBase<T1> const& image1, ImageBase<T2> const& image2);
 
}  // namespace image
}  // namespace afw
}  // namespace lsst
 
#endif