FileDocCategorySizeDatePackage
IIOParam.javaAPI DocJava SE 5 API25075Fri Aug 26 14:57:30 BST 2005javax.imageio

IIOParam

public abstract class IIOParam extends Object
A superclass of all classes describing how streams should be decoded or encoded. This class contains all the variables and methods that are shared by ImageReadParam and ImageWriteParam.

This class provides mechanisms to specify a source region and a destination region. When reading, the source is the stream and the in-memory image is the destination. When writing, these are reversed. In the case of writing, destination regions may be used only with a writer that supports pixel replacement.

Decimation subsampling may be specified for both readers and writers, using a movable subsampling grid.

Subsets of the source and destination bands may be selected.

version
0.5

Fields Summary
protected Rectangle
sourceRegion
The source region, on null if none is set.
protected int
sourceXSubsampling
The decimation subsampling to be applied in the horizontal direction. By default, the value is 1. The value must not be negative or 0.
protected int
sourceYSubsampling
The decimation subsampling to be applied in the vertical direction. By default, the value is 1. The value must not be negative or 0.
protected int
subsamplingXOffset
A horizontal offset to be applied to the subsampling grid before subsampling. The first pixel to be used will be offset this amount from the origin of the region, or of the image if no region is specified.
protected int
subsamplingYOffset
A vertical offset to be applied to the subsampling grid before subsampling. The first pixel to be used will be offset this amount from the origin of the region, or of the image if no region is specified.
protected int[]
sourceBands
An array of ints indicating which source bands will be used, or null. If null, the set of source bands to be used is as described in the comment for the setSourceBands method. No value should be allowed to be negative.
protected ImageTypeSpecifier
destinationType
An ImageTypeSpecifier to be used to generate a destination image when reading, or to set the output color type when writing. If non has been setm the value will be null. By default, the value is null.
protected Point
destinationOffset
The offset in the destination where the upper-left decoded pixel should be placed. By default, the value is (0, 0).
protected IIOParamController
defaultController
The default IIOParamController that will be used to provide settings for this IIOParam object when the activateController method is called. This default should be set by subclasses that choose to provide their own default controller, usually a GUI, for setting parameters.
protected IIOParamController
controller
The IIOParamController that will be used to provide settings for this IIOParam object when the activateController method is called. This value overrides any default controller, even when null.
Constructors Summary
protected IIOParam()
Protected constructor may be called only by subclasses.


                 
      
        controller = defaultController;
    
Methods Summary
public booleanactivateController()
Activates the installed IIOParamController for this IIOParam object and returns the resulting value. When this method returns true, all values for this IIOParam object will be ready for the next read or write operation. If false is returned, no settings in this object will have been disturbed (i.e., the user canceled the operation).

Ordinarily, the controller will be a GUI providing a user interface for a subclass of IIOParam for a particular plug-in. Controllers need not be GUIs, however.

return
true if the controller completed normally.
exception
IllegalStateException if there is no controller currently installed.
see
IIOParamController
see
#setController(IIOParamController)
see
#getController
see
#getDefaultController
see
#hasController

        if (!hasController()) {
            throw new IllegalStateException("hasController() == false!");
        }
        return getController().activate(this);
    
public javax.imageio.IIOParamControllergetController()
Returns whatever IIOParamController is currently installed. This could be the default if there is one, null, or the argument of the most recent call to setController.

return
the currently installed IIOParamController, or null.
see
IIOParamController
see
#setController
see
#getDefaultController
see
#hasController
see
#activateController()

        return controller;
    
public javax.imageio.IIOParamControllergetDefaultController()
Returns the default IIOParamController, if there is one, regardless of the currently installed controller. If there is no default controller, returns null.

return
the default IIOParamController, or null.
see
IIOParamController
see
#setController(IIOParamController)
see
#getController
see
#hasController
see
#activateController()

        return defaultController;
    
public java.awt.PointgetDestinationOffset()
Returns the offset in the destination image at which pixels are to be placed.

If setDestinationOffsets has not been called, a Point with zero X and Y values is returned (which is the correct value).

return
the destination offset as a Point.
see
#setDestinationOffset

        return (Point)destinationOffset.clone();
    
public javax.imageio.ImageTypeSpecifiergetDestinationType()
Returns the type of image to be returned by the read, if one was set by a call to setDestination(ImageTypeSpecifier), as an ImageTypeSpecifier. If none was set, null is returned.

return
an ImageTypeSpecifier describing the destination type, or null.
see
#setDestinationType

        return destinationType;
    
public int[]getSourceBands()
Returns the set of of source bands to be used. The returned value is that set by the most recent call to setSourceBands, or null if there have been no calls to setSourceBands.

Semantically, the array returned is a copy; changes to array contents subsequent to this call have no effect on this IIOParam.

return
the set of source bands to be used, or null.
see
#setSourceBands

        if (sourceBands == null) {
            return null;
        }
        return (int[])(sourceBands.clone());
    
public java.awt.RectanglegetSourceRegion()
Returns the source region to be used. The returned value is that set by the most recent call to setSourceRegion, and will be null if there is no region set.

return
the source region of interest as a Rectangle, or null.
see
#setSourceRegion

        if (sourceRegion == null) {
            return null;
        }
        return (Rectangle)sourceRegion.clone();
    
public intgetSourceXSubsampling()
Returns the number of source columns to advance for each pixel.

If setSourceSubsampling has not been called, 1 is returned (which is the correct value).

return
the source subsampling X period.
see
#setSourceSubsampling
see
#getSourceYSubsampling

        return sourceXSubsampling;
    
public intgetSourceYSubsampling()
Returns the number of rows to advance for each pixel.

If setSourceSubsampling has not been called, 1 is returned (which is the correct value).

return
the source subsampling Y period.
see
#setSourceSubsampling
see
#getSourceXSubsampling

        return sourceYSubsampling;
    
public intgetSubsamplingXOffset()
Returns the horizontal offset of the subsampling grid.

If setSourceSubsampling has not been called, 0 is returned (which is the correct value).

return
the source subsampling grid X offset.
see
#setSourceSubsampling
see
#getSubsamplingYOffset

        return subsamplingXOffset;
    
public intgetSubsamplingYOffset()
Returns the vertical offset of the subsampling grid.

If setSourceSubsampling has not been called, 0 is returned (which is the correct value).

return
the source subsampling grid Y offset.
see
#setSourceSubsampling
see
#getSubsamplingXOffset

        return subsamplingYOffset;
    
public booleanhasController()
Returns true if there is a controller installed for this IIOParam object. This will return true if getController would not return null.

return
true if a controller is installed.
see
IIOParamController
see
#setController(IIOParamController)
see
#getController
see
#getDefaultController
see
#activateController()

        return (controller != null);
    
public voidsetController(javax.imageio.IIOParamController controller)
Sets the IIOParamController to be used to provide settings for this IIOParam object when the activateController method is called, overriding any default controller. If the argument is null, no controller will be used, including any default. To restore the default, use setController(getDefaultController()).

param
controller An appropriate IIOParamController, or null.
see
IIOParamController
see
#getController
see
#getDefaultController
see
#hasController
see
#activateController()

        this.controller = controller;
    
public voidsetDestinationOffset(java.awt.Point destinationOffset)
Specifies the offset in the destination image at which future decoded pixels are to be placed, when reading, or where a region will be written, when writing.

When reading, the region to be written within the destination BufferedImage will start at this offset and have a width and height determined by the source region of interest, the subsampling parameters, and the destination bounds.

Normal writes are not affected by this method, only writes performed using ImageWriter.replacePixels. For such writes, the offset specified is within the output stream image whose pixels are being modified.

There is no unsetDestinationOffset method; simply call setDestinationOffset(new Point(0, 0)) to restore default values.

param
destinationOffset the offset in the destination, as a Point.
exception
IllegalArgumentException if destinationOffset is null.
see
#getDestinationOffset
see
ImageWriter#replacePixels

        if (destinationOffset == null) {
            throw new IllegalArgumentException("destinationOffset == null!");
        }
        this.destinationOffset = (Point)destinationOffset.clone();
    
public voidsetDestinationType(javax.imageio.ImageTypeSpecifier destinationType)
Sets the desired image type for the destination image, using an ImageTypeSpecifier.

When reading, if the layout of the destination has been set using this method, each call to an ImageReader read method will return a new BufferedImage using the format specified by the supplied type specifier. As a side effect, any destination BufferedImage set by ImageReadParam.setDestination(BufferedImage) will no longer be set as the destination. In other words, this method may be thought of as calling setDestination((BufferedImage)null).

When writing, the destination type maybe used to determine the color type of the image. The SampleModel information will be ignored, and may be null. For example, a 4-banded image could represent either CMYK or RGBA data. If a destination type is set, its ColorModel will override any ColorModel on the image itself. This is crucial when setSourceBands is used since the image's ColorModel will refer to the entire image rather than to the subset of bands being written.

param
destinationType the ImageTypeSpecifier to be used to determine the destination layout and color type.
see
#getDestinationType

        this.destinationType = destinationType;
    
public voidsetSourceBands(int[] sourceBands)
Sets the indices of the source bands to be used. Duplicate indices are not allowed.

A null value indicates that all source bands will be used.

At the time of reading, an IllegalArgumentException will be thrown by the reader or writer if a value larger than the largest available source band index has been specified or if the number of source bands and destination bands to be used differ. The ImageReader.checkReadParamBandSettings method may be used to automate this test.

Semantically, a copy is made of the array; changes to the array contents subsequent to this call have no effect on this IIOParam.

param
sourceBands an array of integer band indices to be used.
exception
IllegalArgumentException if sourceBands contains a negative or duplicate value.
see
#getSourceBands
see
ImageReadParam#setDestinationBands
see
ImageReader#checkReadParamBandSettings

        if (sourceBands == null) {
            this.sourceBands = null;
        } else {
            int numBands = sourceBands.length;
            for (int i = 0; i < numBands; i++) {
                int band = sourceBands[i];
                if (band < 0) {
                    throw new IllegalArgumentException("Band value < 0!");
                }
                for (int j = i + 1; j < numBands; j++) {
                    if (band == sourceBands[j]) {
                        throw new IllegalArgumentException("Duplicate band value!");
                    }
                }
                
            }
            this.sourceBands = (int[])(sourceBands.clone());
        }
    
public voidsetSourceRegion(java.awt.Rectangle sourceRegion)
Sets the source region of interest. The region of interest is described as a rectangle, with the upper-left corner of the source image as pixel (0, 0) and increasing values down and to the right. The actual number of pixels used will depend on the subsampling factors set by setSourceSubsampling. If subsampling has been set such that this number is zero, an IllegalStateException will be thrown.

The source region of interest specified by this method will be clipped as needed to fit within the source bounds, as well as the destination offsets, width, and height at the time of actual I/O.

A value of null for sourceRegion will remove any region specification, causing the entire image to be used.

param
sourceRegion a Rectangle specifying the source region of interest, or null.
exception
IllegalArgumentException if sourceRegion is non-null and either sourceRegion.x or sourceRegion.y is negative.
exception
IllegalArgumentException if sourceRegion is non-null and either sourceRegion.width or sourceRegion.height is negative or 0.
exception
IllegalStateException if subsampling is such that this region will have a subsampled width or height of zero.
see
#getSourceRegion
see
#setSourceSubsampling
see
ImageReadParam#setDestinationOffset
see
ImageReadParam#getDestinationOffset

        if (sourceRegion == null) {
            this.sourceRegion = null;
            return;
        }

        if (sourceRegion.x < 0) {
            throw new IllegalArgumentException("sourceRegion.x < 0!");
        }
        if (sourceRegion.y < 0){
            throw new IllegalArgumentException("sourceRegion.y < 0!");
        }
        if (sourceRegion.width <= 0) {
            throw new IllegalArgumentException("sourceRegion.width <= 0!");
        }
        if (sourceRegion.height <= 0) {
            throw new IllegalArgumentException("sourceRegion.height <= 0!");
        }

        // Throw an IllegalStateException if region falls between subsamples
        if (sourceRegion.width <= subsamplingXOffset) {
            throw new IllegalStateException
                ("sourceRegion.width <= subsamplingXOffset!");
        }
        if (sourceRegion.height <= subsamplingYOffset) {
            throw new IllegalStateException
                ("sourceRegion.height <= subsamplingYOffset!");
        }

        this.sourceRegion = (Rectangle)sourceRegion.clone();
    
public voidsetSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset)
Specifies a decimation subsampling to apply on I/O. The sourceXSubsampling and sourceYSubsampling parameters specify the subsampling period (i.e., the number of rows and columns to advance after every source pixel). Specifically, a period of 1 will use every row or column; a period of 2 will use every other row or column. The subsamplingXOffset and subsamplingYOffset parameters specify an offset from the region (or image) origin for the first subsampled pixel. Adjusting the origin of the subsample grid is useful for avoiding seams when subsampling a very large source image into destination regions that will be assembled into a complete subsampled image. Most users will want to simply leave these parameters at 0.

The number of pixels and scanlines to be used are calculated as follows.

The number of subsampled pixels in a scanline is given by

truncate[(width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling].

If the region is such that this width is zero, an IllegalStateException is thrown.

The number of scanlines to be used can be computed similarly.

The ability to set the subsampling grid to start somewhere other than the source region origin is useful if the region is being used to create subsampled tiles of a large image, where the tile width and height are not multiples of the subsampling periods. If the subsampling grid does not remain consistent from tile to tile, there will be artifacts at the tile boundaries. By adjusting the subsampling grid offset for each tile to compensate, these artifacts can be avoided. The tradeoff is that in order to avoid these artifacts, the tiles are not all the same size. The grid offset to use in this case is given by:
grid offset = [period - (region offset modulo period)] modulo period)

If either sourceXSubsampling or sourceYSubsampling is 0 or negative, an IllegalArgumentException will be thrown.

If either subsamplingXOffset or subsamplingYOffset is negative or greater than or equal to the corresponding period, an IllegalArgumentException will be thrown.

There is no unsetSourceSubsampling method; simply call setSourceSubsampling(1, 1, 0, 0) to restore default values.

param
sourceXSubsampling the number of columns to advance between pixels.
param
sourceYSubsampling the number of rows to advance between pixels.
param
subsamplingXOffset the horizontal offset of the first subsample within the region, or within the image if no region is set.
param
subsamplingYOffset the horizontal offset of the first subsample within the region, or within the image if no region is set.
exception
IllegalArgumentException if either period is negative or 0, or if either grid offset is negative or greater than the corresponding period.
exception
IllegalStateException if the source region is such that the subsampled output would contain no pixels.

        if (sourceXSubsampling <= 0) {
            throw new IllegalArgumentException("sourceXSubsampling <= 0!");
        }
        if (sourceYSubsampling <= 0) {
            throw new IllegalArgumentException("sourceYSubsampling <= 0!");
        }
        if (subsamplingXOffset < 0 ||
            subsamplingXOffset >= sourceXSubsampling) {
            throw new IllegalArgumentException
                ("subsamplingXOffset out of range!");
        }
        if (subsamplingYOffset < 0 ||
            subsamplingYOffset >= sourceYSubsampling) {
            throw new IllegalArgumentException
                ("subsamplingYOffset out of range!");
        }
        
        // Throw an IllegalStateException if region falls between subsamples
        if (sourceRegion != null) {
            if (subsamplingXOffset >= sourceRegion.width ||
                subsamplingYOffset >= sourceRegion.height) {
                throw new IllegalStateException("region contains no pixels!");
            }
        }

        this.sourceXSubsampling = sourceXSubsampling;
        this.sourceYSubsampling = sourceYSubsampling;
        this.subsamplingXOffset = subsamplingXOffset;
        this.subsamplingYOffset = subsamplingYOffset;