net.talvi.puffinplot.data

Class GreatCircle

java.lang.Object

net.talvi.puffinplot.data.GreatCircle

public final class GreatCircle
extends java.lang.Object

This class represents a great circle, created either directly by specifying a pole direction or indirectly by giving a list of vectors. If a list of vectors is given, the constructor calculates the best-fit circle.

Method Summary

Modifier and Type	Method and Description
double	angleFromLast(Vec3 v) Returns the angle between the supplied direction and the last point on the great-circle fit.
static GreatCircle	fromBestFit(java.util.List<Vec3> vectors) Constructs a best-fitting great circle for the supplied vectors.
static GreatCircle	fromPole(Vec3 pole) Create a great circle with the given pole.
static java.util.List<java.lang.String>	getEmptyFields() Returns a list of empty strings equal in length to the number of parameters.
static java.util.List<java.lang.String>	getHeaders() Returns the headers describing the parameters as a list of strings.
double	getMad1() Returns the MAD1 (planar maximum angular deviation) value for the great-circle fit.
java.util.List<Vec3>	getPoints() Returns the normalized points to which the great circle was fitted, if any.
Vec3	getPole() Returns a pole to the fitted great circle.
Vec3	lastPoint() Returns the normalized final point used in the great-circle fit, if any.
Vec3	nearestOnCircle(Vec3 point) For a supplied direction, returns the nearest direction which lies on this great circle.
java.util.List<java.lang.String>	toStrings() Returns the statistical parameters as a list of strings.

Methods inherited from class java.lang.Object

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

Method Detail

fromPole

public static GreatCircle fromPole(Vec3 pole)

Create a great circle with the given pole. This produces a great circle with no associated points; methods which require points to return a meaningful result will throw an UnsupportedOperationException if called on a great circle instantiated using this constructor.

Parameters:

pole - pole direction for the great circle

Returns:

a great circle with the supplied pole

fromBestFit

public static GreatCircle fromBestFit(java.util.List<Vec3> vectors)

Constructs a best-fitting great circle for the supplied vectors. The vectors do not need to be normalized, but only their directions are considered when fitting the circle.

Parameters:

vectors - the direction vectors for which to fit the circle

Returns:

a great circle fitted to the supplied vectors

getPoints

public java.util.List<Vec3> getPoints()

Returns the normalized points to which the great circle was fitted, if any. If there are none, an empty list will be returned.

Returns:

the normalized points to which the great circle was fitted

getPole

public Vec3 getPole()

Returns a pole to the fitted great circle. There is no guarantee as to which of the two possible pole directions will be returned.

Returns:

a pole to the fitted great circle

nearestOnCircle

public Vec3 nearestOnCircle(Vec3 point)

For a supplied direction, returns the nearest direction which lies on this great circle.

Parameters:

point - a vector specifying a direction

Returns:

a vector on this great circle, as close as possible to the specified direction

lastPoint

public Vec3 lastPoint()

Returns the normalized final point used in the great-circle fit, if any. If the great circle was instantiated from a pole rather than a set of points, there is no final point to return, and this method will throw a UnsupportedOperationException.

Returns:

the normalized final point used in the great-circle fit

Throws:

java.lang.UnsupportedOperationException - if this great circle has no points

angleFromLast

public double angleFromLast(Vec3 v)

Returns the angle between the supplied direction and the last point on the great-circle fit. A negative value indicates that the supplied direction is before the last great-circle point when travelling along the great circle in the direction in which the original points were provided. A positive value indicates that the supplied direction is beyond the final great-circle point. If the great circle has no points, this method will throw an UnsupportedOperationException.

Parameters:

v - a direction

Returns:

the angle between the supplied direction and the last point on the great-circle fit

Throws:

java.lang.UnsupportedOperationException - if this great circle has no points

toStrings

public java.util.List<java.lang.String> toStrings()

Returns the statistical parameters as a list of strings. The order of the parameters is the same as the order of the headers provided by getHeaders().

Returns:

the statistical parameters as a list of strings

getEmptyFields

public static java.util.List<java.lang.String> getEmptyFields()

Returns a list of empty strings equal in length to the number of parameters.

Returns:

a list of empty strings equal in length to the number of parameters

getHeaders

public static java.util.List<java.lang.String> getHeaders()

Returns the headers describing the parameters as a list of strings.

Returns:

the headers describing the parameters

getMad1

public double getMad1()

Returns the MAD1 (planar maximum angular deviation) value for the great-circle fit. If this great circle was not created by fitting points, this method will throw an UnsupportedOperationException.

Returns:

the MAD1 value for the great-circle fit, if any

Throws:

java.lang.UnsupportedOperationException - if no fit was performed to produce this great circle