//
|
// Copyright 2005-2007 Adobe Systems Incorporated
|
//
|
// Distributed under the Boost Software License, Version 1.0
|
// See accompanying file LICENSE_1_0.txt or copy at
|
// http://www.boost.org/LICENSE_1_0.txt
|
//
|
#ifndef BOOST_GIL_IMAGE_VIEW_HPP
|
#define BOOST_GIL_IMAGE_VIEW_HPP
|
|
#include <boost/gil/dynamic_step.hpp>
|
#include <boost/gil/iterator_from_2d.hpp>
|
|
#include <boost/assert.hpp>
|
|
#include <cstddef>
|
#include <iterator>
|
|
namespace boost { namespace gil {
|
|
////////////////////////////////////////////////////////////////////////////////////////
|
/// \class image_view
|
/// \ingroup ImageViewModel PixelBasedModel
|
/// \brief A lightweight object that interprets memory as a 2D array of pixels. Models ImageViewConcept,PixelBasedConcept,HasDynamicXStepTypeConcept,HasDynamicYStepTypeConcept,HasTransposedTypeConcept
|
///
|
/// Image view consists of a pixel 2D locator (defining the mechanism for navigating in 2D)
|
/// and the image dimensions.
|
///
|
/// Image views to images are what ranges are to STL containers. They are lightweight objects,
|
/// that don't own the pixels. It is the user's responsibility that the underlying data remains
|
/// valid for the lifetime of the image view.
|
///
|
/// Similar to iterators and ranges, constness of views does not extend to constness of pixels.
|
/// A const \p image_view does not allow changing its location in memory (resizing, moving) but does
|
/// not prevent one from changing the pixels. The latter requires an image view whose value_type
|
/// is const.
|
///
|
/// Images have interfaces consistent with STL 1D random access containers, so they can be used
|
/// directly in STL algorithms like:
|
/// \code
|
/// std::fill(img.begin(), img.end(), red_pixel);
|
/// \endcode
|
///
|
/// In addition, horizontal, vertical and 2D random access iterators are provided.
|
///
|
/// Note also that \p image_view does not require that its element type be a pixel. It could be
|
/// instantiated with a locator whose \p value_type models only \p Regular. In this case the image
|
/// view models the weaker RandomAccess2DImageViewConcept, and does not model PixelBasedConcept.
|
/// Many generic algorithms don't require the elements to be pixels.
|
///
|
////////////////////////////////////////////////////////////////////////////////////////
|
template <typename Loc> // Models 2D Pixel Locator
|
class image_view
|
{
|
public:
|
// aliases required by ConstRandomAccessNDImageViewConcept
|
static const std::size_t num_dimensions=2;
|
using value_type = typename Loc::value_type;
|
using reference = typename Loc::reference; // result of dereferencing
|
using coord_t = typename Loc::coord_t; // 1D difference type (same for all dimensions)
|
using difference_type = coord_t; // result of operator-(1d_iterator,1d_iterator)
|
using point_t = typename Loc::point_t;
|
using locator = Loc;
|
using const_t = image_view<typename Loc::const_t>; // same as this type, but over const values
|
template <std::size_t D> struct axis
|
{
|
using coord_t = typename Loc::template axis<D>::coord_t; // difference_type along each dimension
|
using iterator = typename Loc::template axis<D>::iterator; // 1D iterator type along each dimension
|
};
|
using iterator = iterator_from_2d<Loc>; // 1D iterator type for each pixel left-to-right inside top-to-bottom
|
using const_iterator = typename const_t::iterator; // may be used to examine, but not to modify values
|
using const_reference = typename const_t::reference; // behaves as a const reference
|
using pointer = typename std::iterator_traits<iterator>::pointer; // behaves as a pointer to the value type
|
using reverse_iterator = std::reverse_iterator<iterator>;
|
using size_type = std::size_t;
|
|
// aliases required by ConstRandomAccess2DImageViewConcept
|
using xy_locator = locator;
|
using x_iterator = typename xy_locator::x_iterator; // pixel iterator along a row
|
using y_iterator = typename xy_locator::y_iterator; // pixel iterator along a column
|
using x_coord_t = typename xy_locator::x_coord_t;
|
using y_coord_t = typename xy_locator::y_coord_t;
|
|
template <typename Deref>
|
struct add_deref
|
{
|
using type = image_view<typename Loc::template add_deref<Deref>::type>;
|
static type make(image_view<Loc> const& view, Deref const& d)
|
{
|
return type(view.dimensions(), Loc::template add_deref<Deref>::make(view.pixels(), d));
|
}
|
};
|
|
image_view() : _dimensions(0,0) {}
|
image_view(image_view const& img_view)
|
: _dimensions(img_view.dimensions()), _pixels(img_view.pixels())
|
{}
|
|
template <typename View>
|
image_view(View const& view) : _dimensions(view.dimensions()), _pixels(view.pixels()) {}
|
|
template <typename L2>
|
image_view(point_t const& dims, L2 const& loc) : _dimensions(dims), _pixels(loc) {}
|
|
template <typename L2>
|
image_view(coord_t width, coord_t height, L2 const& loc)
|
: _dimensions(x_coord_t(width), y_coord_t(height)), _pixels(loc)
|
{}
|
|
template <typename View>
|
image_view& operator=(View const& view)
|
{
|
_pixels = view.pixels();
|
_dimensions = view.dimensions();
|
return *this;
|
}
|
|
image_view& operator=(image_view const& view)
|
{
|
// TODO: Self-assignment protection?
|
_pixels = view.pixels();
|
_dimensions = view.dimensions();
|
return *this;
|
}
|
|
template <typename View>
|
bool operator==(View const &view) const
|
{
|
return pixels() == view.pixels() && dimensions() == view.dimensions();
|
}
|
|
template <typename View>
|
bool operator!=(View const& view) const
|
{
|
return !(*this == view);
|
}
|
|
template <typename L2>
|
friend void swap(image_view<L2> &lhs, image_view<L2> &rhs);
|
|
/// \brief Exchanges the elements of the current view with those of \a other
|
/// in constant time.
|
///
|
/// \note Required by the Collection concept
|
/// \see https://www.boost.org/libs/utility/Collection.html
|
void swap(image_view<Loc>& other)
|
{
|
using boost::gil::swap;
|
swap(*this, other);
|
}
|
|
auto dimensions() const -> point_t const&
|
{
|
return _dimensions;
|
}
|
|
auto pixels() const -> locator const&
|
{
|
return _pixels;
|
}
|
|
auto width() const -> x_coord_t
|
{
|
return dimensions().x;
|
}
|
|
auto height() const -> y_coord_t
|
{
|
return dimensions().y;
|
}
|
|
auto num_channels() const -> std::size_t
|
{
|
return gil::num_channels<value_type>::value;
|
}
|
|
bool is_1d_traversable() const
|
{
|
return _pixels.is_1d_traversable(width());
|
}
|
|
/// \brief Returns true if the view has no elements, false otherwise.
|
///
|
/// \note Required by the Collection concept
|
/// \see https://www.boost.org/libs/utility/Collection.html
|
bool empty() const
|
{
|
return !(width() > 0 && height() > 0);
|
}
|
|
/// \brief Returns a reference to the first element in raster order.
|
///
|
/// \note Required by the ForwardCollection, since view model the concept.
|
/// \see https://www.boost.org/libs/utility/Collection.html
|
auto front() const -> reference
|
{
|
BOOST_ASSERT(!empty());
|
return *begin();
|
}
|
|
/// \brief Returns a reference to the last element in raster order.
|
///
|
/// \note Required by the ForwardCollection, since view model the concept.
|
/// \see https://www.boost.org/libs/utility/Collection.html
|
auto back() const -> reference
|
{
|
BOOST_ASSERT(!empty());
|
return *rbegin();
|
}
|
|
//\{@
|
/// \name 1D navigation
|
auto size() const -> size_type
|
{
|
return width() * height();
|
}
|
|
auto begin() const -> iterator
|
{
|
return iterator(_pixels, _dimensions.x);
|
}
|
|
auto end() const -> iterator
|
{
|
// potential performance problem!
|
return begin() + static_cast<difference_type>(size());
|
}
|
|
auto rbegin() const -> reverse_iterator
|
{
|
return reverse_iterator(end());
|
}
|
|
auto rend() const -> reverse_iterator
|
{
|
return reverse_iterator(begin());
|
}
|
|
auto operator[](difference_type i) const -> reference
|
{
|
BOOST_ASSERT(i < static_cast<difference_type>(size()));
|
return begin()[i]; // potential performance problem!
|
}
|
|
auto at(difference_type i) const -> iterator
|
{
|
// UB if the specified increment advances non-incrementable iterator (i.e. past-the-end)
|
BOOST_ASSERT(i < static_cast<difference_type>(size()));
|
return begin() + i;
|
}
|
|
auto at(point_t const& p) const -> iterator
|
{
|
// UB if the specified coordinates advance non-incrementable iterator (i.e. past-the-end)
|
BOOST_ASSERT(0 <= p.x && p.x < width());
|
BOOST_ASSERT(0 <= p.y && p.y < height());
|
return begin() + p.y * width() + p.x;
|
}
|
|
auto at(x_coord_t x, y_coord_t y) const -> iterator
|
{
|
// UB if the specified coordinates advance non-incrementable iterator (i.e. past-the-end)
|
BOOST_ASSERT(0 <= x && x < width());
|
BOOST_ASSERT(0 <= y && y < height());
|
return begin() + y * width() + x;
|
}
|
//\}@
|
|
//\{@
|
/// \name 2-D navigation
|
auto operator()(point_t const& p) const -> reference
|
{
|
BOOST_ASSERT(0 <= p.x && p.x < width());
|
BOOST_ASSERT(0 <= p.y && p.y < height());
|
return _pixels(p.x, p.y);
|
}
|
|
auto operator()(x_coord_t x, y_coord_t y) const -> reference
|
{
|
BOOST_ASSERT(0 <= x && x < width());
|
BOOST_ASSERT(0 <= y && y < height());
|
return _pixels(x, y);
|
}
|
|
template <std::size_t D>
|
auto axis_iterator(point_t const& p) const -> typename axis<D>::iterator
|
{
|
// Allow request for iterators from inclusive range of [begin, end]
|
BOOST_ASSERT(0 <= p.x && p.x <= width());
|
BOOST_ASSERT(0 <= p.y && p.y <= height());
|
return _pixels.template axis_iterator<D>(p);
|
}
|
|
auto xy_at(x_coord_t x, y_coord_t y) const -> xy_locator
|
{
|
// TODO: Are relative locations of neighbors with negative offsets valid? Sampling?
|
BOOST_ASSERT(x < width());
|
BOOST_ASSERT(y <= height());
|
return _pixels + point_t(x, y);
|
}
|
|
auto xy_at(point_t const& p) const -> xy_locator
|
{
|
// TODO: Are relative locations of neighbors with negative offsets valid? Sampling?
|
BOOST_ASSERT(p.x < width());
|
BOOST_ASSERT(p.y < height());
|
return _pixels + p;
|
}
|
//\}@
|
|
//\{@
|
/// \name X navigation
|
auto x_at(x_coord_t x, y_coord_t y) const -> x_iterator
|
{
|
BOOST_ASSERT(0 <= x && x <= width()); // allow request for [begin, end] inclusive
|
BOOST_ASSERT(0 <= y && y < height()); // TODO: For empty image/view, shouldn't we accept: row_begin(0) == view.row_end(0) ?
|
return _pixels.x_at(x, y);
|
}
|
|
auto x_at(point_t const& p) const -> x_iterator
|
{
|
BOOST_ASSERT(0 <= p.x && p.x <= width()); // allow request for [begin, end] inclusive
|
BOOST_ASSERT(0 <= p.y && p.y < height()); // TODO: For empty image/view, shouldn't we accept: row_begin(0) == view.row_end(0) ?
|
return _pixels.x_at(p);
|
}
|
|
auto row_begin(y_coord_t y) const -> x_iterator
|
{
|
BOOST_ASSERT(0 <= y && y < height());
|
return x_at(0, y);
|
}
|
|
auto row_end(y_coord_t y) const -> x_iterator
|
{
|
BOOST_ASSERT(0 <= y && y < height());
|
return x_at(width(), y);
|
}
|
//\}@
|
|
//\{@
|
/// \name Y navigation
|
auto y_at(x_coord_t x, y_coord_t y) const -> y_iterator
|
{
|
BOOST_ASSERT(0 <= x && x < width()); // TODO: For empty image/view, shouldn't we accept: view.col_begin(0) == view.col_end(0) ?
|
BOOST_ASSERT(0 <= y && y <= height()); // allow request for [begin, end] inclusive
|
return xy_at(x, y).y();
|
}
|
|
auto y_at(point_t const& p) const -> y_iterator
|
{
|
BOOST_ASSERT(0 <= p.x && p.x < width()); // TODO: For empty image/view, shouldn't we accept: view.col_begin(0) == view.col_end(0) ?
|
BOOST_ASSERT(0 <= p.y && p.y <= height()); // allow request for [begin, end] inclusive
|
return xy_at(p).y();
|
}
|
|
auto col_begin(x_coord_t x) const -> y_iterator
|
{
|
BOOST_ASSERT(0 <= x && x < width());
|
return y_at(x, 0);
|
}
|
|
auto col_end(x_coord_t x) const -> y_iterator
|
{
|
BOOST_ASSERT(0 <= x && x < width());
|
return y_at(x, height());
|
}
|
//\}@
|
|
private:
|
template <typename L2>
|
friend class image_view;
|
|
point_t _dimensions;
|
xy_locator _pixels;
|
};
|
|
template <typename L2>
|
inline void swap(image_view<L2>& x, image_view<L2>& y) {
|
using std::swap;
|
swap(x._dimensions,y._dimensions);
|
swap(x._pixels, y._pixels); // TODO: Extend further
|
}
|
|
/////////////////////////////
|
// PixelBasedConcept
|
/////////////////////////////
|
|
template <typename L>
|
struct channel_type<image_view<L> > : public channel_type<L> {};
|
|
template <typename L>
|
struct color_space_type<image_view<L> > : public color_space_type<L> {};
|
|
template <typename L>
|
struct channel_mapping_type<image_view<L> > : public channel_mapping_type<L> {};
|
|
template <typename L>
|
struct is_planar<image_view<L> > : public is_planar<L> {};
|
|
/////////////////////////////
|
// HasDynamicXStepTypeConcept
|
/////////////////////////////
|
|
template <typename L>
|
struct dynamic_x_step_type<image_view<L>>
|
{
|
using type = image_view<typename gil::dynamic_x_step_type<L>::type>;
|
};
|
|
/////////////////////////////
|
// HasDynamicYStepTypeConcept
|
/////////////////////////////
|
|
template <typename L>
|
struct dynamic_y_step_type<image_view<L>>
|
{
|
using type = image_view<typename gil::dynamic_y_step_type<L>::type>;
|
};
|
|
/////////////////////////////
|
// HasTransposedTypeConcept
|
/////////////////////////////
|
|
template <typename L>
|
struct transposed_type<image_view<L>>
|
{
|
using type = image_view<typename transposed_type<L>::type>;
|
};
|
|
}} // namespace boost::gil
|
|
#endif
|
