2 // Copyright 2005-2007 Adobe Systems Incorporated
4 // Distributed under the Boost Software License, Version 1.0
5 // See accompanying file LICENSE_1_0.txt or copy at
6 // http://www.boost.org/LICENSE_1_0.txt
8 #ifndef BOOST_GIL_IMAGE_VIEW_HPP
9 #define BOOST_GIL_IMAGE_VIEW_HPP
11 #include <boost/gil/dynamic_step.hpp>
12 #include <boost/gil/iterator_from_2d.hpp>
14 #include <boost/assert.hpp>
19 namespace boost { namespace gil {
21 ////////////////////////////////////////////////////////////////////////////////////////
23 /// \ingroup ImageViewModel PixelBasedModel
24 /// \brief A lightweight object that interprets memory as a 2D array of pixels. Models ImageViewConcept,PixelBasedConcept,HasDynamicXStepTypeConcept,HasDynamicYStepTypeConcept,HasTransposedTypeConcept
26 /// Image view consists of a pixel 2D locator (defining the mechanism for navigating in 2D)
27 /// and the image dimensions.
29 /// Image views to images are what ranges are to STL containers. They are lightweight objects,
30 /// that don't own the pixels. It is the user's responsibility that the underlying data remains
31 /// valid for the lifetime of the image view.
33 /// Similar to iterators and ranges, constness of views does not extend to constness of pixels.
34 /// A const \p image_view does not allow changing its location in memory (resizing, moving) but does
35 /// not prevent one from changing the pixels. The latter requires an image view whose value_type
38 /// Images have interfaces consistent with STL 1D random access containers, so they can be used
39 /// directly in STL algorithms like:
41 /// std::fill(img.begin(), img.end(), red_pixel);
44 /// In addition, horizontal, vertical and 2D random access iterators are provided.
46 /// Note also that \p image_view does not require that its element type be a pixel. It could be
47 /// instantiated with a locator whose \p value_type models only \p Regular. In this case the image
48 /// view models the weaker RandomAccess2DImageViewConcept, and does not model PixelBasedConcept.
49 /// Many generic algorithms don't require the elements to be pixels.
51 ////////////////////////////////////////////////////////////////////////////////////////
52 template <typename Loc> // Models 2D Pixel Locator
56 // aliases required by ConstRandomAccessNDImageViewConcept
57 static const std::size_t num_dimensions=2;
58 using value_type = typename Loc::value_type;
59 using reference = typename Loc::reference; // result of dereferencing
60 using coord_t = typename Loc::coord_t; // 1D difference type (same for all dimensions)
61 using difference_type = coord_t; // result of operator-(1d_iterator,1d_iterator)
62 using point_t = typename Loc::point_t;
64 using const_t = image_view<typename Loc::const_t>; // same as this type, but over const values
65 template <std::size_t D> struct axis
67 using coord_t = typename Loc::template axis<D>::coord_t; // difference_type along each dimension
68 using iterator = typename Loc::template axis<D>::iterator; // 1D iterator type along each dimension
70 using iterator = iterator_from_2d<Loc>; // 1D iterator type for each pixel left-to-right inside top-to-bottom
71 using const_iterator = typename const_t::iterator; // may be used to examine, but not to modify values
72 using const_reference = typename const_t::reference; // behaves as a const reference
73 using pointer = typename std::iterator_traits<iterator>::pointer; // behaves as a pointer to the value type
74 using reverse_iterator = std::reverse_iterator<iterator>;
75 using size_type = std::size_t;
77 // aliases required by ConstRandomAccess2DImageViewConcept
78 using xy_locator = locator;
79 using x_iterator = typename xy_locator::x_iterator; // pixel iterator along a row
80 using y_iterator = typename xy_locator::y_iterator; // pixel iterator along a column
81 using x_coord_t = typename xy_locator::x_coord_t;
82 using y_coord_t = typename xy_locator::y_coord_t;
84 template <typename Deref>
87 using type = image_view<typename Loc::template add_deref<Deref>::type>;
88 static type make(image_view<Loc> const& view, Deref const& d)
90 return type(view.dimensions(), Loc::template add_deref<Deref>::make(view.pixels(), d));
94 image_view() : _dimensions(0,0) {}
95 image_view(image_view const& img_view)
96 : _dimensions(img_view.dimensions()), _pixels(img_view.pixels())
99 template <typename View>
100 image_view(View const& view) : _dimensions(view.dimensions()), _pixels(view.pixels()) {}
102 template <typename L2>
103 image_view(point_t const& dims, L2 const& loc) : _dimensions(dims), _pixels(loc) {}
105 template <typename L2>
106 image_view(coord_t width, coord_t height, L2 const& loc)
107 : _dimensions(x_coord_t(width), y_coord_t(height)), _pixels(loc)
110 template <typename View>
111 image_view& operator=(View const& view)
113 _pixels = view.pixels();
114 _dimensions = view.dimensions();
118 image_view& operator=(image_view const& view)
120 // TODO: Self-assignment protection?
121 _pixels = view.pixels();
122 _dimensions = view.dimensions();
126 template <typename View>
127 bool operator==(View const &view) const
129 return pixels() == view.pixels() && dimensions() == view.dimensions();
132 template <typename View>
133 bool operator!=(View const& view) const
135 return !(*this == view);
138 template <typename L2>
139 friend void swap(image_view<L2> &lhs, image_view<L2> &rhs);
141 /// \brief Exchanges the elements of the current view with those of \a other
142 /// in constant time.
144 /// \note Required by the Collection concept
145 /// \see https://www.boost.org/libs/utility/Collection.html
146 void swap(image_view<Loc>& other)
148 using boost::gil::swap;
152 auto dimensions() const -> point_t const&
157 auto pixels() const -> locator const&
162 auto width() const -> x_coord_t
164 return dimensions().x;
167 auto height() const -> y_coord_t
169 return dimensions().y;
172 auto num_channels() const -> std::size_t
174 return gil::num_channels<value_type>::value;
177 bool is_1d_traversable() const
179 return _pixels.is_1d_traversable(width());
182 /// \brief Returns true if the view has no elements, false otherwise.
184 /// \note Required by the Collection concept
185 /// \see https://www.boost.org/libs/utility/Collection.html
188 return !(width() > 0 && height() > 0);
191 /// \brief Returns a reference to the first element in raster order.
193 /// \note Required by the ForwardCollection, since view model the concept.
194 /// \see https://www.boost.org/libs/utility/Collection.html
195 auto front() const -> reference
197 BOOST_ASSERT(!empty());
201 /// \brief Returns a reference to the last element in raster order.
203 /// \note Required by the ForwardCollection, since view model the concept.
204 /// \see https://www.boost.org/libs/utility/Collection.html
205 auto back() const -> reference
207 BOOST_ASSERT(!empty());
212 /// \name 1D navigation
213 auto size() const -> size_type
215 return width() * height();
218 auto begin() const -> iterator
220 return iterator(_pixels, _dimensions.x);
223 auto end() const -> iterator
225 // potential performance problem!
226 return begin() + static_cast<difference_type>(size());
229 auto rbegin() const -> reverse_iterator
231 return reverse_iterator(end());
234 auto rend() const -> reverse_iterator
236 return reverse_iterator(begin());
239 auto operator[](difference_type i) const -> reference
241 BOOST_ASSERT(i < static_cast<difference_type>(size()));
242 return begin()[i]; // potential performance problem!
245 auto at(difference_type i) const ->iterator
247 BOOST_ASSERT(i < size());
251 auto at(point_t const& p) const -> iterator
253 BOOST_ASSERT(0 <= p.x && p.x < width());
254 BOOST_ASSERT(0 <= p.y && p.y < height());
255 return begin() + p.y * width() + p.x;
258 auto at(x_coord_t x, y_coord_t y) const -> iterator
260 BOOST_ASSERT(0 <= x && x < width());
261 BOOST_ASSERT(0 <= y && y < height());
262 return begin() + y * width() + x;
267 /// \name 2-D navigation
268 auto operator()(point_t const& p) const -> reference
270 BOOST_ASSERT(0 <= p.x && p.x < width());
271 BOOST_ASSERT(0 <= p.y && p.y < height());
272 return _pixels(p.x, p.y);
275 auto operator()(x_coord_t x, y_coord_t y) const -> reference
277 BOOST_ASSERT(0 <= x && x < width());
278 BOOST_ASSERT(0 <= y && y < height());
279 return _pixels(x, y);
282 template <std::size_t D>
283 auto axis_iterator(point_t const& p) const -> typename axis<D>::iterator
285 // allow request for iterators from inclusive range of [begin, end]
286 BOOST_ASSERT(0 <= p.x && p.x <= width());
287 BOOST_ASSERT(0 <= p.y && p.y <= height());
288 return _pixels.template axis_iterator<D>(p);
291 auto xy_at(x_coord_t x, y_coord_t y) const -> xy_locator
293 // TODO: Are relative locations of neighbors with negative offsets valid? Sampling?
294 BOOST_ASSERT(x < width());
295 BOOST_ASSERT(y < height());
296 return _pixels + point_t(x, y);
299 auto xy_at(point_t const& p) const -> locator
301 // TODO: Are relative locations of neighbors with negative offsets valid? Sampling?
302 BOOST_ASSERT(p.x < width());
303 BOOST_ASSERT(p.y < height());
309 /// \name X navigation
310 auto x_at(x_coord_t x, y_coord_t y) const -> x_iterator
312 BOOST_ASSERT(0 <= x && x <= width()); // allow request for [begin, end] inclusive
313 BOOST_ASSERT(0 <= y && y < height());
314 return _pixels.x_at(x, y);
317 auto x_at(point_t const& p) const -> x_iterator
319 BOOST_ASSERT(0 <= p.x && p.x <= width()); // allow request for [begin, end] inclusive
320 BOOST_ASSERT(0 <= p.y && p.y < height());
321 return _pixels.x_at(p);
324 auto row_begin(y_coord_t y) const -> x_iterator
326 BOOST_ASSERT(0 <= y && y < height());
330 auto row_end(y_coord_t y) const -> x_iterator
332 BOOST_ASSERT(0 <= y && y < height());
333 return x_at(width(), y);
338 /// \name Y navigation
339 auto y_at(x_coord_t x, y_coord_t y) const -> y_iterator
341 BOOST_ASSERT(0 <= x && x < width());
342 BOOST_ASSERT(0 <= y && y <= height()); // allow request for [begin, end] inclusive
343 return xy_at(x, y).y();
346 auto y_at(point_t const& p) const -> y_iterator
348 BOOST_ASSERT(0 <= p.x && p.x < width());
349 BOOST_ASSERT(0 <= p.y && p.y <= height()); // allow request for [begin, end] inclusive
353 auto col_begin(x_coord_t x) const -> y_iterator
355 BOOST_ASSERT(0 <= x && x < width());
359 auto col_end(x_coord_t x) const -> y_iterator
361 BOOST_ASSERT(0 <= x && x < width());
362 return y_at(x, height());
367 template <typename L2>
368 friend class image_view;
374 template <typename L2>
375 inline void swap(image_view<L2>& x, image_view<L2>& y) {
377 swap(x._dimensions,y._dimensions);
378 swap(x._pixels, y._pixels); // TODO: Extend further
381 /////////////////////////////
383 /////////////////////////////
385 template <typename L>
386 struct channel_type<image_view<L> > : public channel_type<L> {};
388 template <typename L>
389 struct color_space_type<image_view<L> > : public color_space_type<L> {};
391 template <typename L>
392 struct channel_mapping_type<image_view<L> > : public channel_mapping_type<L> {};
394 template <typename L>
395 struct is_planar<image_view<L> > : public is_planar<L> {};
397 /////////////////////////////
398 // HasDynamicXStepTypeConcept
399 /////////////////////////////
401 template <typename L>
402 struct dynamic_x_step_type<image_view<L>>
404 using type = image_view<typename gil::dynamic_x_step_type<L>::type>;
407 /////////////////////////////
408 // HasDynamicYStepTypeConcept
409 /////////////////////////////
411 template <typename L>
412 struct dynamic_y_step_type<image_view<L>>
414 using type = image_view<typename gil::dynamic_y_step_type<L>::type>;
417 /////////////////////////////
418 // HasTransposedTypeConcept
419 /////////////////////////////
421 template <typename L>
422 struct transposed_type<image_view<L>>
424 using type = image_view<typename transposed_type<L>::type>;
427 }} // namespace boost::gil