org.apache.sis.geometry

Class GeneralDirectPosition

Object

AbstractDirectPosition

GeneralDirectPosition

All Implemented Interfaces:

Serializable, Cloneable, Position, DirectPosition

public class GeneralDirectPosition
extends AbstractDirectPosition
implements Serializable, Cloneable

A mutable Direct­Position (the coordinates of a position) of arbitrary dimension. This particular implementation of Direct­Position is said "General" because it uses an array of ordinates of an arbitrary length. If the direct position is known to be always two-dimensional, then Direct­Position2D provides a more efficient implementation.

Coordinate Reference System (CRS) optionality

Since Direct­Positions, as data types, will often be included in larger objects (such as Geometry) that have references to Coordinate­Reference­System, the get­Coordinate­Reference­System() method may returns null if this particular Direct­Position is included in such larger object. In this case, the coordinate reference system is implicitly assumed to take on the value of the containing object's Coordinate­Reference­System.

Since:

0.3

See Also:

Direct­Position1D, Direct­Position2D, Coordinate­Format, Serialized Form

Defined in the sis-referencing module

Field Summary

Fields

Modifier and Type	Field and Description
double[]	ordinates The ordinates of the direct position.

Constructor Summary

Constructors

Constructor and Description
GeneralDirectPosition(CharSequence wkt) Constructs a position initialized to the values parsed from the given string in Well Known Text (WKT) format.
GeneralDirectPosition(CoordinateReferenceSystem crs) Constructs a position using the specified coordinate reference system.
GeneralDirectPosition(DirectPosition point) Constructs a position initialized to the same values than the specified point.
GeneralDirectPosition(double... ordinates) Constructs a position with the specified ordinates.
GeneralDirectPosition(int dimension) Constructs a position with the specified number of dimensions.

Method Summary

Modifier and Type	Method and Description
GeneralDirectPosition	clone() Returns a deep copy of this position.
double[]	getCoordinate() Returns a sequence of numbers that hold the coordinate of this position in its reference system.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the coordinate reference system in which the coordinate is given.
int	getDimension() The length of ordinate sequence (the number of entries).
double	getOrdinate(int dimension) Returns the ordinate at the specified dimension.
int	hashCode() Returns a hash value for this coordinate.
void	setCoordinate(double... ordinates) Sets the ordinate values along all dimensions.
void	setCoordinateReferenceSystem(CoordinateReferenceSystem crs) Sets the coordinate reference system in which the coordinate is given.
void	setLocation(DirectPosition position) Sets this coordinate to the specified direct position.
void	setOrdinate(int dimension, double value) Sets the ordinate value along the specified dimension.
String	toString() Formats this position in the Well Known Text (WKT) format.

Methods inherited from class AbstractDirectPosition

equals, get­Direct­Position, normalize

Methods inherited from class Object

finalize, get­Class, notify, notify­All, wait, wait, wait

Field Detail

ordinates

public final double[] ordinates

The ordinates of the direct position. The length of this array is the dimension of this direct position.

Constructor Detail

GeneralDirectPosition

public GeneralDirectPosition(CoordinateReferenceSystem crs)

Constructs a position using the specified coordinate reference system. The number of dimensions is inferred from the coordinate reference system.

Parameters:

crs - the coordinate reference system to be given to this position.

GeneralDirectPosition

public GeneralDirectPosition(int dimension)
                      throws NegativeArraySizeException

Constructs a position with the specified number of dimensions.

Parameters:

dimension - number of dimensions.

Throws:

Negative­Array­Size­Exception - if dimension is negative.

GeneralDirectPosition

public GeneralDirectPosition(double... ordinates)

Constructs a position with the specified ordinates. This constructor assigns the given array directly (without clone) to the ordinates field. Consequently, callers shall not recycle the same array for creating many instances.

Implementation note: the array is not cloned because this is usually not needed, especially in the context of variable argument lengths since the array is often created implicitly. Furthermore the ordinates field is public, so cloning the array would not protect the state of this object anyway.

Caution: if only one number is specified, make sure that the number type is double, float or long otherwise the General­Direct­Position(int) constructor would be invoked with a very different meaning. For example for creating a one-dimensional coordinate initialized to the ordinate value 100, use new General­Direct­Position(100.0), not new General­Direct­Position(100), because the later would actually create a position with 100 dimensions.

Parameters:

ordinates - the ordinate values. This array is not cloned.

GeneralDirectPosition

public GeneralDirectPosition(DirectPosition point)

Constructs a position initialized to the same values than the specified point. This is a copy constructor.

Parameters:

point - the position to copy.

GeneralDirectPosition

public GeneralDirectPosition(CharSequence wkt)
                      throws IllegalArgumentException

Constructs a position initialized to the values parsed from the given string in Well Known Text (WKT) format. The given string is typically a POINT element like below:

POINT(6 10)

However this constructor is lenient to other types like POINT ZM.

Parameters:

wkt - the POINT or other kind of element to parse.

Throws:

Illegal­Argument­Exception - if the given string can not be parsed.

See Also:

to­String(), Coordinate­Format

Method Detail

getDimension

public final int getDimension()

The length of ordinate sequence (the number of entries). This is always equals to the length of the ordinates array.

Specified by:

get­Dimension in interface Direct­Position

Returns:

the dimensionality of this position.

getCoordinateReferenceSystem

public final CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the coordinate reference system in which the coordinate is given. May be null if this particular Direct­Position is included in a larger object with such a reference to a CRS.

Specified by:

get­Coordinate­Reference­System in interface Direct­Position

Returns:

the coordinate reference system, or null.

setCoordinateReferenceSystem

public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)
                                  throws MismatchedDimensionException

Sets the coordinate reference system in which the coordinate is given.

Parameters:

crs - the new coordinate reference system, or null.

Throws:

Mismatched­Dimension­Exception - if the specified CRS does not have the expected number of dimensions.

getCoordinate

public final double[] getCoordinate()

Returns a sequence of numbers that hold the coordinate of this position in its reference system.

API note: This method is final for ensuring consistency with the ordinates, array field, which is public.

Specified by:

get­Coordinate in interface Direct­Position

Overrides:

get­Coordinate in class Abstract­Direct­Position

Returns:

a copy of the ordinates array.

setCoordinate

public void setCoordinate(double... ordinates)
                   throws MismatchedDimensionException

Sets the ordinate values along all dimensions.

Parameters:

ordinates - the new ordinates values, or a null array for setting all ordinate values to Na­N.

Throws:

Mismatched­Dimension­Exception - if the length of the specified array is not equals to the dimension of this position.

getOrdinate

public final double getOrdinate(int dimension)
                         throws IndexOutOfBoundsException

Returns the ordinate at the specified dimension.

API note: This method is final for ensuring consistency with the ordinates, array field, which is public.

Specified by:

get­Ordinate in interface Direct­Position

Parameters:

dimension - the dimension in the range 0 to dimension-1.

Returns:

the ordinate at the specified dimension.

Throws:

Index­Out­Of­Bounds­Exception - if the specified dimension is out of bounds.

setOrdinate

public void setOrdinate(int dimension,
                        double value)
                 throws IndexOutOfBoundsException

Sets the ordinate value along the specified dimension.

Specified by:

set­Ordinate in interface Direct­Position

Parameters:

dimension - the dimension for the ordinate of interest.

value - the ordinate value of interest.

Throws:

Index­Out­Of­Bounds­Exception - if the specified dimension is out of bounds.

setLocation

public void setLocation(DirectPosition position)
                 throws MismatchedDimensionException

Sets this coordinate to the specified direct position. If the specified position contains a coordinate reference system (CRS), then the CRS for this position will be set to the CRS of the specified position.

Overrides:

set­Location in class Abstract­Direct­Position

Parameters:

position - the new position for this point, or null for setting all ordinate values to Na­N.

Throws:

Mismatched­Dimension­Exception - if the given position does not have the expected dimension.

toString

public String toString()

Formats this position in the Well Known Text (WKT) format. The returned string is like below, where x₀, x₁, x₂, etc. are the ordinate values at index 0, 1, 2, etc.:

POINT(x₀ x₁ x₂ …)

The string returned by this method can be parsed by the General­Direct­Position constructor.

Overrides:

to­String in class Abstract­Direct­Position

Returns:

This position as a POINT in Well Known Text (WKT) format.

clone

public GeneralDirectPosition clone()

Returns a deep copy of this position.

Overrides:

clone in class Object

Returns:

a copy of this direct position.

hashCode

public int hashCode()

Returns a hash value for this coordinate. This method returns a value compliant with the contract documented in the Direct­Position.hash­Code() javadoc. Consequently, it should be possible to mix different Direct­Position implementations in the same hash map.

Specified by:

hash­Code in interface Direct­Position

Overrides:

hash­Code in class Abstract­Direct­Position

Returns:

a hash code value for this position.