PamDetection
Class AbstractLocalisation

java.lang.Object
  PamDetection.AbstractLocalisation

Direct Known Subclasses:

AISLocalisation, ClickLocalisation, ClickTrainLocalisation, GroupDetectionLocalisation, IshLocalisation, TowedArray3DLocalization, WhistleBearingInfo, WhistleLocalisation

public abstract class AbstractLocalisation
extends java.lang.Object

Class for localisation information.

Each AbstractLocalisation should be uniquely linked to a single PamDataUnit, since this class is abstract, where the actual data are stored (in the data unit or in the localisation) is up to the programmer.

This class has been through a number of iterations during 2007 and may well go through a few more before we are all happy with it. The main problem has been whether to reference positions purely by a hydrophone number, a time, a distance and bearing, or simply by a LatLong. It's ended up as a mixture of both.

Things are made worse by ambiguities which means that there may be one or more of each type of information. The key is to correctly set the types of information held within a particular localisation so that other parts of Pamguard may query it and act accordingly. It is vital that the PamDataBlock which will hold the PamDataUnits associated with a localisation have their localisationContents member correctly set to the full range of POSSIBLE localisation information types for the data units they will contain. This is important for the database and the various displays, which will all query the PamDataBlocks before the contain any PamDataUnits in order to see which columns to put in database tables, whether or not the data within a PamDataBlock may plot on a particular display, etc.

Author:

Doug Gillespie

See Also:

PamDataUnit, PamDataBlock

Field Summary

private PamVector[]	arrayAxis Principle axis of the array geometry.
private int	arrayType Type of array, point, line, plane, volume, etc.
static int	HAS_AMBIGUITY
static int	HAS_BEARING
static int	HAS_BEARINGERROR
static int	HAS_DEPTH
static int	HAS_DEPTHERROR
static int	HAS_LATLONG
static int	HAS_PERPENDICULARERRORS Errors parallel and perpendicular to the ships track.
static int	HAS_RANGE
static int	HAS_RANGEERROR
static int	HAS_XY
static int	HAS_XYZ
private int	locContents bitmap of flags saying what's in the localisation information
private PamDataUnit	pamDataUnit reference to parent PamDetection object
private int	referenceHydrophones All localisation must be relative to at least one hydrophone.

Constructor Summary

AbstractLocalisation(PamDataUnit pamDataUnit, int locContents, int referenceHydrophones)

AbstractLocalisation(PamDataUnit pamDataUnit, int locContents, int referenceHydrophones, int arrayType, PamVector[] arrayAxis)

Method Summary

void	addLocContents(int flagsToAdd)
boolean	bearingAmbiguity()
double[]	getAngles()
PamVector[]	getArrayOrientationVectors()
double	getBearing() Deprecated.
double	getBearing(int iSide) Deprecated.
double	getBearingError() Deprecated.
double	getBearingError(int iSide)
double	getBearingReference() Get the reference bearing in radians.
double	getDepth() Deprecated.
double	getDepth(int iSide)
double	getDepthError() Deprecated.
double	getDepthError(int iSide)
double	getErrorDirection(int iSide) Get an angle that the errors are to be plotted relative to.
LatLong	getLatLong(int iSide) Return the latlong for a location.
int	getLocContents()
int	getNumLatLong()
LatLong	getOriginLatLong()
double	getParallelError(int iSide) Get the error parallel to the trackline (in meters)
PamDataUnit	getParentDetection()
double	getPerpendiculaError(int iSide) Get the error perpedicular to the track line (in meters)
double[]	getPlanarAngles() returns angles projected onto the surface.
double	getRange() Deprecated.
double	getRange(int iSide) Get the range for a specific side (where ambiguity exists)
double	getRangeError() Deprecated.
double	getRangeError(int iSide)
int	getReferenceHydrophones()
int	getSubArrayType()
boolean	hasLocContent(int requiredContent) Check that the localisation has specific content.
int	removeLocContents(int flagsToRemove)
void	setLocContents(int locContents)
void	setParentDetection(PamDetection parentDetection)
void	setReferenceHydrophones(int referenceHydrophones)

Methods inherited from class java.lang.Object

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

Field Detail

HAS_BEARING

public static final int HAS_BEARING

See Also:

Constant Field Values

HAS_RANGE

public static final int HAS_RANGE

See Also:

Constant Field Values

HAS_DEPTH

public static final int HAS_DEPTH

See Also:

Constant Field Values

HAS_BEARINGERROR

public static final int HAS_BEARINGERROR

See Also:

Constant Field Values

HAS_RANGEERROR

public static final int HAS_RANGEERROR

See Also:

Constant Field Values

HAS_DEPTHERROR

public static final int HAS_DEPTHERROR

See Also:

Constant Field Values

HAS_LATLONG

public static final int HAS_LATLONG

See Also:

Constant Field Values

HAS_XY

public static final int HAS_XY

See Also:

Constant Field Values

HAS_XYZ

public static final int HAS_XYZ

See Also:

Constant Field Values

HAS_AMBIGUITY

public static final int HAS_AMBIGUITY

See Also:

Constant Field Values

HAS_PERPENDICULARERRORS

public static final int HAS_PERPENDICULARERRORS

Errors parallel and perpendicular to the ships track.

See Also:

Constant Field Values

pamDataUnit

private PamDataUnit pamDataUnit

reference to parent PamDetection object

locContents

private int locContents

bitmap of flags saying what's in the localisation information

arrayType

private int arrayType

Type of array, point, line, plane, volume, etc.

arrayAxis

private PamVector[] arrayAxis

Principle axis of the array geometry.

referenceHydrophones

private int referenceHydrophones

All localisation must be relative to at least one hydrophone. If more than one is specified, then it's assumed that the data are relative to the mean position of all hydrophones.

Constructor Detail

AbstractLocalisation

public AbstractLocalisation(PamDataUnit pamDataUnit,
                            int locContents,
                            int referenceHydrophones)

AbstractLocalisation

public AbstractLocalisation(PamDataUnit pamDataUnit,
                            int locContents,
                            int referenceHydrophones,
                            int arrayType,
                            PamVector[] arrayAxis)

Method Detail

getSubArrayType

public int getSubArrayType()

Returns:

the type of hydrophone sub array used, eg point, planar, line, volumetric. this can tell us the type of information likely to be available in terms of bearings, etc.

Added DG 6 January 2010

getArrayOrientationVectors

public PamVector[] getArrayOrientationVectors()

Returns:

one, two or three orthogonal orientation vectors which tell us the nominal direction the array is pointing in. For a simple towed array, this is likely to be (0,1,0), i.e. aligned with the positive y axis. For a planar array, two vectors should be returned and for a volumetric array, three, although the third will just be the cross product of the first two.

getPlanarAngles

public double[] getPlanarAngles()

returns angles projected onto the surface. for a linear array this will just be +/- the theta angle, or the getBearing(0) angle and there will be two of them, reflecting lr ambiguity. For a planar array, the angle will probably be a single angle, but will be projected onto the plane of the array.

Returns:

array of possible angles.

getAngles

public double[] getAngles()

Returns:

Angles to detection in radians. The number of angles will be 0, 1 or 2.

For a point array, null should be returned.

For a line array a single angle is returned which is the angle relative to the first orientation vector with 0 being in line with the orientation vector (can be thought of as colatitude).

For a planar or volumetric array, two angles should be returned, the first being the colatitude, the second being the longitude which will be between 0 and pi for a planar array and either -pi to pi or 0 to 2pi for a volumetirc array.

getLocContents

public int getLocContents()

Returns:

a set of flags specifying which data are available within this localisation object.

setLocContents

public void setLocContents(int locContents)

Parameters:

locContents - a set of flags specifying which data are available within this localisation object.

addLocContents

public void addLocContents(int flagsToAdd)

Parameters:

flagsToAdd - localisation flags to add to existing flags.

removeLocContents

public int removeLocContents(int flagsToRemove)

Parameters:

flagsToRemove - bitmap of localisation flags to remove.

Returns:

new or remaining localisation content flags.

hasLocContent

public boolean hasLocContent(int requiredContent)

Check that the localisation has specific content.

Parameters:

requiredContent - specified content

Returns:

true if specified content exists, false otherwise.

getParentDetection

public PamDataUnit getParentDetection()

Returns:

Parent detection containing this localisation information

setParentDetection

public void setParentDetection(PamDetection parentDetection)

Parameters:

parentDetection - Parent detection containing this localisation information

getReferenceHydrophones

public int getReferenceHydrophones()

Returns:

a bitmap of hydrophone numbers that form a reference position for this localisation

setReferenceHydrophones

public void setReferenceHydrophones(int referenceHydrophones)

Parameters:

referenceHydrophones - a bitmap of hydrophone numbers that form a reference position for this localisation

getBearing

@Deprecated
public double getBearing()

Deprecated.

Returns:

The bearing to the localisation (in radians)

getBearing

@Deprecated
public double getBearing(int iSide)

Deprecated.

Get the bearing in radians, relative to the bearing reference

Parameters:

iSide - which side is the bearing on

Returns:

bearing in radians

See Also:

getBearingReference

getBearingReference

public double getBearingReference()

Get the reference bearing in radians. This is relative to North, moving in a clockwise direction as would other bearings

Returns:

Reference bearing in radians.

bearingAmbiguity

public boolean bearingAmbiguity()

Returns:

true if the bearing is subject to a left right (or rotational) ambiguity about the reference bearing.

getRange

@Deprecated
public double getRange()

Deprecated.

Returns:

The range to the detection in meters.

getRange

public double getRange(int iSide)

Get the range for a specific side (where ambiguity exists)

Parameters:

iSide -

Returns:

range

getDepth

@Deprecated
public double getDepth()

Deprecated.

Returns:

The depth of the detection in meters

getDepth

public double getDepth(int iSide)

Returns:

The depth of the detection in meters

getBearingError

@Deprecated
public double getBearingError()

Deprecated.

Returns:

The error on the bearing estimation in radians

getBearingError

public double getBearingError(int iSide)

Parameters:

iSide -

Returns:

The error on the bearing estimation in radians for the given side

getRangeError

@Deprecated
public double getRangeError()

Deprecated.

Returns:

The error on the range estimation in meters.

getRangeError

public double getRangeError(int iSide)

Returns:

The error on the range estimation in meters.

getDepthError

@Deprecated
public double getDepthError()

Deprecated.

Returns:

The error on the depth estimation in meters.

getDepthError

public double getDepthError(int iSide)

Returns:

The error on the depth estimation in meters.

getOriginLatLong

public LatLong getOriginLatLong()

Returns:

the latlong of the centre of the hydrophones associated with the channels used in this detection. If no channels are set, then it returns the GPS location for the time of the detection.

getLatLong

public LatLong getLatLong(int iSide)

Return the latlong for a location. There may be more than one of them if there is side to side ambiguity.

Parameters:

iSide - 0, 1, 2, etc.

Returns:

LatLong information

getNumLatLong

public int getNumLatLong()

Returns:

The number of LatLongs (generally 0 to 2)

getPerpendiculaError

public double getPerpendiculaError(int iSide)

Get the error perpedicular to the track line (in meters)

Parameters:

iSide - 0, 1, 2, etc.

Returns:

the error in metres.

getParallelError

public double getParallelError(int iSide)

Get the error parallel to the trackline (in meters)

Parameters:

iSide - 0, 1, 2, etc.

Returns:

the error in metres.

getErrorDirection

public double getErrorDirection(int iSide)

Get an angle that the errors are to be plotted relative to.

Parameters:

iSide -

Returns:

Error direction (radians)