1Image 2===== 3 4.. contents:: 5 :local: 6 :depth: 2 7 8Overview 9-------- 10 11An image is a container that owns the pixels of a given image view 12It allocates them in its constructor and deletes them in the destructor. 13It has a deep assignment operator and copy constructor. Images are used 14rarely, just when data ownership is important. Most STL algorithms operate on 15ranges, not containers. Similarly most GIL algorithms operate on image views 16(which images provide). 17 18In the most general form images are N-dimensional and satisfy the following 19concept: 20 21.. code-block:: cpp 22 23 concept RandomAccessNDImageConcept<typename Img> : Regular<Img> 24 { 25 typename view_t; where MutableRandomAccessNDImageViewConcept<view_t>; 26 typename const_view_t = view_t::const_t; 27 typename point_t = view_t::point_t; 28 typename value_type = view_t::value_type; 29 typename allocator_type; 30 31 Img::Img(point_t dims, std::size_t alignment=0); 32 Img::Img(point_t dims, value_type fill_value, std::size_t alignment); 33 34 void Img::recreate(point_t new_dims, std::size_t alignment=0); 35 void Img::recreate(point_t new_dims, value_type fill_value, std::size_t alignment); 36 37 const point_t& Img::dimensions() const; 38 const const_view_t& const_view(const Img&); 39 const view_t& view(Img&); 40 }; 41 42Two-dimensional images have additional requirements: 43 44.. code-block:: cpp 45 46 concept RandomAccess2DImageConcept<RandomAccessNDImageConcept Img> 47 { 48 typename x_coord_t = const_view_t::x_coord_t; 49 typename y_coord_t = const_view_t::y_coord_t; 50 51 Img::Img(x_coord_t width, y_coord_t height, std::size_t alignment=0); 52 Img::Img(x_coord_t width, y_coord_t height, value_type fill_value, std::size_t alignment); 53 54 x_coord_t Img::width() const; 55 y_coord_t Img::height() const; 56 57 void Img::recreate(x_coord_t width, y_coord_t height, std::size_t alignment=1); 58 void Img::recreate(x_coord_t width, y_coord_t height, value_type fill_value, std::size_t alignment); 59 }; 60 61GIL images have views that model ``ImageViewConcept`` and operate on pixels. 62 63.. code-block:: cpp 64 65 concept ImageConcept<RandomAccess2DImageConcept Img> 66 { 67 where MutableImageViewConcept<view_t>; 68 typename coord_t = view_t::coord_t; 69 }; 70 71Images, unlike locators and image views, don't have 'mutable' set of concepts 72because immutable images are not very useful. 73 74.. seealso:: 75 76 - `RandomAccessNDImageConcept<Image> <reference/structboost_1_1gil_1_1_random_access_n_d_image_concept.html>`_ 77 - `RandomAccess2DImageConcept<Image> <reference/structboost_1_1gil_1_1_random_access2_d_image_concept.html>`_ 78 - `ImageConcept<Image> <reference/structboost_1_1gil_1_1_image_concept.html>`_ 79 80Models 81------ 82 83GIL provides a class, ``image``, which is templated over the value type 84(the pixel) and models ``ImageConcept``: 85 86.. code-block:: cpp 87 88 template 89 < 90 typename Pixel, // Models PixelValueConcept 91 bool IsPlanar, // planar or interleaved image 92 typename A=std::allocator<unsigned char> 93 > 94 class image; 95 96The image constructor takes an alignment parameter which allows for 97constructing images that are word-aligned or 8-byte aligned. The alignment is 98specified in bytes. The default value for alignment is 0, which means there is 99no padding at the end of rows. Many operations are faster using such 1001D-traversable images, because ``image_view::x_iterator`` can be used to 101traverse the pixels, instead of the more complicated ``image_view::iterator``. 102Note that when alignment is 0, packed images are aligned to the bit - i.e. 103there are no padding bits at the end of rows of packed images. 104