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_FACTORY_HPP
9 #define BOOST_GIL_IMAGE_VIEW_FACTORY_HPP
11 #include <boost/gil/color_convert.hpp>
12 #include <boost/gil/dynamic_step.hpp>
13 #include <boost/gil/gray.hpp>
14 #include <boost/gil/image_view.hpp>
15 #include <boost/gil/metafunctions.hpp>
16 #include <boost/gil/point.hpp>
17 #include <boost/gil/detail/mp11.hpp>
19 #include <boost/assert.hpp>
22 #include <type_traits>
24 /// Methods for creating shallow image views from raw pixel data or from other image views -
25 /// flipping horizontally or vertically, axis-aligned rotation, a subimage, subsampled
26 /// or n-th channel image view. Derived image views are shallow copies and are fast to construct.
28 /// \defgroup ImageViewConstructors Image View From Raw Data
29 /// \ingroup ImageViewAlgorithm
30 /// \brief Methods for constructing image views from raw data and for getting raw data from views
32 /// \defgroup ImageViewTransformations Image View Transformations
33 /// \ingroup ImageViewAlgorithm
34 /// \brief Methods for constructing one image view from another
36 namespace boost { namespace gil {
38 struct default_color_converter;
40 template <typename T> struct transposed_type;
42 /// \brief Returns the type of a view that has a dynamic step along both X and Y
43 /// \ingroup ImageViewTransformations
44 template <typename View>
45 struct dynamic_xy_step_type
46 : dynamic_y_step_type<typename dynamic_x_step_type<View>::type> {};
48 /// \brief Returns the type of a transposed view that has a dynamic step along both X and Y
49 /// \ingroup ImageViewTransformations
50 template <typename View>
51 struct dynamic_xy_step_transposed_type
52 : dynamic_xy_step_type<typename transposed_type<View>::type> {};
54 /// \ingroup ImageViewConstructors
55 /// \brief Constructing image views from raw interleaved pixel data
56 template <typename Iterator>
57 typename type_from_x_iterator<Iterator>::view_t
58 interleaved_view(std::size_t width, std::size_t height,
59 Iterator pixels, std::ptrdiff_t rowsize_in_bytes) {
60 using RView = typename type_from_x_iterator<Iterator>::view_t;
61 return RView(width, height, typename RView::locator(pixels, rowsize_in_bytes));
64 /// \ingroup ImageViewConstructors
65 /// \brief Constructing image views from raw interleaved pixel data
66 template <typename Iterator>
67 auto interleaved_view(point<std::ptrdiff_t> dim, Iterator pixels,
68 std::ptrdiff_t rowsize_in_bytes)
69 -> typename type_from_x_iterator<Iterator>::view_t
71 using RView = typename type_from_x_iterator<Iterator>::view_t;
72 return RView(dim, typename RView::locator(pixels, rowsize_in_bytes));
75 /////////////////////////////
76 // interleaved_view_get_raw_data, planar_view_get_raw_data - return pointers to the raw data (the channels) of a basic homogeneous view.
77 /////////////////////////////
80 template <typename View, bool IsMutable> struct channel_pointer_type_impl;
82 template <typename View> struct channel_pointer_type_impl<View, true> {
83 using type = typename channel_type<View>::type *;
85 template <typename View> struct channel_pointer_type_impl<View, false> {
86 using type = const typename channel_type<View>::type *;
89 template <typename View> struct channel_pointer_type
90 : public channel_pointer_type_impl<View, view_is_mutable<View>::value> {};
93 /// \ingroup ImageViewConstructors
94 /// \brief Returns C pointer to the the channels of an interleaved homogeneous view.
95 template <typename HomogeneousView>
96 typename detail::channel_pointer_type<HomogeneousView>::type interleaved_view_get_raw_data(const HomogeneousView& view) {
97 static_assert(!is_planar<HomogeneousView>::value && view_is_basic<HomogeneousView>::value, "");
98 static_assert(std::is_pointer<typename HomogeneousView::x_iterator>::value, "");
100 return &gil::at_c<0>(view(0,0));
103 /// \ingroup ImageViewConstructors
104 /// \brief Returns C pointer to the the channels of a given color plane of a planar homogeneous view.
105 template <typename HomogeneousView>
106 typename detail::channel_pointer_type<HomogeneousView>::type planar_view_get_raw_data(const HomogeneousView& view, int plane_index) {
107 static_assert(is_planar<HomogeneousView>::value && view_is_basic<HomogeneousView>::value, "");
108 return dynamic_at_c(view.row_begin(0),plane_index);
112 /// \defgroup ImageViewTransformationsColorConvert color_converted_view
113 /// \ingroup ImageViewTransformations
114 /// \brief Color converted view of another view
116 /// \ingroup ImageViewTransformationsColorConvert PixelDereferenceAdaptorModel
117 /// \brief Function object that given a source pixel, returns it converted to a given color space and channel depth. Models: PixelDereferenceAdaptorConcept
119 /// Useful in constructing a color converted view over a given image view
120 template <typename SrcConstRefP, typename DstP, typename CC=default_color_converter > // const_reference to the source pixel and destination pixel value
121 class color_convert_deref_fn : public deref_base<color_convert_deref_fn<SrcConstRefP,DstP,CC>, DstP, DstP, const DstP&, SrcConstRefP, DstP, false> {
123 CC _cc; // color-converter
125 color_convert_deref_fn() {}
126 color_convert_deref_fn(CC cc_in) : _cc(cc_in) {}
128 DstP operator()(SrcConstRefP srcP) const {
136 // Add color converter upon dereferencing
137 template <typename SrcView, typename CC, typename DstP, typename SrcP>
138 struct _color_converted_view_type {
140 using deref_t = color_convert_deref_fn<typename SrcView::const_t::reference,DstP,CC>;
141 using add_ref_t = typename SrcView::template add_deref<deref_t>;
143 using type = typename add_ref_t::type;
144 static type make(const SrcView& sv,CC cc) {return add_ref_t::make(sv,deref_t(cc));}
147 // If the Src view has the same pixel type as the target, there is no need for color conversion
148 template <typename SrcView, typename CC, typename DstP>
149 struct _color_converted_view_type<SrcView,CC,DstP,DstP> {
150 using type = SrcView;
151 static type make(const SrcView& sv,CC) {return sv;}
153 } // namespace detail
156 /// \brief Returns the type of a view that does color conversion upon dereferencing its pixels
157 /// \ingroup ImageViewTransformationsColorConvert
158 template <typename SrcView, typename DstP, typename CC=default_color_converter>
159 struct color_converted_view_type : public detail::_color_converted_view_type<SrcView,
162 typename SrcView::value_type> {
163 BOOST_GIL_CLASS_REQUIRE(DstP, boost::gil, MutablePixelConcept)//why does it have to be mutable???
167 /// \ingroup ImageViewTransformationsColorConvert
168 /// \brief view of a different color space with a user defined color-converter
169 template <typename DstP, typename View, typename CC>
170 inline typename color_converted_view_type<View,DstP,CC>::type color_converted_view(const View& src,CC cc) {
171 return color_converted_view_type<View,DstP,CC>::make(src,cc);
174 /// \ingroup ImageViewTransformationsColorConvert
175 /// \brief overload of generic color_converted_view with the default color-converter
176 template <typename DstP, typename View>
177 inline typename color_converted_view_type<View,DstP>::type
178 color_converted_view(const View& src) {
179 return color_converted_view<DstP>(src,default_color_converter());
182 /// \defgroup ImageViewTransformationsFlipUD flipped_up_down_view
183 /// \ingroup ImageViewTransformations
184 /// \brief view of a view flipped up-to-down
186 /// \ingroup ImageViewTransformationsFlipUD
187 template <typename View>
188 inline typename dynamic_y_step_type<View>::type flipped_up_down_view(const View& src) {
189 using RView = typename dynamic_y_step_type<View>::type;
190 return RView(src.dimensions(),typename RView::xy_locator(src.xy_at(0,src.height()-1),-1));
193 /// \defgroup ImageViewTransformationsFlipLR flipped_left_right_view
194 /// \ingroup ImageViewTransformations
195 /// \brief view of a view flipped left-to-right
197 /// \ingroup ImageViewTransformationsFlipLR
198 template <typename View>
199 inline typename dynamic_x_step_type<View>::type flipped_left_right_view(const View& src) {
200 using RView = typename dynamic_x_step_type<View>::type;
201 return RView(src.dimensions(),typename RView::xy_locator(src.xy_at(src.width()-1,0),-1,1));
204 /// \defgroup ImageViewTransformationsTransposed transposed_view
205 /// \ingroup ImageViewTransformations
206 /// \brief view of a view transposed
208 /// \ingroup ImageViewTransformationsTransposed
209 template <typename View>
210 inline typename dynamic_xy_step_transposed_type<View>::type transposed_view(const View& src) {
211 using RView = typename dynamic_xy_step_transposed_type<View>::type;
212 return RView(src.height(),src.width(),typename RView::xy_locator(src.xy_at(0,0),1,1,true));
215 /// \defgroup ImageViewTransformations90CW rotated90cw_view
216 /// \ingroup ImageViewTransformations
217 /// \brief view of a view rotated 90 degrees clockwise
219 /// \ingroup ImageViewTransformations90CW
220 template <typename View>
221 inline typename dynamic_xy_step_transposed_type<View>::type rotated90cw_view(const View& src) {
222 using RView = typename dynamic_xy_step_transposed_type<View>::type;
223 return RView(src.height(),src.width(),typename RView::xy_locator(src.xy_at(0,src.height()-1),-1,1,true));
226 /// \defgroup ImageViewTransformations90CCW rotated90ccw_view
227 /// \ingroup ImageViewTransformations
228 /// \brief view of a view rotated 90 degrees counter-clockwise
230 /// \ingroup ImageViewTransformations90CCW
231 template <typename View>
232 inline typename dynamic_xy_step_transposed_type<View>::type rotated90ccw_view(const View& src) {
233 using RView = typename dynamic_xy_step_transposed_type<View>::type;
234 return RView(src.height(),src.width(),typename RView::xy_locator(src.xy_at(src.width()-1,0),1,-1,true));
237 /// \defgroup ImageViewTransformations180 rotated180_view
238 /// \ingroup ImageViewTransformations
239 /// \brief view of a view rotated 180 degrees
241 /// \ingroup ImageViewTransformations180
242 template <typename View>
243 inline typename dynamic_xy_step_type<View>::type rotated180_view(const View& src) {
244 using RView = typename dynamic_xy_step_type<View>::type;
245 return RView(src.dimensions(),typename RView::xy_locator(src.xy_at(src.width()-1,src.height()-1),-1,-1));
248 /// \defgroup ImageViewTransformationsSubimage subimage_view
249 /// \ingroup ImageViewTransformations
250 /// \brief view of an axis-aligned rectangular area within an image_view
252 /// \ingroup ImageViewTransformationsSubimage
253 template <typename View>
254 inline View subimage_view(
256 typename View::point_t const& topleft,
257 typename View::point_t const& dimensions)
259 return View(dimensions, src.xy_at(topleft));
262 /// \ingroup ImageViewTransformationsSubimage
263 template <typename View>
264 inline View subimage_view(View const& src,
265 typename View::coord_t x_min,
266 typename View::coord_t y_min,
267 typename View::coord_t width,
268 typename View::coord_t height)
270 return View(width, height, src.xy_at(x_min, y_min));
273 /// \defgroup ImageViewTransformationsSubsampled subsampled_view
274 /// \ingroup ImageViewTransformations
275 /// \brief view of a subsampled version of an image_view, stepping over a number of channels in X and number of rows in Y
277 /// \ingroup ImageViewTransformationsSubsampled
278 template <typename View>
280 auto subsampled_view(View const& src, typename View::coord_t x_step, typename View::coord_t y_step)
281 -> typename dynamic_xy_step_type<View>::type
283 BOOST_ASSERT(x_step > 0 && y_step > 0);
284 using view_t =typename dynamic_xy_step_type<View>::type;
286 (src.width() + (x_step - 1)) / x_step,
287 (src.height() + (y_step - 1)) / y_step,
288 typename view_t::xy_locator(src.xy_at(0,0), x_step, y_step));
291 /// \ingroup ImageViewTransformationsSubsampled
292 template <typename View>
293 inline auto subsampled_view(View const& src, typename View::point_t const& step)
294 -> typename dynamic_xy_step_type<View>::type
296 return subsampled_view(src, step.x, step.y);
299 /// \defgroup ImageViewTransformationsNthChannel nth_channel_view
300 /// \ingroup ImageViewTransformations
301 /// \brief single-channel (grayscale) view of the N-th channel of a given image_view
304 template <typename View, bool AreChannelsTogether> struct __nth_channel_view_basic;
306 // nth_channel_view when the channels are not adjacent in memory. This can happen for multi-channel interleaved images
307 // or images with a step
308 template <typename View>
309 struct __nth_channel_view_basic<View,false> {
310 using type = typename view_type<typename channel_type<View>::type, gray_layout_t, false, true, view_is_mutable<View>::value>::type;
312 static type make(const View& src, int n) {
313 using locator_t = typename type::xy_locator;
314 using x_iterator_t = typename type::x_iterator;
315 using x_iterator_base_t = typename iterator_adaptor_get_base<x_iterator_t>::type;
316 x_iterator_t sit(x_iterator_base_t(&(src(0,0)[n])),src.pixels().pixel_size());
317 return type(src.dimensions(),locator_t(sit, src.pixels().row_size()));
321 // nth_channel_view when the channels are together in memory (true for simple grayscale or planar images)
322 template <typename View>
323 struct __nth_channel_view_basic<View,true> {
324 using type = typename view_type<typename channel_type<View>::type, gray_layout_t, false, false, view_is_mutable<View>::value>::type;
325 static type make(const View& src, int n) {
326 using x_iterator_t = typename type::x_iterator;
327 return interleaved_view(src.width(),src.height(),(x_iterator_t)&(src(0,0)[n]), src.pixels().row_size());
331 template <typename View, bool IsBasic> struct __nth_channel_view;
333 // For basic (memory-based) views dispatch to __nth_channel_view_basic
334 template <typename View>
335 struct __nth_channel_view<View,true>
338 using src_x_iterator = typename View::x_iterator;
340 // Determines whether the channels of a given pixel iterator are adjacent in memory.
341 // Planar and grayscale iterators have channels adjacent in memory, whereas multi-channel interleaved and iterators with non-fundamental step do not.
342 static constexpr bool adjacent =
343 !iterator_is_step<src_x_iterator>::value &&
344 (is_planar<src_x_iterator>::value || num_channels<View>::value == 1);
347 using type = typename __nth_channel_view_basic<View,adjacent>::type;
349 static type make(const View& src, int n) {
350 return __nth_channel_view_basic<View,adjacent>::make(src,n);
354 /// \brief Function object that returns a grayscale reference of the N-th channel of a given reference. Models: PixelDereferenceAdaptorConcept.
355 /// \ingroup PixelDereferenceAdaptorModel
357 /// If the input is a pixel value or constant reference, the function object is immutable. Otherwise it is mutable (and returns non-const reference to the n-th channel)
358 template <typename SrcP> // SrcP is a reference to PixelConcept (could be pixel value or const/non-const reference)
359 // Examples: pixel<T,L>, pixel<T,L>&, const pixel<T,L>&, planar_pixel_reference<T&,L>, planar_pixel_reference<const T&,L>
360 struct nth_channel_deref_fn
362 static constexpr bool is_mutable =
363 pixel_is_reference<SrcP>::value && pixel_reference_is_mutable<SrcP>::value;
365 using src_pixel_t = typename std::remove_reference<SrcP>::type;
366 using channel_t = typename channel_type<src_pixel_t>::type;
367 using const_ref_t = typename src_pixel_t::const_reference;
368 using ref_t = typename pixel_reference_type<channel_t,gray_layout_t,false,is_mutable>::type;
370 using const_t = nth_channel_deref_fn<const_ref_t>;
371 using value_type = typename pixel_value_type<channel_t,gray_layout_t>::type;
372 using const_reference = typename pixel_reference_type<channel_t,gray_layout_t,false,false>::type;
373 using argument_type = SrcP;
374 using reference = mp11::mp_if_c<is_mutable, ref_t, value_type>;
375 using result_type = reference;
377 nth_channel_deref_fn(int n=0) : _n(n) {}
378 template <typename P> nth_channel_deref_fn(const nth_channel_deref_fn<P>& d) : _n(d._n) {}
380 int _n; // the channel to use
382 result_type operator()(argument_type srcP) const {
383 return result_type(srcP[_n]);
387 template <typename View> struct __nth_channel_view<View,false> {
389 using deref_t = nth_channel_deref_fn<typename View::reference>;
390 using AD = typename View::template add_deref<deref_t>;
392 using type = typename AD::type;
393 static type make(const View& src, int n) {
394 return AD::make(src, deref_t(n));
397 } // namespace detail
399 /// \brief Given a source image view type View, returns the type of an image view over a single channel of View
400 /// \ingroup ImageViewTransformationsNthChannel
402 /// If the channels in the source view are adjacent in memory (such as planar non-step view or single-channel view) then the
403 /// return view is a single-channel non-step view.
404 /// If the channels are non-adjacent (interleaved and/or step view) then the return view is a single-channel step view.
405 template <typename View>
406 struct nth_channel_view_type {
408 BOOST_GIL_CLASS_REQUIRE(View, boost::gil, ImageViewConcept)
409 using VB = detail::__nth_channel_view<View,view_is_basic<View>::value>;
411 using type = typename VB::type;
412 static type make(const View& src, int n) { return VB::make(src,n); }
416 /// \ingroup ImageViewTransformationsNthChannel
417 template <typename View>
418 typename nth_channel_view_type<View>::type nth_channel_view(const View& src, int n) {
419 return nth_channel_view_type<View>::make(src,n);
428 /// \defgroup ImageViewTransformationsKthChannel kth_channel_view
429 /// \ingroup ImageViewTransformations
430 /// \brief single-channel (grayscale) view of the K-th channel of a given image_view. The channel index is a template parameter
433 template <int K, typename View, bool AreChannelsTogether> struct __kth_channel_view_basic;
435 // kth_channel_view when the channels are not adjacent in memory. This can happen for multi-channel interleaved images
436 // or images with a step
437 template <int K, typename View>
438 struct __kth_channel_view_basic<K,View,false> {
440 using channel_t = typename kth_element_type<typename View::value_type,K>::type;
442 using type = typename view_type<channel_t, gray_layout_t, false, true, view_is_mutable<View>::value>::type;
444 static type make(const View& src) {
445 using locator_t = typename type::xy_locator;
446 using x_iterator_t = typename type::x_iterator;
447 using x_iterator_base_t = typename iterator_adaptor_get_base<x_iterator_t>::type;
448 x_iterator_t sit(x_iterator_base_t(&gil::at_c<K>(src(0,0))),src.pixels().pixel_size());
449 return type(src.dimensions(),locator_t(sit, src.pixels().row_size()));
453 // kth_channel_view when the channels are together in memory (true for simple grayscale or planar images)
454 template <int K, typename View>
455 struct __kth_channel_view_basic<K,View,true> {
457 using channel_t = typename kth_element_type<typename View::value_type, K>::type;
459 using type = typename view_type<channel_t, gray_layout_t, false, false, view_is_mutable<View>::value>::type;
460 static type make(const View& src) {
461 using x_iterator_t = typename type::x_iterator;
462 return interleaved_view(src.width(),src.height(),(x_iterator_t)&gil::at_c<K>(src(0,0)), src.pixels().row_size());
466 template <int K, typename View, bool IsBasic> struct __kth_channel_view;
468 // For basic (memory-based) views dispatch to __kth_channel_view_basic
469 template <int K, typename View> struct __kth_channel_view<K,View,true>
472 using src_x_iterator = typename View::x_iterator;
474 // Determines whether the channels of a given pixel iterator are adjacent in memory.
475 // Planar and grayscale iterators have channels adjacent in memory, whereas multi-channel interleaved and iterators with non-fundamental step do not.
476 static constexpr bool adjacent =
477 !iterator_is_step<src_x_iterator>::value &&
478 (is_planar<src_x_iterator>::value || num_channels<View>::value == 1);
481 using type = typename __kth_channel_view_basic<K,View,adjacent>::type;
483 static type make(const View& src) {
484 return __kth_channel_view_basic<K,View,adjacent>::make(src);
488 /// \brief Function object that returns a grayscale reference of the K-th channel (specified as a template parameter) of a given reference. Models: PixelDereferenceAdaptorConcept.
489 /// \ingroup PixelDereferenceAdaptorModel
491 /// If the input is a pixel value or constant reference, the function object is immutable. Otherwise it is mutable (and returns non-const reference to the k-th channel)
492 /// \tparam SrcP reference to PixelConcept (could be pixel value or const/non-const reference)
493 /// Examples: pixel<T,L>, pixel<T,L>&, const pixel<T,L>&, planar_pixel_reference<T&,L>, planar_pixel_reference<const T&,L>
494 template <int K, typename SrcP>
495 struct kth_channel_deref_fn
497 static constexpr bool is_mutable =
498 pixel_is_reference<SrcP>::value && pixel_reference_is_mutable<SrcP>::value;
501 using src_pixel_t = typename std::remove_reference<SrcP>::type;
502 using channel_t = typename kth_element_type<src_pixel_t, K>::type;
503 using const_ref_t = typename src_pixel_t::const_reference;
504 using ref_t = typename pixel_reference_type<channel_t,gray_layout_t,false,is_mutable>::type;
507 using const_t = kth_channel_deref_fn<K,const_ref_t>;
508 using value_type = typename pixel_value_type<channel_t,gray_layout_t>::type;
509 using const_reference = typename pixel_reference_type<channel_t,gray_layout_t,false,false>::type;
510 using argument_type = SrcP;
511 using reference = mp11::mp_if_c<is_mutable, ref_t, value_type>;
512 using result_type = reference;
514 kth_channel_deref_fn() {}
515 template <typename P> kth_channel_deref_fn(const kth_channel_deref_fn<K,P>&) {}
517 result_type operator()(argument_type srcP) const {
518 return result_type(gil::at_c<K>(srcP));
522 template <int K, typename View> struct __kth_channel_view<K,View,false> {
524 using deref_t = kth_channel_deref_fn<K,typename View::reference>;
525 using AD = typename View::template add_deref<deref_t>;
527 using type = typename AD::type;
528 static type make(const View& src) {
529 return AD::make(src, deref_t());
532 } // namespace detail
534 /// \brief Given a source image view type View, returns the type of an image view over a given channel of View.
535 /// \ingroup ImageViewTransformationsKthChannel
537 /// If the channels in the source view are adjacent in memory (such as planar non-step view or single-channel view) then the
538 /// return view is a single-channel non-step view.
539 /// If the channels are non-adjacent (interleaved and/or step view) then the return view is a single-channel step view.
540 template <int K, typename View>
541 struct kth_channel_view_type {
543 BOOST_GIL_CLASS_REQUIRE(View, boost::gil, ImageViewConcept)
544 using VB = detail::__kth_channel_view<K,View,view_is_basic<View>::value>;
546 using type = typename VB::type;
547 static type make(const View& src) { return VB::make(src); }
550 /// \ingroup ImageViewTransformationsKthChannel
551 template <int K, typename View>
552 typename kth_channel_view_type<K,View>::type kth_channel_view(const View& src) {
553 return kth_channel_view_type<K,View>::make(src);
556 } } // namespace boost::gil