org.gicentre.utils.stat

## Class StandardEllipse

- java.lang.Object
- - org.gicentre.utils.stat.StandardEllipse

-     public class StandardEllipse
      extends java.lang.Object

  Class to create and store a standard ellipse representing the spread of a set of points. The long axis of the ellipse can represent twice the standard deviation of the spread of points in the direction of maximum point dispersion. The short axis represents twice the standard deviation of the spread of points in the direction of least dispersion. Points can be weighted by setting the z value of the `PVector`s used to store point coordinates. The ellipse parameters can be retrieved with the relevant accessor (getter) methods, or the class can draw the ellipse directly with the `draw()` method. For convenience, the scale of the ellipse can be controlled with `setScale()` and the coordinates of the endpoints of the axes can also be retrieved. Weighted or unweighted points can be used by selecting `setIsWeighted()`.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jo Wood, giCentre, City University London.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `StandardEllipse(java.util.Collection<processing.core.PVector> points)` Creates a standard ellipse from the given set of 2D Cartesian point values.
    `StandardEllipse(java.util.Collection<processing.core.PVector> points, boolean isLatLong)` Creates a standard ellipse from the given set of 2D Cartesian or latitude/longitude point values.
    `StandardEllipse(processing.core.PVector centre, float major, float minor, float rotation)` Creates an ellipse with the given location, dimensions and rotation.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `draw(processing.core.PApplet sketch)` Draws the ellipse.
    `void` | `drawAxes(processing.core.PApplet sketch)` Draws the axes of the ellipse.
    `processing.core.PVector` | `getCentre()` Reports the centre of the ellipse.
    `float` | `getMajorAxis()` Reports the length of the major axis of the ellipse.
    `processing.core.PVector` | `getMajorEndpoint1()` Reports the coordinates of one of the end points of the major axis.
    `processing.core.PVector` | `getMajorEndpoint2()` Reports the coordinates of one of the end points of the major axis.
    `float` | `getMinorAxis()` Reports the length of the minor axis of the ellipse.
    `processing.core.PVector` | `getMinorEndpoint1()` Reports the coordinates of one of the end points of the minor axis.
    `processing.core.PVector` | `getMinorEndpoint2()` Reports the coordinates of one of the end points of the minor axis.
    `float` | `getRotation()` Reports the rotation of the ellipse.
    `float` | `getScale()` Reports the scaling of the ellipse.
    `boolean` | `isWeighted()` Reports whether or not weights are used in the calculation of the ellipse.
    `void` | `setIsWeighted(boolean weighted)` Determines if the weighted or unweighted points are used to calculate the ellipse.
    `void` | `setScale(float axisScale)` Sets the scaling of the ellipse.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### StandardEllipse

          public StandardEllipse(processing.core.PVector centre,
                                 float major,
                                 float minor,
                                 float rotation)

      Creates an ellipse with the given location, dimensions and rotation.
      Parameters:
        `centre` - Centre of the ellipse.
        `major` - Length of the major axis of the ellipse.
        `minor` - Length of the minor axis of the ellipse.
        `rotation` - Clockwise rotation of the axes (can be negative for anti-clockwise)

    - #### StandardEllipse

          public StandardEllipse(java.util.Collection<processing.core.PVector> points)

      Creates a standard ellipse from the given set of 2D Cartesian point values. The angle of the two axes of the ellipse will represent the directions of greatest and least point dispersion. Their lengths will be 2*standard deviation of the spread in those directions. See Ebdon, p.139. If the z component of each point is not zero, its value is used to calculate the weighted mean centre and dispersion as well as the unweighted version. The collection should store objects of type `PVector`.
      Parameters:
        `points` - Collection of 2d point values.

    - #### StandardEllipse

          public StandardEllipse(java.util.Collection<processing.core.PVector> points,
                                 boolean isLatLong)

      Creates a standard ellipse from the given set of 2D Cartesian or latitude/longitude point values. The angle of the two axes of the ellipse will represent the directions of greatest and least point dispersion. Their lengths will be 2*standard deviation of the spread in those directions. See Ebdon, p.139. If the z component of each point is not zero, its value is used to calculate the weighted mean centre and dispersion as well as the unweighted version. The collection should store objects of type `PVector`.
      Parameters:
        `points` - Collection of 2d point values. If lat/long angles are assumed to be in decimal degrees in the longitude range of +-180 and latitude range of +-90 degrees.
        `isLatLong` - If true, points are assumed to represent latitude/longitude bearings, otherwise Cartesian points are assumed.

  - ### Method Detail

    - #### setIsWeighted

          public void setIsWeighted(boolean weighted)

      Determines if the weighted or unweighted points are used to calculate the ellipse. Weights are stored in the 'z' component of each point.
      Parameters:
        `weighted` - Uses weighted points if true.

    - #### isWeighted

          public boolean isWeighted()

      Reports whether or not weights are used in the calculation of the ellipse. Weights are stored in the 'z' component of each point.
      Returns:
        True if weighted points are used to calculate the ellipse.

    - #### getCentre

          public processing.core.PVector getCentre()

      Reports the centre of the ellipse. This will be the weighted centre if `isWeighted()` is `true`, otherwise it reports the unweighted mean centre.
      Returns:
        Mean centre of the ellipse.

    - #### getMajorAxis

          public float getMajorAxis()

      Reports the length of the major axis of the ellipse. This will represent the weighted dispersion if `isWeighted()` is true.
      Returns:
        Major axis of the ellipse.

    - #### getMinorAxis

          public float getMinorAxis()

      Reports the length of the minor axis of the ellipse. This will represent the weighted dispersion if `isWeighted()` is true.
      Returns:
        Minor axis of the ellipse.

    - #### getRotation

          public float getRotation()

      Reports the rotation of the ellipse. This will be the based on the weighted dispersion if `isWeighted()` is true.
      Returns:
        Clockwise rotation of the ellipse in radians.

    - #### getMajorEndpoint1

          public processing.core.PVector getMajorEndpoint1()

      Reports the coordinates of one of the end points of the major axis. This will always be the opposite end of that reported by `getMajorEndpoint2()`. This will be based on the weighted dispersion if `isWeighted()` is true.
      Returns:
        End point of the major axis.

    - #### getMajorEndpoint2

          public processing.core.PVector getMajorEndpoint2()

      Reports the coordinates of one of the end points of the major axis. This will always be the opposite end of that reported by `getMajorEndpoint1()`. This will be based on the weighted dispersion if `isWeighted()` is true.
      Returns:
        End point of the major axis.

    - #### getMinorEndpoint1

          public processing.core.PVector getMinorEndpoint1()

      Reports the coordinates of one of the end points of the minor axis. This will always be the opposite end of that reported by `getMinorEndpoint2()`. This will be based on the weighted dispersion if `isWeighted()` is true.
      Returns:
        End point of the minor axis.

    - #### getMinorEndpoint2

          public processing.core.PVector getMinorEndpoint2()

      Reports the coordinates of one of the end points of the minor axis. This will always be the opposite end of that reported by `getMinorEndpoint1()`. This will be based on the weighted dispersion if `isWeighted()` is true.
      Returns:
        End point of the minor axis.

    - #### getScale

          public float getScale()

      Reports the scaling of the ellipse. A scaling factor of 1 means the radius of the major and minor axes represent 1 standard deviation of the point spread.
      Returns:
        Scaling factor of the ellipse.

    - #### setScale

          public void setScale(float axisScale)

      Sets the scaling of the ellipse. A scaling factor of 1 means the radius of the major and minor axes represent 1 standard deviation of the point spread.
      Parameters:
        `axisScale` - New scaling factor of the ellipse.

    - #### draw

          public void draw(processing.core.PApplet sketch)

      Draws the ellipse. Uses the currently defined stroke weight, stroke and fill colours.
      Parameters:
        `sketch` - in which to draw the ellipse.

    - #### drawAxes

          public void drawAxes(processing.core.PApplet sketch)

      Draws the axes of the ellipse. Uses the currently defined stroke weight and colour.
      Parameters:
        `sketch` - in which to draw the axes.