Package PamguardMVC

Class PamDataUnit<T extends PamDataUnit,U extends PamDataUnit>

java.lang.Object
PamguardMVC.PamDataUnit<T,U>
All Implemented Interfaces:
Comparable<PamDataUnit>
Direct Known Subclasses:
AbstractWhistleDataUnit, AISDataUnit, AlarmDataUnit, AnalogArraySensorDataUnit, AngleDataUnit, ArrayAccelDataUnit, AutecDataUnit, AveragedSpectraDataUnit, BackgroundDataUnit, BeamLocaliserData, BuoyStatusDataUnit, CalibrationDataUnit, ClickDetection, ClipDataUnit, ClipSpectrogramMark, CPODClick, D3DataUnit, DaqStatusDataUnit, DataUnit2D, DbHtDataUnit, DepthDataUnit, DLDataUnit, DLDetection, DummyClick, EffortDataUnit, EffortDataUnit, FormsDataUnit, GlobalTimeDataUnit, GPLDetection, GPLStateDataUnit, GpsDataUnit, GridDataUnit, GroupedRawData, GroupLocDataUnit, HydrophoneDataUnit, IshDetection, IshDetFnDataUnit, IshDetWrapper, IshmaelDataUnit, IshTrack, LandmarkDataUnit, LinePlotDataUnit, ListeningEffortData, LogXMLDataUnit, MapComment, MarkDataUnit, MeygenDataUnit, ModelResultDataUnit, NMEADataUnit, NoiseDataUnit, NormalizedDataUnit, OneBandDataUnit, PamBlockDataList, PamImage, PeakDataUnit, PrintScreenDataUnit, QAOpsDataUnit, QAQueuedTask, RavenDataUnit, RawDataUnit, RecorderDataUnit, RoccaContourDataUnit, RoccaDataUnit, RoccaLoggingDataUnit, RoccaSightingDataUnit, RockBlockMessage, SimObjectDataUnit, SimpleClick, SimSoundDataUnit, SpectralEtiDataUnit, SpectrumTemplateDataUnit, StreamerDataUnit, SuperDetection, TargetMotionResult, TaskLoggingData, TempDataUnit, TempDataUnit, TethysLogDataUnit, ThingHeard, ThresholdDetectorDataUnit, TideDataUnit, TowedArray3DDataUnit, TrackedGroupDataUnit, TriggerBackgroundDataUnit, TriggerLevelDataUnit, UserInputDataUnit, VetoBackgroundDataUnit, VetoDataUnit, VRDataUnit, WhistleClassificationDataUnit
public abstract class PamDataUnit<T extends PamDataUnit,U extends PamDataUnit> extends Object implements Comparable<PamDataUnit>
Author:
Doug Gillespie

Class for units of PAM data.

PamDataUnit's are held in ArrayLists within PamDataBlocks.

When a PamDataUnit is added to a PamDataBlock any PamProcesses that subscribe to that PamDataBlock receive a notification and can retrieve the PamDataUnits from the block.

Any data derived from acoustic data should subclass from AcousticDataUnit

Types T is for subdetections, U is for super detections 2021 note: T and U are no longer used since most types of super detection are capable of holding many types of data unit and in any case, the Type of sub detection is held in a subclass of PamDataUnit called SuperDetection and can be configured for that only. the Super Detection type U is now also always of a type derived from SuperDetection, though I daren't change it in the type of PamDataUnit since doing so would break any plugins. So can probably live without useing them, but leave them there unless planning on revising all plugin modules.

See Also:

  • Constructor Details

    • PamDataUnit

      public PamDataUnit(long timeMilliseconds)
      Old constructor using only time - everything has time !
      Parameters:
      timeMilliseconds - Time in standard milliseconds.

    • PamDataUnit

      public PamDataUnit(long timeMilliseconds, int channelBitmap, long startSample, long durationSamples)
      Constructor using the original parameters that have now been moved to DataUnitBaseData
      Parameters:
      timeMilliseconds -
      channelBitmap -
      startSample -
      duration - (number of samples, not milliseconds)

    • PamDataUnit

      public PamDataUnit(DataUnitBaseData basicData)
      Constructor using the new (Oct 2016)
      invalid @linkplain 
      {@linkplain #PamguardMVC.DataUnitBaseData
      } DataUnitBaseData class which speeds up and simplifies construction when reading data units from streams (Files, Network sockets, etc).
      Parameters:
      basicData -

  • Method Details

    • setUID

      public void setUID(long uid)
      Set the data units unique identifier
      Parameters:
      uid - unique identifier

    • getUID

      public long getUID()
      Get the data units unique identifier
      Returns:
      unique identifier

    • setAbsBlockIndex

      public void setAbsBlockIndex(int absBlockIndex)

    • setParentDataBlock

      public void setParentDataBlock(PamDataBlock parentDataBlock)
      Set the datablock for a data unit.
      Parameters:
      parentDataBlock -

    • setTimeMilliseconds

      public void setTimeMilliseconds(long timeMilliseconds)
      Set the millisecond time of the data unit using the standard Java time system of milliseconds since midnight, January 1, 1970 UTC
      Parameters:
      timeMilliseconds - time in milliseconds.

    • getTimeMilliseconds

      public long getTimeMilliseconds()
      Returns:
      The millisecond time of the data unit using the standard Java time system of milliseconds since midnight, January 1, 1970 UTC

    • getStartSample

      public Long getStartSample()
      Returns the start sample stored in the basic data unit
      Returns:

    • setStartSample

      public void setStartSample(Long startSample)
      Sets the start sample stored in the basic data unit
      Parameters:
      startSample -

    • getSeconds

      public double getSeconds()
      Returns:
      the start time of the data unit in seconds relative to the start of the run.

    • getSampleDuration

      public Long getSampleDuration()
      Gets the data unit duration, in samples
      Returns:

    • getSampleDurationAsInt

      public int getSampleDurationAsInt()
      Returns the data unit duration as an int value. If the duration is null, a -1 gets returned. This is helpful for calls that use the duration as a way of initializing the size of an ArrayList
      Returns:

    • getDurationInMilliseconds

      public Double getDurationInMilliseconds()
      Returns the data unit duration in milliseconds, as a Float value.
      Returns:
      null if nothing available - see if this causes problems consider returning a float value of -1.

    • getEndTimeInMilliseconds

      public long getEndTimeInMilliseconds()

    • setDurationInMilliseconds

      public void setDurationInMilliseconds(double durationMs)
      Takes the passed duration, in milliseconds, and converts to a sample duration
      Parameters:
      durationMs -

    • setSampleDuration

      public void setSampleDuration(Long duration)
      Sets the data unit duration, in samples
      Parameters:
      duration -

    • getLastSample

      public long getLastSample()
      get the last sample number in the data unit
      Returns:

    • getTimeOverlap

      public double getTimeOverlap(PamDataUnit o)
      returns the time overlap of another unit on this unit - so if the other unit is longer in time and completely covers this unit, the overlap is 1.0, if the other unit is shorter or not aligned, then the overlap will be invalid input: '<' 1.
      Parameters:
      o - Other PamDataUnit
      Returns:
      fractional overlap in time

    • getTimeNanoseconds

      public long getTimeNanoseconds()
      Get the data unit's time in nanoseconds. Normally this is referenced to the same start as the Java millisecond time (1/1/1970) however there are times (in Viewer mode) when the absolute time may be lost and it will only be useful as a relative measure.

      This should therefore only be used for calculations of time differences between data units and care should be taken to avoid overflows. Ideally you should subtract two nanosecond times as integers before converting to a floating point number. i.e.
      double timeDiffSecs = (double) (nanoTime2 - nanoTime1) / 1.e9;
      may not give the same result as
      double timeDiffSecs = nanoTime2/1.e9 - nanoTime1/1.e9;

      Returns:
      time in nanoseconds.

    • getAbsBlockIndex

      public int getAbsBlockIndex()

    • getParentDataBlock

      public PamDataBlock getParentDataBlock()

    • updateDataUnit

      public void updateDataUnit(long updateTime)

    • clearUpdateCount

      public void clearUpdateCount()
      Do a clear of update count after a database save.

    • getUpdateCount

      public int getUpdateCount()
      Returns:
      the number of times the data unit has been updated.

    • getChannelBitmap

      public int getChannelBitmap()
      Returns:
      Bitmap of software channels used in this data unit

    • setChannelBitmap

      public void setChannelBitmap(int channelBitmap)
      Set the channel bitmap (software channels)
      Parameters:
      channelBitmap -

    • getSequenceBitmap

      public int getSequenceBitmap()
      Get a sequence position within a datablock having multiple channels of data, multiple beams, etc.
      Returns:
      integer position within the sequence.

    • setSequenceBitmap

      public void setSequenceBitmap(Integer sequenceBitmap)
      Set the sequence bitmap - the order of the data within a data stream for beam formed data where the channelBitmap no longer contains a single unique channel.
      Parameters:
      sequenceBitmap -

    • getSequenceBitmapObject

      public Integer getSequenceBitmapObject()
      Get a sequence position within a datablock having multiple channels of data, multiple beams, etc. The difference between this method and getSequenceBitmap is that this will return a null if there is no sequence number, whereas the other method returns the channel map in that situation
      Returns:
      Integer position within the sequence, or null if there is no sequence

    • sortOutputMaps

      public void sortOutputMaps(int sourceChanMap, Integer sourceSeqMap, int localSubsetMap)
      This method will sort out this PamDataUnit's channel map and sequence map, depending on the source that it's getting it's information from. It should typically be called when created, especially if the channel/sequence information is a subset of the source data block (such as when selected in a GroupSourcePanel object).
      There are 3 passed parameters: the source channel map, the source sequence map, and the subset map that this data unit should reference. The local subset map may be the same as the source channel/sequence map, or it may only be a few of the source's channels or sequences.
      If the source has no sequence map (sourceSeqMap==null) then it's a normal FFT data block, and this PamDataUnit should be storing the local subset map in it's channelMap field and keeping it's sequenceMap field = null.
      If the source does have a sequence map (i.e. the source is the output of a Beamformer), then this PamDataUnit should be storing the local subset map in it's sequenceMap field and storing the source channel map in it's channelMap field.
      Parameters:
      sourceChanMap -
      sourceSeqMap -
      localSubsetMap -

    • setInfo

      public void setInfo(long timeMilliseconds, int channelBitmap, long startSample, long duration)
      Sets the original constructor parameters
      Parameters:
      timeMilliseconds -
      channelBitmap -
      startSample -
      duration -

    • getHydrophoneBitmap

      public int getHydrophoneBitmap()
      Returns:
      Bitmap of hydrophones used in this data unit which may be different from the software channel mapping for some configurations.

    • getOriginLatLong

      public GpsData getOriginLatLong(boolean recalculate)
      Get the latlong of the mean hydrophone position at the time of this detection. If the data unit has a channel bitmap of zero, then get the GPS position of the vessel at that time.
      Parameters:
      recalculate -
      Returns:
      Lat long of detection origin (usually the position of the reference hydrophone at time of detection)

    • getHydrophoneHeading

      public double getHydrophoneHeading(boolean recalculate)
      Get the hydrophone heading for the first hydrophone included in the detection. this is now the reference heading from the snapshot geometry for the data unit.
      Parameters:
      reacalculate - force recalculation
      Returns:
      hydrophone heading

    • clearOandAngles

      public void clearOandAngles()

    • getLastUpdateTime

      public long getLastUpdateTime()

    • getLastChangeTime

      public long getLastChangeTime()
      Get the last time that anything happened to this data unit - either created or updated.
      Returns:
      The greater of getLastUpdateTime() and getTimeMilliseconds()

    • setLastUpdateTime

      public void setLastUpdateTime(long lastUpdateTime)

    • getDatabaseIndex

      public int getDatabaseIndex()

    • setDatabaseIndex

      public void setDatabaseIndex(int databaseIndex)

    • getDatabaseUpdateOf

      public int getDatabaseUpdateOf()

    • setDatabaseUpdateOf

      public void setDatabaseUpdateOf(int databaseUpdateOf)

    • getDataUnitFileInformation

      public DataUnitFileInformation getDataUnitFileInformation()

    • setDataUnitFileInformation

      public void setDataUnitFileInformation(DataUnitFileInformation dataUnitFileInformation)

    • compareTo

      public int compareTo(PamDataUnit o)
      Specified by:
      compareTo in interface Comparable<T extends PamDataUnit>

    • getLocalisation

      public AbstractLocalisation getLocalisation()
      Returns:
      Returns the localisation.

    • setLocalisation

      public void setLocalisation(AbstractLocalisation localisation)
      Parameters:
      localisation - The localisation to set.

    • getSummaryString

      public String getSummaryString()
      Return an html formatted summary string describing the detection which can be used in tooltips anywhere in PAMGuard.
      Returns:
      summary string

    • getAnnotationsSummaryString

      public String getAnnotationsSummaryString()
      Get string information for the annotations. Kept separate so it can be called in overridden version of getSummaryString()
      Returns:

    • addDataAnnotation

      public void addDataAnnotation(DataAnnotation dataAnnotation)
      Adds a data annotation to the data unit. Removes any existing annotation of the same type and name.
      Parameters:
      dataAnnotation - data annotation

    • getNumDataAnnotations

      public int getNumDataAnnotations()
      Returns:
      the number of data annotations

    • getDataAnnotation

      public DataAnnotation getDataAnnotation(int index)
      Get a data annotation.

      No array size checking so call getNumDataAnnotations first !

      Parameters:
      index - index of data annotation
      Returns:
      a data annotation.

    • findDataAnnotation

      public DataAnnotation findDataAnnotation(Class annotationClass)
      Find a data annotation that can cast to a certain type.
      Parameters:
      annotationClass - class to search for
      Returns:
      data annotation or null

    • findDataAnnotation

      public DataAnnotation findDataAnnotation(Class annotationClass, String annotationName)
      Find a data annotation that can cast to a certain type, and that has a specific name.
      Parameters:
      annotationClass - class to search for
      Returns:
      data annotation or null

    • removeDataAnnotation

      public DataAnnotation removeDataAnnotation(int index)
      Remove a data annotation
      Parameters:
      index - index of data annotation
      Returns:
      Reference to data annotation or null if it wasn't in the list

    • removeDataAnnotation

      public boolean removeDataAnnotation(DataAnnotation annotation)
      Remove a data annotation
      Parameters:
      annotation - reference to data annotation to remove.
      Returns:
      true if the annotation was included in the list.

    • getBasicData

      public DataUnitBaseData getBasicData()
      Returns:
      the basicData

    • setUniqueSuperDetection

      public int setUniqueSuperDetection(SuperDetection superDetection)
      Sets a unique super detection. i.e. if the data unit already had a super detection of the same class, then this data unit is removed from that pre-existing superdetection.
      Parameters:
      superDetection -

    • addSuperDetection

      public void addSuperDetection(SuperDetection superDetection)

    • getSuperDetectionsCount

      public int getSuperDetectionsCount()

    • getSuperDetection

      public SuperDetection getSuperDetection(Class superClass, boolean includeSubClasses)
      Find a super detection which is of or is assignable to a particular class type
      Parameters:
      superClass - class or dub class of super detection
      includeSubClasses - flag to say search for sub classes
      Returns:
      super detection or null

    • getSuperDetection

      public SuperDetection getSuperDetection(Class superClass)
      Find a super detection of a given class.
      Parameters:
      superClass - class of super detection
      Returns:
      found data unit or null

    • getSuperDetection

      public SuperDetection getSuperDetection(PamDataBlock superDataBlock)
      find a super detection form the parent data block of the super detection.
      Parameters:
      superDataBlock - data block of super detection
      Returns:
      data unit from that block, or null.

    • getSuperDetection

      public SuperDetection getSuperDetection(PamDataBlock superDataBlock, boolean allowSuperSuper)
      find a super detection form the parent data block of the super detection.
      Parameters:
      superDataBlock - data block of super detection
      allowSuperSuper - Allow iteration through mutilple super detection layers
      Returns:
      data unit from that block, or null.

    • getSuperDetection

      public SuperDetection getSuperDetection(int ind)

    • removeSuperDetection

      public void removeSuperDetection(SuperDetection superDetection)

    • getSuperDetectionSyncronisation

      public Object getSuperDetectionSyncronisation()

    • getFrequency

      public double[] getFrequency()
      gets the frequency limits from the DataUnitBaseData object
      Returns:

    • setFrequency

      public void setFrequency(double[] freq)
      Set the frequency limits in the DataUnitBaseData object using a double[] array.
      Parameters:
      freq -

    • getSignalExcess

      public float getSignalExcess()
      Signal excess is the maximum of the ratio of the detection statistic in dB.
      Returns:
      the signalExcess

    • setSignalExcess

      public void setSignalExcess(float signalExcess)
      Signal excess is the maximum of the ratio of the detection statistic in dB.
      Parameters:
      signalExcess - the signalExcess to set

    • setNoiseBackground

      public void setNoiseBackground(Float noiseBackground)

    • getNoiseBackground

      public Float getNoiseBackground()

    • setSignalSPL

      public void setSignalSPL(Float signalSPL)

    • getSignalSPL

      public Float getSignalSPL()

    • getTimeDelaysSeconds

      public double[] getTimeDelaysSeconds()
      gets the array of time delays, measured in seconds
      Returns:

    • setTimeDelaysSeconds

      public void setTimeDelaysSeconds(double[] td)
      Sets the time delays, in seconds
      Parameters:
      td -

    • getFrequencyOverlap

      public double getFrequencyOverlap(PamDataUnit<?,?> o)
      returns the frequency overlap of another unit on this unit - so if the other unit is longer in time and completely covers this unit, the overlap is 1.0, if the other unit is shorter or not aligned, then the overlap will be invalid input: '<' 1.
      Parameters:
      o - Other AcousticDataUnit
      Returns:
      fractional overlap in time

    • getMeasuredAmplitude

      public double getMeasuredAmplitude()
      Returns:
      Returns the measuredAmplitude.

    • getMeasuredAmplitudeType

      public int getMeasuredAmplitudeType()
      Returns:
      Returns the measuredAmplitudeType.

    • setMeasuredAmplitude

      public void setMeasuredAmplitude(double measuredAmplitude)
      Parameters:
      measuredAmplitude -

    • setMeasuredAmplitudeType

      public void setMeasuredAmplitudeType(int measuredAmplitudeType)
      Parameters:
      measuredAmplitudeType -

    • setMeasuredAmpAndType

      public void setMeasuredAmpAndType(double measuredAmplitude, int measuredAmplitudeType)
      Sets both the measured amplitude, as well as the type of measurement (as defined by the DataUnitBaseData constants)
      Parameters:
      measuredAmplitude - The measuredAmplitude to set.
      measuredAmplitudeType - The type of amplitude measurement

    • getCalculatedAmlitudeDB

      public double getCalculatedAmlitudeDB()
      Returns the calculated amplitude in dB, stored in the base data
      Returns:

    • setCalculatedAmlitudeDB

      public void setCalculatedAmlitudeDB(double calculatedAmlitudeDB)
      sets the calculated amplitude in dB, stored in the base data
      Parameters:
      calculatedAmlitudeDB -

    • amplifyMeasuredAmplitudeByDB

      public void amplifyMeasuredAmplitudeByDB(double gaindB)
      Amplifies the measured amplitude stored in the base unit by the gain (in dB). Make sure that the passed gain value is consistent with the measuredAmplitudeType parameter
      Parameters:
      gaindB - the gain factor, in dB

    • amplifyMeasuredAmplitudeByLinear

      public void amplifyMeasuredAmplitudeByLinear(double gain)
      Amplifies the measured amplitude stored in the base unit by the linear gain. Make sure that the passed gain value is consistent with the measuredAmplitudeType parameter
      Parameters:
      gain - the linear gain factor

    • getAmplitudeDB

      public double getAmplitudeDB()
      Get the calculated amplitude, in dB. If it hasn't been calculated yet, do that first and then return the value
      Returns:
      the amplitude in dB with reference unit dictated by the hydrophone/microphone sensitivity value units.

    • linAmplitudeToDB

      public double linAmplitudeToDB(double linamp)
      calculate the amplitude in dB from the measured linear amplitude
      Parameters:
      linamp -
      Returns:

    • isForceAmpRecalc

      public boolean isForceAmpRecalc()
      Check whether force amplitude calculation is set. This will force an amplitude recalculation on calling getAmpliudeDB. After a new amplitude is calculated this is automatically reset to false.
      Returns:
      true if force amplitude is set.

    • setForceAmpRecalc

      public void setForceAmpRecalc(boolean forceAmpRecalc)
      Set whether force amplitude calculation is set. This will force an amplitude recalculation on calling getAmpliudeDB. After a new amplitude is calculated this is automatically reset to false.
      Parameters:
      forceAmpRecalc - - true if force amplitude is set.

    • getSuperId

      public int getSuperId(Class<OfflineEventDataUnit> superClass)

    • freeData

      public void freeData()
      Free as much data as possible. this gets called when processing offline data and during datagramming to free any data that's not needed in memory such as derived spectral data (e.g. from a click waveform) which can be recalculated if necessary.

    • getDataUnitPopupMenu

      public JPopupMenu getDataUnitPopupMenu(DataMenuParent menuParent, Point mousePosition)
      Get a standard popup menu with options for this data unit. PAsses the call through to the datablock, using a function that can handle multiple data units, but for convenience, it's often easier to start here. Override at will, but best to put as much functionality as possible into PamDataBlock.getDataUnitPopupMenu(..) and PamDataBlock.getDataUnitMenuItems(...).

      the standard menu item list contains annotation options (if available) so good to start with that and add to it

      Parameters:
      menuParent -
      mousePosition -
      Returns:
      popup menu or null (mostly null!)

    • getSnapshotGeometry

      public SnapshotGeometry getSnapshotGeometry()
      Get a snapshot of the array geometry at the time of this detection for the channels it uses.
      Returns:

    • calcSnapshotGeometry

      public SnapshotGeometry calcSnapshotGeometry()

    • setSnapshotGeometry

      public void setSnapshotGeometry(SnapshotGeometry snapshotGeometry)
      Parameters:
      snapshotGeometry - the snapshotGeometry to set

    • getColourIndex

      public int getColourIndex()
      Get a colour id. this can be pretty much anything and will be scaled, looped, to fit in the range of whale id colours. Mostly used for superdetection display, but can be used by anything.
      Returns:
      any integer.

    • isEmbryonic

      public boolean isEmbryonic()
      Returns:
      the embryonic

    • setEmbryonic

      public void setEmbryonic(boolean embryonic)
      Parameters:
      embryonic - the embryonic to set