Interface Tile
-
public interface Tile extends Iterable<Tile.Pos>
A tile represents a rectangular region of sample data within the scene rectangle of a data product. Tiles are used to enable the sample data transfer from and to the source and target bands of data products used within operator graphs.Target tiles to be computed are passed into an
Operator
'scomputeTile
andcomputeTileStack
computeTileStack} methods. Source tiles are obtained by using thegetSourceTile
method.Three ways are provided to access and manipulate the sample data of a target tile:
(1) This is the simplest (but also slowest) way to modify sample data of a tile:
for (int y = tile.getMinY(); y <= tile.getMaxY(); y++) { for (int x = tile.getMinX(); x <= tile.getMaxX(); x++) { // compute sample value... tile.setSample(x, y, sample); } }
which can also be written even simpler using a tile iterator:for (Tile.Pos pos : tile) { // compute sample value... tile.setSample(pos.x, pos.y, sample); }
The methods
getSampleFloat(int, int)
andsetSample(int, int, float)
and their derivatives used in option (1) return and expect (geo-)physically scaled sample values.(2) More performance is gained if the sample data buffer is checked out and committed (required after modification only):
ProductData samples = tile.getRawSamples(); // check out for (int y = 0; y < tile.getHeight(); y++) { for (int x = 0; x < tile.getWidth(); x++) { // compute sample value... samples.setElemFloatAt(y * getWidth() + x, sample); // ... } } tile.setRawSamples(samples); // commit
The method
getRawSamples()
used in option (2) returns a writable buffer for the raw, non-calibrated sample values. Use thetoGeoPhysical(float)
andtoRaw(float)
to convert between physical and raw sample values.(3) The the fastest way to read from or write to sample data is to directly access the sample data via their primitive data buffers:
float[] samples = tile.getDataBufferFloat(); float sample; int offset = tile.getScanlineOffset(); for (int y = 0; y < tile.getHeight(); y++) { int index = offset; for (int x = 0; x < tile.getWidth(); x++) { // compute sample value... samples[index] = sample; index++; } offset += tile.getScanlineStride(); }
Note that option (3) can only be used if the exact sample data type is known or has been identified in a former step. The code snippet above implies that the underlying data type is
float
(becausegetRasterDataNode().getDataType()
returnsProductData.TYPE_FLOAT32
). ThegetDataBufferFloat()
and its derivatives all return arrays of raw, non-calibrated sample values. Use thetoGeoPhysical(float)
andtoRaw(float)
to convert between physical and raw sample values.- Since:
- 4.1
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
Tile.Pos
A pixel position within the tile's raster.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description ProductData
getDataBuffer()
Obtains access to the underlying raw sample buffer.byte[]
getDataBufferByte()
Gets the underlying raw sample array of typebyte
(signed or unsigned).double[]
getDataBufferDouble()
Gets the underlying raw sample array of typedouble
.float[]
getDataBufferFloat()
Gets the underlying raw sample array of typefloat
.int
getDataBufferIndex(int x, int y)
Gets the index into the underlying raw sample buffer for the given pixel coordinates.int[]
getDataBufferInt()
Gets the underlying raw sample array of typeint
.short[]
getDataBufferShort()
Gets the underlying raw sample array of typeshort
(signed or unsigned).int
getHeight()
Gets the height in pixels within the scene covered by the tile'sRasterDataNode
.int
getMaxX()
Gets the maximum pixel x-coordinate within the scene covered by the tile'sRasterDataNode
.int
getMaxY()
Gets the maximum pixel y-coordinate within the scene covered by the tile'sRasterDataNode
.int
getMinX()
Gets the minimum pixel x-coordinate within the scene covered by the tile'sRasterDataNode
.int
getMinY()
Gets the minimum pixel y-coordinate within the scene covered by the tile'sRasterDataNode
.RasterDataNode
getRasterDataNode()
Gets theRasterDataNode
associated with this tile, e.g.ProductData
getRawSamples()
Gets the raw (unscaled, uncalibrated) samples, e.g.Rectangle
getRectangle()
Gets the tile rectangle in pixel coordinates within the scene covered by the tile'sRasterDataNode
.boolean
getSampleBit(int x, int y, int bitIndex)
Gets the bit-coded sample value for the given pixel coordinate and the specified bit index as aboolean
.boolean
getSampleBoolean(int x, int y)
Gets the (geo-)physically scaled sample at the given pixel coordinate asboolean
value.double
getSampleDouble(int x, int y)
Gets the (geo-)physically scaled sample value for the given pixel coordinate asdouble
.float
getSampleFloat(int x, int y)
Gets the (geo-)physically scaled sample at the given pixel coordinate asfloat
value.int
getSampleInt(int x, int y)
Gets the (geo-)physically scaled sample at the given pixel coordinate asint
value.byte[]
getSamplesByte()
Gets the scaled, (geo-)physical array ofint
samples, copied from or directly returning the underlying data buffer.double[]
getSamplesDouble()
Gets the scaled, (geo-)physical array ofdouble
samples, copied from or directly returning the underlying data buffer.float[]
getSamplesFloat()
Gets the scaled, (geo-)physical array ofdouble
samples, copied from or directly returning the underlying data buffer.int[]
getSamplesInt()
Gets the scaled, (geo-)physical array ofint
samples, copied from or directly returning the underlying data buffer.short[]
getSamplesShort()
Gets the scaled, (geo-)physical array ofint
samples, copied from or directly returning the underlying data buffer.int
getScanlineOffset()
Gets the scanline offset.int
getScanlineStride()
Gets the raster scanline stride for addressing the internal data buffer.int
getWidth()
Gets the width in pixels within the scene covered by the tile'sRasterDataNode
.boolean
isSampleValid(int x, int y)
Checks whether or not the sample value exists and is valid at a given image pixel position.boolean
isTarget()
Checks if this is a target tile.Iterator<Tile.Pos>
iterator()
Gets an iterator which can be used to visit all pixels in the tile.void
setRawSamples(ProductData rawSamples)
Sets this tile's raw (unscaled, uncalibrated) samples.void
setSample(int x, int y, boolean sample)
Sets the (geo-)physically scaled sample at the given pixel coordinate from aboolean
value.void
setSample(int x, int y, double sample)
Sets the (geo-)physically scaled sample at the given pixel coordinate from adouble
value.void
setSample(int x, int y, float sample)
Sets the (geo-)physically scaled sample at the given pixel coordinate from afloat
value.void
setSample(int x, int y, int sample)
Sets the (geo-)physically scaled sample at the given pixel coordinate from aint
value.void
setSample(int x, int y, int bitIndex, boolean sample)
Sets the bit-coded sample at the given pixel coordinate and the specified bit index from aboolean
value.void
setSamples(byte[] samples)
Sets this tile's scaled, (geo-)physical samples as array offloats
s.void
setSamples(double[] samples)
Sets this tile's scaled, (geo-)physical samples as array ofdouble
s.void
setSamples(float[] samples)
Sets this tile's scaled, (geo-)physical samples as array offloats
s.void
setSamples(int[] samples)
Sets this tile's scaled, (geo-)physical samples as array offloats
s.void
setSamples(short[] samples)
Sets this tile's scaled, (geo-)physical samples as array offloats
s.double
toGeoPhysical(double rawSample)
Converts a raw sample value (e.g.float
toGeoPhysical(float rawSample)
Converts a raw sample value (e.g.double
toRaw(double sample)
Converts a (geo-)physically scaled sample value of typedouble
to a its corresponding raw sample value (e.g.float
toRaw(float sample)
Converts a (geo-)physically scaled sample value of typefloat
to a its corresponding raw sample value (e.g.-
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
-
-
-
Method Detail
-
getRasterDataNode
RasterDataNode getRasterDataNode()
Gets theRasterDataNode
associated with this tile, e.g. aBand
for source and target tiles orTiePointGrid
for a source tile.- Returns:
- The
RasterDataNode
associated with this tile.
-
isTarget
boolean isTarget()
Checks if this is a target tile. Non-target tiles are read only.- Returns:
true
if this is a target tile.
-
toGeoPhysical
float toGeoPhysical(float rawSample)
Converts a raw sample value (e.g. digital counts) to a (geo-)physically scaled sample value of typefloat
.- Parameters:
rawSample
- The raw sample value.- Returns:
- The calibrated sample value.
-
toGeoPhysical
double toGeoPhysical(double rawSample)
Converts a raw sample value (e.g. digital counts) to a (geo-)physically scaled sample value of typedouble
.- Parameters:
rawSample
- The raw sample value.- Returns:
- The calibrated sample value.
-
toRaw
float toRaw(float sample)
Converts a (geo-)physically scaled sample value of typefloat
to a its corresponding raw sample value (e.g. digital counts).- Parameters:
sample
- The calibrated sample value.- Returns:
- The raw sample value.
-
toRaw
double toRaw(double sample)
Converts a (geo-)physically scaled sample value of typedouble
to a its corresponding raw sample value (e.g. digital counts).- Parameters:
sample
- The calibrated sample value.- Returns:
- The raw sample value.
-
getRectangle
Rectangle getRectangle()
Gets the tile rectangle in pixel coordinates within the scene covered by the tile'sRasterDataNode
. Simply returnsnew Rectangle(
.minX
,minY
,width
,height
)- Returns:
- The tile rectangle in pixel coordinates.
-
getMinX
int getMinX()
Gets the minimum pixel x-coordinate within the scene covered by the tile'sRasterDataNode
.- Returns:
- The minimum pixel x-coordinate.
-
getMaxX
int getMaxX()
Gets the maximum pixel x-coordinate within the scene covered by the tile'sRasterDataNode
.- Returns:
- The maximum pixel x-coordinate.
-
getMinY
int getMinY()
Gets the minimum pixel y-coordinate within the scene covered by the tile'sRasterDataNode
.- Returns:
- The minimum pixel y-coordinate.
-
getMaxY
int getMaxY()
Gets the maximum pixel y-coordinate within the scene covered by the tile'sRasterDataNode
.- Returns:
- The maximum pixel y-coordinate.
-
getWidth
int getWidth()
Gets the width in pixels within the scene covered by the tile'sRasterDataNode
.- Returns:
- The width in pixels.
-
getHeight
int getHeight()
Gets the height in pixels within the scene covered by the tile'sRasterDataNode
.- Returns:
- The height in pixels.
-
getDataBufferIndex
int getDataBufferIndex(int x, int y)
Gets the index into the underlying raw sample buffer for the given pixel coordinates.The pixel coordinates are absolute; meaning they are defined in the scene raster coordinate system of this tile's
RasterDataNode
.The returned index is computed as follows:
int dx = x -
getMinX()
; int dy = y -getMinY()
; int index =getScanlineOffset()
+ dy *getScanlineStride()
+ dx;
-
getDataBuffer
ProductData getDataBuffer()
Obtains access to the underlying raw sample buffer. The data buffer holds the raw (unscaled, uncalibrated) sample data (e.g. detector counts). Elements in this array must be addressed by an index computed via the
scanlineStride
andscanlineOffset
properties. The index can also be directly computed using thegetDataBufferIndex(int, int)
method.The most efficient way to access and/or modify the samples in the raw data buffer is using the following nested loops:
int lineStride = tile.
getScanlineStride()
; int lineOffset = tile.getScanlineOffset()
; for (int y = tile.getMinY()
; y <= tile.getMaxY()
; y++) { int index = lineOffset; for (int x = tile.getMinX()
; x <= tile.getMaxX()
; x++) { // use index here to access raw data buffer... index++; } lineOffset += lineStride; }If the absolute x,y pixel coordinates are not required, the following construct maybe more readable:
int lineStride = tile.
getScanlineStride()
; int lineOffset = tile.getScanlineOffset()
; for (int y = 0; y < tile.getHeight()
; y++) { int index = lineOffset; for (int x = 0; x < tile.getWidth()
; x++) { // use index here to access raw data buffer... index++; } lineOffset += lineStride; }- Returns:
- the sample data
-
getDataBufferByte
byte[] getDataBufferByte()
Gets the underlying raw sample array of typebyte
(signed or unsigned). If the underlying data buffer is not of typebyte
,null
is returned.Refer to
getDataBuffer()
for using the primitive array.- Returns:
- The underlying data buffer's primitive array, or
null
(see above). - See Also:
getDataBufferIndex(int, int)
,getDataBuffer()
-
getDataBufferShort
short[] getDataBufferShort()
Gets the underlying raw sample array of typeshort
(signed or unsigned). If the underlying data buffer is not of typeshort
,null
is returned.Refer to
getDataBuffer()
for using the primitive array.- Returns:
- The underlying data buffer's primitive array, or
null
(see above). - See Also:
getDataBufferIndex(int, int)
,getDataBuffer()
-
getDataBufferInt
int[] getDataBufferInt()
Gets the underlying raw sample array of typeint
. If the underlying data buffer is not of typeint
,null
is returned.Refer to
getDataBuffer()
for using the primitive array.- Returns:
- The underlying data buffer's primitive array, or
null
(see above). - See Also:
getDataBufferIndex(int, int)
,getDataBuffer()
-
getDataBufferFloat
float[] getDataBufferFloat()
Gets the underlying raw sample array of typefloat
. If the underlying data buffer is not of typefloat
,null
is returned.Refer to
getDataBuffer()
for using the primitive array.- Returns:
- The underlying data buffer's primitive array, or
null
(see above). - See Also:
getDataBufferIndex(int, int)
,getDataBuffer()
-
getDataBufferDouble
double[] getDataBufferDouble()
Gets the underlying raw sample array of typedouble
. If the underlying data buffer is not of typedouble
,null
is returned.Refer to
getDataBuffer()
for using the primitive array.- Returns:
- The underlying data buffer's primitive array, or
null
(see above). - See Also:
getDataBufferIndex(int, int)
,getDataBuffer()
-
getScanlineOffset
int getScanlineOffset()
Gets the scanline offset. The scanline offset is the index to the first valid sample element in the data buffer.- Returns:
- The raster scanline offset.
- See Also:
getScanlineStride()
-
getScanlineStride
int getScanlineStride()
Gets the raster scanline stride for addressing the internal data buffer. The scanline stride is added to the scanline offset in order to compute offsets of subsequent scanlines.- Returns:
- The raster scanline stride.
- See Also:
getScanlineOffset()
-
getRawSamples
ProductData getRawSamples()
Gets the raw (unscaled, uncalibrated) samples, e.g. detector counts, copied from or wrapping the underlying data buffer. In contradiction to thegetDataBuffer()
method, the returned samples will cover exactly the regiongetRectangle()
rectangle} of this tile. Thus, the number of returned samples will always equalwidth
*
height
.In order to apply changes of the samples values to this tile, it is mandatory to call
setRawSamples(ProductData)
with the modifiedProductData
instance.- Returns:
- The raw samples copied from or wrapping the underlying data buffer.
-
setRawSamples
void setRawSamples(ProductData rawSamples)
Sets this tile's raw (unscaled, uncalibrated) samples. The number of given samples must be equalwidth
*
height
of this tile.This method must be used in order to apply changes made to the samples returned by the
getRawSamples()
method.- Parameters:
rawSamples
- The raw samples to be set.
-
getSamplesByte
byte[] getSamplesByte()
Gets the scaled, (geo-)physical array ofint
samples, copied from or directly returning the underlying data buffer. In contradiction to thegetDataBuffer()
method, the returned samples will cover exactly the regiongetRectangle()
rectangle} of this tile. Thus, the number of returned samples will always equalwidth
*
height
.Sample values that are masked out (see
isSampleValid(int, int)
) are set to zero.- Returns:
- The (geo-)physical samples computed from the underlying raw data buffer.
- Since:
- BEAM 5.0
- See Also:
setSamples(byte[])
-
getSamplesShort
short[] getSamplesShort()
Gets the scaled, (geo-)physical array ofint
samples, copied from or directly returning the underlying data buffer. In contradiction to thegetDataBuffer()
method, the returned samples will cover exactly the regiongetRectangle()
rectangle} of this tile. Thus, the number of returned samples will always equalwidth
*
height
.Sample values that are masked out (see
isSampleValid(int, int)
) are set to zero.- Returns:
- The (geo-)physical samples computed from the underlying raw data buffer.
- Since:
- BEAM 5.0
- See Also:
setSamples(short[])
-
getSamplesInt
int[] getSamplesInt()
Gets the scaled, (geo-)physical array ofint
samples, copied from or directly returning the underlying data buffer. In contradiction to thegetDataBuffer()
method, the returned samples will cover exactly the regiongetRectangle()
rectangle} of this tile. Thus, the number of returned samples will always equalwidth
*
height
.Sample values that are masked out (see
isSampleValid(int, int)
) are set to zero.- Returns:
- The (geo-)physical samples computed from the underlying raw data buffer.
- Since:
- BEAM 4.8
- See Also:
setSamples(int[])
-
getSamplesFloat
float[] getSamplesFloat()
Gets the scaled, (geo-)physical array ofdouble
samples, copied from or directly returning the underlying data buffer. In contradiction to thegetDataBuffer()
method, the returned samples will cover exactly the regiongetRectangle()
rectangle} of this tile. Thus, the number of returned samples will always equalwidth
*
height
.Sample values that are masked out (see
isSampleValid(int, int)
) are set toFloat.NaN
.- Returns:
- The (geo-)physical samples computed from the underlying raw data buffer.
- See Also:
setSamples(float[])
-
getSamplesDouble
double[] getSamplesDouble()
Gets the scaled, (geo-)physical array ofdouble
samples, copied from or directly returning the underlying data buffer. In contradiction to thegetDataBuffer()
method, the returned samples will cover exactly the regiongetRectangle()
rectangle} of this tile. Thus, the number of returned samples will always equalwidth
*
height
.Sample values that are masked out (see
isSampleValid(int, int)
) are set toDouble.NaN
.- Returns:
- The (geo-)physical samples computed from the underlying raw data buffer.
- See Also:
setSamples(double[])
-
setSamples
void setSamples(byte[] samples)
Sets this tile's scaled, (geo-)physical samples as array offloats
s. The number of given samples must be equalwidth
*
height
of this tile.- Parameters:
samples
- The (geo-)physical samples to be set.- Since:
- BEAM 5.0
- See Also:
getSamplesByte()
-
setSamples
void setSamples(short[] samples)
Sets this tile's scaled, (geo-)physical samples as array offloats
s. The number of given samples must be equalwidth
*
height
of this tile.- Parameters:
samples
- The (geo-)physical samples to be set.- Since:
- BEAM 5.0
- See Also:
getSamplesShort()
-
setSamples
void setSamples(int[] samples)
Sets this tile's scaled, (geo-)physical samples as array offloats
s. The number of given samples must be equalwidth
*
height
of this tile.- Parameters:
samples
- The (geo-)physical samples to be set.- Since:
- BEAM 4.8
- See Also:
getSamplesInt()
-
setSamples
void setSamples(float[] samples)
Sets this tile's scaled, (geo-)physical samples as array offloats
s. The number of given samples must be equalwidth
*
height
of this tile.- Parameters:
samples
- The (geo-)physical samples to be set.- See Also:
getSamplesFloat()
-
setSamples
void setSamples(double[] samples)
Sets this tile's scaled, (geo-)physical samples as array ofdouble
s. The number of given samples must be equalwidth
*
height
of this tile.This method must be used in order to apply changes made to the samples returned by the
getRawSamples()
method.- Parameters:
samples
- The (geo-)physical samples to be set.- See Also:
getSamplesDouble()
-
isSampleValid
boolean isSampleValid(int x, int y)
Checks whether or not the sample value exists and is valid at a given image pixel position.- Parameters:
x
- the image pixel x-coordinatey
- the image pixel y-coordinate- Returns:
- true, if the sample exists and is valid
- Since:
- BEAM 4.7.1
-
getSampleBoolean
boolean getSampleBoolean(int x, int y)
Gets the (geo-)physically scaled sample at the given pixel coordinate asboolean
value.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed.
Note that in most cases, accessing the tile's
dataBuffer
directly in conjunction with thescanlineOffset
andscanlineStride
properties gives a better performance.
-
setSample
void setSample(int x, int y, boolean sample)
Sets the (geo-)physically scaled sample at the given pixel coordinate from aboolean
value.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed.
Note that in most cases, accessing the tile's
dataBuffer
directly in conjunction with thescanlineOffset
andscanlineStride
properties gives a better performance.
-
getSampleInt
int getSampleInt(int x, int y)
Gets the (geo-)physically scaled sample at the given pixel coordinate asint
value.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed.
Note that in most cases, accessing the tile's
dataBuffer
directly in conjunction with thescanlineOffset
andscanlineStride
properties gives a better performance.
-
setSample
void setSample(int x, int y, int sample)
Sets the (geo-)physically scaled sample at the given pixel coordinate from aint
value.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed. The conversion ensures that no overflow happens. If necessary the value is cropped to the value range.
Note that in most cases, accessing the tile's
dataBuffer
directly in conjunction with thescanlineOffset
andscanlineStride
properties gives a better performance.
-
getSampleFloat
float getSampleFloat(int x, int y)
Gets the (geo-)physically scaled sample at the given pixel coordinate asfloat
value.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed.
Note that in most cases it is more performant to directly access the tile's
dataBuffer
in conjunction with thescanlineOffset
andscanlineStride
properties.
-
setSample
void setSample(int x, int y, float sample)
Sets the (geo-)physically scaled sample at the given pixel coordinate from afloat
value.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed. The conversion ensures that no overflow happens. If necessary the value is cropped to the value range.
Note that in most cases, accessing the tile's
dataBuffer
directly in conjunction with thescanlineOffset
andscanlineStride
properties gives a better performance.
-
getSampleDouble
double getSampleDouble(int x, int y)
Gets the (geo-)physically scaled sample value for the given pixel coordinate asdouble
.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed.
Note that in most cases, accessing the tile's
dataBuffer
directly in conjunction with thescanlineOffset
andscanlineStride
properties gives a better performance.
-
setSample
void setSample(int x, int y, double sample)
Sets the (geo-)physically scaled sample at the given pixel coordinate from adouble
value.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed. The conversion ensures that no overflow happens. If necessary the value is cropped to the value range.
Note that in most cases, accessing the tile's
dataBuffer
directly in conjunction with thescanlineOffset
andscanlineStride
properties gives a better performance.
-
getSampleBit
boolean getSampleBit(int x, int y, int bitIndex)
Gets the bit-coded sample value for the given pixel coordinate and the specified bit index as aboolean
.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed.
Note that in most cases it is more performant to directly access the tile's
dataBuffer
in conjunction with thescanlineOffset
andscanlineStride
properties.
-
setSample
void setSample(int x, int y, int bitIndex, boolean sample)
Sets the bit-coded sample at the given pixel coordinate and the specified bit index from aboolean
value.If the underlying data buffer is of a different sample data type, an appropriate type conversion is performed.
Note that in most cases it is more performant to directly access the tile's
dataBuffer
in conjunction with thescanlineOffset
andscanlineStride
properties.
-
iterator
Iterator<Tile.Pos> iterator()
Gets an iterator which can be used to visit all pixels in the tile. The method allows this tile to be the target of the Java "foreach" statement. Using the tile as an iterator in a single loopfor (Tile.Pos pos: tile) { int x = pos.x; int y = pos.y; // ... }
is equivalent to iterating over all pixels using two nested loopsfor (int y = tile.getMinY(); y <= tile.getMaxY(); y++) { for (int x = tile.getMinX(); x <= tile.getMaxX(); x++) { // ... } }
-
-