Package org.apache.sis.image

Class Transferer

java.lang.Object

org.apache.sis.image.Transferer

Direct Known Subclasses:

Transferer.DoubleToDirect, Transferer.DoubleToDouble, Transferer.DoubleToInteger, Transferer.FloatToDirect, Transferer.FloatToFloat, Transferer.FloatToInteger

abstract class Transferer
extends Object

Strategy for reading and writing data between two rasters, with a computation between them. Some strategies are to write directly in the destination raster, other strategies are to use an intermediate buffer. This class has the following constraints:

• Source values cannot be modified. Calculations must be done either directly in the target raster, or in a temporary buffer.
• Direct access to the DataBuffer arrays may disable video card acceleration. This class assumes that it is acceptable for float and double types, and to be avoided for integer types.

Since:

1.1

Version:

1.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static final class	Transferer.DoubleToByte	Read double values from the source raster and write unsigned byte values in a temporary buffer.
private static final class	Transferer.DoubleToDirect	Read double values from the source and write double values directly in the target raster, without intermediate buffer.
private static final class	Transferer.DoubleToDouble	Read double values from the source raster and write double values in a temporary buffer.
private static class	Transferer.DoubleToInteger	Read double values from the source raster and write int values in a temporary buffer.
private static final class	Transferer.DoubleToShort	Read double values from the source raster and write signed short values in a temporary buffer.
private static final class	Transferer.DoubleToUShort	Read double values from the source raster and write unsigned short values in a temporary buffer.
private static final class	Transferer.FloatToByte	Read float values from the source raster and write unsigned byte values in a temporary buffer.
private static final class	Transferer.FloatToDirect	Read float values from the source and write float values directly in the target raster, without intermediate buffer.
private static final class	Transferer.FloatToFloat	Read float values from the source raster and write float values in a temporary buffer.
private static class	Transferer.FloatToInteger	Read float values from the source raster and write int values in a temporary buffer.
private static final class	Transferer.FloatToShort	Read float values from the source raster and write signed short values in a temporary buffer.
private static final class	Transferer.FloatToUShort	Read float values from the source raster and write unsigned short values in a temporary buffer.

Field Summary

Fields

Modifier and Type	Field	Description
protected int	band	The band to read and write.
protected final Rectangle	region	Coordinates of the region to read and write.
protected final Raster	source	The image tile from which to read sample values.
protected final WritableRaster	target	The image tile where to write sample values after processing.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Transferer(Raster source, WritableRaster target, Rectangle aoi)	Creates a new instance for transferring data between the two specified rasters.

Method Summary

Modifier and Type	Method	Description
final void	compute(org.opengis.referencing.operation.MathTransform1D[] converters)	Computes all sample values from the source tile and writes the result in the target tile.
(package private) abstract void	computeStrip(org.opengis.referencing.operation.MathTransform1D converter)	Reads sample values from the source tile, applies the given operation for current region and band, then writes results in the target tile.
(package private) static Transferer	create(Raster source, WritableRaster target, Rectangle aoi)	Suggests a strategy for transferring data from the given source to the given target.
(package private) static Transferer	create(RenderedImage source, WritableRaster target)	Suggests a strategy for transferring data from the given source image to the given target.
private static boolean	isDirect(Raster target, Rectangle aoi)	Returns true if the given raster stores sample values at consecutive locations in each band.
(package private) final int	length()	Returns the number of elements in region.
(package private) int	prepareTransferRegion()	Sets region.height to the height of the buffer where values are stored during data transfer and where MathTransform1D operations are applied.
private static boolean	singlePrecision(Raster source)	Returns true if the given raster use a data type that can be casted to the float type without precision lost.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

source

protected final Raster source

The image tile from which to read sample values.

target

protected final WritableRaster target

The image tile where to write sample values after processing.

region

protected final Rectangle region

Coordinates of the region to read and write. This class assumes that source and target share the same coordinate system.

band

protected int band

The band to read and write. This class assumes that source and target have the same number of bands and bands in same order.

Constructor Details

Transferer

protected Transferer(Raster source,
 WritableRaster target,
 Rectangle aoi)

Creates a new instance for transferring data between the two specified rasters. It is caller responsibility to ensure that aoi is contained in the bounds of both source and target rasters.

Parameters:

source - image tile from which to read sample values.

target - image tile where to write sample values after processing.

aoi - the area of interest, often target.getBounds().

Method Details

prepareTransferRegion

int prepareTransferRegion()

Sets region.height to the height of the buffer where values are stored during data transfer and where MathTransform1D operations are applied. If this Transferer does not use an intermediate buffer (i.e. if it copies values directly in the target buffer and processes them in-place), then this method should leave region unchanged.

The default implementation does nothing. This is the most conservative approach since it does not require Transferer to split data processing in strips, at the cost of more memory consumption if this Transferer does not write data directly in the target tile.

Returns:

region.y + region.height.

See Also:

• ImageUtilities.prepareTransferRegion(Rectangle, int)

compute

public final void compute(org.opengis.referencing.operation.MathTransform1D[] converters)
                   throws org.opengis.referencing.operation.TransformException

Computes all sample values from the source tile and writes the result in the target tile. This method invokes computeStrip(MathTransform1D) repetitively for sub-regions of the tile.

Parameters:

converters - the converters to apply on each band.

Throws:

org.opengis.referencing.operation.TransformException - if an error occurred during calculation.

computeStrip

abstract void computeStrip(org.opengis.referencing.operation.MathTransform1D converter)
                    throws org.opengis.referencing.operation.TransformException

Reads sample values from the source tile, applies the given operation for current region and band, then writes results in the target tile. The region and the band number must be set before to invoke this method.

Parameters:

converter - the operation to apply on sample values in current region and current band number.

Throws:

org.opengis.referencing.operation.TransformException - if an error occurred during calculation.

length

final int length()

Returns the number of elements in region. This is a helper method for subclass implementations.

create

static Transferer create(RenderedImage source,
 WritableRaster target)

Suggests a strategy for transferring data from the given source image to the given target. This method assumes that the source image uses the same pixel coordinate system than the target raster (i.e. that pixels at the same coordinates are at the same location on Earth). It also assumes that the target tile is fully included in the bounds of a single source tile. That later condition is met if the target grid tiles has been created by ImageLayout.

Parameters:

source - image from which to read sample values.

target - image tile where to write sample values after processing.

Returns:

object to use for applying the operation.

create

static Transferer create(Raster source,
 WritableRaster target,
 Rectangle aoi)

Suggests a strategy for transferring data from the given source to the given target. The operation to apply on sample values during transfer is specified later, during the call to compute(MathTransform1D[]).

Parameters:

source - image tile from which to read sample values.

target - image tile where to write sample values after processing.

aoi - the area of interest, often target.getBounds(). It is caller responsibility to ensure that aoi is contained in source and target bounds.

Returns:

object to use for applying the operation.

singlePrecision

private static boolean singlePrecision(Raster source)

Returns true if the given raster use a data type that can be casted to the float type without precision lost. If the type is unknown, then this method returns false. Note that this method also returns false for DataBuffer.TYPE_INT because conversion of 32 bits integer to the float type may lost precision digits.

isDirect

private static boolean isDirect(Raster target,
 Rectangle aoi)

Returns true if the given raster stores sample values at consecutive locations in each band. In other words, verifies if the given raster uses a pixel stride of 1 with no gab between lines. Another condition is that the data buffer must start at offset 0.