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 <utility>
#include <functional>

#include "boost/mpl/bool.hpp"
#include <climits>
#include <memory>

#include "lsst/geom.h"
#include "lsst/afw/image/ImageBase.h"
#include "lsst/afw/image/lsstGil.h"
#include "lsst/afw/image/ImageUtils.h"
#include "lsst/afw/image/Mask.h"
#include "lsst/afw/math/Function.h"
#include "lsst/afw/fitsDefaults.h"
#include "lsst/daf/base/PropertySet.h"
#include "lsst/daf/base/Citizen.h"
#include "lsst/pex/exceptions.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;

    typedef detail::Image_tag image_category;

    template <typename ImagePT = PixelT>
    struct ImageTypeFactory {
        typedef Image<ImagePT> type;
    };
    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,
                   std::shared_ptr<lsst::daf::base::PropertySet const> metadata =
                           std::shared_ptr<lsst::daf::base::PropertySet const>(),
                   std::string const& mode = "w") const;

    void writeFits(fits::MemFileManager& manager,
                   std::shared_ptr<lsst::daf::base::PropertySet const> metadata =
                           std::shared_ptr<lsst::daf::base::PropertySet const>(),
                   std::string const& mode = "w") const;

    void writeFits(fits::Fits& fitsfile, std::shared_ptr<lsst::daf::base::PropertySet const> metadata =
                                                 std::shared_ptr<lsst::daf::base::PropertySet const>()) const;

    void writeFits(std::string const& filename, fits::ImageWriteOptions const& options,
                   std::string const& mode = "w",
                   std::shared_ptr<daf::base::PropertySet const> header = nullptr,
                   std::shared_ptr<Mask<MaskPixel> const> mask = nullptr) const;

    void writeFits(fits::MemFileManager& manager, fits::ImageWriteOptions const& options,
                   std::string const& mode = "w",
                   std::shared_ptr<daf::base::PropertySet const> header = nullptr,
                   std::shared_ptr<Mask<MaskPixel> const> mask = nullptr) const;

    void writeFits(fits::Fits& fitsfile, fits::ImageWriteOptions const& options,
                   std::shared_ptr<daf::base::PropertySet const> header = nullptr,
                   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(double 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(double const c, Image<PixelT> const& rhs);
    Image& operator*=(PixelT const rhs);
    Image& operator*=(Image<PixelT> const& rhs);
    void scaledMultiplies(double const c, Image<PixelT> const& rhs);
    Image& operator/=(PixelT const rhs);
    Image& operator/=(Image<PixelT> const& rhs);
    void scaledDivides(double 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 lsst::daf::base::Citizen {
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,
                   std::shared_ptr<lsst::daf::base::PropertySet const> metadata =
                           std::shared_ptr<lsst::daf::base::PropertySet const>(),
                   std::string const& mode = "w") const;

    void writeFits(std::string const& fileName, fits::ImageWriteOptions const& options,
                   std::shared_ptr<lsst::daf::base::PropertySet const> metadata =
                           std::shared_ptr<lsst::daf::base::PropertySet const>(),
                   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