GridCoverageBuilder (Geotoolkit.org 4.x-SNAPSHOT API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.geotoolkit.coverage.grid
Class GridCoverageBuilder

Object
  Builder<GridCoverage>
      GridCoverageBuilder

public class GridCoverageBuilder
extends Builder<GridCoverage>
extends Builder<GridCoverage>

Helper class for the creation of GridCoverage2D instances. This builder can creates the parameters to be given to grid coverage constructor from simpler parameters given to this builder.

The builder supports the following properties:

Properties	Can be set from	Default value
`crs`	CRS instance or authority code	From hints
`envelope`	Envelope instance or ordinate values
`extent`	Grid envelope instance or spans	Image width and height
`pixelAnchor`	Code list value	Pixel center
`gridToCRS`	Transform instance or affine transform coefficients	Computed from the above
`gridGeometry`	Grid geometry instance	Computed from the above
`numBands`	Positive integer	1
`Variable.name`	Character sequence
`Variable.unit`	Unit instance or unit symbol
`Variable.sampleRange`	Range instance or lower and upper values
`Variable.sampleToUnit`	Transform instance or coefficients	Identity
`Variable.colors`	Colors array or palette name
`Variable.sampleDimension`	Sample dimension instance or array	Computed from the above
Tile layout	Tile size and/or tile grid offset
`image`	Image, raster, matrix or function	Empty image
`sources`	Array of grid coverages
`properties`	Map of properties

Envelope vs grid to CRS transform
The preferred way to define the geographic location of a grid coverage is to specify the grid to CRS transform or the grid geometry. However as a convenience, this builder also accepts envelopes. In such case, this builder assumes that axis order in the supplied image matches exactly axis order in the supplied envelope. In other words, in the usual case where axis order in the image is (column, row), then the envelope should probably have a (longitude, latitude) or (easting, northing) axis order.

An exception to the above rule applies for CRS using exactly the following axis order: (NORTH|SOUTH, EAST|WEST). An example of such CRS is EPSG:4326. This builder will interchange automatically the (y,x) axes for those CRS.

See GridToEnvelopeMapper for more information about the heuristic rules. If more control on axis order and direction reversal is wanted, specify explicitely the grid to CRS transform or the grid geometry instead than an envelope.

Examples
Creates a grid coverage from the specified image and envelope. An affine transform will be computed automatically from the specified envelope using heuristic rules described in the above javadoc.

GridCoverageBuilder builder = new GridCoverageBuilder();
builder.setName("My coverage"); // Optional
builder.setEnvelope(envelope);
builder.setRenderedImage(image);
GridCoverage2D coverage = builder.getGridCoverage2D();

Creates a grid coverage from the specified image and grid to CRS transform. In this example, the pixels size is 1000×1000 metres and the CRS is Mercator ("EPSG:3395"). The envelope will be inferred from the grid geometry.

GridCoverageBuilder builder = new GridCoverageBuilder();
builder.setName("My coverage"); // Optional
builder.setCoordinateReferenceSystem("EPSG:3395");
builder.setGridToCRS(AffineTransform.getScaleInstance(1000, -1000));
builder.setSampleDimensions(myFirstBand, mySecondBand); // Optional
builder.setRenderedImage(image);
GridCoverage2D coverage = builder.getGridCoverage2D();

Creates a 600×400 pixels image from -40°S to 40°N and -60°W to 60°E. Uses the 0 pixel value for "no data", and pixel values in the [1…255] range for elevation values in metres. Then draw something on the image using Java2D API:

GridCoverageBuilder builder = new GridCoverageBuilder();
builder.setCoordinateReferenceSystem("CRS:84");
builder.setEnvelope(-60, -40, 60, 40);
builder.setExtent(600, 400);

// Use sample values in the range 1 inclusive to 255 exclusive
// and define elevation in metres as (sample value) / 10.
builder.variable(0).setName("Elevation");
builder.variable(0).setUnit(SI.METRE);
builder.variable(0).setSampleRange(1, 256);
builder.variable(0).setLinearTransform(0.1, 0);
builder.variable(0).addNodataValue("No data", 0, Color.GRAY);

// Gets a 600×400 pixels (the extent) image, then draw something on it.
Graphics2D gr = (Graphics2D) builder.createGraphics();
gr.draw(...);
gr.dispose();

// Gets the coverage.
GridCoverage2D coverage = builder.getGridCoverage2D();

Since:

2.5

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

coverage/geotk-coverage (download)

View source code for this class

Nested Class Summary
`class`	`GridCoverageBuilder.Variable` Helper class for the creation of `SampleDimension` instances.

Field Summary
`protected CoordinateReferenceSystem`	`crs` The coordinate reference system, or `null` if unspecified.
`protected Envelope`	`envelope` The envelope, including coordinate reference system, or `null` if unspecified.
`protected GridEnvelope`	`extent` The grid extent, or `null` if unspecified.
`protected GridGeometry`	`gridGeometry` The grid geometry, or `null` if unspecified.
`protected MathTransform`	`gridToCRS` The grid to CRS transform, or `null` if unspecified.
`protected Hints`	`hints` Optional hints for fetching factories, or `null` if none.
`protected RenderedImage`	`image` The rendered image, or `null` if not yet computed.
`protected CharSequence`	`name` The coverage name, or `null` if unspecified.
`protected int`	`numBands` Number of bands (sample dimensions), or 0 if unspecified.
`protected PixelInCell`	`pixelAnchor` Whatever the `gridToCRS` transform maps pixel center or pixel corner.
`protected Map<?,?>`	`properties` An optional map of properties to be associated with the grid coverage, or `null` if none.
`protected GridCoverage[]`	`sources` An optional array of sources to be associated with the grid coverage, or `null` if none.

Constructor Summary
`GridCoverageBuilder()` Creates a uninitialized builder.
`GridCoverageBuilder(Hints hints)` Creates a uninitialized builder using the given hints.

Method Summary
`GridCoverage`	`build()` Creates the grid coverage.
`Graphics`	`createGraphics(boolean crsUnit)` Creates a graphics which can be used to draw into the rendered image.
`AffineTransform`	`getAffineGridToCRS()` Returns two-dimensional part of the current grid to CRS affine transform.
`ColorModel`	`getColorModel()` Returns or computes the image color model.
`CoordinateReferenceSystem`	`getCoordinateReferenceSystem()` Returns the current coordinate reference system.
`Envelope`	`getEnvelope()` Returns the current envelope.
`GridEnvelope`	`getExtent()` Returns the current grid extent.
`GridCoverage2D`	`getGridCoverage2D()` Returns the grid coverage.
`GridGeometry`	`getGridGeometry()` Returns the current grid geometry.
`MathTransform`	`getGridToCRS()` Returns the current grid to CRS transform.
`Rectangle`	`getImageBounds()` Returns the image bounds.
`CharSequence`	`getName()` Returns the coverage name.
`int`	`getNumBands()` Returns the number of sample dimensions (bands).
`PixelInCell`	`getPixelAnchor()` Returns whatever the grid to CRS transform maps pixel center or pixel corner.
`Map<?,?>`	`getProperties()` Returns optional properties to be given to the coverage, or `null` if none.
`RenderedImage`	`getRenderedImage()` Returns the rendered image to be wrapped by `GridCoverage2D`.
`SampleDimension[]`	`getSampleDimensions()` Returns the sample dimensions, or `null` if none.
`GridCoverage[]`	`getSources()` Returns the optional sources to be associated with the coverage.
`Point`	`getTileGridOffset()` Returns the tile grid offset, or `null` if the image is untiled.
`Dimension`	`getTileSize()` Returns the tile size, or `null` if the image is untiled.
`protected GridCoverageBuilder.Variable`	`newVariable(int band)` Invoked by the `variable(int)` method when a new variable need to be created.
`void`	`reset()` Resets this builder to its initial state.
`void`	`setCoordinateReferenceSystem(CoordinateReferenceSystem crs)` Sets the coordinate reference system to the specified value.
`void`	`setCoordinateReferenceSystem(String code)` Sets the coordinate reference system to the specified authority code.
`void`	`setEnvelope(double... ordinates)` Sets the envelope to the specified values, which must be the lower corner coordinates followed by upper corner coordinates.
`void`	`setEnvelope(Envelope envelope)` Sets the envelope to the specified value.
`void`	`setExtent(GridEnvelope extent)` Sets the grid extent to the specified value.
`void`	`setExtent(int... span)` Sets the grid extent to a grid envelope having the given span.
`void`	`setGridCoverage(GridCoverage coverage)` Configure this builder to the same values than the given coverage.
`void`	`setGridGeometry(GridGeometry geom)` Sets the grid geometry to the given value.
`void`	`setGridToCRS(AffineTransform gridToCRS)` Sets the grid to CRS transform from a Java2D transform.
`void`	`setGridToCRS(double m00, double m10, double m01, double m11, double m02, double m12)` Sets the grid to CRS transform from the given affine transform coefficients.
`void`	`setGridToCRS(MathTransform gridToCRS)` Sets the grid to CRS transform.
`void`	`setGridToCRS(Matrix gridToCRS)` Sets the grid to CRS transform from a matrix.
`void`	`setName(CharSequence name)` Sets the coverage name.
`void`	`setNumBands(int n)` Sets the number of sample dimensions (bands).
`void`	`setPixelAnchor(PixelInCell anchor)` Sets the whatever the grid to CRS transform maps pixel center or pixel corner.
`void`	`setProperties(Map<?,?> properties)` Sets the optional properties to be given to the coverage.
`void`	`setProperties(PropertySource source)` Inherits all the properties from the given source.
`void`	`setRenderedImage(float[][] matrix)` Creates a rendered image from the given matrix.
`void`	`setRenderedImage(ImageFunction function)` Creates a rendered image from the given image function.
`void`	`setRenderedImage(RenderedImage image)` Sets the rendered image.
`void`	`setRenderedImage(WritableRaster raster)` Creates a rendered image from the given raster.
`void`	`setSampleDimensions(double[] minValues, double[] maxValues, Unit<?> units, Color[]... colors)` Sets all variables information to the given ranges, units and colors.
`void`	`setSampleDimensions(SampleDimension... bands)` Sets all sample dimensions.
`void`	`setSources(GridCoverage... sources)` Sets the optional sources to be associated with the coverage.
`void`	`setTileGridOffset(Point offset)` Sets the tile offset.
`void`	`setTileSize(Dimension size)` Sets the tile size.
`GridCoverageBuilder.Variable`	`variable(int band)` Returns the sample dimension builder for the given band index.

Methods inherited from class Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

name

protected CharSequence name

The coverage name, or null if unspecified. This field is non-null only if the name has been explicitely specified by the user. The values inferred from other attributes are not stored in this field.

Since:: 3.20
See Also:: getName(), setName(CharSequence)

crs

protected CoordinateReferenceSystem crs

The coordinate reference system, or null if unspecified. This field is non-null only if the CRS has been explicitely specified by the user. The values inferred from other attributes are not stored in this field.

Since:: 3.20
See Also:: getCoordinateReferenceSystem(), setCoordinateReferenceSystem(CoordinateReferenceSystem), setCoordinateReferenceSystem(String)

envelope

protected Envelope envelope

The envelope, including coordinate reference system, or null if unspecified. This field is non-null only if the envelope has been explicitely specified by the user. The values inferred from other attributes are not stored in this field.

Since:: 3.20 (derived from 2.5)
See Also:: getEnvelope(), setEnvelope(Envelope), setEnvelope(double[])

extent

protected GridEnvelope extent

The grid extent, or null if unspecified. This field is non-null only if the extent has been explicitely specified by the user. The values inferred from other attributes are not stored in this field.

Since:: 3.20
See Also:: getExtent(), setExtent(GridEnvelope), setExtent(int[])

gridToCRS

protected MathTransform gridToCRS

The grid to CRS transform, or null if unspecified. This field is non-null only if the transform has been explicitely specified by the user. The values inferred from other attributes are not stored in this field.

Since:: 3.20
See Also:: getGridToCRS(), setGridToCRS(MathTransform), setGridToCRS(double, double, double, double, double, double)

pixelAnchor

protected PixelInCell pixelAnchor

Whatever the gridToCRS transform maps pixel center or pixel corner. This field is non-null only if it has been explicitely specified by the user. The values inferred from other attributes are not stored in this field.

Since:: 3.20
See Also:: getPixelAnchor(), setPixelAnchor(PixelInCell)

gridGeometry

protected GridGeometry gridGeometry

The grid geometry, or null if unspecified. This field is non-null only if the grid geometry has been explicitely specified by the user. The values inferred from other attributes are not stored in this field.

Since:: 3.20
See Also:: getGridGeometry(), setGridGeometry(GridGeometry)

numBands

protected int numBands

Number of bands (sample dimensions), or 0 if unspecified. This field is non-zero only if the number of bands has been explicitely specified by the user, or variables were created. The values inferred from other attributes are not stored in this field.

Since:: 3.20
See Also:: getNumBands(), setNumBands(int)

image

protected RenderedImage image

The rendered image, or null if not yet computed. This image can either be specified explicitely by the user or created from other properties.

The preferred implementation class is BufferedImage. However in some cases this builder may instantiate other kind of images, like TiledImage.

Since:: 3.20 (derived from 2.5)
See Also:: getRenderedImage(), setRenderedImage(RenderedImage)

sources

protected GridCoverage[] sources

An optional array of sources to be associated with the grid coverage, or null if none. Those sources will be given to the grid coverage constructor without any processing by this class.

Since:: 3.20
See Also:: getSources(), setSources(GridCoverage[])

properties

protected Map<?,?> properties

An optional map of properties to be associated with the grid coverage, or null if none. Those properties will be given to the grid coverage constructor without any processing by this builder class.

Since:: 3.20
See Also:: getProperties(), setProperties(Map)

hints

protected final Hints hints

Optional hints for fetching factories, or null if none. Those hints can be specified at builder construction time.

Since:: 3.20

Constructor Detail

GridCoverageBuilder

public GridCoverageBuilder()

Creates a uninitialized builder. All fields values are null.

GridCoverageBuilder

public GridCoverageBuilder(Hints hints)

Creates a uninitialized builder using the given hints. Hints of special interest are:

Hints.DEFAULT_COORDINATE_REFERENCE_SYSTEM - The CRS to use when none is explicitely set.
Hints.SAMPLE_DIMENSION_TYPE - specifies the SampleDimensionType to be used at rendering time, which can be one of UNSIGNED_8BITS or UNSIGNED_16BITS.
Hints.TILE_ENCODING - controls the compression to use for the serialization of GridCoverage2D instances.

Parameters:: hints - Optional hints for fetching factories, or null if none.
Since:: 3.20

Method Detail

getName

public CharSequence getName()

Returns the coverage name. This method returns the first non-null value in the above choices, in preference order:

The value defined by the last call to setName(CharSequence).
In an iteration over all variables (if any), the first non-null value returned by Variable.getName().

As a consequence of the above, the coverage name will be the name of the first sample dimension, unless a coverage name is explicitely given.

Returns:: The coverage name, or null.
Since:: 3.20
See Also:: AbstractCoverage.getName()

setName

public void setName(CharSequence name)

Sets the coverage name. The given name is typically (but not restricted to) a String or InternationalString instance.

Parameters:: name - The new name, or null.
Since:: 3.20

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the current coordinate reference system. This method returns the first non-null value in the above choices, in preference order:

The value defined by the last call to setCoordinateReferenceSystem(CoordinateReferenceSystem).
The envelope CRS.
The grid geometry CRS.
The value of Hints.DEFAULT_COORDINATE_REFERENCE_SYSTEM.

Returns:: The current CRS, or null if unspecified and can not be inferred.
See Also:: crs, Envelope.getCoordinateReferenceSystem(), GeneralGridGeometry.getCoordinateReferenceSystem(), AbstractCoverage.getCoordinateReferenceSystem()

setCoordinateReferenceSystem

public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
                                  throws IllegalArgumentException

Sets the coordinate reference system to the specified value. If an envelope has been explicitely defined, it will be reprojected to the new CRS.

Precedence
If a grid geometry has been explicitely set and contains a CRS, then that later CRS will have precedence for the creation of GridCoverage2D instances.

Parameters:: crs - The new CRS to use, or null.
Throws:: IllegalArgumentException - if the given CRS is illegal for the current envelope.
See Also:: crs, Envelopes.transform(Envelope, CoordinateReferenceSystem)

setCoordinateReferenceSystem

public void setCoordinateReferenceSystem(String code)
                                  throws IllegalArgumentException

Sets the coordinate reference system to the specified authority code. This method gives a preference to axes in (longitude, latitude) order. This convenience method is equivalent to the following code (omitting exception handling):

setCoordinateReferenceSystem(CRS.decode(code, true));

See setCoordinateReferenceSystem(CoordinateReferenceSystem) for information about precedence.

Parameters:: code - The authority code of the CRS to use, or null.
Throws:: IllegalArgumentException - if the given authority code is illegal.
See Also:: crs, CRS.decode(String, boolean)

getEnvelope

public Envelope getEnvelope()

Returns the current envelope. This method returns the first non-null value in the above choices, in preference order:

The value defined by the last call to setEnvelope(Envelope).
The grid geometry envelope.

Returns:: A copy of the current envelope, or null if unspecified and can not be inferred.
See Also:: envelope, GeneralGridGeometry.getEnvelope(), GridCoverage2D.getEnvelope()

setEnvelope

public void setEnvelope(Envelope envelope)
                 throws IllegalArgumentException

Sets the envelope to the specified value. If a CRS has been explicitely defined, then the given envelope will be reprojected to that CRS.

This method is not recommended, since the creation of a grid coverage from an envelope implies some arbitrary choices. Those arbitrary choices are implemented as heuristic rules documented in this class javadoc. The recommended usage is to specify the grid to CRS transform or the grid geometry instead, and specify an envelope only when the other information are not available.

Precedence
If a grid geometry has been explicitely set and contains an envelope, then that later envelope will have precedence for the creation of GridCoverage2D instances.

Parameters:: envelope - The new envelope to use, or null.
Throws:: IllegalArgumentException - if the envelope is illegal for the CRS.
See Also:: envelope, Envelopes.transform(Envelope, CoordinateReferenceSystem)

setEnvelope

public void setEnvelope(double... ordinates)
                 throws IllegalArgumentException

Sets the envelope to the specified values, which must be the lower corner coordinates followed by upper corner coordinates. The number of arguments provided shall be twice the envelope dimension, and minimum shall not be greater than maximum.

Example: (x_min, y_min, z_min, x_max, y_max, z_max)

See setEnvelope(Envelope) for information about recommended practices and precedence.

Parameters:: ordinates - The ordinates of the new envelope to use, or null.
Throws:: IllegalArgumentException - if the envelope is illegal.

getExtent

public GridEnvelope getExtent()

Returns the current grid extent. This method returns the first non-null value in the above choices, in preference order:

The value defined by the last call to setExtent(GridEnvelope).
The grid geometry extent.
The image bounds (including minX and minY values).

Returns:: The current grid extent, or null if unspecified and can not be inferred.
Since:: 3.20
See Also:: extent, GeneralGridGeometry.getExtent(), Grid.getExtent()

setExtent

public void setExtent(GridEnvelope extent)
               throws MismatchedDimensionException

Sets the grid extent to the specified value.

Precedence
If a grid geometry has been explicitely set and contains an extent, then that later extent will have precedence for the creation of GridCoverage2D instances.

Parameters:: extent - The new grid extent to use, or null.
Throws:: MismatchedDimensionException - If the extent dimension is not equal to the grid to CRS source dimensions.
Since:: 3.20

setExtent

public void setExtent(int... span)
               throws MismatchedDimensionException

Sets the grid extent to a grid envelope having the given span. The low ordinate values are set to 0.

This method is typically invoked for defining image dimension as below:

setExtent(width, height);

See setExtent(GridEnvelope) for information about precedence.

Parameters:: span - The span values for all dimensions, or null.
Throws:: MismatchedDimensionException - If the arguments contain negative span values, or the number of values is not equal to the grid to CRS source dimensions.
Since:: 3.20

getAffineGridToCRS

public AffineTransform getAffineGridToCRS()
                                   throws IllegalStateException

Returns two-dimensional part of the current grid to CRS affine transform. This method gets the transform as documented in the getGridToCRS() method, except that it tries to extract only the two-dimensional component of that transform.

Whatever the returned transform maps pixel centers or pixel corners depends on the pixelAnchor value.

Returns:: The grid to CRS transform, or null if unspecified and can not be inferred.
Throws:: IllegalStateException - If a transform exists but that transform is not affine.
Since:: 3.20

getGridToCRS

public MathTransform getGridToCRS()

Returns the current grid to CRS transform. This method returns the first non-null value in the above choices, in preference order:

The value defined by the last call to setGridToCRS(MathTransform).
The grid geometry transform.

Whatever the returned transform maps pixel centers or pixel corners depends on the pixelAnchor value.

Returns:: The grid to CRS transform, or null if unspecified and can not be inferred.
Since:: 3.20
See Also:: gridToCRS, GeneralGridGeometry.getGridToCRS()

setGridToCRS

public void setGridToCRS(MathTransform gridToCRS)
                  throws MismatchedDimensionException

Sets the grid to CRS transform. Whatever the transform maps pixel centers or pixel corners depends on the pixelAnchor value.

Restrictions

The number of source dimensions shall matches the grid extent dimensions (if any)
The number of target dimensions shall matches the crs and envelope dimensions (if any).

Precedence
If a grid geometry has been explicitely set and contains a transform, then that later transform will have precedence for the creation of GridCoverage2D instances.

Parameters:: gridToCRS - The new grid to CRS transform, or null.
Throws:: MismatchedDimensionException - If the given transform is invalid, for example if the dimensions don't match.
Since:: 3.20

setGridToCRS

public void setGridToCRS(Matrix gridToCRS)
                  throws MismatchedDimensionException

Sets the grid to CRS transform from a matrix. Whatever the transform maps pixel centers or pixel corners depends on the pixelAnchor value.

See setGridToCRS(MathTransform) for information about restrictions and precedence.

Parameters:: gridToCRS - The new grid to CRS transform, or null.
Throws:: MismatchedDimensionException - If the current extent and envelope (if any) are not two-dimensional.
Since:: 3.20

setGridToCRS

public void setGridToCRS(AffineTransform gridToCRS)
                  throws MismatchedDimensionException

Sets the grid to CRS transform from a Java2D transform. Whatever the transform maps pixel centers or pixel corners depends on the pixelAnchor value.

See setGridToCRS(MathTransform) for information about restrictions and precedence.

Parameters:: gridToCRS - The new grid to CRS transform, or null.
Throws:: MismatchedDimensionException - If the current extent and envelope (if any) are not two-dimensional.
Since:: 3.20

setGridToCRS

public void setGridToCRS(double m00,
                         double m10,
                         double m01,
                         double m11,
                         double m02,
                         double m12)
                  throws MismatchedDimensionException

Sets the grid to CRS transform from the given affine transform coefficients. Whatever the transform maps pixel centers or pixel corners depends on the pixelAnchor value.

See setGridToCRS(MathTransform) for information about restrictions and precedence.

Parameters:: m00 - the X coordinate scaling.; m10 - the Y coordinate shearing.; m01 - the X coordinate shearing.; m11 - the Y coordinate scaling.; m02 - the X coordinate translation.; m12 - the Y coordinate translation.
Throws:: MismatchedDimensionException - If the current extent and envelope (if any) are not two-dimensional.
Since:: 3.20
See Also:: AffineTransform2D

getPixelAnchor

public PixelInCell getPixelAnchor()

Returns whatever the grid to CRS transform maps pixel center or pixel corner. The OGC 01-004 specification mandates pixel center, but some computation are more convenient when mapping pixel corners.

Returns:: The "pixel in cell" policy. If unspecified, default value is PixelInCell.CELL_CENTER.
Since:: 3.20
See Also:: pixelAnchor, GeneralGridGeometry.GeneralGridGeometry(GridEnvelope, PixelInCell, MathTransform, CoordinateReferenceSystem)

setPixelAnchor

public void setPixelAnchor(PixelInCell anchor)

Sets the whatever the grid to CRS transform maps pixel center or pixel corner. Note that this attribute has no effect if the gridToCRS attribute is not used (for example because the gridGeometry attribute has precedence).

Parameters:: anchor - The new "pixel in cell" policy, or null.
Since:: 3.20

getGridGeometry

public GridGeometry getGridGeometry()

Returns the current grid geometry. If no grid geometry has been explicitly defined, then this method builds a default instance from the values returned by one of the following set of getter methods:

Recommended		Alternative
`getExtent()` `getPixelAnchor()` `getGridToCRS()` `getCoordinateReferenceSystem()`	or	`getExtent()` `getEnvelope()`

Note that creation of grid geometries from the parameters listed in the right column use heuristic rules documented here. In order to keep grid geometry creations more determinist, we recommend to specify the parameters listed in the left column instead.

Returns:: The grid geometry, or null if unspecified and can not be inferred.
Since:: 3.20
See Also:: gridGeometry, GridCoverage2D.getGridGeometry()

setGridGeometry

public void setGridGeometry(GridGeometry geom)

Sets the grid geometry to the given value. If non-null, this value will have precedence over the crs, envelope, extent, grid to CRS and pixel anchor attributes.

Note: If this property is set to null in the intend to force computation of a new grid geometry from the envelope value, then the caller will also needs to ensure that the gridToCRS property is null.

Parameters:: geom - The new grid geometry, or null.
Since:: 3.20

getNumBands

public int getNumBands()

Returns the number of sample dimensions (bands). This method returns the first defined value in the above choices, in preference order:

The value defined by the last call to setNumBands(int).
The highest n+1 value given to variable(int).
The number of bands in the image.
The default value 1.

Returns:: The number of sample dimensions (bands).
Since:: 3.20
See Also:: numBands, SampleModel.getNumBands()

setNumBands

public void setNumBands(int n)
                 throws IllegalArgumentException

Sets the number of sample dimensions (bands). If any variable existed at the index n or greater, they will be discarded.

Parameters:: n - Number of sample dimensions, or 0 to unspecify.
Throws:: IllegalArgumentException - If the given value is negative.
Since:: 3.20

variable

public GridCoverageBuilder.Variable variable(int band)
                                      throws IllegalArgumentException

Returns the sample dimension builder for the given band index. If a Variable instance exists at the given index, it will be returned. Otherwise a new instance will be created.

If the given band index is equals or greater than the number of sample dimensions, then the later will be increased as needed.

Parameters:: band - The index of the sample dimension for which to get the variable.
Returns:: The builder for the given sample dimension.
Throws:: IllegalArgumentException - If the given band index is negative.
Since:: 3.20

newVariable

protected GridCoverageBuilder.Variable newVariable(int band)

Invoked by the variable(int) method when a new variable need to be created. This method is a hook for subclasses that wish to instantiate their own Variable subclasses. The default implementation is:

return new Variable(band);

Parameters:: band - The index of the sample dimension for which to get the new variable.
Returns:: The new variable.
Since:: 3.20

getSampleDimensions

public SampleDimension[] getSampleDimensions()

Returns the sample dimensions, or null if none. If all sample dimensions are actually instances of GridSampleDimension, then the array type is GridSampleDimension[].

Returns:: The sample dimensions, or null if none.
Since:: 3.20

setSampleDimensions

public void setSampleDimensions(SampleDimension... bands)

Sets all sample dimensions. This convenience method sets the number of bands to the number of given arguments, then invokes setSampleDimension(...) for each element.

Parameters:: bands - The new sample dimensions, or null.
Since:: 3.20

setSampleDimensions

public void setSampleDimensions(double[] minValues,
                                double[] maxValues,
                                Unit<?> units,
                                Color[]... colors)

Sets all variables information to the given ranges, units and colors. This convenience method sets the number of bands to the maximal length of the non-null arrays, then invokes setSampleRange(NumberRange), setUnit(Unit) and setColors(Color[]) methods for each variable.

Parameters:: minValues - The minimal value for each band in the raster, or null.; maxValues - The maximal value for each band in the raster, or null.; units - The units, or null if unknown.; colors - The colors to use for values from minValues to maxValues for each bands, or null. Can contains null elements.
Since:: 3.20

getColorModel

public ColorModel getColorModel()

Returns or computes the image color model. This method returns the first non-null value in the above choices, in preference order:

A color model created by one of the getColorModel(...) methods invoked on the first GridSampleDimension instance returned by getSampleDimensions().
The image color model.

Returns:: The color model, or null if none.
Since:: 3.20

createGraphics

public Graphics createGraphics(boolean crsUnit)
                        throws UnsupportedOperationException

Creates a graphics which can be used to draw into the rendered image. It is caller responsibility to invoke Graphics.dispose() after the drawing has been completed.

The returned value can usually be casted to Graphics2D.

Parameters:: crsUnit - true for drawing using the coverage units (typically metres or degrees of longitude/latitude), or false for drawing using pixel units. The value of true is supported only for Graphics2D instances.
Returns:: A graphics (usually a Graphics2D) for drawing into the image.
Throws:: UnsupportedOperationException - If the rendered image does not support drawing, or if crsUnit is true and the graphics is not an instance of Graphics2D.
Since:: 3.20

getImageBounds

public Rectangle getImageBounds()
                         throws InvalidGridGeometryException

Returns the image bounds. This method returns the first non-null value in the above choices, in preference order:

The grid geometry extent.
The image bounds.

Note that the (x,y) origin must be (0,0) for building a BufferedImage, but can be different for other kinds of RenderedImage.

Returns:: The current image bounds. Never null since no image can be built without this information.
Throws:: InvalidGridGeometryException - if there is no grid geometry or no extent associated to that grid geometry.
Since:: 3.20
See Also:: GridGeometry2D.getExtent2D()

getTileSize

public Dimension getTileSize()

Returns the tile size, or null if the image is untiled. This method returns the first non-null value in the above choices, in preference order:

The value defined by the last call to setTileSize(Dimension).
The image tile size.

Returns:: The tile size, or null if the image is untiled.
Since:: 3.20
See Also:: RenderedImage.getTileWidth(), RenderedImage.getTileHeight()

setTileSize

public void setTileSize(Dimension size)

Sets the tile size.

Precedence
If an image has been explicitely set, then its tile setting will have precedence over this attribute for the creation of GridCoverage2D instances (i.e. this method does not retile existing images).

Parameters:: size - The new tile size, or null for untiled image.
Since:: 3.20

getTileGridOffset

public Point getTileGridOffset()

Returns the tile grid offset, or null if the image is untiled. This method returns the first non-null value in the above choices, in preference order:

The value defined by the last call to setTileGridOffset(Point).
The image tile grid offset.

Returns:: The tile grid offset, or null if the image is untiled.
Since:: 3.20
See Also:: RenderedImage.getTileGridXOffset(), RenderedImage.getTileGridYOffset()

setTileGridOffset

public void setTileGridOffset(Point offset)

Sets the tile offset.

Parameters:: offset - The new tile offset, or null if none.
Since:: 3.20

getRenderedImage

public RenderedImage getRenderedImage()

Returns the rendered image to be wrapped by GridCoverage2D. If no image has been explicitly defined, a new one is created the first time this method is invoked. Users can modify the pixel values in this image before to create the grid coverage.

In the common case of untiled image having a lower corner located at (0,0), this method returns an instance of BufferedImage. If the builder settings do not allow the creation of a BufferedImage instance, then the default implementation fallbacks on a TiledImage instance.

Returns:: The rendered image to be wrapped by GridCoverage2D.
Since:: 3.20 (derived from 2.5)

setRenderedImage

public void setRenderedImage(RenderedImage image)

Sets the rendered image.

Parameters:: image - The rendered image to be wrapped by GridCoverage2D, or null.
Since:: 3.20 (derived from 2.5)

setRenderedImage

public void setRenderedImage(WritableRaster raster)

Creates a rendered image from the given raster. This methods create a color model for the given raster, then creates a BufferedImage using that color model and the raster, and finally invokes setRenderedImage(RenderedImage) with the result in argument.

Parameters:: raster - The raster to be wrapped by GridCoverage2D, or null.
Since:: 3.20

setRenderedImage

public void setRenderedImage(float[][] matrix)

Creates a rendered image from the given matrix. This method copies the values from the given matrix to a new raster, then invokes setRenderedImage(WritableRaster). NaN values are mapped to a transparent color by default.

The image height will be the length of the matrix argument. The image width will be the length of the largest row. If some rows or missing (null) or shorter than the image width, then the missing values will be padded with NaN.

Parameters:: matrix - The matrix data in a [row][column] layout. Can contains null elements (missing rows).
Since:: 3.20 (derived from 2.2)

setRenderedImage

public void setRenderedImage(ImageFunction function)

Creates a rendered image from the given image function. The getGridGeometry() method must return a fully defined value before this method can be invoked.

Parameters:: function - The image function, or null.
Since:: 3.20 (derived from 2.2)
See Also:: ImageFunctionDescriptor

getGridCoverage2D

public GridCoverage2D getGridCoverage2D()

Returns the grid coverage. The default implementation builds a coverage like below (omitting the conversions of some argument types):

return new GridCoverage2D(
         getName(),
         getRenderedImage(),
         getGridGeometry(),
         getSampleDimensions(),
         getSources(),
         getProperties(),
         hints)

Returns:: The grid coverage.

setGridCoverage

public void setGridCoverage(GridCoverage coverage)

Configure this builder to the same values than the given coverage. This method invokes the following methods with values inferred from the given coverage:

setName(CharSequence) (for instances of GridCoverage2D only)
setRenderedImage(RenderedImage)
setGridGeometry(GridGeometry)
setGridToCRS(MathTransform)
setExtent(GridEnvelope)
setCoordinateReferenceSystem(CoordinateReferenceSystem)
setSampleDimensions(SampleDimension[])
setSources(GridCoverage[])
setProperties(PropertySource) (for instances of PropertySource only)

Parameters:: coverage - The coverage to set.
Since:: 3.20

getSources

public GridCoverage[] getSources()

Returns the optional sources to be associated with the coverage. If there is no sources, then this method returns null.

Implementation note
This method returns a direct reference to the sources field. The array is not cloned because it is not used for any calculation in this class. GridCoverageBuilder users are responsible for the content of this array.

Returns:: Optional grid coverage sources, or null if none.
Since:: 3.20
See Also:: sources, AbstractGridCoverage.getSources()

setSources

public void setSources(GridCoverage... sources)

Sets the optional sources to be associated with the coverage.

Implementation note
The given array is not cloned at this method invocation time. The array will be cloned by the grid coverage constructor. This builder does nothing but passing the array to that constructor.

Parameters:: sources - Optional grid coverage sources, or null or an empty array if none.
Since:: 3.20

getProperties

public Map<?,?> getProperties()

Returns optional properties to be given to the coverage, or null if none.

Implementation note
This method returns a direct reference to the properties field. The map is not cloned because it is not used for any calculation in this class. GridCoverageBuilder users are responsible for the content of this map.

Returns:: Optional map of coverage properties, or null.
Since:: 3.20
See Also:: properties, PropertySourceImpl.getProperties(), PropertySourceImpl.getPropertyNames()

setProperties

public void setProperties(Map<?,?> properties)

Sets the optional properties to be given to the coverage.

Reference to the given map
The given map is not cloned at this method invocation time. The map will be cloned by the grid coverage constructor. This builder does nothing but passing the map to that constructor.

Parameters:: properties - Optional map of coverage properties, or null.
Since:: 3.20

setProperties

public void setProperties(PropertySource source)

Inherits all the properties from the given source. This convenience methods copies the properties in a new Map object, then invokes setProperties(Map).

Parameters:: source - The source from which to get the properties, null.
Since:: 3.20

build

public GridCoverage build()

Creates the grid coverage. Current implementation delegates to getGridCoverage2D(), but future implementations may instantiate different coverage types.

Specified by:: build in class Builder<GridCoverage>

Returns:: The new object created from the user values.
Since:: 3.20

reset

public void reset()

Resets this builder to its initial state. This method can be invoked in order to reuse this builder for creating new GridCoverage2D instances.

Since:: 3.20

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.geotoolkit.coverage.grid Class GridCoverageBuilder

name

crs

envelope

extent

gridToCRS

pixelAnchor

gridGeometry

numBands

image

sources

properties

hints

GridCoverageBuilder

GridCoverageBuilder

getName

setName

getCoordinateReferenceSystem

setCoordinateReferenceSystem

setCoordinateReferenceSystem

getEnvelope

setEnvelope

setEnvelope

getExtent

setExtent

setExtent

getAffineGridToCRS

getGridToCRS

setGridToCRS

setGridToCRS

setGridToCRS

setGridToCRS

getPixelAnchor

setPixelAnchor

getGridGeometry

setGridGeometry

getNumBands

setNumBands

variable

newVariable

getSampleDimensions

setSampleDimensions

setSampleDimensions

getColorModel

createGraphics

getImageBounds

getTileSize

setTileSize

getTileGridOffset

setTileGridOffset

getRenderedImage

setRenderedImage

setRenderedImage

setRenderedImage

setRenderedImage

getGridCoverage2D

setGridCoverage

getSources

setSources

getProperties

setProperties

setProperties

build

reset

org.geotoolkit.coverage.grid
Class GridCoverageBuilder