Interface PointArray

  • All Superinterfaces:
    Collection<Position>, Iterable<Position>, List<Position>

    @UML(identifier="GM_PointArray",
         specification=ISO_19107)
    public interface PointArray
    extends List<Position>
    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 may store 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 iterator() instead.

    Since:
    GeoAPI 1.0
    See Also:
    Position, PointGrid
    • Method Detail

      • getDimension

        int getDimension()
        Returns the dimensionality of the coordinates in this array. It shall be equal to the dimensionality of the coordinate reference system for these coordinates.

        This method is the same as:

         return getCoordinateReferenceSystem().getCoordinateSystem().getDimension();
         
        Returns:
        the dimensionality of this array.
        See Also:
        DirectPosition.getDimension()
      • getCoordinateReferenceSystem

        CoordinateReferenceSystem getCoordinateReferenceSystem()
        Returns the Coordinate Reference System in which the coordinates are given. May be null if this particular PointArray is included in a larger object with such a reference to a coordinate reference system}. In this case, the cordinate reference system is implicitly assumed to take on the value of the containing object's coordinate reference system.
        Returns:
        the coordinate reference system, or null.
        See Also:
        DirectPosition.getCoordinateReferenceSystem()
      • getDirectPosition

        DirectPosition getDirectPosition​(int index,
                                         DirectPosition dest)
                                  throws IndexOutOfBoundsException
        Gets a copy of the direct position 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;
         final int length = array.length();
         for (int i=0; i<length; i++) {
             position = array.getDirectPosition(i, position);
             // Do some processing...
         }
         
        Parameters:
        index - The location in the array, from 0 inclusive to the array 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.
      • setDirectPosition

        void setDirectPosition​(int index,
                               DirectPosition position)
                        throws IndexOutOfBoundsException,
                               UnsupportedOperationException
        Sets 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:
        index - The location in the array, from 0 inclusive to the array 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)
      • positions

        @Deprecated
        @UML(identifier="column",
             obligation=MANDATORY,
             specification=ISO_19107)
        List<Position> positions()
        Deprecated.
        use this
        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.

        Note that random access may be costly in some implementations. If the returned list doesn't implement the RandomAccess interface, then consider avoiding the List.get(int) method. Favor the list iterator instead.

        Returns:
        the list of positions in this array.