AbstractLocalisation

java.lang.Object
- PamDetection.AbstractLocalisation

Direct Known Subclasses:

AISLocalisation, ClickLocalisation, ClickTrainLocalisation, DifarLocalisation, GroupDetectionLocalisation, IshLocalisation, TargetMotionLocalisation, TargetMotionLocalisation, 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

Fields
Modifier and Type	Field and Description
`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`

Constructor Summary

Constructors
Constructor and Description
`AbstractLocalisation(PamDataUnit pamDataUnit, int locContents, int referenceHydrophones)`
`AbstractLocalisation(PamDataUnit pamDataUnit, int locContents, int referenceHydrophones, int arrayType, PamVector[] arrayAxis)`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addLocContents(int flagsToAdd)`
`boolean`	`bearingAmbiguity()`
`double[]`	`getAngleErrors()`
`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()`
`GpsData`	`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 of a plane defined by the first two (or first in the case of a linear array) array axis directions.
`PamVector`	`getPlanarVector()` Get a unit vector pointing towards this localisation in the coordinate frame of the array geometry.
`double`	`getRange()` Deprecated.
`double`	`getRange(int iSide)` Get the range for a specific side (where ambiguity exists)
`double`	`getRangeError()` Deprecated.
`double`	`getRangeError(int iSide)`
`PamVector[]`	`getRealWorldVectors()` Get vectors to the detection in real world (relative to earths surface) coordinates.
`int`	`getReferenceHydrophones()`
`int`	`getSubArrayType()`
`double[]`	`getTimeDelayErrors()` Time delay errors
`double[]`	`getTimeDelays()` Time delays in seconds.
`PamVector[]`	`getWorldVectors()` Get vectors pointing at this localisation in a real world coordinate frame.
`boolean`	`hasLocContent(int requiredContent)` Check that the localisation has specific content.
`static java.util.ArrayList<java.lang.Integer>`	`indexM1(int numberOfHydrophones)`
`static java.util.ArrayList<java.lang.Integer>`	`indexM2(int numberOfHydrophones)` IndexM1 and IndexM2 specify which hydrophones to calculate time delays between.
`int`	`removeLocContents(int flagsToRemove)`
`void`	`setArrayAxis(PamVector[] arrayAxis)` Set the array axis - one, two or three axes defining the principle orientations of the array used for the localisation.
`void`	`setLocContents(int locContents)`
`void`	`setParentDetection(PamDetection parentDetection)`
`void`	`setReferenceHydrophones(int referenceHydrophones)`
`void`	`setSubArrayType(int arrayType)` Set the type of array (or sub array) used for this particular localisation This may not be the entire array if detection was only on some channels.

Methods inherited from class java.lang.Object
equals, 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
- 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
  - setSubArrayType
```
public void setSubArrayType(int arrayType)
```
    Set the type of array (or sub array) used for this particular localisation This may not be the entire array if detection was only on some channels.
    
    Parameters:
    arrayType -
  - 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.
  - setArrayAxis
```
public void setArrayAxis(PamVector[] arrayAxis)
```
    Set the array axis - one, two or three axes defining the principle orientations of the array used for the localisation. The angles in the localisation will be relative to these axes.
    
    Parameters:
    arrayAxis - array axis vectors.
  - getPlanarAngles
```
public double[] getPlanarAngles()
```
    returns angles projected onto the surface of a plane defined by the first two (or first in the case of a linear array) array axis directions.
    In an ideal world, this plane will be aligned with the sea surface, in which case it will be relatively easy to convert these angles to a surface angle. However, the choice of array primary and secondary axes may vary a lot (depending on hydrophone order) and there is no implicit guarantee that these angles will be relative to the real x and y axis of the array.
    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.
    For a volumetric array, it will be a projection of the two angles.
    To use these data though, it will also be necessary to know the orientation of the principle axes of the array. For a linear array, this will just be the line of the array. For a planar and volumetric array, these may depend on the type of localiser used. The array axes should be available in arrayAxes.
    The planar angles will be correct relative to the two primary array axis directions.
    
    Returns:
    array of possible angles.
  - getPlanarVector
```
public PamVector getPlanarVector()
```
    Get a unit vector pointing towards this localisation in the coordinate frame of the array geometry.
    
    Returns:
    a unit vector in the coordinate frame of the array geometry.
    If you want the projection of this vector onto the plane, simply set the third element to zero. If you do that, do not normalise in case the direction is perpendicular to the plane, in which case you'll get a divide by zero.
  - getWorldVectors
```
public PamVector[] getWorldVectors()
```
    Get vectors pointing at this localisation in a real world coordinate frame.
    N.B. Real world in this instance means relative to the xyz coordinate frame of the hydrophone array. To get real real world vectors relative to the planet, the vectors will need to be further rotated by the course of the vessel/array and the pitch, roll of the hydrophone array
    
    Returns:
    vectors pointing at this localisation in a real world coordinate frame. For a volumetric array, there should be a single vector since the geometry gives an unambiguous result. For a planar array we will get two vectors, one either side of the plane.
  - getRealWorldVectors
```
public PamVector[] getRealWorldVectors()
```
    Get vectors to the detection in real world (relative to earths surface) coordinates.
    This is the output of getWorldVectors rotated by the reference bearing from the GPS data.
    
    Returns:
    real world vectors.
  - 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 volumetric array.
  - getAngleErrors
```
public double[] getAngleErrors()
```
    Returns:
    Angle errors 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 error 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 errors should be returned, the first being the error on 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 volumetric array.
  - indexM2
```
public static java.util.ArrayList<java.lang.Integer> indexM2(int numberOfHydrophones)
```
    IndexM1 and IndexM2 specify which hydrophones to calculate time delays between. In the case of a paired array this will simply be the hydrophones in pairs so Index M1 will be 0 and even numbers and IndexM2 will be odd numbers.
    
    Returns:
  - indexM1
```
public static java.util.ArrayList<java.lang.Integer> indexM1(int numberOfHydrophones)
```
  - getTimeDelays
```
public double[] getTimeDelays()
```
    Time delays in seconds.
    These are calculated between every hydrophone pair in a group. To get the pairs use indexM1 and indexM2 functions. For example for four hydrophones in an array;
    IndexM1=0 0 0 1 1 2
    IndexM2=1 2 3 2 3 3
    So the first time delay will be between hydrophones 0 and 1, the second time delay between hydrophones 0 and 2 and so on. Time delay convention. The time delay is positive if it hits the indexM1 hydrophone BEFORE hitting the indexM2 hydrophone.
    
    Returns:
    array of time delays in seconds.
  - getTimeDelayErrors
```
public double[] getTimeDelayErrors()
```
    Time delay errors
    
    Returns:
  - 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.
    now that the general code for localisation using vectors has been sorted out so that the getWorldVectors now returns vectors which are correct in the general xyz frame of the array geometry, all that is actually needed here now is the array heading at the time of the event, while in previous versions, this required the actual bearing between two hydrophones (which was the same as the array heading for linear arrays which is why it all worked).
    
    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 GpsData 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)

Class AbstractLocalisation

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

HAS_BEARING

HAS_RANGE

HAS_DEPTH

HAS_BEARINGERROR

HAS_RANGEERROR

HAS_DEPTHERROR

HAS_LATLONG

HAS_XY

HAS_XYZ

HAS_AMBIGUITY

HAS_PERPENDICULARERRORS

Constructor Detail

AbstractLocalisation

AbstractLocalisation

Method Detail

getSubArrayType

setSubArrayType

getArrayOrientationVectors

setArrayAxis

getPlanarAngles

getPlanarVector

getWorldVectors

getRealWorldVectors

getAngles

getAngleErrors

indexM2

indexM1

getTimeDelays

getTimeDelayErrors

getLocContents

setLocContents

addLocContents

removeLocContents

hasLocContent

getParentDetection

setParentDetection

getReferenceHydrophones

setReferenceHydrophones

getBearing

getBearing

getBearingReference

bearingAmbiguity

getRange

getRange

getDepth

getDepth

getBearingError

getBearingError

getRangeError

getRangeError

getDepthError

getDepthError

getOriginLatLong

getLatLong

getNumLatLong

getPerpendiculaError

getParallelError

getErrorDirection