Programming in Java Advanced Imaging

C H A P T E R11

THIS 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. JAI 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:

1. Synthetic properties (see below).

2. Local properties, i.e., those set by an invocation of setProperty() on the node.

3. The source image of the operation specified by invoking the method OperationRegsitry.copyPropertyFromSource().

4. The rendering of the node. Note however that properties set by invoking setProperty() on the rendering of the node rather than on the node itself will not be propagated back to the node itself.

5. Any PropertyGenerators either defined by the associated operation or added by an invocation of RenderedOp.addPropertyGenerator(). PropertyGenerators added by the latter method supersede those associated with the operation, e.g., via its OperationDescriptor.

6. The sources of the operation. The first source has higher precedence than the second source and so on.

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 JAI are descendents of PlanarImage which implements ImageJAI, all images may be assumed to implement PropertySource.

API: javax.media.jai.PropertySource

String[] getPropertyNames()

returns an array of Strings recognized as names by this property source.

String[] getPropertyNames(String prefix)

returns an array of Strings recognized as names by this property source that begin with the supplied prefix. If the method cannot find any property names that match, null is returned.

Object getProperty(String name)

returns the value of a property.

Parameters:

name

The name of the property, as a String.

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: javax.media.jai.PropertyGenerator

String[] getPropertyNames()

returns an array of Strings naming properties emitted by this property generator.

Object getProperty(String name, RenderedOp op)

computes the value of a property relative to an environment of pre-existing properties emitted by the sources of a RenderedOp, and the parameters of that operation.

Parameters:	name	The name of the property, as a String.
	op	The RenderedOp representing the operation.

The operation name, sources, and ParameterBlock of the RenderedOp being processed may be obtained by means of the op.getOperationName, op.getSources(), and op.getParameterBlock() methods. It is legal to call getProperty() on the operation's sources.

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 that is propagated through the rendering chain. Image pixels that lie outside the ROI are simply ignored by the rendering chain. For more information, see Section 6.2, "Region of Interest Control."

ROIs are defined and stored using the ROI and ROIShape classes. The ROIShape class stores its area using Shape classes, which define the area as a geometrical description of its region of support. The ROI class stores an area as a grayscale (single-banded) image. The ROIShape class provides the most efficient use of storage and transformation since it applies a Boolean operation to the Shape. The ROI class applies a threshold value to each pixel in the image. An ROIShape may be converted into an ROI, but an ROI cannot be converted into an ROIShape.

The ROI, like other properties, does not affect pixel processing. The ROI is transformed appropriately (inherited) for all geometric and area operators. For all other types of operations it is simply copied.

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."

---

Programming in Java Advanced Imaging

Copyright © 1999, Sun Microsystems, Inc. All rights reserved.