org.opengis.spatialschema.geometry.geometry
Interface PointArray

public interface PointArray

A sequence of points. The PointArray interface outlines a means of efficiently storing large numbers of 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.

Version:

2.0

Author:

ISO/DIS 19107, OpenGIS® consortium

See Also:

Position, PointGrid

UML identifier (data type): GM_PointArray

Method Summary

DirectPosition	get(int column) Returns the point at the given index.
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() Returns the dimensionality of the coordinates in this array.
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 many non-trivial (I'm tempted to said "real world") applications, since many implementations will be backed by a float[] array rather than a highly inefficient DirectPosition array, so invoking toArray() may have a high cost if thousands of DirectPosition objects most be created immediately. So I suggest to just remove this method.

Method Detail

length

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

int getDimension()

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

CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the Coordinate Reference System of this array.

Returns:

the Coordinate Reference System for this array.

See Also:

DirectPosition.getCoordinateReferenceSystem()

get

DirectPosition get(int column)
                   throws IndexOutOfBoundsException

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

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

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

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

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 many non-trivial (I'm tempted to said "real world") applications, since many implementations will be backed by a float[] array rather than a highly inefficient DirectPosition array, so invoking toArray() may have a high cost if thousands of DirectPosition objects most be created immediately. So I suggest to just remove this method.

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

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.

UML identifier (mandatory attribute): column