Package org.geotools.geometry.jts

Class JTS

Object
JTS
public final class JTS extends Object
JTS Geometry utility methods, bringing Geotools to JTS.

Offers geotools based services such as reprojection.

Responsibilities:

  • transformation
  • coordinate sequence editing
  • common coordinate sequence implementations for specific uses
Since:
2.2
Author:
Jody Garnett, Martin Desruisseaux, Simone Giannecchini, GeoSolutions., Michael Bedward

  • Field Details

  • Method Details

    • transform

      public static Envelope transform(Envelope envelope, MathTransform transform) throws TransformException
      Transforms the envelope using the specified math transform. Note that this method can not handle the case where the envelope contains the North or South pole, or when it cross the ±180� longitude, because math transforms do not carry suffisient informations. For a more robust envelope transformation, use ReferencedEnvelope.transform(CoordinateReferenceSystem, boolean) instead.
      Parameters:
      envelope - The envelope to transform.
      transform - The transform to use.
      Returns:
      The transformed Envelope
      Throws:
      TransformException - if at least one coordinate can't be transformed.

    • transform

      public static Envelope transform(Envelope sourceEnvelope, Envelope targetEnvelope, MathTransform transform, int npoints) throws TransformException
      Transforms the densified envelope using the specified math transform. The envelope is densified (extra points put around the outside edge) to provide a better new envelope for high deformed situations.

      If an optional target envelope is provided, this envelope will be expanded with the transformation result. It will not be nullified before the expansion.

      Note that this method can not handle the case where the envelope contains the North or South pole, or when it cross the ±180� longitude, because math transforms do not carry suffisient informations. For a more robust envelope transformation, use ReferencedEnvelope.transform(CoordinateReferenceSystem, boolean, int) instead.

      Parameters:
      sourceEnvelope - The envelope to transform.
      targetEnvelope - An envelope to expand with the transformation result, or null for returning an new envelope.
      transform - The transform to use.
      npoints - Densification of each side of the rectangle.
      Returns:
      targetEnvelope if it was non-null, or a new envelope otherwise. In all case, the returned envelope fully contains the transformed envelope.
      Throws:
      TransformException - if a coordinate can't be transformed.

    • transformTo3D

      public static ReferencedEnvelope3D transformTo3D(ReferencedEnvelope sourceEnvelope, CoordinateReferenceSystem targetCRS, boolean lenient, int npoints) throws TransformException, OperationNotFoundException, FactoryException
      Transform from D up to 3D.

      This method transforms each ordinate into WGS84, manually converts this to WGS84_3D with the addition of a Double.NaN, and then transforms to the final 3D position.

      Returns:
      ReferencedEnvelope3D in targetCRS describing the sourceEnvelope bounds
      Throws:
      FactoryException - If operationis unavailable from source CRS to WGS84, to from WGS84_3D to targetCRS
      TransformException
      OperationNotFoundException

    • transformTo2D

      public static ReferencedEnvelope transformTo2D(ReferencedEnvelope sourceEnvelope, CoordinateReferenceSystem targetCRS, boolean lenient, int npoints) throws TransformException, OperationNotFoundException, FactoryException
      Transform from 3D down to 2D.

      This method transforms each ordinate into WGS84, manually converts this to WGS84_3D with the addition of a Double.NaN, and then transforms to the final 2D position.

      Returns:
      ReferencedEnvelope matching provided 2D TargetCRS
      Throws:
      TransformException
      OperationNotFoundException
      FactoryException

    • transform

      public static Geometry transform(Geometry geom, MathTransform transform) throws MismatchedDimensionException, TransformException
      Transforms the geometry using the default transformer.
      Parameters:
      geom - The geom to transform
      transform - the transform to use during the transformation.
      Returns:
      the transformed geometry. It will be a new geometry.
      Throws:
      MismatchedDimensionException - if the geometry doesn't have the expected dimension for the specified transform.
      TransformException - if a point can't be transformed.

    • transform

      public static Coordinate transform(Coordinate source, Coordinate dest, MathTransform transform) throws TransformException
      Transforms the coordinate using the provided math transform.
      Parameters:
      source - the source coordinate that will be transformed
      dest - the coordinate that will be set. May be null or the source coordinate (or new coordinate of course).
      Returns:
      the destination coordinate if not null or a new Coordinate.
      Throws:
      TransformException - if the coordinate can't be transformed.

    • toGeographic

      public static Envelope toGeographic(Envelope envelope, CoordinateReferenceSystem crs) throws TransformException
      Transforms the envelope from its current crs to DefaultGeographicCRS.WGS84. If the specified envelope is already in WGS84, then it is returned unchanged.

      The method CRS.equalsIgnoreMetadata(Object, Object) is used to compare the numeric values and axis order (so CRS.decode("CRS.84") or CRS.decode("4326",true) provide an appropriate match).

      Parameters:
      envelope - The envelope to transform.
      crs - The CRS the envelope is currently in.
      Returns:
      The envelope transformed to be in DefaultGeographicCRS.WGS84.
      Throws:
      TransformException - If at least one coordinate can't be transformed.

    • toGeographic

      public static ReferencedEnvelope toGeographic(ReferencedEnvelope envelope) throws TransformException
      Transforms the envelope to DefaultGeographicCRS.WGS84.

      This method will transform to DefaultGeographicCRS.WGS84_3D if necessary (and then drop the height axis).

      This method is identical to calling: envelope.transform(DefaultGeographicCRS.WGS84,true)

      Parameters:
      envelope - The envelope to transform
      Returns:
      The envelope transformed to be in WGS84 CRS
      Throws:
      TransformException

    • xform

      public static void xform(MathTransform transform, double[] src, double[] dest) throws TransformException
      Like a transform but eXtreme!

      Transforms an array of coordinates using the provided math transform. Each coordinate is transformed separately. In case of a transform exception then the new value of the coordinate is the last coordinate correctly transformed.

      Parameters:
      transform - The math transform to apply.
      src - The source coordinates.
      dest - The destination array for transformed coordinates.
      Throws:
      TransformException - if this method failed to transform any of the points.

    • orthodromicDistance

      public static double orthodromicDistance(Coordinate p1, Coordinate p2, CoordinateReferenceSystem crs) throws TransformException
      Computes the orthodromic distance between two points. This method:

      1. Transforms both points to geographic coordinates (latitude,longitude).
      2. Computes the orthodromic distance between the two points using ellipsoidal calculations.

      The real work is performed by GeodeticCalculator. This convenience method simply manages a pool of pre-defined geodetic calculators for the given coordinate reference system in order to avoid repetitive object creation. If a large amount of orthodromic distances need to be computed, direct use of GeodeticCalculator provides better performance than this convenience method.

      Parameters:
      p1 - First point
      p2 - Second point
      crs - Reference system the two points are in.
      Returns:
      Orthodromic distance between the two points, in meters.
      Throws:
      TransformException - if the coordinates can't be transformed from the specified CRS to a geographic CRS.

    • toDirectPosition

      public static Position toDirectPosition(Coordinate point, CoordinateReferenceSystem crs)
      Creates a DirectPosition from the provided point.
      Returns:
      DirectPosition

    • copy

      public static void copy(Coordinate point, double[] ordinates)
      Copies the ordinates values from the specified JTS coordinates to the specified array. The destination array can have any length. Only the relevant field of the source coordinate will be copied. If the array length is greater than 3, then all extra dimensions will be set to NaN.
      Parameters:
      point - The source coordinate.
      ordinates - The destination array.

    • toGeometry

      public static Geometry toGeometry(Shape shape)
      Converts an arbitrary Java2D shape into a JTS geometry. The created JTS geometry may be any of LineString, LinearRing or MultiLineString.
      Parameters:
      shape - the input shape
      Returns:
      A new JTS geometry instance
      Throws:
      IllegalArgumentException - if shape is null

    • toGeometry

      public static Geometry toGeometry(Shape shape, GeometryFactory factory)
      Converts an arbitrary Java2D shape into a JTS geometry. The created JTS geometry may be any of LineString, LinearRing or MultiLineString.
      Parameters:
      shape - the input shape
      factory - the JTS factory to use to create the geometry
      Returns:
      A new JTS geometry instance
      Throws:
      IllegalArgumentException - if either shape or factory is null

    • toGeometry

      public static Point toGeometry(Position position)
      Create a Point from a ISO Geometry DirectPosition.
      Returns:
      Point

    • toGeometry

      public static Point toGeometry(Position position, GeometryFactory factory)
      Create a Point from a ISO Geometry DirectPosition.
      Parameters:
      factory - Optional GeometryFactory
      Returns:
      Point

    • toGeometry

      public static Polygon toGeometry(Envelope envelope)
      Converts an envelope to a JTS polygon.

      The resulting polygon contains an outer ring with vertices: (x1,y1),(x2,y1),(x2,y2),(x1,y2),(x1,y1)

      Parameters:
      envelope - The original envelope.
      Returns:
      The envelope as a polygon.
      Throws:
      IllegalArgumentException - if env is null
      Since:
      2.4

    • toGeometry

      public static Polygon toGeometry(Envelope envelope, GeometryFactory factory)
      Converts an envelope to a JTS polygon using the given JTS geometry factory.

      The resulting polygon contains an outer ring with vertices: (x1,y1),(x2,y1),(x2,y2),(x1,y2),(x1,y1)

      Parameters:
      envelope - The original envelope.
      Returns:
      The envelope as a polygon.
      Throws:
      IllegalArgumentException - if either env or factory is null
      Since:
      2.8

    • toEnvelope

      public static ReferencedEnvelope toEnvelope(Geometry geom)
      Create a ReferencedEnvelope from the provided geometry, we will do our best to guess the CoordinateReferenceSystem making use of getUserData() and getSRID() as needed.
      Parameters:
      geom - Provided Geometry
      Returns:
      ReferencedEnvelope describing the bounds of the provided Geometry

    • toGeometry

      public static Polygon toGeometry(ReferencedEnvelope bbox)
      Converts a ReferencedEnvelope to a JTS polygon.

      The resulting polygon contains an outer ring with vertices: (x1,y1),(x2,y1),(x2,y2),(x1,y2),(x1,y1)

      Parameters:
      bbox - The original envelope.
      Returns:
      The envelope as a polygon.
      Throws:
      IllegalArgumentException - if bbox is null
      Since:
      2.4

    • toGeometry

      public static Polygon toGeometry(BoundingBox bbox, GeometryFactory factory, int npoints)
      Convert the provided bbox to a polygon, sampling a set number of points along each side.
      Parameters:
      bbox - bounding box being converted to a Polygon
      factory - geometry factory used to create the polygon
      npoints - number of points to sample along each edge
      Returns:
      Polygon

    • toGeographic

      public static Geometry toGeographic(Geometry geom, CoordinateReferenceSystem crs) throws TransformException
      Transforms the geometry from its current crs to DefaultGeographicCRS.WGS84. If the specified geometry is already in WGS84, then it is returned unchanged.

      The method CRS.equalsIgnoreMetadata(Object, Object) is used to compare the numeric values and axis order (so CRS.decode("CRS.84") or CRS.decode("4326",true) provide an appropriate match).

      Parameters:
      geom - The geometry to transform.
      crs - The CRS the geometry is currently in.
      Returns:
      The geometry transformed to be in DefaultGeographicCRS.WGS84.
      Throws:
      TransformException - If at least one coordinate can't be transformed.

    • toGeometry

      public static Polygon toGeometry(BoundingBox bbox)
      Converts a BoundingBox to a JTS polygon.

      The resulting polygon contains an outer ring with vertices: (x1,y1),(x2,y1),(x2,y2),(x1,y2),(x1,y1)

      Parameters:
      bbox - The original envelope.
      Returns:
      The envelope as a polygon.
      Throws:
      IllegalArgumentException - if bbox is null
      Since:
      2.4

    • toGeometry

      public static Polygon toGeometry(BoundingBox bbox, GeometryFactory factory)
      Converts a BoundingBox to a JTS polygon using the given JTS geometry factory.

      The resulting polygon contains an outer ring with vertices: (x1,y1),(x2,y1),(x2,y2),(x1,y2),(x1,y1)

      Parameters:
      bbox - The original envelope.
      Returns:
      The envelope as a polygon.
      Throws:
      IllegalArgumentException - if either bbox or factory is null
      Since:
      2.8

    • checkCoordinatesRange

      public static void checkCoordinatesRange(Geometry geom, CoordinateReferenceSystem crs) throws PointOutsideEnvelopeException
      Checks a Geometry coordinates are within the area of validity of the specified reference system. If a coordinate falls outside the area of validity a PointOutsideEnvelopeException is thrown
      Parameters:
      geom - the geometry to check
      crs - the crs that defines the are of validity (must not be null)
      Throws:
      PointOutsideEnvelopeException
      Since:
      2.4

    • smooth

      public static Geometry smooth(Geometry geom, double fit)
      Creates a smoothed copy of the input Geometry. This is only useful for polygonal and lineal geometries. Point objects will be returned unchanged. The smoothing algorithm inserts new vertices which are positioned using Bezier splines. All vertices of the input Geometry will be present in the output Geometry.

      The fit parameter controls how tightly the smoothed lines conform to the input line segments, with a value of 1 being tightest and 0 being loosest. Values outside this range will be adjusted up or down as required.

      The input Geometry can be a simple type (e.g. LineString, Polygon), a multi-type (e.g. MultiLineString, MultiPolygon) or a GeometryCollection. The returned object will be of the same type.

      Parameters:
      geom - the input geometry
      fit - tightness of fit from 0 (loose) to 1 (tight)
      Returns:
      a new Geometry object of the same class as geom
      Throws:
      IllegalArgumentException - if geom is null

    • smooth

      public static Geometry smooth(Geometry geom, double fit, GeometryFactory factory)
      Creates a smoothed copy of the input Geometry. This is only useful for polygonal and lineal geometries. Point objects will be returned unchanged. The smoothing algorithm inserts new vertices which are positioned using Bezier splines. All vertices of the input Geometry will be present in the output Geometry.

      The fit parameter controls how tightly the smoothed lines conform to the input line segments, with a value of 1 being tightest and 0 being loosest. Values outside this range will be adjusted up or down as required.

      The input Geometry can be a simple type (e.g. LineString, Polygon), a multi-type (e.g. MultiLineString, MultiPolygon) or a GeometryCollection. The returned object will be of the same type.

      Parameters:
      geom - the input geometry
      fit - tightness of fit from 0 (loose) to 1 (tight)
      factory - the GeometryFactory to use for creating smoothed objects
      Returns:
      a new Geometry object of the same class as geom
      Throws:
      IllegalArgumentException - if either geom or factory is null

    • createCS

      public static CoordinateSequence createCS(CoordinateSequenceFactory csFactory, int size, int dimension)
      Creates a CoordinateSequence using the provided factory confirming the provided size and dimension are respected.

      If the requested dimension is larger than the CoordinateSequence implementation can provide, then a sequence of maximum possible dimension should be created. An error should not be thrown.

      This method is functionally identical to calling csFactory.create(size,dim) - it contains additional logic to work around a limitation on the commonly used CoordinateArraySequenceFactory.

      Parameters:
      size - the number of coordinates in the sequence
      dimension - the dimension of the coordinates in the sequence

    • createCS

      public static CoordinateSequence createCS(CoordinateSequenceFactory csFactory, int size, int dimension, int measures)
      Creates a CoordinateSequence using the provided factory confirming the provided size and dimension are respected.

      If the requested dimension is larger than the CoordinateSequence implementation can provide, then a sequence of maximum possible dimension should be created. An error should not be thrown.

      This method is functionally identical to calling csFactory.create(size,dim) - it contains additional logic to work around a limitation on the commonly used CoordinateArraySequenceFactory.

      Parameters:
      size - the number of coordinates in the sequence
      dimension - the dimension of the coordinates in the sequence
      measures - the measures of the coordinates in the sequence

    • bounds

      public static ReferencedEnvelope bounds(Geometry geometry, CoordinateReferenceSystem crs)
      Replacement for geometry.getEnvelopeInternal() that returns ReferencedEnvelope or ReferencedEnvelope3D as appropriate for the provided CRS.
      Returns:
      ReferencedEnvelope (or ReferencedEnvelope3D) as appropriate

    • removeCollinearVertices

      public static Geometry removeCollinearVertices(Geometry g)
      Removes collinear vertices from the provided Geometry.

      For the moment this implementation only accepts, Polygon, LineString and MultiPolygon It will throw an exception if the geometry is not one of those types

      Parameters:
      g - the instance of a Geometry to remove collinear vertices from.
      Returns:
      a new instance of the provided Geometry without collinear vertices.

    • removeCollinearVertices

      public static Geometry removeCollinearVertices(Geometry geometry, int minPoints)
      Removes collinear vertices from the provided Geometry if the number of point exceeds the requested minPoints.

      For the moment this implementation only accepts, Polygon, LineString and MultiPolygon It will throw an exception if the geometry is not one of those types

      Parameters:
      geometry - the instance of a Geometry to remove collinear vertices from.
      minPoints - perform removal of collinear points if num of vertices exceeds minPoints.
      Returns:
      a new instance of the provided Geometry without collinear vertices.

    • makeValid

      public static List<Polygon> makeValid(Polygon polygon, boolean removeHoles)
      Given a potentially invalid polygon it rebuilds it as a list of valid polygons, eventually removing the holes

    • toRectangle2D

      public static Rectangle2D toRectangle2D(Envelope envelope)
      Converts a JTS Envelope into an equivalent Rectangle2D
      Parameters:
      envelope - The source envelope

    • toEnvelope

      public static Envelope toEnvelope(Rectangle2D rectangle)
      Converts a AWT Rectangle2D into a JTS Envelope
      Parameters:
      rectangle - The source rectangle

    • toPolygon

      public static Polygon toPolygon(Polygon polygon)
      Converts a AWT polygon into a JTS one (unlike toGeometry(java.awt.Shape) which always returns lines instead)

    • toPolygon

      public static Polygon toPolygon(Rectangle rectangle)
      Converts a AWT rectangle into a JTS one (unlike toGeometry(java.awt.Shape) which always returns lines instead)

    • toPolygon

      public static Polygon toPolygon(Rectangle2D rectangle)
      Converts a AWT rectangle into a JTS one (unlike toGeometry(java.awt.Shape) which always returns lines instead)

    • equals

      public static boolean equals(Envelope e1, Envelope e2, double tolerance)
      Envelope equality with target tolerance.
      Parameters:
      e1 - The first envelope
      e2 - The second envelope
      tolerance - The tolerance
      Returns:
      True if the envelopes have the same boundaries, minus the given tolerance

    • equals

      public static boolean equals(BoundingBox a, BoundingBox b, double tolerance)
      BoundingBox equality with target tolerance. This method compares also coordinate reference systems.
      Parameters:
      a - The first envelope
      b - The second envelope
      tolerance - The tolerance
      Returns:
      True if the envelopes have the same boundaries, minus the given tolerance, and the CRSs are equal according to CRS#equalsIgnoreMetadata

    • getCRS

      public static CoordinateReferenceSystem getCRS(Geometry geometry)
      Get the CRS of a geometry, stored in Geometry.getUserData() (as a CoordinateReferenceSystem directly, or as a Map<Class,Value>) or as a non-zero Geometry.getSRID().
      Parameters:
      geometry - the geometry
      Returns:
      the CRS, or null if not available

    • setCRS

      public static void setCRS(Geometry geometry, CoordinateReferenceSystem crs)
      Set the CRS of a geometry is Geometry.getUserData().

      Stored in Geometry.getUserData() as a CoordinateReferenceSystem directly, or as a Map<Object,Object> using CoordinateReferenceSystem.class as a key.

      If user data is being used to store another kind of value geometry will not be changed.

      Stored in Geometry.getSRID() as EPSG code.

      Parameters:
      geometry - the geometry
      crs - the CRS, or null to clear CRS from geometry