Package PamDetection

Class AbstractLocalisation

java.lang.Object
PamDetection.AbstractLocalisation
Direct Known Subclasses:
AISLocalisation, BeamFormerLocalisation, BeamOGramLocalisation, BearingLocalisation, ClickLocalisation, DifarLocalisation, DLLocalisation, GroupLocalisation, IshLocalisation, IshLocalisation, LinearLocalisation, TargetMotionLocalisation, TargetMotionLocalisation, TowedArray3DLocalization, TrackedGroupLocalisation, WhistleBearingInfo, WhistleLocalisation
public abstract class AbstractLocalisation extends 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:

  • Constructor Details

    • AbstractLocalisation

      public AbstractLocalisation(PamDataUnit pamDataUnit, int locContents, int referenceHydrophones)
      Constructor for a localisation.
      Parameters:
      pamDataUnit - - the pam data units the localisation is associated with
      locContents - - the localisation contents bitmap.
      referenceHydrophones - - the reference hydrophones.

    • AbstractLocalisation

      public AbstractLocalisation(PamDataUnit pamDataUnit, LocContents locContents, int referenceHydrophones)
      Constructor for a localisation.
      Parameters:
      pamDataUnit - - the pam data units the localisation is associated with.
      locContents - - the localisation contents class.
      referenceHydrophones - - the reference hydrophones.

    • AbstractLocalisation

      public AbstractLocalisation(PamDataUnit pamDataUnit, int locContents, int referenceHydrophones, int arrayType, PamVector[] arrayAxis)
      Constructor for a localisation.
      Parameters:
      pamDataUnit - - the pam data units the localisation is associated with
      locContents - - the localisation contents bitmap.
      referenceHydrophones - - the reference hydrophones.
      arrayType - - the array type.
      arrayAxis - - the array axis.

  • Method Details

    • 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.

      ***************** CHANGES FROM AUGUST 2017 *******************
      Now oriented the 'globe' differently, so that the first angle can be between -Pi and +Pi or between 0 and 2Pi. The second angle is the elevation angle which is either up (+ve angles) or down (-ve angles) having a range of -Pi/2 to +Pi/2. This change will only affect data from volumetric arrays when the animal is at significant depth. Changes are being made to data from click and whistle detectors which used the older system to maintain compatibility.

      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 colongitude, the second being the latitude. Imagine a globe, with North vertical and 0 longitude pointing along the main axis of the array geometry.

    • 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.

    • getTimeDelayChIndex

      public static int[][] getTimeDelayChIndex(int numberOfHydrophones)
      The PAMGuard convention on the order of hydrophone pairs to calculate time delays between. In the case of a simple stereo array this will simply be an array {{0,1}}. For a more complex array e.g. 4 channels the function would return {{0,1},{0,2},{0,3},{1,2},{1,3},{2,3}}.
      Parameters:
      the - number of receivers/hydrophones in the array.
      Returns:
      an array with channel numbers showing which receivers/hydrophones to calculate time delays between.

    • 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 LocalisationInfo getLocContents()
      Returns:
      a set of flags specifying which data are available within this localisation object.

    • setLocContents

      public void setLocContents(LocalisationInfo 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(PamDataUnit 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

    • 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.

    • getRange

      public double getRange(int iSide)
      Get the range for a specific side (where ambiguity exists)
      Parameters:
      iSide -
      Returns:
      range

    • getHeight

      public double getHeight(int iSide)
      Get height of the detection in meters. Depth is -height.
      Returns:
      The height of the detection in meters.

    • getBearingError

      public double getBearingError(int iSide)
      Parameters:
      iSide -
      Returns:
      The error on the bearing estimation in radians for the given side

    • 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

    • getAmbiguityCount

      public int getAmbiguityCount()
      Get the number of localisation results present.
      Note: There are two types of ambiguity, ambiguity in 'raw' localisation data e.g. 3D bearings from a planar array and ambiguity in localisation result e.g. multiple possible animal locations. This function return the number of localisation results e.g. usually 2 for a towed stereo or planar array.
      Parameters:
      side - - the ambiguity index.
      Returns:
      the number of localisation results available.

    • getLocError

      public LocaliserError getLocError(int side)
      Get the loclaisation error. The error class allows users to specify an error in any direction. The error is plotted relative to
      Parameters:
      side - - the ambiguity index.
      Returns:

    • getPerpendiculaError

      public double getPerpendiculaError(int iSide)
      Get the error perpendicular to the track line (in meters). Perpendicular error can be two things. It can be the error perpendicular to a track line or it can be the y error from a static system
      Parameters:
      iSide - 0, 1, 2, etc.
      Returns:
      the error in metres.

    • getParallelError

      public double getParallelError(int iSide)
      Get the error parallel to the track line (in meters). Parallel error can be two things. It can be the error parallel to a track line or it can be the x error from a static system
      Parameters:
      iSide - 0, 1, 2, etc.
      Returns:
      the error in metres.

    • getRangeError

      public double getRangeError(int iSide)
      The error on the range. The range is A direct line from the origin to the localisation. It includes depth.
      Parameters:
      side - - the ambiguity index.
      Returns:
      The error on the range estimation in meters.

    • getHeightError

      public double getHeightError(int iSide)
      The error in the height. (height is -depth).
      Parameters:
      side - - the ambiguity index.
      Returns:
      The error on the depth estimation in meters.

    • getErrorDirection

      public PamVector getErrorDirection(int iSide)
      Get an angle that the errors are to be plotted relative to. This is the real world angle. So if plotted relative to the direction of a ship the angle will be the direction of the ship. If plotted in y= north and x=east Cartesian then the error direction will be 0
      Parameters:
      iSide -
      Returns:
      Error direction (radians)

    • bearingAmbiguity

      @Deprecated public boolean bearingAmbiguity()
      Deprecated.
      Returns:
      true if the bearing is subject to a left right (or rotational) ambiguity about the reference bearing.

    • getNumLatLong

      @Deprecated public int getNumLatLong()
      Deprecated.
      Gte the number of lat long results (replaced by getAmbiguityCount());
      Returns:
      The number of LatLongs (generally 0 to 2)

    • 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:

    • getDepth

      @Deprecated public double getDepth()
      Deprecated.

    • toString

      public String toString()
      Overrides:
      toString in class Object