ImageBase.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/>.
 */

/*
 * Support for 2-D images
 *
 * This file contains the basic 2-d image support for LSST
 */
#ifndef LSST_AFW_IMAGE_IMAGEBASE_H
#define LSST_AFW_IMAGE_IMAGEBASE_H

#include <string>
#include <utility>
#include <functional>

#include <memory>

#include "lsst/geom.h"
#include "lsst/afw/image/lsstGil.h"
#include "lsst/afw/image/ImageUtils.h"
#include "lsst/afw/math/Function.h"
#include "lsst/pex/exceptions.h"
#include "ndarray.h"

namespace lsst {
namespace afw {

namespace fits {
class Fits;
class MemFileManager;
struct ImageWriteOptions;
}  // namespace fits

namespace image {
namespace detail {
//
// Traits for image types
//
struct basic_tag {};
struct Image_tag : public basic_tag {};
template <typename ImageT>
struct image_traits {
    typedef typename ImageT::image_category image_category;
};
//
std::string const wcsNameForXY0 = "A";  // the name of the WCS to use to save (X0, Y0) to FITS files; e.g. "A"
}  // namespace detail

class CheckIndices {
public:
    explicit CheckIndices(bool check = true) : _check(check) {}
    operator bool() const { return _check; }

private:
    bool _check;
};

template <typename PixelT>
struct Reference {
    typedef typename boost::gil::channel_traits<PixelT>::reference type;  
};
template <typename PixelT>
struct ConstReference {
    typedef typename boost::gil::channel_traits<PixelT>::const_reference type;  
};

enum ImageOrigin { PARENT, LOCAL };

//
// You are not expected to use this class directly in your own code; use one of the
// specialised subclasses
//
template <typename PixelT>
class ImageBase {
private:
    typedef typename lsst::afw::image::detail::types_traits<PixelT>::view_t _view_t;
    typedef typename lsst::afw::image::detail::types_traits<PixelT>::const_view_t _const_view_t;

    typedef ndarray::Manager Manager;

public:
    typedef detail::basic_tag image_category;  

    typedef PixelT SinglePixel;
    typedef PixelT Pixel;
    typedef typename Reference<PixelT>::type PixelReference;
    typedef typename ConstReference<PixelT>::type PixelConstReference;
    typedef typename _view_t::xy_locator xy_locator;
    typedef typename _view_t::xy_locator::const_t const_xy_locator;
    typedef typename _view_t::iterator iterator;
    typedef typename _const_view_t::iterator const_iterator;
    typedef typename _view_t::reverse_iterator reverse_iterator;
    typedef typename _const_view_t::reverse_iterator const_reverse_iterator;
    typedef typename _view_t::x_iterator x_iterator;
    typedef x_iterator fast_iterator;
    typedef typename _view_t::x_iterator xy_x_iterator;
    typedef typename _const_view_t::x_iterator const_x_iterator;
    typedef typename _view_t::y_iterator y_iterator;
    typedef typename _view_t::y_iterator xy_y_iterator;
    typedef typename _const_view_t::y_iterator const_y_iterator;
    typedef typename ndarray::Array<PixelT, 2, 1> Array;
    typedef typename ndarray::Array<PixelT const, 2, 1> ConstArray;

    template <typename OtherPixelT>
    friend class ImageBase;  // needed by generalised copy constructors

    template <typename SinglePixelT>
    static SinglePixel PixelCast(SinglePixelT rhs) {
        return SinglePixel(rhs);
    }
    //
    // DecoratedImage needs enough access to ImageBase to read data from disk; we might be able to design
    // around this
    //
    template <typename>
    friend class DecoratedImage;
    template <typename, typename, typename>
    friend class MaskedImage;
    explicit ImageBase(const lsst::geom::Extent2I& dimensions = lsst::geom::Extent2I());
    explicit ImageBase(const lsst::geom::Box2I& bbox);
    ImageBase(const ImageBase& src, const bool deep = false);
    ImageBase(ImageBase&& src);
    explicit ImageBase(const ImageBase& src, const lsst::geom::Box2I& bbox, const ImageOrigin origin = PARENT,
                       const bool deep = false);
    template <typename OtherPixelT>
    ImageBase(const ImageBase<OtherPixelT>& rhs, const bool deep) {
        if (!deep) {
            throw LSST_EXCEPT(lsst::pex::exceptions::InvalidParameterError,
                              "Only deep copies are permitted for ImageBases with different pixel types");
        }

        ImageBase<PixelT> tmp(rhs.getBBox());
        copy_and_convert_pixels(rhs._gilView, tmp._gilView);  // from boost::gil

        using std::swap;               // See Meyers, Effective C++, Item 25
        ImageBase<PixelT>::swap(tmp);  // See Meyers, Effective C++, Items 11 and 43
    }

    explicit ImageBase(Array const& array, bool deep = false,
                       lsst::geom::Point2I const& xy0 = lsst::geom::Point2I());

    virtual ~ImageBase() = default;
    ImageBase& operator=(const ImageBase& rhs);
    ImageBase& operator=(ImageBase&& rhs);
    ImageBase& operator=(const PixelT rhs);
    [[deprecated("Use `assign` instead. To be removed after 20.0.0.")]]  // DM-22276
            ImageBase&
            operator<<=(const ImageBase& rhs);

    void assign(ImageBase const& rhs, lsst::geom::Box2I const& bbox = lsst::geom::Box2I(),
                ImageOrigin origin = PARENT);

    // TODO: should deprecate these, but the replacement should take two ints
    // rather than a Point2I, to keep C++ loops simple
    PixelReference operator()(int x, int y);
    PixelReference operator()(int x, int y, CheckIndices const&);
    PixelConstReference operator()(int x, int y) const;
    PixelConstReference operator()(int x, int y, CheckIndices const&) const;


    [[deprecated("Use `operator[Point2I(x, y)]` instead. To be removed after 20.0.0.")]]  // DM-22276
            PixelConstReference
            get0(int x, int y) const {
        return operator()(x - getX0(), y - getY0());
    }
    [
            [deprecated("No replacement; `operator[Point2I(x, y)]` provides unchecked lookup. To be "
                        "removed after 20.0.0.")]]  // DM-22276
            PixelConstReference
            get0(int x, int y, CheckIndices const& check) const {
        return operator()(x - getX0(), y - getY0(), check);
    }
    [[deprecated("Use `operator[Point2I(x, y)]` instead. To be removed after 20.0.0.")]]  // DM-22276
            void
            set0(int x, int y, const PixelT v) {
        operator()(x - getX0(), y - getY0()) = v;
    }
    [
            [deprecated("No replacement; `operator[Point2I(x, y)]` provides unchecked lookup. To be "
                        "removed after 20.0.0.")]]  // DM-22276
            void
            set0(int x, int y, const PixelT v, CheckIndices const& check) {
        operator()(x - getX0(), y - getY0(), check) = v;
    }

    PixelReference get(lsst::geom::Point2I const& index, ImageOrigin origin);

    PixelConstReference get(lsst::geom::Point2I const& index, ImageOrigin origin) const;

    PixelReference operator[](lsst::geom::Point2I const& index) { return get(index, PARENT); }

    PixelConstReference operator[](lsst::geom::Point2I const& index) const { return get(index, PARENT); }

    int getWidth() const { return _gilView.width(); }
    int getHeight() const { return _gilView.height(); }
    int getX0() const { return _origin.getX(); }
    int getY0() const { return _origin.getY(); }

    lsst::geom::Point2I getXY0() const { return _origin; }

    std::pair<int, double> positionToIndex(
            double const pos,                
            lsst::afw::image::xOrY const xy  
            ) const {
        double const fullIndex = pos - PixelZeroPos - (xy == X ? getX0() : getY0());
        int const roundedIndex = static_cast<int>(fullIndex + 0.5);
        double const residual = fullIndex - roundedIndex;
        return std::pair<int, double>(roundedIndex, residual);
    }

    inline double indexToPosition(double ind,                      
                                  lsst::afw::image::xOrY const xy  
                                  ) const {
        return ind + PixelZeroPos + (xy == X ? getX0() : getY0());
    }

    lsst::geom::Extent2I getDimensions() const { return lsst::geom::Extent2I(getWidth(), getHeight()); }

    void swap(ImageBase& rhs);

    Array getArray();
    ConstArray getArray() const;
    //
    // Iterators and Locators
    //
    iterator begin() const;
    iterator end() const;
    reverse_iterator rbegin() const;
    reverse_iterator rend() const;
    iterator at(int x, int y) const;

    fast_iterator begin(bool contiguous) const;
    fast_iterator end(bool contiguous) const;

    x_iterator row_begin(int y) const { return _gilView.row_begin(y); }

    x_iterator row_end(int y) const { return _gilView.row_end(y); }

    x_iterator x_at(int x, int y) const { return _gilView.x_at(x, y); }

    y_iterator col_begin(int x) const { return _gilView.col_begin(x); }

    y_iterator col_end(int x) const { return _gilView.col_end(x); }

    y_iterator y_at(int x, int y) const { return _gilView.y_at(x, y); }

    xy_locator xy_at(int x, int y) const { return xy_locator(_gilView.xy_at(x, y)); }
    void setXY0(lsst::geom::Point2I const origin) { _origin = origin; }
    void setXY0(int const x0, int const y0) { setXY0(lsst::geom::Point2I(x0, y0)); }

    lsst::geom::Box2I getBBox(ImageOrigin origin = PARENT) const {
        if (origin == PARENT) {
            return lsst::geom::Box2I(_origin, getDimensions());
        } else
            return lsst::geom::Box2I(lsst::geom::Point2I(0, 0), getDimensions());
    }

private:
    lsst::geom::Point2I _origin;
    Manager::Ptr _manager;
    _view_t _gilView;

    // oring of ImageBase in some larger image as returned to and manipulated
    // by the user

protected:
    static _view_t _allocateView(lsst::geom::Extent2I const& dimensions, Manager::Ptr& manager);
    static _view_t _makeSubView(lsst::geom::Extent2I const& dimensions, lsst::geom::Extent2I const& offset,
                                const _view_t& view);

    _view_t _getRawView() const { return _gilView; }

    inline bool isContiguous() const { return begin() + getWidth() * getHeight() == end(); }
};

template <typename PixelT>
void swap(ImageBase<PixelT>& a, ImageBase<PixelT>& b);

// Inline template definitions

template <typename PixelT>
typename ImageBase<PixelT>::Array ImageBase<PixelT>::getArray() {
    int rowStride = reinterpret_cast<PixelT*>(row_begin(1)) - reinterpret_cast<PixelT*>(row_begin(0));
    return ndarray::external(reinterpret_cast<PixelT*>(row_begin(0)),
                             ndarray::makeVector(getHeight(), getWidth()), ndarray::makeVector(rowStride, 1),
                             this->_manager);
}

template <typename PixelT>
typename ImageBase<PixelT>::ConstArray ImageBase<PixelT>::getArray() const {
    int rowStride = reinterpret_cast<PixelT*>(row_begin(1)) - reinterpret_cast<PixelT*>(row_begin(0));
    return ndarray::external(reinterpret_cast<PixelT*>(row_begin(0)),
                             ndarray::makeVector(getHeight(), getWidth()), ndarray::makeVector(rowStride, 1),
                             this->_manager);
}

}  // namespace image
}  // namespace afw
}  // namespace lsst

#endif