Image types

Last modified: January 19, 2009

Contents

Editors:Michael Droettboom, Christoph Dalitz

There are a number of different image types in Gamera that serve different purposes. Fortunately, they all share a common interface, which allows many operations on images to be compiled for different image types from the same source code using C++ templates. This is why all Gamera plugin methods are templatized (see Writing Gamera Plugins).

Image types are specified on two axes: 1] the type of pixels the contain, and 2] the storage type:

Pixel types

The pixels in an image can be one of the following types:

RGB
24-bit color pixels (8-bits per pixel), representing 2 ^ 24 (16,777,216) different colors. RGBPixel objects have some special properties and methods.
GREYSCALE
8-bit greyscale, representing 256 different levels of grey.
GREY16
16-bit greyscale, representing 65,536 different levels of grey.
ONEBIT
For black-and-white images. The underlying representation is actually 16 bits-per-pixel, since connected component labelling stores information with each pixel. This seems like wasted space, but since connected component labelling is so common in Gamera, it more often is a space savings from the fact that the image data can be "shared."
FLOAT
Double-precision floating point greyscale. This is useful for images that need a really wide dynamic range.

Warning

Unfortunately, at this time FLOAT images can not be saved or loaded.

Note

When FLOAT images are displayed in the GUI, the output is automatically "normalized" so that the total range in the image is equal to the range of brightnesses your monitor can display.

The pixel type of an image can be retrieved in two ways.

image.pixel_type_name

returns a string which is one of RGB, GreyScale, Grey16, OneBit or Float.

image.data.pixel_type

returns an integer which will be one of the constants RGB, GREYSCALE, GREY16, ONEBIT or FLOAT.

Storage formats

Gamera has two ways of storing the image data in memory behind the scenes:

DENSE
Uncompressed. The image data is a contiguous chunk of memory that is addressed in row-major order (left-to-right, top-to-bottom).
RLE
Run-length encoded. For certain kinds of images, run-length-encoding can be a performance improvement since less data needs to be transferred between main memory and the CPU.

Warning

At present, RLE is only available for ONEBIT images.

The storage format of an image can be determined in two ways.

image.storage_format_name()

returns a string which is either Dense or RLE.

image.data.storage_format

returns an integer corresponding to the constants DENSE and RLE.

Note

Any performance improvement should be justified only by profiling on real-world data

Image methods

The methods on images include all of the plugin methods in the current environment. These are documented in the plugin reference. In addition, there are number of core properties and methods.

Constructors

Image.__init__

The Image constructor creates a new image with newly allocated underlying data.

There are multiple ways to create an Image:

  • Image (Point upper_left, Point lower_right, Choice pixel_type = ONEBIT, Choice format = DENSE)
  • Image (Point upper_left, Size size, Choice pixel_type = ONEBIT, Choice format = DENSE)
  • Image (Point upper_left, Dim dim, Choice pixel_type = ONEBIT, Choice format = DENSE)
  • Image (Rect rectangle, Choice pixel_type = ONEBIT, Choice format = DENSE)
  • Image (Image image, Choice pixel_type = ONEBIT, Choice format = DENSE)

Deprecated forms:

  • Image (Point upper_left, Dimensions dimensions, Choice pixel_type = ONEBIT, Choice format = DENSE)
  • Image (Int offset_y, Int offset_x, Int nrows, Int ncols, Choice pixel_type = ONEBIT, Choice format = DENSE)

Note that the constructor taking an Image creates a new image with the same position and dimensions as the passed in image, but does not copy the data. (For that, use image_copy).

pixel_type
An integer value specifying the type of the pixels in the image. See pixel types for more information.
storage_format
An integer value specifying the method used to store the image data. See storage formats for more information.

SubImage.__init__

Creates a new view on existing data.

There are a number of ways to create a subimage:

  • SubImage (Image image, Point upper_left, Point lower_right)
  • SubImage (Image image, Point upper_left, Size size)
  • SubImage (Image image, Point upper_left, Dim dim)
  • SubImage (Image image, Rect rectangle)

Deprecated forms:

  • SubImage (Image image, Point upper_left, Dimensions dimensions)
  • SubImage (Image image, Int offset_y, Int offset_x, Int nrows, Int ncols)

Changes to subimages will affect all other subimages viewing the same data.

Cc.__init__

Creates a connected component representing part of a OneBit image.

It is rare to create one of these objects directly: most often you will just use cc_analysis to create connected components.

There are a number of ways to create a Cc:

  • Cc (Image image, Int label, Point upper_left, Point lower_right)
  • Cc (Image image, Int label, Point upper_left, Size size)
  • Cc (Image image, Int label, Point upper_left, Dim dim)
  • Cc (Image image, Int label, Rect rectangle)

Deprecated forms:

  • Cc (Image image, Int label, Point upper_left, Dimensions dimensions)
  • Cc (Image image, Int label, Int offset_y, Int offset_x, Int nrows, Int ncols)
label
The pixel value used to represent this Cc.

Pixel access

get

get (Point p)

Gets a pixel value at the given (x, y) coordinate.

A 2-element sequence may be used in place of the Point argument. For instance, the following are all equivalent:

px = image.get(Point(5, 2))
px = image.get((5, 2))
px = image.get([5, 2])

This coordinate is relative to the image view, not the logical coordinates.

set

set (Point p, Pixel value)

Sets a pixel value at the given (x, y) coordinate.

A 2-element sequence may be used in place of the Point argument. For instance, the following are all equivalent:

image.set(Point(5, 2), value)
image.set((5, 2), value)
image.set([5, 2], value)

This coordinate is relative to the image view, not the logical coordinates.

Informational

These methods provide information about the image.

pixel_type_name

String pixel_type_name ()

Returns a string representing the pixel type of the image. Intended primarily for display (GUI) purposes, since using the integer values in Image.data.pixel_type is more efficient.

See pixel types for more information.

storage_format_name

String storage_format_name ()

Returns a string representing the storage format of the image. Intended primarily for display (GUI) purposes, since using the integer values in Image.data.storage_format is more efficient.

See storage formats for more information.

memory_size

Int memory_size ()

Returns the memory used by the underlying data of the image (in bytes). Note that this memory may be shared with other image views on the same data.

resolution

(read/write property)

The resolution of the image

label

(read/write property)

The pixel label value for the Cc

data

(read-only property)

Returns the underlying ImageData object.

ncols

(int property)

The number of columns in the rectangle.

nrows

(int property)

The number of rows in the rectangle.

offset_x

(int property)

The left edge of the rectangle in the logical coordinate space.

offset_y

(int property)

The upper edge of the rectable in the logical coordinate space.

ul

(Point property)

The upper-left coordinate of the rectangle in logical coordinate space.

ur

(Point property)

The upper-right coordinate of the rectangle in logical coordinate space.

ll

(Point property)

The lower-left coordinate of the rectangle in logical coordinate space.

lr

(Point property)

The lower-right coordinate of the rectangle in logical coordinate space.

Bounding box

Bounding box operations on Image objects are inherited from the Rect class.

Image functions

There are a number of free functions for dealing with images.

File

load_image

load_image (FileOpen filename, Choice storage_format = DENSE)

Load an image from the given filename. At present, TIFF and PNG files are supported.

storage_format
The type of storage format to use for the resulting image.

image_info

ImageInfo image_info (FileOpen filename)

Retrieve information about an image file without loading it.

The result is an ImageInfo object about a given filename. The ImageInfo object gives information such as the type (color, greyscale, onebit), the bit-depth, resolution, size, etc.

GUI

display_multi

display_multi (ImageList list)

Displays a list of images in a grid-like window. This function has no effect if the Gamera GUI is not running.