org.gicentre.utils.stat
Class StandardEllipse

java.lang.Object
  extended by 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 PVectors 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.3, 1st August, 2011.
Author:
Jo Wood, giCentre, City University London.

Constructor Summary
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
 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.


giCentre Utilities V.3.3, API documentation generated 6th April, 2013