001: /*
002: * The JTS Topology Suite is a collection of Java classes that
003: * implement the fundamental operations required to validate a given
004: * geo-spatial data set to a known topological specification.
005: *
006: * Copyright (C) 2001 Vivid Solutions
007: *
008: * This library is free software; you can redistribute it and/or
009: * modify it under the terms of the GNU Lesser General Public
010: * License as published by the Free Software Foundation; either
011: * version 2.1 of the License, or (at your option) any later version.
012: *
013: * This library is distributed in the hope that it will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
016: * Lesser General Public License for more details.
017: *
018: * You should have received a copy of the GNU Lesser General Public
019: * License along with this library; if not, write to the Free Software
020: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
021: *
022: * For more information, contact:
023: *
024: * Vivid Solutions
025: * Suite #1A
026: * 2328 Government Street
027: * Victoria BC V8T 5G5
028: * Canada
029: *
030: * (250)385-6040
031: * www.vividsolutions.com
032: */
033: package com.vividsolutions.jts.geom;
034:
035: /**
036: * The internal representation of a list of coordinates inside a Geometry.
037: * <p>
038: * There are some cases in which you might want Geometries to store their
039: * points using something other than the JTS Coordinate class. For example, you
040: * may want to experiment with another implementation, such as an array of x's
041: * and an array of y's. Or you might want to use your own coordinate class, one
042: * that supports extra attributes like M-values.
043: * <p>
044: * You can do this by implementing the CoordinateSequence and
045: * CoordinateSequenceFactory interfaces. You would then create a
046: * GeometryFactory parameterized by your CoordinateSequenceFactory, and use
047: * this GeometryFactory to create new Geometries. All of these new Geometries
048: * will use your CoordinateSequence implementation.
049: * <p>
050: * For an example, see the code for
051: * {@link com.vividsolutions.jtsexample.geom.TwoArrayCoordinateSequenceExample}.
052: *
053: * @see DefaultCoordinateSequenceFactory
054: * @see TwoArrayCoordinateSequenceFactory
055: *
056: * @version 1.7
057: */
058: public interface CoordinateSequence extends Cloneable {
059: /**
060: * Standard ordinate index values
061: */
062: int X = 0;
063: int Y = 1;
064: int Z = 2;
065: int M = 3;
066:
067: /**
068: * Returns the dimension (number of ordinates in each coordinate)
069: * for this sequence.
070: *
071: * @return the dimension of the sequence.
072: */
073: int getDimension();
074:
075: /**
076: * Returns (possibly a copy of) the i'th coordinate in this sequence.
077: * Whether or not the Coordinate returned is the actual underlying
078: * Coordinate or merely a copy depends on the implementation.
079: * <p>
080: * Note that in the future the semantics of this method may change
081: * to guarantee that the Coordinate returned is always a copy.
082: * Callers should not to assume that they can modify a CoordinateSequence by
083: * modifying the object returned by this method.
084: *
085: * @param i the index of the coordinate to retrieve
086: * @return the i'th coordinate in the sequence
087: */
088: Coordinate getCoordinate(int i);
089:
090: /**
091: * Returns a copy of the i'th coordinate in this sequence.
092: * This method optimizes the situation where the caller is
093: * going to make a copy anyway - if the implementation
094: * has already created a new Coordinate object, no further copy is needed.
095: *
096: * @param i the index of the coordinate to retrieve
097: * @return a copy of the i'th coordinate in the sequence
098: */
099: Coordinate getCoordinateCopy(int i);
100:
101: /**
102: * Copies the i'th coordinate in the sequence to the supplied
103: * {@link Coordinate}. Only the first two dimensions are copied.
104: *
105: * @param index the index of the coordinate to copy
106: * @param coord a {@link Coordinate} to receive the value
107: */
108: void getCoordinate(int index, Coordinate coord);
109:
110: /**
111: * Returns ordinate X (0) of the specified coordinate.
112: *
113: * @param index
114: * @return the value of the X ordinate in the index'th coordinate
115: */
116: double getX(int index);
117:
118: /**
119: * Returns ordinate Y (1) of the specified coordinate.
120: *
121: * @param index
122: * @return the value of the Y ordinate in the index'th coordinate
123: */
124: double getY(int index);
125:
126: /**
127: * Returns the ordinate of a coordinate in this sequence.
128: * Ordinate indices 0 and 1 are assumed to be X and Y.
129: * Ordinates indices greater than 1 have user-defined semantics
130: * (for instance, they may contain other dimensions or measure values).
131: *
132: * @param index the coordinate index in the sequence
133: * @param ordinateIndex the ordinate index in the coordinate (in range [0, dimension-1])
134: */
135: double getOrdinate(int index, int ordinateIndex);
136:
137: /**
138: * Returns the number of coordinates in this sequence.
139: * @return the size of the sequence
140: */
141: int size();
142:
143: /**
144: * Sets the value for a given ordinate of a coordinate in this sequence.
145: *
146: * @param index the coordinate index in the sequence
147: * @param ordinateIndex the ordinate index in the coordinate (in range [0, dimension-1])
148: * @param value the new ordinate value
149: */
150: void setOrdinate(int index, int ordinateIndex, double value);
151:
152: /**
153: * Returns (possibly copies of) the Coordinates in this collection.
154: * Whether or not the Coordinates returned are the actual underlying
155: * Coordinates or merely copies depends on the implementation. Note that
156: * if this implementation does not store its data as an array of Coordinates,
157: * this method will incur a performance penalty because the array needs to
158: * be built from scratch.
159: *
160: * @return a array of coordinates containing the point values in this sequence
161: */
162: Coordinate[] toCoordinateArray();
163:
164: /**
165: * Expands the given {@link Envelope} to include the coordinates in the sequence.
166: * Allows implementing classes to optimize access to coordinate values.
167: *
168: * @param env the envelope to expand
169: * @return a ref to the expanded envelope
170: */
171: Envelope expandEnvelope(Envelope env);
172:
173: /**
174: * Returns a deep copy of this collection.
175: * Called by Geometry#clone.
176: *
177: * @return a copy of the coordinate sequence containing copies of all points
178: */
179: Object clone();
180: }
|