org.geotoolkit.image.io.metadata
Class SpatialMetadataFormat

Object
  IIOMetadataFormatImpl
      SpatialMetadataFormat

All Implemented Interfaces:

IIOMetadataFormat

Direct Known Subclasses:

PredefinedMetadataFormat

public class SpatialMetadataFormat
extends IIOMetadataFormatImpl

Describes the structure of spatial metadata. The default stream and image formats are inferred from a subset of the GeoAPI metadata interfaces, especially Metadata and ImageDescription. Consequently those instances can be considered as profiles of ISO 19115-2, with a few minor departures:

• The Band interface defined by ISO 19115-2 is used only when the values are measurements of wavelengths in the electromagnetic spectrum, as specified in the ISO specification. Otherwise the SampleDimension interface (which is very similar) is used.

The tree structures are show below. As a general rule, the name of elements start with a upper case letter while the name of attributes start with a lower case letter. The valid types of attributes values are listed here. For browsing these trees in an applet together with additional information, see the IIOMetadataPanel applet.

Stream metadata

Image metadata

geotk-coverageio_3.07 ├───DiscoveryMetadata : DataIdentification │ ├───citation │ ├───abstract │ ├───purpose │ ├───credits │ ├───status │ ├───DescriptiveKeywords : Keywords[] │ │ └───DescriptiveKeywordsEntry │ │ ├───keywords │ │ ├───thesaurusName │ │ └───type │ ├───SpatialResolution : Resolution │ │ ├───distance │ │ └───EquivalentScale │ │ └───denominator │ ├───topicCategories │ ├───environmentDescription │ ├───Extent : Extent │ │ ├───description │ │ ├───GeographicElement : GeographicBoundingBox │ │ │ ├───inclusion │ │ │ ├───westBoundLongitude │ │ │ ├───eastBoundLongitude │ │ │ ├───southBoundLatitude │ │ │ └───northBoundLatitude │ │ └───VerticalElement : VerticalExtent │ │ ├───minimumValue │ │ ├───maximumValue │ │ └───verticalCRS │ └───supplementalInformation ├───AcquisitionMetadata : AcquisitionInformation │ ├───EnvironmentalConditions : EnvironmentalRecord │ │ ├───averageAirTemperature │ │ ├───maxRelativeHumidity │ │ ├───maxAltitude │ │ └───meteorologicalConditions │ └───Platform : Platform │ ├───citation │ ├───identifier │ ├───description │ └───Instruments │ └───Instrument : Instrument │ ├───citation │ ├───Identifier : Identifier │ │ ├───code │ │ └───authority │ ├───type │ └───description └───QualityMetadata : DataQuality └───Report : Element ├───namesOfMeasure ├───measureIdentification ├───measureDescription ├───evaluationMethodType ├───evaluationMethodDescription ├───evaluationProcedure └───date

geotk-coverageio_3.07 ├───ImageDescription : ImageDescription │ ├───contentType │ ├───illuminationElevationAngle │ ├───illuminationAzimuthAngle │ ├───imagingCondition │ ├───ImageQualityCode : Identifier │ │ ├───code │ │ └───authority │ ├───cloudCoverPercentage │ ├───ProcessingLevelCode : Identifier │ │ ├───code │ │ └───authority │ ├───compressionGenerationQuantity │ ├───triangulationIndicator │ ├───radiometricCalibrationDataAvailable │ ├───cameraCalibrationInformationAvailable │ ├───filmDistortionInformationAvailable │ ├───lensDistortionInformationAvailable │ ├───Dimensions : SampleDimension[] │ │ └───Dimension │ │ ├───descriptor │ │ ├───sequenceIdentifier │ │ ├───validSampleValues │ │ ├───fillSampleValues │ │ ├───minValue │ │ ├───maxValue │ │ ├───units │ │ ├───peakResponse │ │ ├───bitsPerValue │ │ ├───toneGradation │ │ ├───scaleFactor │ │ ├───offset │ │ ├───bandBoundaryDefinition │ │ ├───nominalSpatialResolution │ │ ├───transferFunctionType │ │ ├───transmittedPolarization │ │ └───detectedPolarization │ └───RangeElementDescriptions : RangeElementDescription │ └───RangeElementDescription │ ├───name │ ├───definition │ └───rangeElements ├───SpatialRepresentation : Georectified │ ├───numberOfDimensions │ ├───cellGeometry │ ├───centerPoint │ └───pointInPixel └───RectifiedGridDomain : RectifiedGrid ├───Limits : GridEnvelope │ ├───low │ └───high ├───origin ├───OffsetVectors │ └───OffsetVector │ └───values └───CoordinateReferenceSystem : CoordinateReferenceSystem ├───name ├───type ├───CoordinateSystem : CoordinateSystem │ ├───name │ ├───type │ ├───dimension │ └───Axes │ └───CoordinateSystemAxis : CoordinateSystemAxis │ ├───name │ ├───direction │ ├───minimumValue │ ├───maximumValue │ ├───rangeMeaning │ └───unit ├───Datum : Datum │ ├───name │ ├───type │ ├───Ellipsoid : Ellipsoid │ │ ├───name │ │ ├───axisAbbrev │ │ ├───axisUnit │ │ ├───semiMajorAxis │ │ ├───semiMinorAxis │ │ └───inverseFlattening │ └───PrimeMeridian : PrimeMeridian │ ├───name │ ├───greenwichLongitude │ └───angularUnit └───Conversion : Conversion ├───name ├───method └───Parameters : ParameterValueGroup └───ParameterValue : ParameterValue ├───name └───value

Since:

3.04 (derived from 2.4)

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

See Also:

SpatialMetadata

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

static String	FORMAT_NAME The metadata format name, which is "geotk-coverageio_3.07".
static SpatialMetadataFormat	IMAGE Deprecated. Replaced by call to getImageInstance(FORMAT_NAME).
static String	ISO_FORMAT_NAME The ISO-19115 format name, which is "ISO-19115".
static SpatialMetadataFormat	STREAM Deprecated. Replaced by call to getStreamInstance(FORMAT_NAME).

Fields inherited from class IIOMetadataFormatImpl

standardMetadataFormatName

Fields inherited from interface IIOMetadataFormat

CHILD_POLICY_ALL, CHILD_POLICY_CHOICE, CHILD_POLICY_EMPTY, CHILD_POLICY_MAX, CHILD_POLICY_REPEAT, CHILD_POLICY_SEQUENCE, CHILD_POLICY_SOME, DATATYPE_BOOLEAN, DATATYPE_DOUBLE, DATATYPE_FLOAT, DATATYPE_INTEGER, DATATYPE_STRING, VALUE_ARBITRARY, VALUE_ENUMERATION, VALUE_LIST, VALUE_NONE, VALUE_RANGE, VALUE_RANGE_MAX_INCLUSIVE, VALUE_RANGE_MAX_INCLUSIVE_MASK, VALUE_RANGE_MIN_INCLUSIVE, VALUE_RANGE_MIN_INCLUSIVE_MASK, VALUE_RANGE_MIN_MAX_INCLUSIVE

Constructor Summary

protected

SpatialMetadataFormat(String rootName) Creates an initially empty format.

Method Summary

protected void	addTree(MetadataStandard standard, Class<?> type, Map<Class<?>,Class<?>> substitution) Deprecated. Replaced by SpatialMetadataFormatBuilder.
protected void	addTree(MetadataStandard standard, Class<?> type, String elementName, String parentName, Map<Class<?>,Class<?>> substitution) Deprecated. Replaced by SpatialMetadataFormatBuilder.
boolean	canNodeAppear(String elementName, ImageTypeSpecifier imageType) Returns true if the element (and the subtree below it) is allowed to appear in a metadata document for an image of the given type.
String	getAttributeDescription(String elementName, String attrName, Locale locale) Returns a description of the named attribute, or null.
<T> T	getDefaultValue(Class<T> type) Returns the default value for an object reference of the given type.
String	getElementDescription(String elementName, Locale locale) Returns a description of the named element, or null.
String	getElementParent(String elementName) Returns the element which is the parent of the named element, or null if none.
String	getElementPath(String elementName) Returns the path to the named element, or null if none.
MetadataStandard	getElementStandard(String elementName) Returns the metadata standard implemented by the element of the given name.
static SpatialMetadataFormat	getImageInstance(String name) Returns the image metadata format for the given name.
static SpatialMetadataFormat	getStreamInstance(String name) Returns the stream metadata format for the given name.
protected void	removeAttribute(String elementName, String attributeName) Removes an attribute from a previously defined element.
protected void	removeElement(String elementName) Removes an element from the format.
String	toString() Returns a string representation of this format.
TreeTableNode	toTreeTable(Locale locale) Returns a tree table representation of this metadata standard.

Methods inherited from class IIOMetadataFormatImpl

addAttribute, addAttribute, addAttribute, addAttribute, addBooleanAttribute, addChildElement, addElement, addElement, addObjectValue, addObjectValue, addObjectValue, addObjectValue, getAttributeDataType, getAttributeDefaultValue, getAttributeEnumerations, getAttributeListMaxLength, getAttributeListMinLength, getAttributeMaxValue, getAttributeMinValue, getAttributeNames, getAttributeValueType, getChildNames, getChildPolicy, getElementMaxChildren, getElementMinChildren, getObjectArrayMaxLength, getObjectArrayMinLength, getObjectClass, getObjectDefaultValue, getObjectEnumerations, getObjectMaxValue, getObjectMinValue, getObjectValueType, getResourceBaseName, getRootName, getStandardFormatInstance, isAttributeRequired, removeObjectValue, setResourceBaseName

Methods inherited from class Object

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

Field Detail

FORMAT_NAME

public static final String FORMAT_NAME

The metadata format name, which is "geotk-coverageio_3.07". The javax.imageio.metadata package description requires that we provide a version number as part of the format name. The version number provided in this constant is set to the last Geotk version when this format has been modified, and may change in any future version.

See Also:

Constant Field Values

ISO_FORMAT_NAME

public static final String ISO_FORMAT_NAME

The ISO-19115 format name, which is "ISO-19115". This metadata format is big and supported only by a few plugins like NetcdfImageReader. For applications that don't need to full verbosity of ISO 19115, consider using the stream metadata instance identified by the FORMAT_NAME name instead.

Since:

3.20

See Also:

Constant Field Values

STREAM

@Deprecated
public static final SpatialMetadataFormat STREAM

Deprecated. Replaced by call to getStreamInstance(FORMAT_NAME).

The default instance for stream metadata format. This is the metadata format that apply to file as a whole, which may contain more than one image. The tree structure is documented in the class javadoc.

Since:

3.05

IMAGE

@Deprecated
public static final SpatialMetadataFormat IMAGE

Deprecated. Replaced by call to getImageInstance(FORMAT_NAME).

The default instance for image metadata format. This is the metadata format that apply to a particular image in a file. The tree structure is documented in the class javadoc.

Since:

3.05

Constructor Detail

SpatialMetadataFormat

protected SpatialMetadataFormat(String rootName)

Creates an initially empty format. Subclasses shall invoke the various addFoo(...) methods defined in this class or parent class for adding new elements and attributes.

Parameters:

rootName - the name of the root element.

Method Detail

getStreamInstance

public static SpatialMetadataFormat getStreamInstance(String name)

Returns the stream metadata format for the given name. This is the metadata format that apply to a file as a whole, which may contain more than one image. The tree structure is documented in the class javadoc.

Parameters:

name - The FORMAT_NAME or ISO_FORMAT_NAME constant, or null for the default format (currently "geotk-coverageio_3.07").

Returns:

The stream metadata format for the given name.

Throws:

IllegalArgumentException - If the given name is not one of the supported constants.

Since:

3.20

getImageInstance

public static SpatialMetadataFormat getImageInstance(String name)

Returns the image metadata format for the given name. This is the metadata format that apply to a particular image in a file. The tree structure is documented in the class javadoc.

Parameters:

name - The FORMAT_NAME constant, or null for the default format (currently "geotk-coverageio_3.07").

Returns:

The image metadata format for the given name.

Throws:

IllegalArgumentException - If the given name is not one of the supported constants.

Since:

3.20

addTree

@Deprecated
protected void addTree(MetadataStandard standard,
                                  Class<?> type,
                                  Map<Class<?>,Class<?>> substitution)

Deprecated. Replaced by SpatialMetadataFormatBuilder.

Adds a new element or attribute of the given type as a child of the root. This method performs the same work than addTree(MetadataStandard, Class, String, String, Map), except that the element is added at the root and the name is inferred from the given type for convenience.

Parameters:

standard - The metadata standard of the element or attribute to be added.

type - The type of the element or attribute to be added.

substitution - The map of children types to substitute by other types, or null.

addTree

@Deprecated
protected void addTree(MetadataStandard standard,
                                  Class<?> type,
                                  String elementName,
                                  String parentName,
                                  Map<Class<?>,Class<?>> substitution)

Deprecated. Replaced by SpatialMetadataFormatBuilder.

Adds a new element or attribute of the given type and name as a child of the given node. If the given type is a metadata, then that child is added as an element and all its children are added recursively. Otherwise the type is added as an attribute.

Element type
This method expects a type argument, which can be a CodeList subclass, one of the interfaces member of the given metadata standard, or a simple JSE type (boolean, number of String). Do not specify collection types, since the type of collection elements can not be inferred easily. To specify a multi-occurrence, use the array type instead (e.g. CoordinateSystemAxis[].class).

Substitution map
This method can be given an optional substitution map. If this map is non null, then every occurrence of a class in the set of keys is replaced by the associated class in the collection of values. The purpose of this map is to:

• Replace a base class by some specialized subclass. Since IIOMetadata is about grided data (not generic Features), the exact subtype is often known at compile time, and we want the additional attributes to be declared unconditionally. Example:

  substitution.put(RangeDimension.class, Band.class);

• Exclude a particular class by setting the replacement to null. This is used for excluding large tree of metadata which may not be applicable. Example:

  substitution.put(Objective.class, null);

• Replace an element class (including the whole tree behind it) by a single attribute. This simplification is especially useful for Citation because they typically appear in many different places with the same name ("citation"), while Image I/O does not allow many elements to have the same name (actually this is not strictly forbidden, but the getter methods return information only about the first occurrence of a given name). Converting an element to an attribute allow it to appear with the same name under different nodes, and can make the tree considerably simpler (at the cost of losing all the sub-tree below the converted element). Example:

  substitution.put(Citation.class, String.class);

• Replace a collection by a singleton, by setting the source type to an array and the target type to the element of that array. This is useful when a collection seems an overkill for the specific case of stream or image metadata. Example:

  substitution.put(Identification[].class, Identification.class);

The substitution map applies only to children (if any), not to the type given directly to this method.

Parameters:

standard - The metadata standard of the element or attribute to be added.

type - The type of the element or attribute to be added (see javadoc).

elementName - The name of the element or attribute node to be added.

parentName - The name of the parent node to where to add the child.

substitution - The map of children types to substitute by other types (see javadoc), or null if none.

removeAttribute

protected void removeAttribute(String elementName,
                               String attributeName)

Removes an attribute from a previously defined element. If no attribute with the given name was present in the given element, nothing happens and no exception is thrown.

Overrides:

removeAttribute in class IIOMetadataFormatImpl

Parameters:

elementName - The name of the element.

attributeName - The name of the attribute being removed.

removeElement

protected void removeElement(String elementName)

Removes an element from the format. If no element with the given name was present, nothing happens and no exception is thrown.

Overrides:

removeElement in class IIOMetadataFormatImpl

Parameters:

elementName - the name of the element to be removed.

canNodeAppear

public boolean canNodeAppear(String elementName,
                             ImageTypeSpecifier imageType)

Returns true if the element (and the subtree below it) is allowed to appear in a metadata document for an image of the given type. The default implementation always returns true.

Specified by:

canNodeAppear in interface IIOMetadataFormat

Specified by:

canNodeAppear in class IIOMetadataFormatImpl

getElementParent

public String getElementParent(String elementName)

Returns the element which is the parent of the named element, or null if none. For example if this metadata format is the stream instance, then:

• The path to "GeographicElement" is "DiscoveryMetadata/Extent/GeographicElement".
• The parent of "GeographicElement" returned by this method is "Extent".

Note: An element may have more than one parent, since the same element can be copied under many nodes using addChildElement(...). In such case, this method returns only the first path. Such cases do not occur with the Geotk formats identified by FORMAT_NAME in this class, but occur with the more complex ISO-19115 format.

Parameters:

elementName - The element for which the parent is desired.

Returns:

The parent of the given element, or null.

Since:

3.06

See Also:

getElementPath(String)

getElementPath

public String getElementPath(String elementName)

Returns the path to the named element, or null if none. For example if this metadata format is the stream instance, then the path to the "GeographicElement" is "DiscoveryMetadata/Extent/GeographicElement".

Note: An element may have more than one path, since the same element can be copied under many nodes using addChildElement(...). In such case, this method returns only the first path. Such cases do not occur with the Geotk formats identified by FORMAT_NAME in this class, but occur with the more complex ISO-19115 format.

Parameters:

elementName - The element for which the path is desired.

Returns:

The path to the given element, or null.

Since:

3.06

See Also:

getElementParent(String)

getElementStandard

public MetadataStandard getElementStandard(String elementName)

Returns the metadata standard implemented by the element of the given name. If the given element does not implement a standard (which may happen if the element has not been added by SpatialMetadataFormatBuilder method), then this method returns null.

Parameters:

elementName - The element for which the standard is desired.

Returns:

The standard implemented by the given element, or null.

Since:

3.06

getElementDescription

public String getElementDescription(String elementName,
                                    Locale locale)

Returns a description of the named element, or null. The description will be localized for the supplied locale if possible.

The default implementation first queries the description map associated with the metadata standard. If no description is found, then the super-class implementation is used.

Specified by:

getElementDescription in interface IIOMetadataFormat

Overrides:

getElementDescription in class IIOMetadataFormatImpl

Parameters:

elementName - The name of the element.

locale - The Locale for which localization will be attempted, or null.

Returns:

The attribute description.

Since:

3.05

getAttributeDescription

public String getAttributeDescription(String elementName,
                                      String attrName,
                                      Locale locale)

Returns a description of the named attribute, or null. The description will be localized for the supplied locale if possible.

The default implementation first queries the description map associated with the metadata standard. If no description is found, then the super-class implementation is used.

Specified by:

getAttributeDescription in interface IIOMetadataFormat

Overrides:

getAttributeDescription in class IIOMetadataFormatImpl

Parameters:

elementName - The name of the element.

attrName - The name of the attribute.

locale - The Locale for which localization will be attempted, or null.

Returns:

The attribute description.

Since:

3.05

getDefaultValue

public <T> T getDefaultValue(Class<T> type)

Returns the default value for an object reference of the given type. This method is invoked automatically by SpatialMetadataFormatBuilder for determining the value of the defaultValue argument in the call to the addObjectValue method.

This method is also invoked by ReferencingBuilder.getDefault(Class), which does not rely on IIOMetadataFormat.getObjectDefaultValue(String) because the default value of some referencing objects depends on the type of the enclosing element. For example the default coordinate system shall be ellipsoidal for a geographic CRS and Cartesian for a projected CRS.

The default implementation returns a value determined from the table below. Subclasses can override this method for providing different default values.

Type	Default value
PrimeMeridian	DefaultPrimeMeridian.GREENWICH
Ellipsoid	DefaultEllipsoid.WGS84
GeodeticDatum	DefaultGeodeticDatum.WGS84
VerticalDatum	DefaultVerticalDatum.GEOIDAL
EngineeringDatum	DefaultEngineeringDatum.UNKNOWN
EllipsoidalCS	DefaultEllipsoidalCS.GEODETIC_2D
CartesianCS	DefaultCartesianCS.GENERIC_2D
GeographicCRS	DefaultGeographicCRS.WGS84
GeocentricCRS	DefaultGeocentricCRS.CARTESIAN
All other type	null

Type Parameters:

T - The compile-time type of classType.

Parameters:

type - The class type of the object for which to get a default value.

Returns:

The default value for an object of the given type, or null if none.

Since:

3.08

See Also:

ReferencingBuilder.getDefault(Class), IIOMetadataFormatImpl.getObjectDefaultValue(String)

toTreeTable

public TreeTableNode toTreeTable(Locale locale)

Returns a tree table representation of this metadata standard. This convenience method delegates the work to MetadataTreeTable.

Parameters:

locale - The locale for which localization will be attempted, or null.

Returns:

A tree representation of this metadata standard.

toString

public String toString()

Returns a string representation of this format. The default implementation formats this object as a tree.

Overrides:

toString in class Object