libs/gil/doc/html/_sources/design/image.rst.txt

   1 Image
   2 =====
   3
   4 .. contents::
   5    :local:
   6    :depth: 2
   7
   8 Overview
   9 --------
  10
  11 An image is a container that owns the pixels of a given image view
  12 It allocates them in its constructor and deletes them in the destructor.
  13 It has a deep assignment operator and copy constructor. Images are used
  14 rarely, just when data ownership is important. Most STL algorithms operate on
  15 ranges, not containers. Similarly most GIL algorithms operate on image views
  16 (which images provide).
  17
  18 In the most general form images are N-dimensional and satisfy the following
  19 concept:
  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
  42 Two-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
  61 GIL 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
  71 Images, unlike locators and image views, don't have 'mutable' set of concepts
  72 because 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
  80 Models
  81 ------
  82
  83 GIL 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
  96 The image constructor takes an alignment parameter which allows for
  97 constructing images that are word-aligned or 8-byte aligned. The alignment is
  98 specified in bytes. The default value for alignment is 0, which means there is
  99 no padding at the end of rows. Many operations are faster using such
 100 1D-traversable images, because ``image_view::x_iterator`` can be used to
 101 traverse the pixels, instead of the more complicated ``image_view::iterator``.
 102 Note that when alignment is 0, packed images are aligned to the bit - i.e.
 103 there are no padding bits at the end of rows of packed images.