org.opengis.spatialschema.geometry.geometry
Interface PointArray

@UML(identifier="GM_PointArray",
     specification=ISO_19107)
public interface PointArray

A sequence of points. The PointArray interface outlines a means of efficiently storing large numbers of usually homogeneous positions; i.e. all having the same coordinate reference system. While a point array conceptually contains positions, it provides convenience methods for fetching directly the direct positions instead.

A simple implementation of PointArray will generally be no more efficient than a simple array of Positions. More efficient implementations will generally stores coordinates in a more compact form (e.g. in a single float[] array) and creates Position objects on the fly when needed.

If a particular PointArray implementation supports efficiently random access through any get or set method, it shall announce this capability by implementing the RandomAccess interface. Otherwise, users should read the positions through the positions().iterator() instead.

Since:

GeoAPI 1.0

Version:

Abstract specification 5

See Also:

Position, PointGrid

Method Summary

DirectPosition	get(int column) Deprecated. This method may conflict with an implementation of List interface. It also raise a performance and behavior issue: should the direct position be backed by this PointArray, so changes to the position will be reflected in the PointArray and vice-versa? The proposed alternative, get(int, DirectPosition), avoid those questions.
DirectPosition	get(int column, DirectPosition dest) Gets a copy of the DirectPosition at the particular location in this PointArray.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the Coordinate Reference System of this array.
int	getDimension() Deprecated. This method definition conflict with section 6.2.2.10 in ISO 19107: "The operation coordinateDimension shall return the dimension of the coordinates that define this GM_Object, which must be the same as the coordinate dimension of the coordinate reference system for this GM_Object.".
int	length() Returns the length (the number of elements) of this array.
List<Position>	positions() Returns a view of the points in this array as a list of positions.
void	set(int column, DirectPosition position) Set the point at the given index.
DirectPosition[]	toArray() Deprecated. This method raise a number of implementation issues: what should be the behavior if a single point in this array is modified? Should it be reflected in the PointArray? Furthermore, this method will be inefficient in some implementations, for example an implementations backed by a float[] array. Invoking toArray() in such case may create thousands of DirectPosition objects. positions() is safer, since it expose the positions through an iterator.

Method Detail

length

@Extension
int length()

Returns the length (the number of elements) of this array. This is equivalent to positions().size().

Returns:

The array length.

See Also:

List.size(), PointGrid.width()

getDimension

@Extension
@Deprecated
int getDimension()

Deprecated. This method definition conflict with section 6.2.2.10 in ISO 19107: "The operation coordinateDimension shall return the dimension of the coordinates that define this GM_Object, which must be the same as the coordinate dimension of the coordinate reference system for this GM_Object.".

Returns the dimensionality of the coordinates in this array. This may be less than or equal to the dimensionality of the coordinate reference system for these coordinates.

Returns:

the dimensionality of this array.

See Also:

DirectPosition.getDimension()

getCoordinateReferenceSystem

@Extension
CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the Coordinate Reference System of this array.

Returns:

the Coordinate Reference System for this array.

See Also:

DirectPosition.getCoordinateReferenceSystem()

get

@Extension
@Deprecated
DirectPosition get(int column)
                   throws IndexOutOfBoundsException

Deprecated. This method may conflict with an implementation of List interface. It also raise a performance and behavior issue: should the direct position be backed by this PointArray, so changes to the position will be reflected in the PointArray and vice-versa? The proposed alternative, get(int, DirectPosition), avoid those questions.

Returns the point at the given index. This is equivalent to positions().get(column).getPosition().

Parameters:

column - The location in the array, from 0 inclusive to the array's length() exclusive.

Returns:

The point at the given location in this array.

Throws:

IndexOutOfBoundsException - if the index is out of bounds.

See Also:

List.get(int), get(int, DirectPosition)

get

@Extension
DirectPosition get(int column,
                             DirectPosition dest)
                   throws IndexOutOfBoundsException

Gets a copy of the DirectPosition at the particular location in this PointArray. If the dest argument is non-null, that object will be populated with the value from the array. In all cases, the position in insulated from changes in the PointArray, and vice-versa. Consequently, the same DirectPosition object can be reused for fetching many points from this array. Example:

  DirectPosition position = null;
  for (int i=0; i<array.length(); i++) {
      position = array.get(i, position);
      // Do some processing...
  }
 

Parameters:

column - The location in the array, from 0 inclusive to the array's length() exclusive.

dest - An optionnaly pre-allocated direct position.

Returns:

The dest argument, or a new object if dest was null.

Throws:

IndexOutOfBoundsException - if the index is out of bounds.

See Also:

get(int)

set

@Extension
void set(int column,
                   DirectPosition position)
         throws IndexOutOfBoundsException,
                UnsupportedOperationException

Set the point at the given index. The point coordinates will be copied, i.e. changes to the given position after this method call will not be reflected into this point array. Consequently, the same DirectPosition object can be reused for setting many points in this array.

Parameters:

column - The location in the array, from 0 inclusive to the array's length() exclusive.

position - The point to set at the given location in this array.

Throws:

IndexOutOfBoundsException - if the index is out of bounds.

UnsupportedOperationException - if this array is immutable.

See Also:

List.set(int, E)

toArray

@Extension
@Deprecated
DirectPosition[] toArray()

Deprecated. This method raise a number of implementation issues: what should be the behavior if a single point in this array is modified? Should it be reflected in the PointArray? Furthermore, this method will be inefficient in some implementations, for example an implementations backed by a float[] array. Invoking toArray() in such case may create thousands of DirectPosition objects. positions() is safer, since it expose the positions through an iterator.

Returns the elements of this PointArray as an array of DirectPositions.

Returns:

The elements as an array of direct positions.

See Also:

List.toArray()

positions

@UML(identifier="column",
     obligation=MANDATORY,
     specification=ISO_19107)
List<Position> positions()

Returns a view of the points in this array as a list of positions. The list is backed by this PointArray, so changes to the point array are reflected in the list, and vice-versa.

Returns:

The list of positions in this array.