# Class Shapes2D

Object
Shapes2D

public final class Shapes2D extends Object
Utility methods working on Java2D shapes. The `transform(…)` methods in this class work in the same way as the methods of the same signature in `Envelopes`, except that they work on `Rectangle2D` objects instead of `Envelope`. In particular, the same treatment for curvatures and poles is applied.

Since:
  0.8

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Ellipse2D`
  `circle(Point2D P1, Point2D P2, Point2D P3)`
  Returns a circle passing by the 3 given points.
  `static Point2D`
  `colinearPoint(Line2D line, Point2D point, double distance)`
  Returns a point on the given `line` segment located at the given `distance` from that line.
  `static void`
  `intersect(RectangularShape shape, Envelope envelope, int xdim, int ydim)`
  Sets the given shape to the intersection of that shape with the given envelope.
  `static Point2D`
  `intersectionPoint(Line2D a, Line2D b)`
  Returns the intersection point between two line segments.
  `static Point2D`
  `nearestColinearPoint(Line2D segment, Point2D point)`
  Returns the point on the given `line` segment which is closest to the given `point`.
  `static Rectangle2D`
  `transform(CoordinateOperation operation, Rectangle2D envelope, Rectangle2D destination)`
  Transforms a rectangular envelope using the given coordinate operation.
  `static Rectangle2D`
  `transform(MathTransform2D transform, Rectangle2D envelope, Rectangle2D destination)`
  Transforms a rectangular envelope using the given math transform.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### intersectionPoint

    public static Point2D intersectionPoint(Line2D a, Line2D b)
    Returns the intersection point between two line segments. The lines do not continue to infinity; if the intersection does not occur between the ending points P1 and P2 of the two line segments, then this method returns `null`.
    Parameters:
      `a` - the first line segment.
      `b` - the second line segment.
    Returns:
      the intersection point, or `null` if none.

  - ### nearestColinearPoint

    public static Point2D nearestColinearPoint(Line2D segment, Point2D point)
    Returns the point on the given `line` segment which is closest to the given `point`. Let `result` be the returned point. This method guarantees (except for rounding errors) that:
    - `result` is a point on the `line` segment. It is located between the P1 and P2 ending points of that line segment.
    - The distance between the `result` point and the given `point` is the shortest distance among the set of points meeting the previous condition. This distance can be obtained with `point​.distance(result)`.
    Parameters:
      `segment` - the line on which to search for a point.
      `point` - a point close to the given line.
    Returns:
      the nearest point on the given line.
    See Also:
      - `colinearPoint(Line2D, Point2D, double)`

  - ### colinearPoint

    public static Point2D colinearPoint(Line2D line, Point2D point, double distance)
    Returns a point on the given `line` segment located at the given `distance` from that line. Let `result` be the returned point. If `result` is not null, then this method guarantees (except for rounding error) that:
    - `result` is a point on the `line` segment. It is located between the P1 and P2 ending points of that line segment.
    - The distance between the `result` and the given `point` is exactly equal to `distance`.
    If no result point meets those conditions, then this method returns `null`. If two result points met those conditions, then this method returns the point which is the closest to `line​.getP1()`.
    Parameters:
      `line` - the line on which to search for a point.
      `point` - a point close to the given line.
      `distance` - the distance between the given point and the point to be returned.
    Returns:
      a point on the given line located at the given distance from the given point.
    See Also:
      - `nearestColinearPoint(Line2D, Point2D)`

  - ### circle

    public static Ellipse2D circle(Point2D P1, Point2D P2, Point2D P3)
    Returns a circle passing by the 3 given points.
    Parameters:
      `P1` - the first point.
      `P2` - the second point.
      `P3` - the third point.
    Returns:
      a circle passing by the given points.

  - ### intersect

    public static void intersect(RectangularShape shape, Envelope envelope, int xdim, int ydim)
    Sets the given shape to the intersection of that shape with the given envelope.
    Parameters:
      `shape` - the shape to intersect. Will be modified in-place.
      `envelope` - the envelope to intersect with the given shape.
      `xdim` - dimension of x coordinates in the envelope. This is usually 0.
      `ydim` - dimension of y coordinates in the envelope. This is usually 1.
    Since:
      1.3

  - ### transform

    public static Rectangle2D transform(MathTransform2D transform, Rectangle2D envelope, Rectangle2D destination) throws TransformException
    Transforms a rectangular envelope using the given math transform. The transformation is only approximated: the returned envelope may be bigger than necessary, or smaller than required if the bounding box contains a pole.

    Note that this method cannot handle the case where the rectangle contains the North or South pole, or when it cross the ±180° longitude, because `MathTransform` does not carry sufficient information. For a more robust rectangle transformation, use `transform(CoordinateOperation, Rectangle2D, Rectangle2D)` instead.

    Parameters:
      `transform` - the transform to use. Source and target dimension must be 2.
      `envelope` - the rectangle to transform (may be `null`).
      `destination` - the destination rectangle (may be `envelope`). If `null`, a new rectangle will be created and returned.
    Returns:
      `destination`, or a new rectangle if `destination` was null and `envelope` was non-null.
    Throws:
      `TransformException` - if a transform failed.
    See Also:
      - `transform(CoordinateOperation, Rectangle2D, Rectangle2D)`
      - `Envelopes​.transform(MathTransform, Envelope)`

  - ### transform

    public static Rectangle2D transform(CoordinateOperation operation, Rectangle2D envelope, Rectangle2D destination) throws TransformException
    Transforms a rectangular envelope using the given coordinate operation. The transformation is only approximated: the returned envelope may be bigger than the smallest possible bounding box, but should not be smaller in most cases.

    This method can handle the case where the rectangle contains the North or South pole, or when it cross the ±180° longitude.

    Parameters:
      `operation` - the operation to use. Source and target dimension must be 2.
      `envelope` - the rectangle to transform (may be `null`).
      `destination` - the destination rectangle (may be `envelope`). If `null`, a new rectangle will be created and returned.
    Returns:
      `destination`, or a new rectangle if `destination` was null and `envelope` was non-null.
    Throws:
      `TransformException` - if a transform failed.
    See Also:
      - `transform(MathTransform2D, Rectangle2D, Rectangle2D)`
      - `Envelopes​.transform(CoordinateOperation, Envelope)`