geometry.java

GEo 地理操作源代码

     * "distance" value shall be a positive number associated to a distance unit such as meter
     * or standard foot. If necessary, the second geometric object shall be transformed into
     * the same coordinate reference system as the first before the distance is calculated.
     * <br><br>
     * If the geometric objects overlap, or touch, then their distance apart shall be zero.
     * Some current implementations use a "negative" distance for such cases, but the approach
     * is neither consistent between implementations, nor theoretically viable.
     * <br><br>
     * <strong>NOTE:</strong> The role of the reference system in distance calculations is
     * important. Generally, there are at least three types of distances that may be defined
     * between points (and therefore between geometric objects): map distance, geodesic distance,
     * and terrain distance.
     * <ul>
     *   <li>Map distance is the distance between the points as defined by their positions in a
     *       coordinate projection (such as on a map when scale is taken into account). Map distance
     *       is usually accurate for small areas where scale functions have well-behaved derivatives.</li>
     *   <li>Geodesic distance is the length of the shortest curve between those two points along the
     *       surface of the earth model being used by the coordinate reference system. Geodesic
     *       distance behaves well for wide areas of coverage, and takes the earth's curvature
     *       into account. It is especially handy for air and sea navigation, although care should
     *       be taken to distinguish between rhumb line (curves of constant bearing) and geodesic
     *       curve distance.</li>
     *   <li>Terrain distance takes into account the local vertical displacements (hypsography).
     *       Terrain distance can be based either on a geodesic distance or a map distance.</li>
     * </ul>
     *
     * @param  geometry The other object.
     * @return The distance between the two objects.
     * @unitof Distance
     * @UML operation distance
     *
     * @see #getBoundary
     * @see #getBuffer
     * @see org.opengis.referencing.cs.CoordinateSystem#getAxis
     */
    public double getDistance(Geometry geometry);

    /**
     * Returns the inherent dimension of this <code>Geometry</code>, which shall be less than or
     * equal to the {@linkplain #getCoordinateDimension coordinate dimension}. The dimension of
     * a collection of geometric objects shall be the largest dimension of any of its pieces.
     * Points are 0-dimensional, curves are 1-dimensional, surfaces are 2-dimensional, and solids
     * are 3-dimensional. Locally, the dimension of a geometric object at a point is the dimension
     * of a local neighborhood of the point - that is the dimension of any coordinate neighborhood
     * of the point. Dimension is unambiguously defined only for {@linkplain DirectPosition direct
     * positions} interior to this <code>Geometry</code>. If the passed {@linkplain DirectPosition
     * direct position} is <code>null</code>, then the operation shall return the largest possible
     * dimension for any {@linkplain DirectPosition direct position} in this <code>Geometry</code>.
     *
     * @param point The point where to evaluate the dimension, or <code>null</code>.
     * @return The inherent dimension.
     * @UML operation dimension
     *
     * @see #getCoordinateDimension
     */
    public int getDimension(DirectPosition point);

    /**
     * Returns the dimension of the coordinates that define this <code>Geometry</code>, which must
     * be the same as the coordinate dimension of the coordinate reference system for this
     * <code>Geometry</code>.
     *
     * @return The coordinate dimension.
     * @UML operation coordinateDimension
     *
     * @see #getDimension
     * @see #getCoordinateReferenceSystem
     */
    public int getCoordinateDimension();

    /**
     * Returns the set of maximal complexes within which this <code>Geometry</code> is contained.
     * As a set of primitives, a {@linkplain Complex complex} may be contained as a set in another
     * larger {@linkplain Complex complex}, referred to as a "super complex" of the original.
     * A {@linkplain Complex complex} is maximal if there is no such larger super complex.
     *
     * @return The set of maximal complexes within which this <code>Geometry</code> is contained.
     * @UML operation maximalComplex
     */
    public Set getMaximalComplex();

    /**
     * Returns a new <code>Geometry</code> that is the coordinate transformation of this
     * <code>Geometry</code> into the passed coordinate reference system within the accuracy
     * of the transformation.
     *
     * @param  newCRS The new coordinate reference system.
     * @return The transformed <code>Geometry</code>.
     * @throws TransformException if the transformation failed.
     * @UML operation transform
     */
    public Geometry transform(CoordinateReferenceSystem newCRS) throws TransformException;

    /**
     * Returns a new <code>Geometry</code> that is the coordinate transformation of this
     * <code>Geometry</code> into the passed coordinate reference system, using the
     * specified transform. It is the user responsability to ensure that the supplied
     * transform is appropriate for this geometry.
     *
     * @param  newCRS The new coordinate reference system.
     * @param  transform The transform from the existing coordinate reference system
     *         to the new coordinate reference system.
     * @throws TransformException if the transformation failed.
     * @return The transformed <code>Geometry</code>.
     */
    public Geometry transform(CoordinateReferenceSystem newCRS, MathTransform transform) throws TransformException;

    /**
     * Returns the minimum bounding box for this <code>Geometry</code>. This shall be the
     * coordinate region spanning the minimum and maximum value for each ordinate taken on by
     * {@linkplain DirectPosition direct positions} in this <code>Geometry</code>. The simplest
     * representation for an envelope consists of two {@linkplain DirectPosition direct positions},
     * the first one containing all the minimums for each ordinate, and second one containing all
     * the maximums. However, there are cases for which these two positions would be outside the
     * domain of validity of the object's coordinate reference system.
     *
     * @return The envelope.
     * @UML operation envelope
     *
     * @see #getMbRegion
     */
    public Envelope getEnvelope();

    /**
     * Returns the mathematical centroid for this <code>Geometry</code>. The result is not guaranteed
     * to be on the object. For heterogeneous collections of primitives, the centroid only takes
     * into account those of the largest dimension. For example, when calculating the centroid of
     * surfaces, an average is taken weighted by area. Since curves have no area they do not
     * contribute to the average.
     *
     * @return The centroid.
     * @UML operation centroid
     *
     * @see #getRepresentativePoint
     */
    public DirectPosition getCentroid();

    /**
     * Returns a <code>Geometry</code> that represents the convex hull of this <code>Geometry</code>.
     * Convexity requires the use of "lines" or "curves of shortest length" and the use of different
     * coordinate systems may result in different versions of the convex hull of an object. Each
     * implementation shall decide on an appropriate solution to this ambiguity. For two reasonable
     * coordinate systems, a convex hull of an object in one will be very closely approximated by
     * the transformed image of the convex hull of the same object in the other.
     *
     * @return The convex hull.
     * @UML operation convexHull
     */
    public Geometry getConvexHull();

    /**
     * Returns a <code>Geometry</code> containing all points whose distance from this
     * <code>Geometry</code> is less than or equal to the distance passed as a parameter.
     * The <code>Geometry</code> returned is in the same reference system as this original
     * <code>Geometry</code>. The dimension of the returned <code>Geometry</code> is normally
     * the same as the coordinate dimension - a collection of
     * {@linkplain org.opengis.spatialschema.geometry.primitive.Surface surfaces} in 2D space and a collection of
     * {@linkplain org.opengis.spatialschema.geometry.primitive.Solid solids} in 3D space, but this may be application
     * defined.
     *
     * @param distance The distance.
     * @return A geometry containing all points whose distance from this <code>Geometry</code>
     *         is less than or equal to the specified distance.
     * @unitof Distance (for the argument)
     * @UML operation buffer
     *
     * @see #getBoundary
     * @see #getDistance
     * @see org.opengis.referencing.cs.CoordinateSystem#getAxis
     */
    public Geometry getBuffer(double distance);
}