org.geotoolkit.image.io.metadata
Class MetadataHelper

Object
  MetadataHelper

All Implemented Interfaces:

Localized

public class MetadataHelper
extends Object
implements Localized

Utility methods extracting commonly used informations from ISO 19115-2 or ISO 19123 objects. Instances of ISO 19115-2 metadata are typically obtained from SpatialMetadata objects.

Since:

3.07

Version:

3.19

Author:

Martin Desruisseaux (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

static MetadataHelper

INSTANCE The default instance.

Constructor Summary

MetadataHelper(Localized owner)
Creates a new metadata helper for the given ImageReader or ImageWriter.

Method Summary

double	adjustForRoundingError(double value) Works around the rounding errors found in some metadata numbers.
String	formatCellDimension(RectifiedGrid domain, CoordinateSystem cs) Returns the dimension of pixels as a text, or null if none.
AffineTransform	getAffineTransform(RectifiedGrid domain, IIOParam param) Creates an affine transform from the origin and offset vectors of the given domain.
Dimension2D	getCellDimension(AffineTransform gridToCRS) Returns the dimension of pixels, or null if not applicable.
double	getCellSize(AffineTransform gridToCRS) Returns the size of pixels, which must be square.
List<GridSampleDimension>	getGridSampleDimensions(List<? extends SampleDimension> sampleDimensions) Converts the given SampleDimension instances to GridSampleDimension instances.
MathTransform	getGridToCRS(RectifiedGrid domain) Creates the Grid to CRS conversion from the origin and offset vectors of the given domain.
Locale	getLocale() Returns the locale used by this helper, or null for the default locale.
NumberRange<?>	getValidSampleValues(SampleDimension dimension) Returns the range of sample values defined in the given SampleDimension object.
NumberRange<?>	getValidSampleValues(SampleDimension dimension, double[] fillSampleValues) Returns the range of sample values defined in the given SampleDimension object.
NumberRange<?>	getValidValues(SampleDimension dimension) Returns the range of geophysics values defined in the given SampleDimension object.

Methods inherited from class Object

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

Field Detail

INSTANCE

public static final MetadataHelper INSTANCE

The default instance.

Constructor Detail

MetadataHelper

public MetadataHelper(Localized owner)

Creates a new metadata helper for the given ImageReader or ImageWriter.

Parameters:

owner - The image reader or writer for which we are creating metadata, or null if none.

Method Detail

getLocale

public Locale getLocale()

Returns the locale used by this helper, or null for the default locale. This is used for formatting text in methods like formatCellDimension, and for localization of error messages when an exception is thrown.

Specified by:

getLocale in interface Localized

Returns:

The locale, or null if unspecified.

Since:

3.09

getValidValues

public NumberRange<?> getValidValues(SampleDimension dimension)

Returns the range of geophysics values defined in the given SampleDimension object. This method tries to build the range from the minimum value, maximum value, scale factor, offset and the fill sample values metadata attributes.

Parameters:

dimension - The object from which to extract the range.

Returns:

The range of geophysics values, or null.

Since:

3.08

getValidSampleValues

public NumberRange<?> getValidSampleValues(SampleDimension dimension)

Returns the range of sample values defined in the given SampleDimension object. This method first looks at the value returned by SampleDimension.getValidSampleValues(). If the later returns null, then this method tries to build the range from the minimum value, maximum value and the fill sample values metadata attributes.

The fill sample values are used in order to determine if the minimum and maximum values are inclusive or exclusive: if an extremum is equals to a fill sample value, then it is considered exclusive. Otherwise it is considered inclusive.

Parameters:

dimension - The object from which to extract the range.

Returns:

The range of sample values, or null.

getValidSampleValues

public NumberRange<?> getValidSampleValues(SampleDimension dimension,
                                           double[] fillSampleValues)

Returns the range of sample values defined in the given SampleDimension object. This method performs the same work than getValidSampleValues(SampleDimension), except that the fill sample values are given explicitly. Note that the fill sample values is not an ISO 19115-2 attribute.

Parameters:

dimension - The object from which to extract the range.

fillSampleValues - The no-data values, or null if none.

Returns:

The range of sample values, or null.

getGridToCRS

public MathTransform getGridToCRS(RectifiedGrid domain)
                           throws ImageMetadataException

Creates the Grid to CRS conversion from the origin and offset vectors of the given domain.

This method is similar to getAffineTransform(RectifiedGrid, IIOParam), except that it is not restricted to a two-dimensional conversion and does not take an IIOParam object in account.

Parameters:

domain - The domain from which to extract the origin and offset vectors.

Returns:

The Grid to CRS conversion extracted from the given domain.

Throws:

ImageMetadataException - If a mandatory attribute is missing from the given domain.

Since:

3.09

getAffineTransform

public AffineTransform getAffineTransform(RectifiedGrid domain,
                                          IIOParam param)
                                   throws ImageMetadataException

Creates an affine transform from the origin and offset vectors of the given domain. If the param parameter is non-null, then the affine transform is scaled and translated according the subsampling, source and destination regions specified.

Note that the returned transform may maps pixel corner or pixel center, depending on the value returned by Georectified.getPointInPixel(). It is caller responsibility to make the necessary adjustments (tip: PixelTranslation may be useful).

Parameters:

domain - The domain from which to extract the origin and offset vectors.

param - Optional Image I/O parameters, or null if none.

Returns:

The affine transform extracted from the given domain.

Throws:

ImageMetadataException - If a mandatory attribute is missing from the given domain, or if this method can not extract the two first dimensions from the domain.

getCellSize

public double getCellSize(AffineTransform gridToCRS)
                   throws ImageMetadataException

Returns the size of pixels, which must be square. The gridToCRS argument is typically the output of getAffineTransform. This method checks if the given transform complies with the following conditions:

• The scaleX coefficient must be greater than zero.
• The scaleY coefficient must be the negative value of scaleX, because the Y axis is assumed reversed.
• The shearX and shearY coefficients must be zero.

If all those conditions are meet, then scaleX is returned. Otherwise an exception is thrown. This behavior is convenient for code like the ASCII Grid writer, which require square pixels as of format specification.

Parameters:

gridToCRS - The affine transform from which to extract the cell size.

Returns:

The cell size as a positive and non-null value.

Throws:

ImageMetadataException - If the affine transform does not comply with the above cited conditions.

getCellDimension

public Dimension2D getCellDimension(AffineTransform gridToCRS)

Returns the dimension of pixels, or null if not applicable. The gridToCRS argument is typically the output of getAffineTransform. This method checks if the given transform complies with the following conditions:

• The shearX and shearY coefficients are zero.

If this condition is meet, then scaleX and the negative value of scaleY (because the Y axis is assumed reversed) are returned in a new Dimension2D object. Otherwise null is returned. This behavior is convenient for code like the ASCII Grid writer, which require square pixels unless some extensions are enabled for rectangular pixel.

Parameters:

gridToCRS - The affine transform from which to extract the cell size.

Returns:

The cell dimension, or null if the image is rotated.

formatCellDimension

public String formatCellDimension(RectifiedGrid domain,
                                  CoordinateSystem cs)

Returns the dimension of pixels as a text, or null if none. This method computes the dimension from the offset vectors and appends the axis units, if any.

Parameters:

domain - The domain from which to compute the cell dimensions.

cs - The "real world" coordinate system, or null if unknown.

Returns:

A text representation of the cell dimension, or null if there is no offset vectors.

Since:

3.09

getGridSampleDimensions

public List<GridSampleDimension> getGridSampleDimensions(List<? extends SampleDimension> sampleDimensions)
                                                  throws ImageMetadataException

Converts the given SampleDimension instances to GridSampleDimension instances. For each input sample dimension, this method creates a qualitative category for each fill values (if any) and a single quantitative category for the range of sample values.

The sampleDimensions argument is typically obtained by the following method call:

SpatialMetadata metadata = ...
sampleDimensions = metadata.getListForType(SampleDimension.class);

Parameters:

sampleDimensions - The sample dimensions from Image I/O metadata, or null.

Returns:

The GridSampleDimensions, or null if the given list was null or empty.

Throws:

ImageMetadataException - If this method can not create the grid sample dimensions.

Since:

3.13

adjustForRoundingError

public double adjustForRoundingError(double value)

Works around the rounding errors found in some metadata numbers. We usually don't try to "fix" rounding errors, but affine transform coefficients are an exception because they have a very deep impact on performance, especially the scale factors: integer scales are often processed by optimized loops much faster than the loops for fractional scales, and operations like matrix multiplications are more likely to produce special cases like the identity transform when the initial matrix coefficients have an exact IEEE 754 representation.

This method processes as below:

• First, the given value is multiplied by 360. We choose the 360 value arbitrarily because it is a multiple of many commonly used factors: 2, 3, 4, 5, 6, 10, 60 and others.
• If the result of the above step is almost an integer, then round it, divide by 360 and return the result.
• Otherwise return the given value unchanged (we do not return the result of multiplication followed by a division, in order to avoid additional rounding error).

Parameters:

value - The value that we want to adjust.

Returns:

The adjusted value, or the given value unchanged if no adjustment were found.

See Also:

XMath.roundIfAlmostInteger(double, int), XAffineTransform.roundIfAlmostInteger(AffineTransform, double)