Image Properties

Chapter describes image properties.

11.1 Introduction

In addition to the pixel data, images occasionally have many other kinds of data associated with them. These data, known as properties, is a simple database of arbitrary data attached to the images. Each property is simply an Object with a unique, case-insensitive name.

The properties are arbitrary and depend on the intended application. ImageN provides methods that enable effective use of properties in the context of an image processing application but, in most cases, leaves the specification of the property objects themselves to the developer.

Some examples of properties are:

  • Descriptions of exotic shapes, such as hexagonal grids
  • Mapping from digital pixel values to photometric values
  • A defined region of interest (ROI) in the source image

Every node in an image chain may be queried for its properties. The value of a property at a particular node may be derived by one of the following mechanisms:

  • It may be copied from the node's sources. This is the default behavior if no other behavior is specified.
  • It may be produced by the node from non-property information available in the node.
  • It may be synthesized by the node from a rendering.
  • It may be inherited or produced computationally from the properties of the node's sources.
  • It may be set explicitly by the setProperty method in one of the appropriate classes: Planarimage, RenderedOp, or RenderableOp. Properties of a node may not be set once the node has been rendered.

When the value of a property is requested from a node in a rendered chain, i.e., a RenderedOp node, it will be derived from the first of the following for which it is defined:

The same order of precedence applies in the case of renderable chains, i.e., RenderableOp nodes, with the exception of item 4, viz., properties created within the contextual rendering of the RenderableOp are not propagated back to the RenderableOp node itself.

There are a couple of important items to note at this point. First, when a node is created with another node or nodes as its source(s), it might invoke methods on the source node that force the source node to be rendered. Consequently properties should be set on a node before it is used as the source of other operations. Second, the rendering of a node does not inherit the properties of the node itself nor are properties set on the rendering of the node propagated back to the node. Image properties are controlled and generated by the PropertySource and PropertyGenerator interfaces.

11.1.1 The PropertySource Interface

The PropertySource interface contains methods from the RenderedImage and RenderableImage interfaces that identify and read properties. PlanarImage, RenderableOp, and RenderedOp all implement PropertySource.

The interface consists of the getProperty and getPropertyNames methods familiar from the RenderedImage and RenderableImage interfaces.

PropertySource is implemented by ImageJAI. Since all RenderedImages used within ImageN are descendents of PlanarImage which implements ImageJAI, all images may be assumed to implement PropertySource.

API: org.eclipse.imagen.PropertySource

  • String[] getPropertyNames()
  • String[] getPropertyNames(String prefix)
  • Object getProperty(String name)

11.1.2 The PropertyGenerator Interface

The PropertyGenerator interface allows you to affect the property inheritance computation of an operation. A PropertyGenerator simply implements two methods:

  • The getPropertyNames method returns a list of the names of all available properties.

  • The getProperty method returns the value of the property, given the property name and a RenderedOp.

New PropertyGenerators may be added to the OperationRegistry to be applied at a particular operation node. The OperationRegistry also allows an existing property on a node to be suppressed if it is no longer useful. See Chapter 14, "Extending the API," for more information on the OperationRegistry.

API: org.eclipse.imagen.PropertyGenerator

  • String[] getPropertyNames()

  • Object getProperty(String name, RenderedOp op)

11.2 Synthetic Properties

Certain properties are synthesized when a node is rendered. These synthetic properties are image width (image_width), image height (image_height), minimum x coordinate (image_min_x_coord), and minimum y coordinate (image_min_y_coord). All of these properties have a value of class java.lang.Integer. These properties are fixed and any attempt to set them will result in an error.

11.3 Regions of Interest

The specification of a region of interest (ROI) is a common property that is supported by all of the standard operators. The ROI is simply a description of some portion of an image. This description is propogated, along with the image, through the rendering chain. The ROI is transformed appropriately (inherited) for all geometric and area operators. For all other types of operations it is simply copied. The ROI has no bearing on the processing of image pixels, although in its rendered form it can be used as input to histogram operations. For more information, see Section 6.2, "Region of Interest Control."

The ROI may be used as an argument to the TiledImage.set and TiledImage.setData methods so as to copy a selected area of a source or Raster into an existing TiledImage (see Section 4.2.2, "Tiled Image" ). The ROI may also be used as an argument to many compositing (see Section 7.11.2, "Image Compositing") and statistical operators (see Chapter 9, "Image Analysis").

11.4 Complex Data

The COMPLEX property has value of class java.lang.Boolean and indicates whether the pixel values of an image represent complex-value data. (A complex-valued image wherein each pixel has N complex elements contains 2N bands with the real and imaginary components of the ith complex element being stored in bands 2i and 2i + 1, respectively.) This property may be produced by a given node either with a fixed value or with a value dependent on the parameters of the node. See Section 7.9, "Frequency Domain Processing."