Boost GIL

locator.hpp
Go to the documentation of this file.
1 /*
2  Copyright 2005-2007 Adobe Systems Incorporated
3 
4  Use, modification and distribution are subject to the Boost Software License,
5  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
6  http://www.boost.org/LICENSE_1_0.txt).
7 
8  See http://opensource.adobe.com/gil for most recent version including documentation.
9 */
10 
11 /*************************************************************************************************/
12 
13 #ifndef BOOST_GIL_LOCATOR_HPP
14 #define BOOST_GIL_LOCATOR_HPP
15 
24 
25 #include <boost/gil/pixel_iterator.hpp>
26 
27 #include <cassert>
28 #include <cstddef>
29 
33 
34 namespace boost { namespace gil {
35 //forward declarations
36 template <typename P> std::ptrdiff_t memunit_step(const P*);
37 template <typename P> P* memunit_advanced(const P* p, std::ptrdiff_t diff);
38 template <typename P> P& memunit_advanced_ref(P* p, std::ptrdiff_t diff);
39 template <typename Iterator, typename D> struct iterator_add_deref;
40 template <typename T> class point2;
41 namespace detail {
42  // helper class specialized for each axis of pixel_2d_locator
43  template <std::size_t D, typename Loc> class locator_axis;
44 }
45 template <typename T> struct dynamic_x_step_type;
46 template <typename T> struct dynamic_y_step_type;
47 
48 template <typename T> struct channel_type;
49 template <typename T> struct color_space_type;
50 template <typename T> struct channel_mapping_type;
51 template <typename T> struct is_planar;
52 template <typename T> struct num_channels;
53 
54 // The type of a locator or a view that has X and Y swapped. By default it is the same
55 template <typename T> struct transposed_type {
56  typedef T type;
57 };
58 
117 
118 template <typename Loc, typename XIterator, typename YIterator> // The concrete subclass, the X-iterator and the Y-iterator
119 class pixel_2d_locator_base {
120 public:
121  typedef XIterator x_iterator;
122  typedef YIterator y_iterator;
123 
124  // typedefs required by ConstRandomAccessNDLocatorConcept
125  static const std::size_t num_dimensions=2;
126  typedef typename std::iterator_traits<x_iterator>::value_type value_type;
127  typedef typename std::iterator_traits<x_iterator>::reference reference; // result of dereferencing
128  typedef typename std::iterator_traits<x_iterator>::difference_type coord_t; // 1D difference type (same for all dimensions)
129  typedef point2<coord_t> difference_type; // result of operator-(locator,locator)
130  typedef difference_type point_t;
131  template <std::size_t D> struct axis {
132  typedef typename detail::locator_axis<D,Loc>::coord_t coord_t;
133  typedef typename detail::locator_axis<D,Loc>::iterator iterator;
134  };
135 
136 // typedefs required by ConstRandomAccess2DLocatorConcept
137  typedef typename point_t::template axis<0>::coord_t x_coord_t;
138  typedef typename point_t::template axis<1>::coord_t y_coord_t;
139 
140  bool operator!=(const Loc& p) const { return !(concrete()==p); }
141 
142  x_iterator x_at(x_coord_t dx, y_coord_t dy) const { Loc tmp=concrete(); tmp+=point_t(dx,dy); return tmp.x(); }
143  x_iterator x_at(const difference_type& d) const { Loc tmp=concrete(); tmp+=d; return tmp.x(); }
144  y_iterator y_at(x_coord_t dx, y_coord_t dy) const { Loc tmp=concrete(); tmp+=point_t(dx,dy); return tmp.y(); }
145  y_iterator y_at(const difference_type& d) const { Loc tmp=concrete(); tmp+=d; return tmp.y(); }
146  Loc xy_at(x_coord_t dx, y_coord_t dy) const { Loc tmp=concrete(); tmp+=point_t(dx,dy); return tmp; }
147  Loc xy_at(const difference_type& d) const { Loc tmp=concrete(); tmp+=d; return tmp; }
148 
149  template <std::size_t D> typename axis<D>::iterator& axis_iterator() { return detail::locator_axis<D,Loc>()(concrete()); }
150  template <std::size_t D> typename axis<D>::iterator const& axis_iterator() const { return detail::locator_axis<D,Loc>()(concrete()); }
151  template <std::size_t D> typename axis<D>::iterator axis_iterator(const point_t& p) const { return detail::locator_axis<D,Loc>()(concrete(),p); }
152 
153  reference operator()(x_coord_t dx, y_coord_t dy) const { return *x_at(dx,dy); }
154  reference operator[](const difference_type& d) const { return *x_at(d.x,d.y); }
155 
156  reference operator*() const { return *concrete().x(); }
157 
158  Loc& operator+=(const difference_type& d) { concrete().x()+=d.x; concrete().y()+=d.y; return concrete(); }
159  Loc& operator-=(const difference_type& d) { concrete().x()-=d.x; concrete().y()-=d.y; return concrete(); }
160 
161  Loc operator+(const difference_type& d) const { return xy_at(d); }
162  Loc operator-(const difference_type& d) const { return xy_at(-d); }
163 
164  // Some locators can cache 2D coordinates for faster subsequent access. By default there is no caching
165  typedef difference_type cached_location_t;
166  cached_location_t cache_location(const difference_type& d) const { return d; }
167  cached_location_t cache_location(x_coord_t dx, y_coord_t dy)const { return difference_type(dx,dy); }
168 
169 private:
170  Loc& concrete() { return (Loc&)*this; }
171  const Loc& concrete() const { return (const Loc&)*this; }
172 
173  template <typename X> friend class pixel_2d_locator;
174 };
175 
176 // helper classes for each axis of pixel_2d_locator_base
177 namespace detail {
178  template <typename Loc>
179  class locator_axis<0,Loc> {
180  typedef typename Loc::point_t point_t;
181  public:
182  typedef typename point_t::template axis<0>::coord_t coord_t;
183  typedef typename Loc::x_iterator iterator;
184 
185  inline iterator& operator()( Loc& loc) const { return loc.x(); }
186  inline iterator const& operator()(const Loc& loc) const { return loc.x(); }
187  inline iterator operator()( Loc& loc, const point_t& d) const { return loc.x_at(d); }
188  inline iterator operator()(const Loc& loc, const point_t& d) const { return loc.x_at(d); }
189  };
190 
191  template <typename Loc>
192  class locator_axis<1,Loc> {
193  typedef typename Loc::point_t point_t;
194  public:
195  typedef typename point_t::template axis<1>::coord_t coord_t;
196  typedef typename Loc::y_iterator iterator;
197 
198  inline iterator& operator()( Loc& loc) const { return loc.y(); }
199  inline iterator const& operator()(const Loc& loc) const { return loc.y(); }
200  inline iterator operator()( Loc& loc, const point_t& d) const { return loc.y_at(d); }
201  inline iterator operator()(const Loc& loc, const point_t& d) const { return loc.y_at(d); }
202  };
203 }
204 
205 template <typename Loc, typename XIt, typename YIt>
206 struct channel_type<pixel_2d_locator_base<Loc,XIt,YIt> > : public channel_type<XIt> {};
207 
208 template <typename Loc, typename XIt, typename YIt>
209 struct color_space_type<pixel_2d_locator_base<Loc,XIt,YIt> > : public color_space_type<XIt> {};
210 
211 template <typename Loc, typename XIt, typename YIt>
212 struct channel_mapping_type<pixel_2d_locator_base<Loc,XIt,YIt> > : public channel_mapping_type<XIt> {};
213 
214 template <typename Loc, typename XIt, typename YIt>
215 struct is_planar<pixel_2d_locator_base<Loc,XIt,YIt> > : public is_planar<XIt> {};
216 
237 
238 template <typename StepIterator>
239 class memory_based_2d_locator : public pixel_2d_locator_base<memory_based_2d_locator<StepIterator>, typename iterator_adaptor_get_base<StepIterator>::type, StepIterator> {
240  typedef memory_based_2d_locator<StepIterator> this_t;
241  GIL_CLASS_REQUIRE(StepIterator, boost::gil, StepIteratorConcept)
242 public:
243  typedef pixel_2d_locator_base<memory_based_2d_locator<StepIterator>, typename iterator_adaptor_get_base<StepIterator>::type, StepIterator> parent_t;
244  typedef memory_based_2d_locator<typename const_iterator_type<StepIterator>::type> const_t; // same as this type, but over const values
245 
246  typedef typename parent_t::coord_t coord_t;
247  typedef typename parent_t::x_coord_t x_coord_t;
248  typedef typename parent_t::y_coord_t y_coord_t;
249  typedef typename parent_t::x_iterator x_iterator;
250  typedef typename parent_t::y_iterator y_iterator;
251  typedef typename parent_t::difference_type difference_type;
252  typedef typename parent_t::reference reference;
253 
254  template <typename Deref> struct add_deref {
255  typedef memory_based_2d_locator<typename iterator_add_deref<StepIterator,Deref>::type> type;
256  static type make(const memory_based_2d_locator<StepIterator>& loc, const Deref& nderef) {
257  return type(iterator_add_deref<StepIterator,Deref>::make(loc.y(),nderef));
258  }
259  };
260 
261  memory_based_2d_locator() {}
262  memory_based_2d_locator(const StepIterator& yit) : _p(yit) {}
263  template <typename SI> memory_based_2d_locator(const memory_based_2d_locator<SI>& loc, coord_t y_step) : _p(loc.x(), loc.row_size()*y_step) {}
264  template <typename SI> memory_based_2d_locator(const memory_based_2d_locator<SI>& loc, coord_t x_step, coord_t y_step, bool transpose=false)
265  : _p(make_step_iterator(loc.x(),(transpose ? loc.row_size() : loc.pixel_size())*x_step),
266  (transpose ? loc.pixel_size() : loc.row_size())*y_step ) {}
267 
268  memory_based_2d_locator(x_iterator xit, std::ptrdiff_t row_bytes) : _p(xit,row_bytes) {}
269  template <typename X> memory_based_2d_locator(const memory_based_2d_locator<X>& pl) : _p(pl._p) {}
270  memory_based_2d_locator(const memory_based_2d_locator& pl) : _p(pl._p) {}
271 
272  bool operator==(const this_t& p) const { return _p==p._p; }
273 
274  x_iterator const& x() const { return _p.base(); }
275  y_iterator const& y() const { return _p; }
276  x_iterator& x() { return _p.base(); }
277  y_iterator& y() { return _p; }
278 
279  // These are faster versions of functions already provided in the superclass
280  x_iterator x_at (x_coord_t dx, y_coord_t dy) const { return memunit_advanced(x(), offset(dx,dy)); }
281  x_iterator x_at (const difference_type& d) const { return memunit_advanced(x(), offset(d.x,d.y)); }
282  this_t xy_at (x_coord_t dx, y_coord_t dy) const { return this_t(x_at( dx , dy ), row_size()); }
283  this_t xy_at (const difference_type& d) const { return this_t(x_at( d.x, d.y), row_size()); }
284  reference operator()(x_coord_t dx, y_coord_t dy) const { return memunit_advanced_ref(x(),offset(dx,dy)); }
285  reference operator[](const difference_type& d) const { return memunit_advanced_ref(x(),offset(d.x,d.y)); }
286  this_t& operator+=(const difference_type& d) { memunit_advance(x(),offset(d.x,d.y)); return *this; }
287  this_t& operator-=(const difference_type& d) { memunit_advance(x(),offset(-d.x,-d.y)); return *this; }
288 
289  // Memory-based locators can have 1D caching of 2D relative coordinates
290  typedef std::ptrdiff_t cached_location_t; // type used to store relative location (to allow for more efficient repeated access)
291  cached_location_t cache_location(const difference_type& d) const { return offset(d.x,d.y); }
292  cached_location_t cache_location(x_coord_t dx, y_coord_t dy)const { return offset(dx,dy); }
293  reference operator[](const cached_location_t& loc) const { return memunit_advanced_ref(x(),loc); }
294 
295  // Only make sense for memory-based locators
296  std::ptrdiff_t row_size() const { return memunit_step(y()); } // distance in mem units (bytes or bits) between adjacent rows
297  std::ptrdiff_t pixel_size() const { return memunit_step(x()); } // distance in mem units (bytes or bits) between adjacent pixels on the same row
298 
299  bool is_1d_traversable(x_coord_t width) const { return row_size()-pixel_size()*width==0; } // is there no gap at the end of each row?
300 
301  // Returns the vertical distance (it2.y-it1.y) between two x_iterators given the difference of their x positions
302  std::ptrdiff_t y_distance_to(const this_t& p2, x_coord_t xDiff) const {
303  std::ptrdiff_t rowDiff=memunit_distance(x(),p2.x())-pixel_size()*xDiff;
304  assert(( rowDiff % row_size())==0);
305  return rowDiff / row_size();
306  }
307 
308 private:
309  template <typename X> friend class memory_based_2d_locator;
310  std::ptrdiff_t offset(x_coord_t x, y_coord_t y) const { return y*row_size() + x*pixel_size(); }
311  StepIterator _p;
312 };
313 
315 // PixelBasedConcept
317 
318 template <typename SI>
319 struct color_space_type<memory_based_2d_locator<SI> > : public color_space_type<typename memory_based_2d_locator<SI>::parent_t> {
320 };
321 
322 template <typename SI>
323 struct channel_mapping_type<memory_based_2d_locator<SI> > : public channel_mapping_type<typename memory_based_2d_locator<SI>::parent_t> {
324 };
325 
326 template <typename SI>
327 struct is_planar<memory_based_2d_locator<SI> > : public is_planar<typename memory_based_2d_locator<SI>::parent_t> {
328 };
329 
330 template <typename SI>
331 struct channel_type<memory_based_2d_locator<SI> > : public channel_type<typename memory_based_2d_locator<SI>::parent_t> {
332 };
333 
335 // HasDynamicXStepTypeConcept
337 
338 // Take the base iterator of SI (which is typically a step iterator) and change it to have a step in x
339 template <typename SI>
340 struct dynamic_x_step_type<memory_based_2d_locator<SI> > {
341 private:
342  typedef typename iterator_adaptor_get_base<SI>::type base_iterator_t;
343  typedef typename dynamic_x_step_type<base_iterator_t>::type base_iterator_step_t;
344  typedef typename iterator_adaptor_rebind<SI, base_iterator_step_t>::type dynamic_step_base_t;
345 public:
346  typedef memory_based_2d_locator<dynamic_step_base_t> type;
347 };
348 
350 // HasDynamicYStepTypeConcept
352 
353 template <typename SI>
354 struct dynamic_y_step_type<memory_based_2d_locator<SI> > {
355  typedef memory_based_2d_locator<SI> type;
356 };
357 } } // namespace boost::gil
358 
359 #endif
boost::gil::pixel_2d_locator_base
base class for models of PixelLocatorConceptPixel locator is similar to a pixel iterator, but allows for 2D navigation of pixels within an image view. It has a 2D difference_type and supports random access operations like:
Definition: locator.hpp:119
boost::gil::iterator_add_deref
Returns the type (and creates an instance) of an iterator that invokes the given dereference adaptor ...
Definition: locator.hpp:39
pixel_iterator.hpp
pixel iterator support
boost::gil::point2
2D point both axes of which have the same dimension typeModels: Point2DConcept
Definition: concept.hpp:54
boost::gil::num_channels
Returns the number of channels of a pixel-based GIL construct.
Definition: concept.hpp:68
Generated on Wed Jun 20 2018 12:45:38 for Generic Image Library by  doxygen 1.8.6