javax.media.jai
Class ImageMIPMap

java.lang.Object
  extended byjavax.media.jai.ImageMIPMap
All Implemented Interfaces:
ImageJAI, PropertyChangeEmitter, PropertySource, WritablePropertySource
Direct Known Subclasses:
ImagePyramid

public class ImageMIPMap
extends Object
implements ImageJAI

A class implementing the "MIP map" operation on a RenderedImage. Given a RenderedImage, which represents the image at the highest resolution level, the image at each lower resolution level may be derived by performing a specific chain of operations to down sample the image at the next higher resolution level repeatedly. The highest resolution level is defined as level 0.

The downSampler is a chain of operations that is used to derive the image at the next lower resolution level from the image at the current resolution level. That is, given an image at resolution level i, the downSampler is used to obtain the image at resolution level i+1. The chain may contain one or more operation nodes; however, each node must be a RenderedOp. The parameter points to the last node in the chain. The very first node in the chain must be a RenderedOp that takes one RenderedImage as its source. All other nodes may have multiple sources. When traversing back up the chain, if a node has more than one source, the first source, source0, is used to move up the chain. This parameter is saved by reference.

See Also:
ImagePyramid

Field Summary
protected  RenderedImage currentImage
          The image at the current resolution level.
protected  int currentLevel
          The current resolution level.
protected  RenderedOp downSampler
          The operation chain used to derive the lower resolution images.
protected  PropertyChangeSupportJAI eventManager
          A helper object to manage firing events.
protected  RenderedImage highestImage
          The image with the highest resolution.
protected  WritablePropertySourceImpl properties
          A helper object to manage the image properties.
 
Constructor Summary
protected ImageMIPMap()
          The default constructor.
  ImageMIPMap(RenderedImage image, AffineTransform transform, Interpolation interpolation)
          Constructor.
  ImageMIPMap(RenderedImage image, RenderedOp downSampler)
          Constructor.
  ImageMIPMap(RenderedOp downSampler)
          Constructs a new ImageMIPMap from a RenderedOp chain.
 
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
          Add a PropertyChangeListener to the listener list.
 void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)
          Add a PropertyChangeListener for a specific property.
protected  RenderedOp duplicate(RenderedOp op, Vector images)
          Duplicates a RenderedOp chain.
 RenderableImage getAsRenderable()
          Returns the current image as a RenderableImage.
 RenderableImage getAsRenderable(int numImages, float minX, float minY, float height)
          Returns the current image as a RenderableImage.
 RenderedImage getCurrentImage()
          Returns the image at the current resolution level.
 int getCurrentLevel()
          Returns the current resolution level.
 RenderedImage getDownImage()
          Returns the image at the next lower resolution level, obtained by applying the downSampler on the image at the current resolution level.
 RenderedImage getImage(int level)
          Returns the image at the specified resolution level.
 Object getProperty(String name)
          Returns the specified property.
 Class getPropertyClass(String name)
          Returns the class expected to be returned by a request for the property with the specified name.
 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.
 void removeProperty(String name)
          Removes the named property from the ImageMIPMap.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Remove a PropertyChangeListener from the listener list.
 void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)
          Remove a PropertyChangeListener for a specific property.
 void setProperty(String name, Object value)
          Sets a property on a ImageMIPMap.
protected  Vector vectorize(RenderedImage image)
          Creates and returns a Vector containing a single element equal to the supplied RenderedImage.
protected  Vector vectorize(RenderedImage im1, RenderedImage im2)
          Creates and returns a Vector containing two elements equal to the supplied RenderedImages in the order given.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

highestImage

protected RenderedImage highestImage
The image with the highest resolution.


currentImage

protected RenderedImage currentImage
The image at the current resolution level.


currentLevel

protected int currentLevel
The current resolution level.


downSampler

protected RenderedOp downSampler
The operation chain used to derive the lower resolution images.


eventManager

protected PropertyChangeSupportJAI eventManager
A helper object to manage firing events.

Since:
JAI 1.1

properties

protected WritablePropertySourceImpl properties
A helper object to manage the image properties.

Since:
JAI 1.1
Constructor Detail

ImageMIPMap

protected ImageMIPMap()
The default constructor.


ImageMIPMap

public ImageMIPMap(RenderedImage image,
                   AffineTransform transform,
                   Interpolation interpolation)
Constructor. The down sampler is an "affine" operation that uses the supplied AffineTransform and Interpolation objects. All input parameters are saved by reference.

Parameters:
image - The image with the highest resolution.
transform - An affine matrix used with an "affine" operation to derive the lower resolution images.
interpolation - The interpolation method for the "affine" operation. It may be null, in which case the default "nearest neighbor" interpolation method is used.
Throws:
IllegalArgumentException - if image is null.
IllegalArgumentException - if transform is null.

ImageMIPMap

public ImageMIPMap(RenderedImage image,
                   RenderedOp downSampler)
Constructor. The downSampler points to the last operation node in the RenderedOp chain. The very first operation in the chain must not have any source images specified; that is, its number of sources must be 0. All input parameters are saved by reference.

Parameters:
image - The image with the highest resolution.
downSampler - The operation chain used to derive the lower resolution images. No validation is done on the first operation in the chain.
Throws:
IllegalArgumentException - if image is null.
IllegalArgumentException - if downSampler is null.

ImageMIPMap

public ImageMIPMap(RenderedOp downSampler)
Constructs a new ImageMIPMap from a RenderedOp chain. The downSampler points to the last operation node in the RenderedOp chain. The source image is determined by traversing up the chain: starting at the bottom node, given by the downSample parameter, we move to the first source of the node and repeat until we find either a sourceless RenderedOp or any other type of RenderedImage. The downSampler parameter is saved by reference and should not be modified during the lifetime of any ImageMIPMap referring to it.

Parameters:
downSampler - The operation chain used to derive the lower resolution images. The source of the first node in this chain is taken as the image with the highest resolution.
Throws:
IllegalArgumentException - if downSampler is null.
IllegalArgumentException - if downSampler has no sources.
IllegalArgumentException - if an object other than a RenderedImage is found in the downSampler chain.
Method Detail

getPropertyNames

public String[] getPropertyNames()
Returns an array of Strings recognized as names by this property source. If no property names match, null will be returned.

The default implementation returns null, i.e., no property names are recognized.

Specified by:
getPropertyNames in interface PropertySource
Returns:
An array of Strings giving the valid property names.

getPropertyNames

public String[] getPropertyNames(String prefix)
Returns an array of Strings recognized as names by this property source that begin with the supplied prefix. If no property names are recognized, or no property names match, null will be returned. The comparison is done in a case-independent manner.

Specified by:
getPropertyNames in interface PropertySource
Parameters:
prefix - the supplied prefix for the property source.
Returns:
An array of Strings giving the valid property names.
Throws:
IllegalArgumentException - if prefix is null.

getPropertyClass

public Class getPropertyClass(String name)
Returns the class expected to be returned by a request for the property with the specified name. If this information is unavailable, null will be returned.

Specified by:
getPropertyClass in interface PropertySource
Parameters:
name - the name of the property, as a String.
Returns:
The Class expected to be return by a request for the value of this property or null.
Throws:
IllegalArgumentException - if name is null.
Since:
JAI 1.1

getProperty

public Object getProperty(String name)
Returns the specified property. The default implementation returns java.awt.Image.UndefinedProperty.

Specified by:
getProperty in interface PropertySource
Parameters:
name - The name of the property.
Returns:
The value of the property, as an Object.
Throws:
IllegalArgumentException - if name is null.

setProperty

public void setProperty(String name,
                        Object value)
Sets a property on a ImageMIPMap.

Specified by:
setProperty in interface WritablePropertySource
Parameters:
name - a String containing the property's name.
value - the property, as a general Object.
Throws:
IllegalArgumentException - If name or value is null.
Since:
JAI 1.1

removeProperty

public void removeProperty(String name)
Removes the named property from the ImageMIPMap.

Specified by:
removeProperty in interface WritablePropertySource
Parameters:
name - the name of the property, as a String.
Throws:
IllegalArgumentException - if name is null.
Since:
JAI 1.1

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Add a PropertyChangeListener to the listener list. The listener is registered for all properties.

Specified by:
addPropertyChangeListener in interface PropertyChangeEmitter
Since:
JAI 1.1

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener listener)
Add a PropertyChangeListener for a specific property. The listener will be invoked only when a call on firePropertyChange names that specific property. The case of the name is ignored.

Specified by:
addPropertyChangeListener in interface PropertyChangeEmitter
Since:
JAI 1.1

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Remove a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Specified by:
removePropertyChangeListener in interface PropertyChangeEmitter
Since:
JAI 1.1

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener listener)
Remove a PropertyChangeListener for a specific property. The case of the name is ignored.

Specified by:
removePropertyChangeListener in interface PropertyChangeEmitter
Since:
JAI 1.1

getCurrentLevel

public int getCurrentLevel()
Returns the current resolution level. The highest resolution level is defined as level 0.


getCurrentImage

public RenderedImage getCurrentImage()
Returns the image at the current resolution level.


getImage

public RenderedImage getImage(int level)
Returns the image at the specified resolution level. The requested level must be greater than or equal to 0 or null will be returned.

Parameters:
level - The specified level of resolution

getDownImage

public RenderedImage getDownImage()
Returns the image at the next lower resolution level, obtained by applying the downSampler on the image at the current resolution level.


duplicate

protected RenderedOp duplicate(RenderedOp op,
                               Vector images)
Duplicates a RenderedOp chain. Each node in the chain must be a RenderedOp. The op parameter points to the last RenderedOp in the chain. The very first op in the chain must have no sources and its source will be set to the supplied image vector. When traversing up the chain, if any node has more than one source, the first source will be used. The first source of each node is duplicated; all other sources are copied by reference.

Parameters:
op - RenderedOp chain
Throws:
IllegalArgumentException - if op is null.
IllegalArgumentException - if images is null.

getAsRenderable

public RenderableImage getAsRenderable(int numImages,
                                       float minX,
                                       float minY,
                                       float height)
Returns the current image as a RenderableImage. This method returns a MultiResolutionRenderableImage. The numImages parameter indicates the number of RenderedImages used to construct the MultiResolutionRenderableImage. Starting with the current image, the images are obtained by finding the necessary number of lower resolution images using the downSampler. The current level and current image will not be changed. If the width or height reaches 1, the downsampling will stop and return the renderable image.

The numImages should be greater than or equal to 1. If a value of less than 1 is specified, this method uses 1 image, which is the current image.

Parameters:
numImages - The number of lower resolution images.
minX - The minimum X coordinate of the Renderable, as a float.
minY - The minimum Y coordinate of the Renderable, as a float.
height - The height of the Renderable, as a float.
Throws:
IllegalArgumentException - if height is less than 0.
See Also:
MultiResolutionRenderableImage

getAsRenderable

public RenderableImage getAsRenderable()
Returns the current image as a RenderableImage. This method returns a MultiResolutionRenderableImage with the current image as the only source image, minX and minY set to 0.0, and height set to 1.0.

See Also:
MultiResolutionRenderableImage

vectorize

protected final Vector vectorize(RenderedImage image)
Creates and returns a Vector containing a single element equal to the supplied RenderedImage.

Since:
JAI 1.1

vectorize

protected final Vector vectorize(RenderedImage im1,
                                 RenderedImage im2)
Creates and returns a Vector containing two elements equal to the supplied RenderedImages in the order given.

Since:
JAI 1.1