Module org.opengis.geoapi

Package org.opengis.coordinate

Interface CoordinateSet

All Superinterfaces:

Iterable<DirectPosition>

@UML(identifier="CoordinateSet",
     specification=ISO_19111)
public interface CoordinateSet
extends Iterable<DirectPosition>

A collection of coordinate tuples referenced to the same coordinate reference system (CRS). If the CRS is dynamic, the CoordinateSet metadata contains also a coordinate epoch. Operations on the geometry of the tuples within the coordinate set are valid only if all tuples are referenced to the same coordinate epoch.

Coordinate operations

Coordinate sets referenced to one CRS may be referenced to another CRS through the application of a coordinate operation. If the CRS is dynamic, the CoordinateSet may be converted to another coordinate epoch through a point motion coordinate operation that includes time evolution.

Since:

3.1

See Also:

• CoordinateOperation.transform(CoordinateSet)

Method Summary

Modifier and Type	Method	Description
default Optional<Stream<DoubleBuffer>>	asDoubleBuffers()	If the coordinates are packed in sequences of double-precision floating point values, returns views over those sequences.
default Optional<Stream<FloatBuffer>>	asFloatBuffers()	If the coordinates are packed in sequences of single-precision floating point values, returns views over those sequences.
CoordinateMetadata	getCoordinateMetadata()	Coordinate metadata to which this coordinate set is referenced.
default int	getDimension()	Returns the number of dimensions of coordinate tuples.
Iterator<DirectPosition>	iterator()	Returns an iterator over the positions described by coordinate tuples.
default Stream<DirectPosition>	stream()	Returns a sequential stream of coordinate tuples.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Details

getCoordinateMetadata

@UML(identifier="coordinateMetadata",
     obligation=MANDATORY,
     specification=ISO_19111)
CoordinateMetadata getCoordinateMetadata()

Coordinate metadata to which this coordinate set is referenced. Coordinate metadata includes a coordinate reference system (CRS) and, if the CRS is dynamic, a coordinate epoch.

Returns:

coordinate metadata to which this coordinate set is referenced.

getDimension

default int getDimension()

Returns the number of dimensions of coordinate tuples. This is determined by the coordinate reference system.

Returns:

the number of dimensions of coordinate tuples.

Convenience extension to OGC/ISO standard

This shortcut has been added because this is a frequently used information.

iterator

@UML(identifier="coordinateTuple",
     obligation=MANDATORY,
     specification=ISO_19111)
Iterator<DirectPosition> iterator()

Returns an iterator over the positions described by coordinate tuples. The positions shall be in a well-defined encounter order. For each element, the following constraints shall be met:

• DirectPosition.getDimension() is equal to getDimension().
• DirectPosition.getCoordinateReferenceSystem() is null or equal to CoordinateMetadata.getCoordinateReferenceSystem().

Invoking this method is equivalent to invoking stream().iterator().

Specified by:

iterator in interface Iterable<DirectPosition>

Returns:

a new iterator over the positions described by coordinate tuples.

stream

default Stream<DirectPosition> stream()

Returns a sequential stream of coordinate tuples. The positions shall be in a well-defined encounter order (i.e., positions are ordered).

Default implementation

If asDoubleBuffers() or asFloatBuffers() (in that preference order) returns a non-empty value, then the default method returns a stream of views over the buffers content. Otherwise, the default method returns a stream backed by iterator().

Returns:

a sequential stream of coordinate tuples.

Departure from OGC/ISO standard for closer integration with the Java environment

Added for allowing developers to process coordinate tuples efficiently in Java environments. The use of Java streams makes parallel processing easier.

asDoubleBuffers

default Optional<Stream<DoubleBuffer>> asDoubleBuffers()

If the coordinates are packed in sequences of double-precision floating point values, returns views over those sequences. For example, if the number of dimensions is 3, then the coordinates can be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).

The coordinates may be packed in a single buffer, or may be partitioned in many buffers. For each buffer, the number of coordinate tuples is Buffer.remaining() / getDimension(). Each buffer may have a different number of coordinate tuples. It shall be safe to modify the position, limit or mark of buffer instances (see example below). Each DoubleBuffer instance should be a view over an underlying coordinate array, those arrays should not be copied.

Examples

For an implementation with all coordinates packed in a single array of double primitive values:

private final double[] coordinates = ...;

public Optional<Stream<DoubleBuffer>> asDoubleBuffers() {
    return Optional.of(Stream.of(DoubleBuffer.wrap(coordinates)));
}

For an implementation with all coordinates partitioned in an array of DoubleBuffer wrappers. Note the call to DoubleBuffer.duplicate() for protecting the internal buffers from changes:

private final DoubleBuffer[] buffers = ...;

public Optional<Stream<DoubleBuffer>> asDoubleBuffers() {
    return Optional.of(Arrays.stream(buffers).map(DoubleBuffer::duplicate));
}

API notes

The use of DoubleBuffer makes possible to handle coordinate values not only from a Java array, but also from a sub-array, from a region of a file or from the memory of a native application.

Empty Optional and empty Stream are not synonymous. An empty optional means that this CoordinateSet is not backed by sequences of double-precision values, or that those values are not packed in the way described above, or are not accessible for any reason. An empty stream means that the coordinates are accessible by this method, but there is none (i.e., this CoordinateSet is empty).

At most one of asDoubleBuffers() and asFloatBuffers() should return a non-empty value, because a CoordinateSet may be backed by single- or double-precision floating point values, but usually not both in same time.

Returns:

a view over the sequences of coordinates as double-precision floating point values.

See Also:

• stream()
• MathTransform.transform(DoubleBuffer, DoubleBuffer)
• MathTransform.transform(DoubleBuffer, FloatBuffer)

Departure from OGC/ISO standard for closer integration with the Java environment

Added for allowing developers to access coordinate tuples efficiently in Java environments, including the case where the coordinate values are in the memory of a native application.

asFloatBuffers

default Optional<Stream<FloatBuffer>> asFloatBuffers()

If the coordinates are packed in sequences of single-precision floating point values, returns views over those sequences. This method contract is the same as asDoubleBuffers(), with only the float type instead of double.

At most one of asFloatBuffers() and asDoubleBuffers() should return a non-empty value, because a CoordinateSet may be backed by single- or double-precision floating point values, but usually not both in same time.

Returns:

a view over the sequences of coordinates as single-precision floating point values.

See Also:

• stream()
• MathTransform.transform(FloatBuffer, FloatBuffer)
• MathTransform.transform(FloatBuffer, DoubleBuffer)

Departure from OGC/ISO standard for closer integration with the Java environment

Added for allowing developers to access coordinate tuples efficiently in Java environments, including the case where the coordinate values are in the memory of a native application.