Class ResampledImage
- All Implemented Interfaces:
RenderedImage
,Disposable
- Direct Known Subclasses:
Visualization
MathTransform
(for example a map projection)
which converts pixel center coordinates from this image to pixel center coordinates
in the source image.
The converted coordinates usually contain fraction digits, in which case an interpolation is applied.
Usage note
This class should be used with non-linear transforms such as map projections. It is technically possible to use this class with linear transforms such asAffineTransform
,
but there is more efficient alternatives for linear cases (for example
specifying the affine transform at rendering time).- Since:
- 1.1
- Version:
- 1.2
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) static final int
The 2 value for identifying code expecting exactly 2 dimensions.private final Object
The values to use if a pixel in this image cannot be mapped to a pixel in the source image.private final int
Domain of pixel coordinates in this image.protected final Interpolation
The object to use for performing interpolations.private final javax.measure.Quantity
<javax.measure.quantity.Length> The largest accuracy declared in theaccuracy
argument given to constructor, ornull
if none.private Reference
<ComputedImage> PlanarImage.MASK_KEY
value, computed when first requested.private final int
Index of the first tile.private final int
Index of the first tile.private final int
Domain of pixel coordinates in this image.private final int
Domain of pixel coordinates in this image.static final String
Key of a property providing an estimation of positional error for each pixel.private Reference
<ComputedImage> POSITIONAL_CONSISTENCY_KEY
value, computed when first requested.protected final org.opengis.referencing.operation.MathTransform
Conversion from pixel center coordinates of this image to pixel center coordinates of source image.private final org.opengis.referencing.operation.MathTransform
Same astoSource
but with the addition of a shift for taking in account the number of pixels required for interpolations.private final int
Domain of pixel coordinates in this image.Fields inherited from class org.apache.sis.image.ComputedImage
sampleModel, SOURCE_PADDING_KEY
Fields inherited from class org.apache.sis.image.PlanarImage
GRID_GEOMETRY_KEY, MASK_KEY, POSITIONAL_ACCURACY_KEY, SAMPLE_RESOLUTIONS_KEY, STATISTICS_KEY
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
ResampledImage
(RenderedImage source, SampleModel sampleModel, Point minTile, Rectangle bounds, org.opengis.referencing.operation.MathTransform toSource, Interpolation interpolation, Number[] fillValues, javax.measure.Quantity<?>[] accuracy) Creates a new image which will resample the given image. -
Method Summary
Modifier and TypeMethodDescriptionprotected Raster
computeTile
(int tileX, int tileY, WritableRaster tile) Invoked when a tile need to be computed or updated.boolean
Compares the given object with this image for equality.Returns the color model of this resampled image.final int
Returns the number of rows in this image.private RenderedImage
getMask()
Computes the "org.apache.sis.Mask" value.final int
Returns the minimum tile index in the x direction.final int
Returns the minimum tile index in the y direction.final int
getMinX()
Returns the minimum x coordinate (inclusive) of this image.final int
getMinY()
Returns the minimum y coordinate (inclusive) of this image.private javax.measure.Quantity<?>[]
Computes the "org.apache.sis.PositionalAccuracy" value.private int
Returns the number of quantities in the array returned bygetPositionalAccuracy()
.private RenderedImage
Computes the "org.apache.sis.PositionalConsistency" value.getProperty
(String key) Gets a property from this image.String[]
Returns the names of all recognized properties, ornull
if this image has no properties.final int
getWidth()
Returns the number of columns in this image.int
hashCode()
Returns a hash code value for this image.(package private) boolean
Returnstrue
if this image cannot have mask.private static double
interpolationLimit
(double max, int span) Returns the upper limit (inclusive) where an interpolation is possible.(package private) static double
interpolationSupportOffset
(int span) The relative index of the first pixel needed on the left or top side of the region to use for interpolation.protected Disposable
Notifies the source image that tiles will be computed soon in the given region.private static void
recoverableException
(String method, Exception error) Invoked when a non-fatal error occurred.verify()
Verifies whether image layout information are consistent.Methods inherited from class org.apache.sis.image.ComputedImage
clearErrorFlags, createTile, dispose, equalsBase, getDestination, getSampleModel, getSource, getSource, getSources, getTile, getTileHeight, getTileWidth, getWritableTileIndices, hashCodeBase, hasTileWriters, isTileWritable, markDirtyTiles, markTileWritable, reference, setDestination, sourceTileChanged
Methods inherited from class org.apache.sis.image.PlanarImage
copyData, getBounds, getData, getData, getNumXTiles, getNumYTiles, getTileGridXOffset, getTileGridYOffset, toString
-
Field Details
-
POSITIONAL_CONSISTENCY_KEY
Key of a property providing an estimation of positional error for each pixel. Values shall be instances ofRenderedImage
with same size and origin than this image. The image should contain a single band where all sample values are error estimations in pixel units (relative to pixels of this image). The value should be small, for example between 0 and 0.2.The default implementation transforms all pixel coordinates to source, then convert them back to pixel coordinates in this image. The result is compared with expected coordinates and the distance is stored in the image.
- See Also:
-
BIDIMENSIONAL
static final int BIDIMENSIONALThe 2 value for identifying code expecting exactly 2 dimensions.- See Also:
-
minX
private final int minXDomain of pixel coordinates in this image. -
minY
private final int minYDomain of pixel coordinates in this image. -
width
private final int widthDomain of pixel coordinates in this image. -
height
private final int heightDomain of pixel coordinates in this image. -
minTileX
private final int minTileXIndex of the first tile. -
minTileY
private final int minTileYIndex of the first tile. -
toSource
protected final org.opengis.referencing.operation.MathTransform toSourceConversion from pixel center coordinates of this image to pixel center coordinates of source image. This transform should be an instance ofMathTransform2D
, but this is not required by this class (a future version may allow interpolations in a n-dimensional cube).- See Also:
-
toSourceSupport
private final org.opengis.referencing.operation.MathTransform toSourceSupportSame astoSource
but with the addition of a shift for taking in account the number of pixels required for interpolations. For example if a bicubic interpolation needs 4×4 pixels, then the source coordinates that we need are not the coordinates of the pixel we want to interpolate, but 1 or 2 pixels before for making room for interpolation support.This transform may be an instance of
ResamplingGrid
if the usage of such grid has been authorized. That transform may be non-invertible. Consequently, this transform should not be used for inverse operations and should not be made accessible to the user.This transform maps pixel centers of both images, except in the case of nearest-neighbor interpolation. In that special case only, the transform maps target pixel center to source pixel corner. We have to map corners in source images because source pixel coordinates are computed by taking the integer parts of
toSourceSupport
results, without rounding.- See Also:
-
interpolation
The object to use for performing interpolations. -
fillValues
The values to use if a pixel in this image cannot be mapped to a pixel in the source image. Must be anint[]
ordouble[]
array (no other type allowed). The array length must be equal to the number of bands. Cannot be null. -
linearAccuracy
private final javax.measure.Quantity<javax.measure.quantity.Length> linearAccuracyThe largest accuracy declared in theaccuracy
argument given to constructor, ornull
if none. This is for information purpose only.- See Also:
-
positionalConsistency
POSITIONAL_CONSISTENCY_KEY
value, computed when first requested.- See Also:
-
mask
PlanarImage.MASK_KEY
value, computed when first requested.- See Also:
-
-
Constructor Details
-
ResampledImage
protected ResampledImage(RenderedImage source, SampleModel sampleModel, Point minTile, Rectangle bounds, org.opengis.referencing.operation.MathTransform toSource, Interpolation interpolation, Number[] fillValues, javax.measure.Quantity<?>[] accuracy) Creates a new image which will resample the given image. The resampling operation is defined by a potentially non-linear transform from this image to the specified source image. That transform should map pixel centers.The
sampleModel
determines the tile size and the target data type. This is often the same sample model than the one used by thesource
image, but may also be different for forcing a different tile size or a different data type (e.g.byte
versusfloat
) for storing resampled values. If the specified sample model is not the same than the one used by the source image, then subclass should overridegetColorModel()
for returning a color model which is compatible with the sample model.If a pixel in this image cannot be mapped to a pixel in the source image, then the sample values are set to
fillValues
. If the given array isnull
, or if any element in the given array isnull
, then the default fill value is NaN for floating point data types or zero for integer data types. If the array is shorter than the number of bands, then above-cited default values are used for missing values. If longer than the number of bands, extraneous values are ignored.- Parameters:
source
- the image to be resampled.sampleModel
- the sample model shared by all tiles in this resampled image.minTile
- indices of the first tile (minTileX
,minTileY
), ornull
for (0,0).bounds
- domain of pixel coordinates of this resampled image.toSource
- conversion of pixel coordinates of this image to pixel coordinates ofsource
image.interpolation
- the object to use for performing interpolations.fillValues
- the values to use for pixels in this image that cannot be mapped to pixels in source image. May benull
or containnull
elements, and may have any length (see above for more details).accuracy
- values of "org.apache.sis.PositionalAccuracy" property, ornull
if none. This constructor may retain only a subset of specified values or replace some of them. If an accuracy is specified in pixel units, then a value such as 0.125 pixel may enable the use of a slightly faster algorithm at the expense of accuracy. This is only a hint honored on a best-effort basis.- See Also:
-
-
Method Details
-
interpolationSupportOffset
static double interpolationSupportOffset(int span) The relative index of the first pixel needed on the left or top side of the region to use for interpolation. The index is relative to the two central pixels needed for a bilinear interpolation. This value is negative or zero. A value of 0 means that we need no pixels in addition of the two central pixels:sample[0] … (position where to interpolate) … sample[1]
A value of -1 means that we need one more pixel on the left or top side. It often means that we also need one more pixel on the right or bottom sides, but not necessarily; those sides are not this method business.sample[-1] … sample[0] … (position where to interpolate) … sample[1] … sample[2]
Nearest-neighbor special case
The nearest-neighbor interpolation (identified byspan == 1
) is handled in a special way. The return value should be 0 according above contract, but this method returns 0.5 instead. This addition of a 0.5 offset allows the following substitution:Math.round(double)
is the desired behavior for nearest-neighbor interpolation, but the buffer given toInterpolation.interpolate(DoubleBuffer, int, double, double, double[], int)
is filled with values at coordinates determined byMath.floor(double)
semantic. Because the buffer has only one value,interpolate(…)
has no way to look at neighbor values for the best match (contrarily to what other interpolation implicitly do, through mathematics). The 0.5 offset is necessary for compensating.- Parameters:
span
- the width or height of the support region for interpolations.- Returns:
- relative index of the first pixel needed on the left or top sides, as a value ≤ 0 (except in nearest-neighbor special case).
- See Also:
-
interpolationLimit
private static double interpolationLimit(double max, int span) Returns the upper limit (inclusive) where an interpolation is possible. The givenmax
value is the maximal coordinate value (inclusive) traversed byPixelIterator
. Note that this is not the image size because of margin required by interpolation methods.Since interpolator will receive data at coordinates
max
tomax + span - 1
inclusive and since those coordinates are pixel centers, the points to interpolate are on the surface of a valid pixel until(max + span - 1) + 0.5
. Consequently, this method computesmax + span - 0.5
. An additional 0.5 offset is added in the special case of nearest-neighbor interpolation for consistency withinterpolationSupportOffset(int)
.- Parameters:
max
- the maximal coordinate value, inclusive.span
- the width or height of the support region for interpolations.- Returns:
max + span - 0.5
(except in nearest-neighbor special case).- See Also:
-
getPositionalAccuracyCount
private int getPositionalAccuracyCount()Returns the number of quantities in the array returned bygetPositionalAccuracy()
. -
getPositionalAccuracy
private javax.measure.Quantity<?>[] getPositionalAccuracy()Computes the "org.apache.sis.PositionalAccuracy" value. This method is invoked bygetProperty(String)
when thePlanarImage.POSITIONAL_ACCURACY_KEY
property value is requested. -
getPositionalConsistency
private RenderedImage getPositionalConsistency() throws org.opengis.referencing.operation.TransformExceptionComputes the "org.apache.sis.PositionalConsistency" value. This method is invoked bygetProperty(String)
when thePOSITIONAL_CONSISTENCY_KEY
property value is requested. The result is saved by weak reference since recomputing this image is rarely requested, and if needed can be recomputed easily.- Throws:
org.opengis.referencing.operation.TransformException
-
getMask
Computes the "org.apache.sis.Mask" value. This method is invoked bygetProperty(String)
when thePlanarImage.MASK_KEY
property value is requested. The result is saved by weak reference since recomputing this image is rarely requested, and if needed can be recomputed easily. -
hasNoMask
boolean hasNoMask()Returnstrue
if this image cannot have mask. -
verify
Verifies whether image layout information are consistent. This method verifies that source coordinates required by this image (computed by converting this image bounds using thetoSource
transform) intersects the bounds of the source image. If this is not the case, then this method returns"toSource"
for signaling that the transform may have a problem. Otherwise this method completes the check with all verifications documented in parent class- Overrides:
verify
in classPlanarImage
- Returns:
null
if image layout information are consistent, or the name of inconsistent attribute if a problem is found.
-
recoverableException
Invoked when a non-fatal error occurred.- Parameters:
method
- the method where the ignorable error occurred.error
- the ignore which can be ignored.
-
getColorModel
Returns the color model of this resampled image. Default implementation assumes that this image has the same color model than the source image.- Returns:
- the color model, or
null
if unspecified.
-
getProperty
Gets a property from this image. Current default implementation supports the following keys (more properties may be added to this list in future Apache SIS versions):- "org.apache.sis.PositionalAccuracy"
- "org.apache.sis.PositionalConsistency"
- "org.apache.sis.SampleResolution" (forwarded to the source image)
- "org.apache.sis.Mask" if the image uses floating point numbers.
Note: the sample resolutions are retained because they should have approximately the same values before and after resampling. Statistics are not in this list because, while minimum and maximum values should stay approximately the same, the average value and standard deviation may be quite different.- Specified by:
getProperty
in interfaceRenderedImage
- Overrides:
getProperty
in classPlanarImage
- Parameters:
key
- the name of the property to get.- Returns:
- the property value, or
Image.UndefinedProperty
if none.
-
getPropertyNames
Returns the names of all recognized properties, ornull
if this image has no properties. The returned array contains the properties listed ingetProperty(String)
if the source image has those properties.- Specified by:
getPropertyNames
in interfaceRenderedImage
- Overrides:
getPropertyNames
in classPlanarImage
- Returns:
- names of all recognized properties, or
null
if none.
-
getMinTileX
public final int getMinTileX()Returns the minimum tile index in the x direction. This is often 0.- Specified by:
getMinTileX
in interfaceRenderedImage
- Overrides:
getMinTileX
in classPlanarImage
- Returns:
- the minimum tile index in the x direction.
-
getMinTileY
public final int getMinTileY()Returns the minimum tile index in the y direction. This is often 0.- Specified by:
getMinTileY
in interfaceRenderedImage
- Overrides:
getMinTileY
in classPlanarImage
- Returns:
- the minimum tile index in the y direction.
-
getMinX
public final int getMinX()Returns the minimum x coordinate (inclusive) of this image. This is theRectangle.x
value of thebounds
specified at construction time.- Specified by:
getMinX
in interfaceRenderedImage
- Overrides:
getMinX
in classPlanarImage
- Returns:
- the minimum x coordinate (column) of this image.
-
getMinY
public final int getMinY()Returns the minimum y coordinate (inclusive) of this image. This is theRectangle.y
value of thebounds
specified at construction time.- Specified by:
getMinY
in interfaceRenderedImage
- Overrides:
getMinY
in classPlanarImage
- Returns:
- the minimum y coordinate (row) of this image.
-
getWidth
public final int getWidth()Returns the number of columns in this image. This is theRectangle.width
value of thebounds
specified at construction time.- Returns:
- number of columns in this image.
-
getHeight
public final int getHeight()Returns the number of rows in this image. This is theRectangle.height
value of thebounds
specified at construction time.- Returns:
- number of rows in this image.
-
computeTile
protected Raster computeTile(int tileX, int tileY, WritableRaster tile) throws org.opengis.referencing.operation.TransformException Invoked when a tile need to be computed or updated. This method fills all pixel values of the tile with values interpolated from the source image. It may be invoked concurrently in different threads.- Specified by:
computeTile
in classComputedImage
- Parameters:
tileX
- the column index of the tile to compute.tileY
- the row index of the tile to compute.tile
- if the tile already exists but needs to be updated, the tile to update. Otherwisenull
.- Returns:
- computed tile for the given indices.
- Throws:
org.opengis.referencing.operation.TransformException
- if an error occurred while computing pixel coordinates.
-
prefetch
Notifies the source image that tiles will be computed soon in the given region. If the source image is an instance ofComputedImage
, then this method forwards the notification to it. Otherwise default implementation does nothing.- Overrides:
prefetch
in classComputedImage
- Parameters:
tiles
- indices of the tiles which will be prefetched.- Returns:
- handler on which to invoke
dispose()
after the prefetch operation completed (successfully or not), ornull
if none. - Since:
- 1.2
-
equals
Compares the given object with this image for equality. This method returnstrue
if the given object is non-null, is an instance of the exact same class than this image, has equal sources and do the same resampling operation (same interpolation method, same fill values, same coordinates). -
hashCode
public int hashCode()Returns a hash code value for this image.
-