org.geotools.coverage.io.util

Class Utilities

Object

Utilities

public class Utilities
extends Object

Author:

Daniele Romagnoli, GeoSolutions

Method Summary

Modifier and Type	Method and Description
static NameImpl	buildCoverageName(URL input)
static String	buildIso8601Time(String date, String time)
static boolean	checkFileReadable(File file) Checks that a File is a real file, exists and is readable.
static GridCoverage	compute(Object input, int imageIndex, boolean needTransformation, boolean isEmptyRequest, boolean useJAI, ImageReadParam imageReadParam, boolean useMultithreading, GridSampleDimension[] sampleDimensions, ImageReaderSpi imageReaderSpi, String coverageName, GridCoverageFactory coverageFactory, MathTransform raster2Model, CoordinateReferenceSystem coordinateReferenceSystem, GeneralEnvelope envelope2D) Compute the coverage request and produce a grid coverage.
static GridCoverage	createCoverage(ImageReaderSpi spi, Object input, int imageIndex, ImageReadParam imageReadParam, boolean useJAI, boolean useMultithreading, boolean newTransform, GridSampleDimension[] sampleDimensions, String coverageName, GridCoverageFactory coverageFactory, MathTransform raster2Model, CoordinateReferenceSystem coordinateReferenceSystem, GeneralEnvelope coverageEnvelope2D) This method creates the GridCoverage2D from the underlying file given a specified envelope, and a requested dimension.
static GridCoverage	createCoverageFromImage(GridCoverageFactory coverageFactory, String coverageName, int imageIndex, PlanarImage image, MathTransform raster2Model, CoordinateReferenceSystem spatialReferenceSystem2D, GeneralEnvelope coverageEnvelope2D, GridSampleDimension[] sampleDimensions) Creates a GridCoverage for the provided PlanarImage using the #raster2Model that was provided for this coverage.
static boolean	ensureValidString(String... strings)
static GeneralEnvelope	evaluateRequestedParams(GridEnvelope originalGridRange, Envelope2D baseEnvelope2D, CoordinateReferenceSystem spatialReferenceSystem2D, MathTransform originalGridToWorld, GeneralEnvelope requestedEnvelope, Rectangle sourceRegion, Rectangle requestedDim, MathTransform2D readGridToWorld, Envelope2D wgs84BaseEnvelope2D) Evaluates the requested envelope and builds a new adjusted version of it fitting this coverage envelope.
static String	getAttributeValue(NamedNodeMap attributes, String attributeName) Simple method returning the value (as String) of the attribute with name attributeName from the input attributes map.
static GeographicCRS	getBaseCRS(double equatorialRadius, double inverseFlattening) Build a base GeographicCRS given the parameters to specify a Geodetic Datum
static Rectangle	getCropRegion(GeneralEnvelope envelope, MathTransform gridToWorldTransform) Return a crop region from a specified envelope, leveraging on a grid to world transformation.
static DefaultGeodeticDatum	getDefaultGeodeticDatum(String name, double equatorialRadius, double inverseFlattening, Unit unit) Build a DefaultGeodeticDatum given a set of parameters.
static Envelope	getEnvelopeAsWGS84(Envelope envelope, boolean get2D) Get a WGS84 envelope for the specified envelope.
static File	getFileFromCustomInput(Object input) Temp utility method which allows to get the real file name from a custom input File, where "custom" means a file having a special name structured as "originalFileName:imageIndex"
static String	getFileInfo(File file) Creates a human readable message that describe the provided File object in terms of its properties.
static ReferenceIdentifier[]	getIdentifiers(String nameIdentifier)
static GeneralEnvelope	getIntersection(Envelope2D baseEnvelope2D, CoordinateReferenceSystem spatialReferenceSystem2D, GeneralEnvelope requestedEnvelope2D, Rectangle requestedDim, MathTransform2D readGridToWorld, Envelope2D wgs84BaseEnvelope2D) Returns the intersection between the base envelope and the requested envelope.
static CoordinateReferenceSystem	getMercator2SPProjectedCRS(double standardParallel, double centralMeridian, double natOriginLat, GeographicCRS sourceCRS, Hints hints) Simple utility method which allows to build a Mercator2SP Projected CRS given the set of required parameters.
static MathTransform	getOriginalGridToWorld(MathTransform raster2Model, PixelInCell pixInCell) Retrieves the original grid to world transformation for this AbstractGridCoverage2DReader.
static GeneralEnvelope	getRequestedEnvelope2D(GeneralEnvelope requestedEnvelope) Return a 2D version of a requestedEnvelope
static Properties	loadPropertiesFromURL(URL propsURL)
static Unit<? extends Quantity>	parseUnit(String uom) Return a Unit instance for the specified uom String.
static PlanarImage	readImage(ImageReaderSpi spi, Object input, int imageIndex, boolean useJAI, ImageReadParam imageReadParam, boolean useMultithreading) Returns a PlanarImage given a set of parameter specifying the type of read operation to be performed.
static void	setDecimationParameters(ImageReadParam readP, GridEnvelope baseGridRange, double[] requestedRes, double[] highestRes) This method is responsible for evaluating possible subsampling factors once the best resolution level has been found in case we have support for overviews, or starting from the original coverage in case there are no overviews available.
static void	setReadParameters(OverviewPolicy overviewPolicy, ImageReadParam readParam, GeneralEnvelope requestedEnvelope, Rectangle requestedDim, double[] highestRes, GridEnvelope gridRange, PixelInCell pixelInCell) Prepares the read parameters for doing an ImageReader.read(int, ImageReadParam).

Methods inherited from class Object

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

Method Detail

getIdentifiers

public static ReferenceIdentifier[] getIdentifiers(String nameIdentifier)

getDefaultGeodeticDatum

public static DefaultGeodeticDatum getDefaultGeodeticDatum(String name,
                                                           double equatorialRadius,
                                                           double inverseFlattening,
                                                           Unit unit)

Build a DefaultGeodeticDatum given a set of parameters.

Parameters:

name - the datum name

equatorialRadius - the equatorial radius parameter

inverseFlattening - the inverse flattening parameter

unit - the UoM

Returns:

a properly built Datum.

getFileFromCustomInput

public static File getFileFromCustomInput(Object input)

Temp utility method which allows to get the real file name from a custom input File, where "custom" means a file having a special name structured as "originalFileName:imageIndex"

getMercator2SPProjectedCRS

public static CoordinateReferenceSystem getMercator2SPProjectedCRS(double standardParallel,
                                                                   double centralMeridian,
                                                                   double natOriginLat,
                                                                   GeographicCRS sourceCRS,
                                                                   Hints hints)
                                                            throws DataSourceException

Simple utility method which allows to build a Mercator2SP Projected CRS given the set of required parameters. It will be used by several Terascan products.

Throws:

DataSourceException

getBaseCRS

public static GeographicCRS getBaseCRS(double equatorialRadius,
                                       double inverseFlattening)

Build a base GeographicCRS given the parameters to specify a Geodetic Datum

getAttributeValue

public static String getAttributeValue(NamedNodeMap attributes,
                                       String attributeName)

Simple method returning the value (as String) of the attribute with name attributeName from the input attributes map.

Parameters:

attributes - the attributes map

attributeName - the requested attribute

Returns:

the value of the requested attribute as a String. Returns null in case of no attribute found.

parseUnit

public static Unit<? extends Quantity> parseUnit(String uom)

Return a Unit instance for the specified uom String.

getEnvelopeAsWGS84

public static Envelope getEnvelopeAsWGS84(Envelope envelope,
                                          boolean get2D)
                                   throws FactoryException,
                                          TransformException

Get a WGS84 envelope for the specified envelope. The get2D parameter allows to specify if we need the returned coverage as an Envelope2D or a more general GeneralEnvelope instance. if true, the requested envelope will be an instance of Envelope2D. If false it will be an instance of {@link GeneralEnvelope

Returns:

a WGS84 envelope as Envelope2D in case of request for a 2D WGS84 Envelope, or a GeneralEnvelope otherwise.

Throws:

FactoryException

TransformException

getRequestedEnvelope2D

public static GeneralEnvelope getRequestedEnvelope2D(GeneralEnvelope requestedEnvelope)
                                              throws FactoryException,
                                                     TransformException

Return a 2D version of a requestedEnvelope

Parameters:

requestedEnvelope - the GeneralEnvelope to be returned as 2D.

Returns:

the 2D requested envelope

Throws:

FactoryException

TransformException

getCropRegion

public static Rectangle getCropRegion(GeneralEnvelope envelope,
                                      MathTransform gridToWorldTransform)
                               throws TransformException

Return a crop region from a specified envelope, leveraging on a grid to world transformation.

Parameters:

envelope - the crop envelope

gridToWorldTransform - the grid2world transformation

Returns:

a Rectangle representing the crop region.

Throws:

TransformException - in case a problem occurs when going back to raster space.

getIntersection

public static GeneralEnvelope getIntersection(Envelope2D baseEnvelope2D,
                                              CoordinateReferenceSystem spatialReferenceSystem2D,
                                              GeneralEnvelope requestedEnvelope2D,
                                              Rectangle requestedDim,
                                              MathTransform2D readGridToWorld,
                                              Envelope2D wgs84BaseEnvelope2D)
                                       throws TransformException,
                                              FactoryException

Returns the intersection between the base envelope and the requested envelope.

Parameters:

baseEnvelope2D - the base envelope.

requestedEnvelope2D - the requested 2D envelope to be intersected with the base envelope.

requestedDim - is the requested region where to load data of the specified envelope.

readGridToWorld - the Grid to world transformation to be used in read

wgs84BaseEnvelope2D - a WGS84 version of the baseEnvelope to be used to try finding an intersection in wgs84 in case it is impossible to compute an intersection of the base envelope with the specified requested envelope.

Returns:

the resulting intersection of envelopes. In case of empty intersection, this method is allowed to return null

Throws:

TransformException

FactoryException

getOriginalGridToWorld

public static MathTransform getOriginalGridToWorld(MathTransform raster2Model,
                                                   PixelInCell pixInCell)

Retrieves the original grid to world transformation for this AbstractGridCoverage2DReader.

Parameters:

pixInCell - specifies the datum of the transformation we want.

Returns:

the original grid to world transformation

evaluateRequestedParams

public static GeneralEnvelope evaluateRequestedParams(GridEnvelope originalGridRange,
                                                      Envelope2D baseEnvelope2D,
                                                      CoordinateReferenceSystem spatialReferenceSystem2D,
                                                      MathTransform originalGridToWorld,
                                                      GeneralEnvelope requestedEnvelope,
                                                      Rectangle sourceRegion,
                                                      Rectangle requestedDim,
                                                      MathTransform2D readGridToWorld,
                                                      Envelope2D wgs84BaseEnvelope2D)
                                               throws DataSourceException

Evaluates the requested envelope and builds a new adjusted version of it fitting this coverage envelope.

While adjusting the requested envelope this methods also compute the source region as a rectangle which is suitable for a successive read operation with ImageIO to do crop-on-read.

Parameters:

requestedEnvelope - is the envelope we are requested to load.

sourceRegion - represents the area to load in raster space. This parameter cannot be null since it gets filled with whatever the crop region is depending on the requestedEnvelope.

requestedDim - is the requested region where to load data of the specified envelope.

readGridToWorld - the Grid to world transformation to be used

Returns:

the adjusted requested envelope, empty if no requestedEnvelope has been specified, null in case the requested envelope does not intersect the coverage envelope or in case the adjusted requested envelope is covered by a too small raster region (an empty region).

Throws:

DataSourceException - in case something bad occurs

createCoverageFromImage

public static GridCoverage createCoverageFromImage(GridCoverageFactory coverageFactory,
                                                   String coverageName,
                                                   int imageIndex,
                                                   PlanarImage image,
                                                   MathTransform raster2Model,
                                                   CoordinateReferenceSystem spatialReferenceSystem2D,
                                                   GeneralEnvelope coverageEnvelope2D,
                                                   GridSampleDimension[] sampleDimensions)
                                            throws IOException

Creates a GridCoverage for the provided PlanarImage using the #raster2Model that was provided for this coverage.

This method is vital when working with coverages that have a raster to model transformation that is not a simple scale and translate.

Parameters:

image - contains the data for the coverage to create.

raster2Model - is the MathTransform that maps from the raster space to the model space.

Returns:

a GridCoverage

Throws:

IOException

setDecimationParameters

public static void setDecimationParameters(ImageReadParam readP,
                                           GridEnvelope baseGridRange,
                                           double[] requestedRes,
                                           double[] highestRes)

This method is responsible for evaluating possible subsampling factors once the best resolution level has been found in case we have support for overviews, or starting from the original coverage in case there are no overviews available.

Parameters:

readP - the imageRead parameter to be set

requestedRes - the requested resolutions from which to determine the decimation parameters.

buildCoverageName

public static NameImpl buildCoverageName(URL input)

setReadParameters

public static void setReadParameters(OverviewPolicy overviewPolicy,
                                     ImageReadParam readParam,
                                     GeneralEnvelope requestedEnvelope,
                                     Rectangle requestedDim,
                                     double[] highestRes,
                                     GridEnvelope gridRange,
                                     PixelInCell pixelInCell)
                              throws IOException,
                                     TransformException

Prepares the read parameters for doing an ImageReader.read(int, ImageReadParam).

It sets the passed ImageReadParam in terms of decimation on reading using the provided requestedEnvelope and requestedDim to evaluate the needed resolution.

Parameters:

overviewPolicy - it can be one of Hints#VALUE_OVERVIEW_POLICY_IGNORE, Hints#VALUE_OVERVIEW_POLICY_NEAREST, Hints#VALUE_OVERVIEW_POLICY_QUALITY or Hints#VALUE_OVERVIEW_POLICY_SPEED. It specifies the policy to compute the overviews level upon request.

readParam - an instance of ImageReadParam for setting the subsampling factors.

requestedEnvelope - the GeneralEnvelope we are requesting.

requestedDim - the requested dimensions.

Throws:

IOException

TransformException

createCoverage

public static GridCoverage createCoverage(ImageReaderSpi spi,
                                          Object input,
                                          int imageIndex,
                                          ImageReadParam imageReadParam,
                                          boolean useJAI,
                                          boolean useMultithreading,
                                          boolean newTransform,
                                          GridSampleDimension[] sampleDimensions,
                                          String coverageName,
                                          GridCoverageFactory coverageFactory,
                                          MathTransform raster2Model,
                                          CoordinateReferenceSystem coordinateReferenceSystem,
                                          GeneralEnvelope coverageEnvelope2D)
                                   throws IOException

This method creates the GridCoverage2D from the underlying file given a specified envelope, and a requested dimension.

Parameters:

useJAI - specify if the underlying read process should leverage on a JAI ImageRead operation or a simple direct call to the read method of a proper ImageReader.

useMultithreading - specify if the underlying read process should use multithreading when a JAI ImageRead operation is requested

Returns:

a GridCoverage

Throws:

IOException

readImage

public static PlanarImage readImage(ImageReaderSpi spi,
                                    Object input,
                                    int imageIndex,
                                    boolean useJAI,
                                    ImageReadParam imageReadParam,
                                    boolean useMultithreading)
                             throws IOException

Returns a PlanarImage given a set of parameter specifying the type of read operation to be performed.

Parameters:

input - the input to be used for reading the image.

useJAI - true if we need to use a JAI ImageRead operation, false if we need a simple direct ImageReader.read(...) call.

imageReadParam - an ImageReadParam specifying the read parameters

useMultithreading - true if a JAI ImageRead operation is requested with support for multithreading. This parameter will be ignored if requesting a direct read operation.

Returns:

the read PlanarImage

Throws:

IOException

compute

public static GridCoverage compute(Object input,
                                   int imageIndex,
                                   boolean needTransformation,
                                   boolean isEmptyRequest,
                                   boolean useJAI,
                                   ImageReadParam imageReadParam,
                                   boolean useMultithreading,
                                   GridSampleDimension[] sampleDimensions,
                                   ImageReaderSpi imageReaderSpi,
                                   String coverageName,
                                   GridCoverageFactory coverageFactory,
                                   MathTransform raster2Model,
                                   CoordinateReferenceSystem coordinateReferenceSystem,
                                   GeneralEnvelope envelope2D)
                            throws IOException

Compute the coverage request and produce a grid coverage. The produced grid coverage may be null in case of empty request.

Throws:

IOException - @TODO: handle more input types

ensureValidString

public static final boolean ensureValidString(String... strings)

buildIso8601Time

public static String buildIso8601Time(String date,
                                      String time)

checkFileReadable

public static boolean checkFileReadable(File file)

Checks that a File is a real file, exists and is readable.

Parameters:

file - the File instance to check. Must not be null.

Returns:

true in case the file is a real file, exists and is readable; false otherwise.

getFileInfo

public static String getFileInfo(File file)

Creates a human readable message that describe the provided File object in terms of its properties.

Useful for creating meaningful log messages.

Parameters:

file - the File object to create a descriptive message for

Returns:

a String containing a descriptive message about the provided File.

loadPropertiesFromURL

public static Properties loadPropertiesFromURL(URL propsURL)