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.
Parameters:
- 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.
Throws:
- 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.