ImageReadParam
, ImageWriteParam
public abstract class IIOParam extends Object
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.
Modifier and Type | Field | Description |
---|---|---|
protected IIOParamController |
controller |
The IIOParamController that will be used to provide settings for this IIOParam object when the activateController method is called. |
protected IIOParamController |
defaultController |
The default IIOParamController that will be used to provide settings for this IIOParam object when the activateController method is called. |
protected Point |
destinationOffset |
The offset in the destination where the upper-left decoded pixel should be placed. |
protected ImageTypeSpecifier |
destinationType |
An ImageTypeSpecifier to be used to generate a destination image when reading, or to set the output color type when writing. |
protected int[] |
sourceBands |
An array of int s indicating which source bands will be used, or null . |
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. |
protected int |
sourceYSubsampling |
The decimation subsampling to be applied in the vertical direction. |
protected int |
subsamplingXOffset |
A horizontal offset to be applied to the subsampling grid before subsampling. |
protected int |
subsamplingYOffset |
A vertical offset to be applied to the subsampling grid before subsampling. |
Modifier | Constructor | Description |
---|---|---|
protected |
Protected constructor may be called only by subclasses. |
Modifier and Type | Method | Description |
---|---|---|
boolean |
activateController() |
Activates the installed IIOParamController for this IIOParam object and returns the resulting value. |
IIOParamController |
getController() |
Returns whatever IIOParamController is currently installed. |
IIOParamController |
getDefaultController() |
Returns the default IIOParamController , if there is one, regardless of the currently installed controller. |
Point |
getDestinationOffset() |
Returns the offset in the destination image at which pixels are to be placed. |
ImageTypeSpecifier |
getDestinationType() |
Returns the type of image to be returned by the read, if one was set by a call to setDestination(ImageTypeSpecifier) , as an ImageTypeSpecifier . |
int[] |
getSourceBands() |
Returns the set of source bands to be used. |
Rectangle |
getSourceRegion() |
Returns the source region to be used. |
int |
getSourceXSubsampling() |
Returns the number of source columns to advance for each pixel. |
int |
getSourceYSubsampling() |
Returns the number of rows to advance for each pixel. |
int |
getSubsamplingXOffset() |
Returns the horizontal offset of the subsampling grid. |
int |
getSubsamplingYOffset() |
Returns the vertical offset of the subsampling grid. |
boolean |
hasController() |
Returns true if there is a controller installed for this IIOParam object. |
void |
setController |
Sets the IIOParamController to be used to provide settings for this IIOParam object when the activateController method is called, overriding any default controller. |
void |
setDestinationOffset |
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. |
void |
setDestinationType |
Sets the desired image type for the destination image, using an ImageTypeSpecifier . |
void |
setSourceBands |
Sets the indices of the source bands to be used. |
void |
setSourceRegion |
Sets the source region of interest. |
void |
setSourceSubsampling |
Specifies a decimation subsampling to apply on I/O. |
protected Rectangle sourceRegion
null
if none is set.protected int sourceXSubsampling
1
. The value must not be negative or 0.protected int sourceYSubsampling
1
. The value must not be negative or 0.protected int subsamplingXOffset
protected int subsamplingYOffset
protected int[] sourceBands
int
s 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
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 Point destinationOffset
protected IIOParamController defaultController
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
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.protected IIOParam()
public void setSourceRegion(Rectangle sourceRegion)
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.
sourceRegion
- a Rectangle
specifying the source region of interest, or null
.IllegalArgumentException
- if sourceRegion
is non-null
and either sourceRegion.x
or sourceRegion.y
is negative.IllegalArgumentException
- if sourceRegion
is non-null
and either sourceRegion.width
or sourceRegion.height
is negative or 0.IllegalStateException
- if subsampling is such that this region will have a subsampled width or height of zero.public Rectangle getSourceRegion()
setSourceRegion
, and will be null
if there is no region set.Rectangle
, or null
.public void setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset)
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.
sourceXSubsampling
- the number of columns to advance between pixels.sourceYSubsampling
- the number of rows to advance between pixels.subsamplingXOffset
- the horizontal offset of the first subsample within the region, or within the image if no region is set.subsamplingYOffset
- the horizontal offset of the first subsample within the region, or within the image if no region is set.IllegalArgumentException
- if either period is negative or 0, or if either grid offset is negative or greater than the corresponding period.IllegalStateException
- if the source region is such that the subsampled output would contain no pixels.public int getSourceXSubsampling()
If setSourceSubsampling
has not been called, 1 is returned (which is the correct value).
public int getSourceYSubsampling()
If setSourceSubsampling
has not been called, 1 is returned (which is the correct value).
public int getSubsamplingXOffset()
If setSourceSubsampling
has not been called, 0 is returned (which is the correct value).
public int getSubsamplingYOffset()
If setSourceSubsampling
has not been called, 0 is returned (which is the correct value).
public void setSourceBands(int[] sourceBands)
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
.
sourceBands
- an array of integer band indices to be used.IllegalArgumentException
- if sourceBands
contains a negative or duplicate value.public int[] getSourceBands()
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
.
null
.public void setDestinationType(ImageTypeSpecifier destinationType)
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.
destinationType
- the ImageTypeSpecifier
to be used to determine the destination layout and color type.public ImageTypeSpecifier getDestinationType()
setDestination(ImageTypeSpecifier)
, as an ImageTypeSpecifier
. If none was set, null
is returned.ImageTypeSpecifier
describing the destination type, or null
.public void setDestinationOffset(Point destinationOffset)
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.
destinationOffset
- the offset in the destination, as a Point
.IllegalArgumentException
- if destinationOffset
is null
.public Point getDestinationOffset()
If setDestinationOffsets
has not been called, a Point
with zero X and Y values is returned (which is the correct value).
Point
.public void setController(IIOParamController controller)
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())
.controller
- An appropriate IIOParamController
, or null
.public IIOParamController getController()
IIOParamController
is currently installed. This could be the default if there is one, null
, or the argument of the most recent call to setController
.IIOParamController
, or null
.public IIOParamController getDefaultController()
IIOParamController
, if there is one, regardless of the currently installed controller. If there is no default controller, returns null
.IIOParamController
, or null
.public boolean hasController()
true
if there is a controller installed for this IIOParam
object. This will return true
if getController
would not return null
.true
if a controller is installed.public boolean activateController()
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.
true
if the controller completed normally.IllegalStateException
- if there is no controller currently installed.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/imageio/IIOParam.html