Class ImageRenderer
GridCoverage.render(GridExtent)
.
This builder does not copy any sample values. Instead, it wraps existing data arrays into
Raster
objects by computing required information such as
pixel stride,
scanline stride and
band offsets.
Different setData(…)
methods are provided for allowing to specify the data arrays
from different objects such as Java2D DataBuffer
or NIO Buffer
.
All setData(…)
methods assume that the first valid element in each array is the value
located at GridCoverage.getGridGeometry().getExtent().getLow()
. This ImageRenderer
class
computes automatically the offsets from that position to the position of the first value included
in the sliceExtent
given to the constructor.
class MyResource extends GridCoverage { @Override public RenderedImage render(GridExtent sliceExtent) { ImageRenderer renderer = new ImageRenderer(this, sliceExtent); try { renderer.setData(data); return renderer.createImage(); } catch (IllegalArgumentException | ArithmeticException | RasterFormatException e) { throw new CannotEvaluateException("Can not create an image.", e); } } }
Limitations
Current implementation constructs only images made of a single tile. Support for tiled images will be added in a future version.- Since:
- 1.0
- See Also:
Defined in the sis-feature
module
-
Constructor Summary
ConstructorsConstructorDescriptionImageRenderer
(GridCoverage coverage, GridExtent sliceExtent) Creates a new image renderer for the given slice extent. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addProperty
(String key, Object value) Adds a value associated to a property.Creates an image with the data specified by the last call to asetData(…)
method.Creates a raster with the data specified by the last call to asetData(…)
method.final Rectangle
Returns the location of the image upper-left corner together with the image size.getImageGeometry
(int dimCRS) Computes the conversion from pixel coordinates to CRS, together with the geospatial envelope of the image.final int
Returns the number of bands that the image will have.getProperty
(String key) Returns the value associated to the given property.image()
Deprecated.raster()
Deprecated.RenamedcreateRaster()
.void
Deprecated.Replaced bysetData(DataType, Buffer...)
.void
setData
(DataBuffer data) Sets the data as a Java2D buffer.void
Sets the data as NIO buffers.void
Sets the data as vectors.void
setInterleavedPixelOffsets
(int pixelStride, int[] bandOffsets) Specifies the offsets to add to sample index in each band in order to reach the sample value in theDataBuffer
bank.
-
Constructor Details
-
ImageRenderer
Creates a new image renderer for the given slice extent.- Parameters:
coverage
- the source coverage for which to build an image.sliceExtent
- the domain from which to create an image, ornull
for thecoverage
extent.- Throws:
SubspaceNotSpecifiedException
- if this method can not infer a two-dimensional slice fromsliceExtent
.DisjointExtentException
- if the given extent does not intersect the given coverage.ArithmeticException
- if a stride calculation overflows the 32 bits integer capacity.
-
-
Method Details
-
getNumBands
public final int getNumBands()Returns the number of bands that the image will have. By default, this is the number of sample dimensions in the grid coverage.- Returns:
- the number of bands in the rendered image.
-
getBounds
Returns the location of the image upper-left corner together with the image size. The image coordinate system is relative to thesliceExtent
specified at construction time: the (0,0) pixel coordinates correspond to thesliceExtent
low coordinates. Consequently the rectangle x and y coordinates are (0,0) if the image is located exactly in the area requested bysliceExtent
, or is shifted as below otherwise:( x, y ) = (grid coordinates of actually provided region) − (grid coordinates of requested region)
- Returns:
- the rendered image location and size (never null).
-
getImageGeometry
Computes the conversion from pixel coordinates to CRS, together with the geospatial envelope of the image. TheGridGeometry
returned by this method is derived from the coverage grid geometry with the following changes:- The number of grid dimensions is always 2.
- The number of CRS dimensions
is specified by
dimCRS
(usually 2). - The envelope may be a sub-region of the coverage envelope.
- The grid extent is the image bounds.
- The grid to CRS transform is derived from the coverage transform
with a translation for mapping the
sliceExtent
low coordinates to (0,0) pixel coordinates.
- Parameters:
dimCRS
- desired number of dimensions in the CRS. This is usually 2.- Returns:
- conversion from pixel coordinates to CRS of the given number of dimensions, together with image bounds and geospatial envelope if possible.
- Since:
- 1.1
- See Also:
-
getProperty
Returns the value associated to the given property. By default the only property is "org.apache.sis.GridGeometry", but more properties can be added by calls toaddProperty(String, Object)
.- Parameters:
key
- the property for which to get a value.- Returns:
- value associated to the given property, or
null
if none. - Since:
- 1.1
-
addProperty
Adds a value associated to a property. This method can be invoked only once for eachkey
. Those properties will be given to the image created by thecreateImage()
method.- Parameters:
key
- key of the property to set.value
- value to associate to the given key.- Throws:
IllegalArgumentException
- if a value is already associated to the given key.- Since:
- 1.1
-
setData
Sets the data as a Java2D buffer. The number of banks in the given buffer must be equal to the expected number of bands. In each bank, the value located at the bank offset is the value located atGridCoverage.getGridGeometry().getExtent().getLow()
, as specified in class javadoc.- Parameters:
data
- the Java2D buffer containing data for all bands.- Throws:
NullArgumentException
- ifdata
is null.MismatchedCoverageRangeException
- if the given data buffer does not have the expected amount of banks.
-
setData
Sets the data as NIO buffers. The number of buffers must be equal to the expected number of bands. All buffers must be backed by arrays of the type specified by thedataType
argument and have the same amount of remaining elements. This method wraps the underlying arrays of a primitive type into a Java2D buffer; data are not copied. For each buffer, the grid coverage data (not only the slice data) starts at buffer position and ends at that position + remaining.The data type must be specified in order to distinguish between the signed and unsigned types.
DataType.BYTE
andDataType.USHORT
are unsigned, all other supported types are signed.Implementation note: the Java2D buffer is set by a call to
setData(DataBuffer)
, which can be overridden by subclasses if desired.- Parameters:
dataType
- type of data.data
- the buffers wrapping arrays of primitive type.- Throws:
NullArgumentException
- ifdata
is null or one ofdata
element is null.MismatchedCoverageRangeException
- if the number of specified buffers is not equal to the number of bands.UnsupportedOperationException
- if a buffer is not backed by an accessible array or is read-only.ArrayStoreException
- if a buffer type is incompatible withdataType
.RasterFormatException
- if buffers do not have the same amount of remaining values.ArithmeticException
- if a buffer position overflows the 32 bits integer capacity.- Since:
- 1.1
-
setData
Deprecated.Replaced bysetData(DataType, Buffer...)
.- Parameters:
dataType
- type of data as one ofDataBuffer.TYPE_BYTE
,TYPE_SHORT
TYPE_USHORT
,TYPE_INT
,TYPE_FLOAT
orTYPE_DOUBLE
constants.data
- the buffers wrapping arrays of primitive type.- Throws:
RasterFormatException
- ifdataType
is not a supported value.
-
setData
Sets the data as vectors. The number of vectors must be equal to the expected number of bands. All vectors must be backed by arrays (indirectly, through buffers backed by arrays) and have the same size. This method wraps the underlying arrays of a primitive type into a Java2D buffer; data are not copied.Implementation note: the NIO buffers are set by a call to
setData(DataType, Buffer...)
, which can be overridden by subclasses if desired.- Parameters:
data
- the vectors wrapping arrays of primitive type.- Throws:
NullArgumentException
- ifdata
is null or one ofdata
element is null.MismatchedCoverageRangeException
- if the number of specified vectors is not equal to the number of bands.UnsupportedOperationException
- if a vector is not backed by an accessible array or is read-only.RasterFormatException
- if vectors do not have the same size.ArithmeticException
- if a buffer position overflows the 32 bits integer capacity.
-
setInterleavedPixelOffsets
public void setInterleavedPixelOffsets(int pixelStride, int[] bandOffsets) Specifies the offsets to add to sample index in each band in order to reach the sample value in theDataBuffer
bank. This method should be invoked when the data given tosetData(…)
contains only oneVector
,Buffer
orDataBuffer
bank, and the bands in that unique bank are interleaved.Example: for an image having three bands named Red (R), Green (G) and Blue (B), if the sample values are stored in a single bank in a R₀,G₀,B₀, R₁,G₁,B₁, R₂,G₂,B₂, R₃,G₃,B₃, etc. fashion, then this method should be invoked as below:setInterleavedPixelOffsets(3, new int[] {0, 1, 2});
- Parameters:
pixelStride
- the number of data elements between each pixel in the data vector or buffer.bandOffsets
- offsets to add to sample index in each band. This is typically {0, 1, 2, …}. The length of this array shall be equal togetNumBands()
.
-
raster
Deprecated.RenamedcreateRaster()
. -
createRaster
Creates a raster with the data specified by the last call to asetData(…)
method. The raster upper-left corner is located at the position given bygetBounds()
. The returned raster is often an instance ofWritableRaster
, but read-only rasters are also allowed.- Returns:
- the raster, usually (but not necessarily) an instance of
WritableRaster
. - Throws:
IllegalStateException
- if nosetData(…)
method has been invoked before this method call.RasterFormatException
- if a call to aRaster
factory method failed.ArithmeticException
- if a property of the raster to construct exceeds the capacity of 32 bits integers.- Since:
- 1.1
-
image
Deprecated.RenamedcreateImage()
. -
createImage
Creates an image with the data specified by the last call to asetData(…)
method. The image upper-left corner is located at the position given bygetBounds()
. The two-dimensional image geometry is stored as a property associated to the "org.apache.sis.GridGeometry" key.The default implementation returns an instance of
WritableRenderedImage
if thecreateRaster()
return value is an instance ofWritableRaster
, or a read-onlyRenderedImage
otherwise.- Returns:
- the image.
- Throws:
IllegalStateException
- if nosetData(…)
method has been invoked before this method call.RasterFormatException
- if a call to aRaster
factory method failed.ArithmeticException
- if a property of the image to construct exceeds the capacity of 32 bits integers.- Since:
- 1.1
-
createImage()
.