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.
*
*/
public abstract class IIOParam {
/**
* The source region, on null if none is set.
*/
protected Rectangle sourceRegion = null;
/**
* 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 sourceXSubsampling = 1;
/**
* 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 sourceYSubsampling = 1;
/**
* 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 subsamplingXOffset = 0;
/**
* 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 subsamplingYOffset = 0;
/**
* 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 int[] sourceBands = null;
/**
* 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 set the value will be
* null. By default, the value is null.
*/
protected ImageTypeSpecifier destinationType = null;
/**
* The offset in the destination where the upper-left decoded
* pixel should be placed. By default, the value is (0, 0).
*/
protected Point destinationOffset = new Point(0, 0);
/**
* 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.
*
* @see IIOParamController
* @see #getDefaultController
* @see #activateController
*/
protected IIOParamController defaultController = null;
/**
* 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.
*
* @see IIOParamController
* @see #setController(IIOParamController)
* @see #hasController()
* @see #activateController()
*/
protected IIOParamController controller = null;
/**
* Protected constructor may be called only by subclasses.
*/
protected IIOParam() {
controller = defaultController;
}
/**
* 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
*/
public void setSourceRegion(Rectangle sourceRegion) {
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();
}
/**
* 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
*/
public Rectangle getSourceRegion() {
if (sourceRegion == null) {
return null;
}
return (Rectangle)sourceRegion.clone();
}
/**
* 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.
*/
public void setSourceSubsampling(int sourceXSubsampling,
int sourceYSubsampling,
int subsamplingXOffset,
int subsamplingYOffset) {
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;
}
/**
* 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
*/
public int getSourceXSubsampling() {
return sourceXSubsampling;
}
/**
* 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
*/
public int getSourceYSubsampling() {
return sourceYSubsampling;
}
/**
* 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
*/
public int getSubsamplingXOffset() {
return subsamplingXOffset;
}
/**
* 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
*/
public int getSubsamplingYOffset() {
return subsamplingYOffset;
}
/**
* 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
*/
public void setSourceBands(int[] sourceBands) {
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 = (sourceBands.clone());
}
}
/**
* 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
*/
public int[] getSourceBands() {
if (sourceBands == null) {
return null;
}
return (sourceBands.clone());
}
/**
* 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
*/
public void setDestinationType(ImageTypeSpecifier destinationType) {
this.destinationType = destinationType;
}
/**
* 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
*/
public ImageTypeSpecifier getDestinationType() {
return destinationType;
}
/**
* 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
*/
public void setDestinationOffset(Point destinationOffset) {
if (destinationOffset == null) {
throw new IllegalArgumentException("destinationOffset == null!");
}
this.destinationOffset = (Point)destinationOffset.clone();
}
/**
* 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
*/
public Point getDestinationOffset() {
return (Point)destinationOffset.clone();
}
/**
* 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()
*/
public void setController(IIOParamController controller) {
this.controller = controller;
}
/**
* 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()
*/
public IIOParamController getController() {
return controller;
}
/**
* 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()
*/
public IIOParamController getDefaultController() {
return defaultController;
}
/**
* 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()
*/
public boolean hasController() {
return (controller != null);
}
/**
* 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
*/
public boolean activateController() {
if (!hasController()) {
throw new IllegalStateException("hasController() == false!");
}
return getController().activate(this);
}
}