ImageData<T> objects

Data objects are instances of the ImageData<T> class (in include/image_data.hpp) where T is the pixel type. If you wish to use run-length encoding to store the data, you can use the RleImageData<T> class. These classes both have the same interface and are completely interchangeable, but will exhibit different algorithmic complexities.

There are some typedefs in image_types.hpp to make creating different kinds of image data objects more convenient:

/*
  Image Data
 */
typedef ImageData<GreyScalePixel> GreyScaleImageData;
typedef ImageData<Grey16Pixel> Grey16ImageData;
typedef ImageData<FloatPixel> FloatImageData;
typedef ImageData<RGBPixel> RGBImageData;
typedef ImageData<OneBitPixel> OneBitImageData;
typedef RleImageData<OneBitPixel> OneBitRleImageData;

There are a few different constructors available for data objects:

ImageData(const Dim& dim, const Point& offset);
ImageData(const Dim& dim); // offset == (0, 0)
ImageData(const Size& size, const Point& offset);
ImageData(const Size& size); // offset == (0, 0)
ImageData(const Rect& rect);

There are also some deprecated forms that you may see in legacy code, but which are no longer supported since they are not consistent about specifying x before y:

ImageData(size_t nrows = 1, size_t ncols = 1, size_t page_offset_y = 0,
          size_t page_offset_x = 0);
ImageData(const Size& size, size_t page_offset_y = 0,
          size_t page_offset_x = 0);
ImageData(const Dimensions& dim, size_t page_offset_y = 0,
          size_t page_offset_x = 0);

The offset arguments are used to specify a logical offset of the data. For instance, if the image data is from part of the page, the upper left corner may not be logically (0, 0). This is purely for logical purposes when your system needs to know the relative positions of image bounding boxes, and does not affect the size of the image data created in any way.

The Size and Dim classes are simple ways of storing sizes and dimensions defined in gamera/dimensions.hpp. (See the Dimension types chapter for more information). Size(w, h) is always equal to Dim(w + 1, h + 1). Both forms are supported to make it easier to adapt existing algorithms that use one or the other standard.

While there are other public members and methods to the ImageData class, we do not recommend using any of them unless you really know what you're doing. All of the image data can be accessed much more flexibly and conveniently through ImageView objects.

ImageView<T> objects

Views objects are instances of the ImageView<T> class (in include/image_view.hpp), where T is the data object type (a templatization of ImageData<T>). There is also a special version of ImageView<T> for connected components, ConnectedComponent<T> defined in include/connected_components.hpp. Connected components are discussed below.

As with the data objects, there are some typedefs for convenience:

/*
  ImageView
 */
typedef ImageView<GreyScaleImageData> GreyScaleImageView;
typedef ImageView<Grey16ImageData> Grey16ImageView;
typedef ImageView<FloatImageData> FloatImageView;
typedef ImageView<RGBImageData> RGBImageView;
typedef ImageView<OneBitImageData> OneBitImageView;
typedef ImageView<OneBitRleImageData> OneBitRleImageView;

/*
  Connected-components
 */
typedef ConnectedComponent<OneBitImageData> Cc;
typedef ConnectedComponent<OneBitRleImageData> RleCc;

There are a number of different ways to construct image views:

// Creates a view covering all of the data
ImageView(T& image_data);

ImageView(T& image_data, const Rect& rect,
          bool do_range_check = true);
ImageView(T& image_data, const Point& upper_left,
          const Point& lower_right, bool do_range_check = true)
ImageView(T& image_data, const Point& upper_left,
          const Size& size, bool do_range_check = true)
ImageView(T& image_data, const Point& upper_left,
          const Dim& dim, bool do_range_check = true)

There are also some deprecated forms that you may see in legacy code, but which are no longer supported since they are not consistent about specifying x before y:

// Creates a view with a specified bounding box
ImageView(T& image_data, size_t offset_y,
          size_t offset_x, size_t nrows, size_t ncols,
          bool do_range_check = true);
ImageView(T& image_data, const Point& upper_left,
          const Dimensions& dim, bool do_range_check = true)

The Size, Point and Dim classes are simple ways of storing sizes and dimensions defined in gamera/dimensions.hpp. (See the Dimension types chapter for more information).

Coordinates for any given bounding boxes are relative to the offset of the underlying data. Therefore:

// Create data with a size of (64, 64) and an offset of (32, 32);
OneBitImageData image_data(Size(64, 64), Point(32, 32));
// This is a view over all of the data
OneBitImageView image_view(image_data, Point(32, 32), Size(64, 64));
// This raises an exception, since it's out of range for the data
OneBitImageView image_view(image_data, Point(0, 0), Size(64, 64));

You can get the type of the pixels referenced by an ImageView using the expression typename T::value_type.

TypeIdImageFactory

TypeIdImageFactory is useful if you want to create an image of a specific type based on a pair of integer constants. For example, the following code snippit creates a DENSE or RLE image based on an integer constant passed in as a parameter to the function. Note that the types of each of the TypeIdImageFactory s are different and not polymorphic, so the interior function (threshold_fill) must be called from two locations.

template<class T>
Image* threshold(const T &m, int threshold, int storage_format) {
  if (storage_format == DENSE) {
    typedef TypeIdImageFactory<ONEBIT, DENSE> fact_type;
    typename fact_type::image_type* view = fact_type::create(m.origin(), m.dim());
    threshold_fill(m, *view, threshold);
    return view;
  } else {
    typedef TypeIdImageFactory<ONEBIT, RLE> fact_type;
    typename fact_type::image_type* view = fact_type::create(m.origin(), m.dim());
    threshold_fill(m, *view, threshold);
    return view;
  }
}

ImageFactory

It is a common use case to create a result image whose type is related to the type of an input image. In many cases, one could just use the same type as the result type. However, if a Cc image type is passed into a function, you would most likely want to return a regular OneBit image as a result. ImageFactory is designed to get around this problem. It will create an appropriate result type from a given input type. For example, see the following code snippet:

template<class T>
Image* abutaleb_threshold(const T &m, int storage_format) {
  typedef typename ImageFactory<T>::view_type view_type;
  view_type* average = mean(m);
...

get and set methods

This is perhaps the most straightforward way to access the pixels of an image. There are two public methods of ImageView:

• value_type get (const Point& point)
• void set (const Point& point, value_type value)

There are also deprecated forms that you may see in legacy code:

• value_type get (size_t row, size_t col)
• void set (size_t row, size_t col, value_type value)

get returns the value of the pixel at the given row and column. set changes the pixel at the given row and column to the given value.

An example using get / set over an entire image:

template<class T>
typename ImageFactory<T>::view_type* test_get_set(const T& image) {
  typedef typename ImageFactory<T>::data_type data_type;
  typedef typename ImageFactory<T>::view_type view_type;
  data_type* new_data = new data_type(image);
  view_type* new_view = new view_type(*new_data);

  for (size_t r = 0; r < in.nrows(); ++r) {
    for (size_t c = 0; c < in.ncols(); ++c) {
      new_view.set(Point(c, r), image.get(Point(c, r)) / 2);
    }
  }

  return new_view;
}

C-style 2-dimensional array

An alternative is to use the notation of C-style 2-dimensional arrays:

value = image[row][col];
image[row][col] = value;

This interface is provided as a convenience to support the large body of legacy code written in this style. Note that [row][col] is the reverse of get and set's Point(x, y). Keep in mind, it is not really a 2-dimensional array underneath -- this view is "faked."

An example using the C-style 2-dimensional array interface:

template<class T>
typename ImageFactory<T>::view_type* test_c_2d(const T& image) {
  typedef typename ImageFactory<T>::data_type data_type;
  typedef typename ImageFactory<T>::view_type view_type;
  data_type* new_data = new data_type(image);
  view_type* new_view = new view_type(*new_data);

  for (size_t r = 0; r < image.nrows(); ++r) {
    for (size_t c = 0; c < image.ncols(); ++c) {
      (*new_view)[r][c] = image[r][c] / 2;
    }
  }

  return new_view;
}

Iterators

Iterators provide a lot of readability and convenience advantages over the other approaches.

Gamera has three kinds of iterators:

1. Vector iterator: a one-dimensional iterator that iterates from the upper left hand corner, left-to-right, top-to-bottom.
2. Row/column iterators: Iterates along either rows or columns. Incrementing the iterator moves one row down or one column to the right. Calling begin() on a row_iterator, returns a col_iterator and vice versa.
3. Two-dimensional iterators: Provide free movement of the iterator in any direction.

The first two kinds of iterators follow the conventions of the C++ STL enough that they can be used with STL algorithms. All iterators are available in const and non-const versions. const iterators cannot change the underlying data. If you have an image passed into your function as a const ImageView<T> &, you will not be able to change the pixels in the image, and thus will only be able to get const iterators from it.

Note that you can call row( ) or col( ) on any iterator to obtain the current row and column position of the iterator.

All Gamera iterators can get/set their values in two ways, both of which boiling down to exactly the same machine code, and therefore having the same efficiency:

1. The standard "C pointer-like" way:

// i is any iterator type
value = *i;
*i = value;

2. Using get and set methods:

// i is any iterator type
value = i.get();
i.set(value);

template<class T>
typename ImageFactory<T>::view_type* test_vec_iterator(const T& image) {
  typedef typename ImageFactory<T>::data_type data_type;
  typedef typename ImageFactory<T>::view_type view_type;
  data_type* new_data = new data_type(image);
  view_type* new_view = new view_type(*new_data);

  typename T::const_vec_iterator i = image.vec_begin();
  typename view_type::vec_iterator j = new_view->vec_begin();

  for ( ; i != image.vec_end(); ++i, ++j) {
    *j = *i / 2;  // or  j.set(i.get() / 2);
  }

  return new_view;
}

#include <algorithm>

template<class T>
void fill_white(T& image) {
  std::fill(image.vec_begin(), image.vec_end(), white(image));
}

template<class T>
typename ImageFactory<T>::view_type* test_row_col_iterator(const T& image) {
  typedef typename ImageFactory<T>::data_type data_type;
  typedef typename ImageFactory<T>::view_type view_type;
  data_type* new_data = new data_type(image);
  view_type* new_view = new view_type(*new_data);

  typedef typename T::const_row_iterator IteratorI;
  IteratorI ir = image.row_begin();
  typedef typename view_type::row_iterator IteratorJ;
  IteratorJ jr = new_view->row_begin();
  for ( ; ir != image.row_end(); ++ir, ++jr) {
    typename IteratorI::iterator ic = ir.begin();
    typename IteratorJ::iterator jc = jr.begin();
    for ( ; ic != ir.end(); ++ic, ++jc)
      *jc = *ic / 2;
  }

  return new_view;
}

template<class T>
typename ImageFactory<T>::view_type* test_col_row_iterator(const T& image) {
  typedef typename ImageFactory<T>::data_type data_type;
  typedef typename ImageFactory<T>::view_type view_type;
  data_type* new_data = new data_type(image);
  view_type* new_view = new view_type(*new_data);

  typedef typename T::const_col_iterator IteratorI;
  IteratorI ir = image.col_begin();
  typedef typename view_type::col_iterator IteratorJ;
  IteratorJ jr = new_view->col_begin();
  for ( ; ir != image.col_end(); ++ir, ++jr) {
    typename IteratorI::iterator ic = ir.begin();
    typename IteratorJ::iterator jc = jr.begin();
    for ( ; ic != ir.end(); ++ic, ++jc)
      *jc = *ic / 2;
  }

  return new_view;
}

Iterator upperLeft();
Iterator lowerRight();

typename T::Iterator i;

++i.x; // move right
--i.x; // move left
++i.y; // move down
--i.y; // move up

typename T::Iterator center, below;

...

below = center;
++below.y;   // 'below' points to the pixel below 'center'
++center.x;  // 'center' moved.  'below' did not.

typename T::Iterator center, below;

...

below = center.y + 1; // 'center' is not moved

typename T::Iterator i, relative;

...

relative = i + Diff2D(1, 1)   // down and to the right
relative = i[Diff2D(1, 1)]    // equivalent to above
relative = i + Diff2D(-1, -1) // up and to the left

relative = i - Diff2D(1, 1)   // up and to the left
relative = i - Diff2D(-1, -1) // down and to the right

relative = i(1, 1)            // down and to the right
relative = i(-1, -1)          // up and to the left

Speed tests

The different interfaces are provided primarily to support different programming styles. However, they do not run at the same speed.

The following graph shows the relative speeds of different pixel access methods (using the examples above). These results are largely processor and architecture dependent, so take them with a truckload of salt.

The performance of the 1-dimensional iterator is perhaps surprising, since it appears to be the simplest code. In fact, however, vec_iterators must support the image view model, and therefore do basic "range checking" upon each increment. This introduces some overhead.

The row/column iterators in row major order (rows in the outer loop) is the clear winner. Since the underlying data is stored row major order, accessing it in column major order is a major performance hit, in part due to the extra pointer arithmetic and in part due to worse cache performance.