Package PamguardMVC

Class PamProcess

java.lang.Object
PamguardMVC.PamProcess
All Implemented Interfaces:
PamObserver, ProcessAnnotator
Direct Known Subclasses:
AcquireNmeaData, AcquisitionProcess, AirgunProcess, AlarmProcess, AmpProcess, AngleListener, AngleProcess, ArrayAccelProcess, ArraySensorProcess, AzigramProcess, BackupProcess, BeamFormerBaseProcess, BeamformProcess, BinaryClickProcess, BinaryStoreProcess, CepstrumProcess, ClickAlarmManager, ClickDetector, ClickTrainDetector, ClickTrainProcess, CPODProcess, DbHtProcess, DBProcess, DecimatorProcess, DecimatorProcessW, DepthProcess, DetectionGroupProcess, DifarProcess, EnvelopeProcess, FilterProcess, FormsProcess, Group3DProcess, HydrophoneProcess, IMUListener, IMUProcess, IshDetFnProcess, IshLocProcess, IshPeakProcess, KernelSmoothingProcess, LikelihoodFFTProcess, LinearAverageSpectraProcess, ListeningProcess, LtsaProcess, MapProcess, MarkGroupProcess, MarkProcess, NetworkSendProcess, NoiseBandProcess, NoiseProcess, NormalizerProcess, OfflineFileProcess, OfflineProcessingProcess, OneBandProcess, OneBandPulseProcess, PamBlockProcess, PamFFTProcess, PamInstantProcess, PatchPanelProcess, PeakDetector, ProcessAISData, ProcessHeadingData, ProcessIshmaelData, ProcessNmeaData, QAMonitorProcess, RavenProcess, RecorderProcess, RoccaProcess, RoccaWhistleSelect, RockBlockProcess2, RWEProcess, SegmenterProcess, SonobuoyManager, SpectralEtiProcess, SpectrogramMarkProcess, SpectrogramMedianFilter, SpectrogramNoiseProcess, TargetMotionProcess, ThresholdDetectorProcess, TowedArray3DProcess, TrackedClickLocaliser, TrackedGroupProcess, UserDisplayProcess, UserInputProcess, VetoProcess, VRProcess, WhistleClassifierProcess, WhistleDetector, WhistleEventDetector, WhistleLinker, WhistleToneConnectProcess
public abstract class PamProcess extends Object implements PamObserver, ProcessAnnotator
Author:
Doug Gillespie

PamProcess is an abstract class used as a supertype for the creation of processes which either convert one type of PamData into a new type or add existing information to already existing data

All PamProcesses are Listeners and implement the Observer Class from java.util

The first PamProcess to be created will often be something which generates raw data (either by reading an input device or by reading chunks of data from a file).

Each PamProcess will require a source of data, which apart from the top level processes which acquire data, will be a PamDataBlock. The PamProcess will generally subscribe to the PamDataBlock so that it is notified of any changes (i.e. new data) being added to that block.

The PamController ...

  • Constructor Details

    • PamProcess

      public PamProcess(PamControlledUnit pamControlledUnit, PamDataBlock parentDataBlock)
      Parameters:
      pamControlledUnit - Reference to the PamControlledUnit containing this process (PamProcesses can only exist within PamControlledUnits, but a PamControlledUnit can contain multiple PamProcesses)
      parentDataBlock - Source data block for this process (can be null for raw data input devices)

    • PamProcess

      public PamProcess(PamControlledUnit pamControlledUnit, PamDataBlock parentDataBlock, String processName)

  • Method Details

    • getObserverObject

      public PamObserver getObserverObject()
      Specified by:
      getObserverObject in interface PamObserver
      Returns:
      the actual observer. In most cases concrete classes will just return 'this' in response. The exception is the Threaded observer, which will return the single thread observer.

    • destroyProcess

      public void destroyProcess()
      Called from the PamControlled unit when a PamControlled unit is removed from the model. Offers an opportunity to disconnect individual processed from the rest of the model. May be necessary to override to clean up some processes.

    • removeAllDataBlocks

      public void removeAllDataBlocks()
      Remove all data blocks from a process.

    • makePamProcess

      public void makePamProcess(PamControlledUnit pamControlledUnit, PamDataBlock parentDataBlock, String processName)

    • getParentDataBlock

      public PamDataBlock getParentDataBlock()
      Returns:
      Returns the parentDataBlock.

    • getParentDataBlocks

      public ArrayList<PamDataBlock> getParentDataBlocks()
      Get a list of the parent datablock and any multiplex datablocks.
      Returns:
      a list where the first element is the parent datablock and other elements are multiplex data blocks.

    • getParentProcess

      public PamProcess getParentProcess()

    • getAncestorDataBlock

      public PamDataBlock getAncestorDataBlock(Class unitDataType)
      Useful function to go back through the chain of data blocks and data units upstream of this process and look for a data block which has a particular data type. For instance, you may want the raw audio data upstream of FFT data. This may not be the data input to the FFT source, since you may be looking at some secondary FFT data source (smoothed, or noise suppressed spectrogram data for instance).
      Parameters:
      unitDataType - class type of data in the sought after data block (e.g. RawDataUnit.class
      Returns:
      reference to data block or null if none found
      See Also:

    • setParentDataBlock

      public void setParentDataBlock(PamDataBlock newParentDataBlock)
      Set a parent data block with the default options of rethreading if set
      Parameters:
      newParentDataBlock - source data block.

    • setParentDataBlock

      public void setParentDataBlock(PamDataBlock newParentDataBlock, boolean reThread)
      Set a parent data block for the process with the option to rethread the data exchange process. This is overridden to false if the main PAMGUARD option to rethread is off.
      Parameters:
      newParentDataBlock - source data block
      reThread - rethread if multithreading is enabled.

    • createAnnotations

      public final void createAnnotations(boolean notifyDownstream)

    • changedThreading

      public void changedThreading()
      Function that gets called in every process (or all processes that are listed in PamControlledUnits) and re-sets up the data source using the correct threading model. All this actually involves is resubscribing to the same data since everything else is handled in setParentDataBlock;

    • setProcessName

      public void setProcessName(String processName)
      Parameters:
      processName - Sets the name of the process

    • getProcessName

      public String getProcessName()
      Returns:
      Name of the PamProcess

    • getObserverName

      public String getObserverName()
      Specified by:
      getObserverName in interface PamObserver

    • setSampleRate

      public void setSampleRate(float sampleRate, boolean notify)
      Description copied from interface: PamObserver
      New sample rate
      Specified by:
      setSampleRate in interface PamObserver
      Parameters:
      notify - Notify other PamObservers and PamObservables in the chain.

    • masterClockUpdate

      public void masterClockUpdate(long timeMilliseconds, long sampleNumber)
      Specified by:
      masterClockUpdate in interface PamObserver

    • relSamplesToMilliseconds

      public long relSamplesToMilliseconds(long samples)
      Convert a number of samples into a number of milliseconds
      Parameters:
      samples - Number of ADC samples
      Returns:
      equivalent number of milliseconds

    • absSamplesToMilliseconds

      public long absSamplesToMilliseconds(long samples)
      Convert am ADC sample number to a millisecond time. This function was re-written on 11/11/08 to deal with problems of sound card clocks not running at same speed as PC clock, so milliseconds from PC clock and milliseconds based on samples would drift apart. This new system bases the calculation on the times of the most recently received data unit.
      Parameters:
      samples - sample number (from start of run)
      Returns:
      Millisecond time (UTC milliseconds from the epoch - the standard Java way)

    • absMillisecondsToSamples

      public long absMillisecondsToSamples(long millis)
      Convert a time in milliseconds to a number of samples.
      Parameters:
      millis - Current time in milliseconds (UTC millseconds from the epoch - the standard Java way)
      Returns:
      ADC Samples since the run start.
      See Also:

    • relMillisecondsToSamples

      public long relMillisecondsToSamples(double millis)
      Convert a number of milliseconds to a number of samples.
      Parameters:
      millis - number of milliseconds
      Returns:
      number of ADC samples corresponding to millis milliseconds.
      See Also:

    • noteNewSettings

      public void noteNewSettings()
      Specified by:
      noteNewSettings in interface PamObserver

    • getSampleRate

      public float getSampleRate()
      Returns:
      The sample rate in the process

    • getFrequencyRange

      public double[] getFrequencyRange()
      Get the range of frequencies over which the data in this process are likely to be present. Note that this is pretty crude and may not reflect the true range, for example, the click detector will return the limits of it's trigger filter, and there are plenty of sounds outside of that range which may have most of their energy well outside of the trigger range of the detector.
      Returns:
      Nominal frequency range for data in this block.

    • getSourceProcess

      public PamProcess getSourceProcess()
      Returns:
      The original data source process, i.e. the one reading the soundcard or the file, the one that doesn't have a parentDataBlock

    • getSourceDataBlock

      public PamDataBlock<PamDataUnit> getSourceDataBlock()
      find the absolute source of data, if one exists. i.e. the data output of a process that has no data input.

      If this is called from within acquisition, it will return null

      It there is no raw data source, i.e. if the type is not PamRawDataBlock, then return null.

      Returns:
      a PamRawDataBlock or null

    • getProcessCheck

      public ProcessCheck getProcessCheck()
      Get a process check object. This indicates the current status of a process.
      Returns:
      the process check object.

    • setProcessCheck

      public void setProcessCheck(ProcessCheck processCheck)
      Set a process check object. This indicates the current status of a process.

    • getRawSourceDataBlock

      public PamRawDataBlock getRawSourceDataBlock()
      Find the absolute source of raw audio data if one exists

      Returns:
      a PamRawDataBlock or null

    • getRawSourceDataBlock

      @Deprecated public PamRawDataBlock getRawSourceDataBlock(float sampleRate)
      Deprecated.
      Find the absolute source of raw audio data if one exists

      Returns:
      a PamRawDataBlock or null

    • getChainPosition

      public int getChainPosition()

    • getOutputDataBlock

      public PamDataBlock getOutputDataBlock(int block)
      Each process may produce multiple data blocks. This returns the reference to a specific block
      Parameters:
      block - Index of the required block
      Returns:
      PamDataBlock

    • getNumOutputDataBlocks

      public int getNumOutputDataBlocks()
      Returns:
      Total number of PamDataBlocks created by this process

    • addOutputDataBlock

      public void addOutputDataBlock(PamDataBlock outputDataBlock)
      Adds an additional PamDataBlock to the process
      Parameters:
      outputDataBlock - Reference to a PamDataBlock

    • removeOutputDatablock

      public void removeOutputDatablock(PamDataBlock outputDataBlock)

    • hasOutputDatablock

      public boolean hasOutputDatablock(PamDataBlock outputDataBlock)
      Test to see if an output datablock exists.
      Parameters:
      outputDataBlock - Output datablock
      Returns:
      true if the output datablock exists.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • clearOldData

      public void clearOldData()
      Clears all data from all output data blocks of this process.
      This gets called from the main controller at the start of operations. Can be overridden in some classes which don't want to delete existing data or they can set the clearAtStart flag in any data block.

    • resetDataBlocks

      public void resetDataBlocks()
      reset datablocks. Mostly concerned with setting timing counts in row data which may need a bit of an extra kick when handling networked data.

    • prepareProcessOK

      public boolean prepareProcessOK()
      New version of prepareProcess which get's called from PAMController prior to PAMGuard starting up. If a single process returns false from this function, startup will be aborted.

      For backwards compatibility (to save the need to modify every process) there is a default function which simply calls the older prepareProcess() function, then return true, but processes which might fail can override this and return false instead if they so wish.

      Initial motivation for this function was to stop millions of empty files being created when the watchdog is running but the DAQ can't start.

      Returns:
      true if it's looking highly likely that the process is going to start OK.

    • prepareProcess

      public void prepareProcess()
      Called for each process before any of them receive the PamStart command

    • getRequiredDataHistory

      public long getRequiredDataHistory(PamObservable o, Object arg)
      Specified by:
      getRequiredDataHistory in interface PamObserver
      Parameters:
      arg - optional argument from PamObservable
      Returns:
      time in milliseconds required by data held in PamObservable

    • addData

      public final void addData(PamObservable o, PamDataUnit arg)
      Description copied from interface: PamObserver
      Informs the PamObserver that new data have been added to the Observable class
      Specified by:
      addData in interface PamObserver

    • newData

      public void newData(PamObservable o, PamDataUnit arg)

    • updateData

      public void updateData(PamObservable o, PamDataUnit arg)
      Description copied from interface: PamObserver
      Informs the PamObserver that existing data have been updated
      Specified by:
      updateData in interface PamObserver

    • setupProcess

      public void setupProcess()
      called for every process once the systemmodel has been created. this is a good time to check out and find input data blocks and similar tasks.

    • getCpuPercent

      public double getCpuPercent()

    • pamStart

      public abstract void pamStart()
      Called for each process to tell it to start (may not be necessary for processes which are listening for data anyway).

    • pamStop

      public abstract void pamStop()
      Stops the process.

    • removeObservable

      public void removeObservable(PamObservable observable)
      Called when a PamDataBlock observed by this PamProcess is removed.
      Specified by:
      removeObservable in interface PamObserver

    • getPamControlledUnit

      public PamControlledUnit getPamControlledUnit()

    • getAnnotation

      public ProcessAnnotation getAnnotation(PamDataBlock pamDataBlock, int annotation)
      Description copied from interface: ProcessAnnotator
      Get an Annotation
      Specified by:
      getAnnotation in interface ProcessAnnotator
      Parameters:
      pamDataBlock - Annotated datablock
      annotation - annotation number
      Returns:
      Annotation

    • getNumAnnotations

      public int getNumAnnotations(PamDataBlock pamDataBlock)
      Specified by:
      getNumAnnotations in interface ProcessAnnotator
      Parameters:
      pamDataBlock - Annotated datablock
      Returns:
      the number of annotations

    • notifyModelChanged

      public void notifyModelChanged(int changeType)

    • setCanMultiThread

      public void setCanMultiThread(boolean canMultiThread)
      Parameters:
      canMultiThread - the canMultiThread to set

    • isCanMultiThread

      public boolean isCanMultiThread()
      Returns:
      the canMultiThread

    • saveViewerData

      public void saveViewerData()
      Save data (to binary files and to database) in viewer mode.

      This gets called automatically on system exit and can also be called from the file menu.

    • getOfflineData

      public int getOfflineData(PamDataBlock dataBlock, PamObserver endUser, long startMillis, long endMillis, int loadKeepLayers)
      Request offline data.

      This will be called from a PamDatablock in offline viewer mode from requestOfflineData(PamObserver observer, long startMillis, long endMillis).

      this is used to request data from upstream processes, e.g. o get raw data to turn into FFT data units to go to the spectrogram display (possible going via decimators and any other processes before spitting out the right data.

      Parameters:
      dataBlock - data block making the request.
      endUser - observer which made the original data request.
      startMillis - start time in milliseconds
      endMillis - end time in milliseconds.
      loadKeepLayers -
      cancellationObject -
      Returns:
      true if request can be satisfied (or partially satisfied).

    • getOfflineData

      public int getOfflineData(OfflineDataLoadInfo offlineLoadInfo)

    • flushDataBlockBuffers

      public boolean flushDataBlockBuffers(long maxWait)
      Work through all the output datablocks and wait for their internal buffers to flush through.

      This is used when stopping PAMGUARD to ensure that all data complete processing before anything else happens.

      Parameters:
      maxWait - maxWait time in milliseconds.
      Returns:
      true if successful, or false if there was a timeout.

    • processNewBuoyData

      public void processNewBuoyData(BuoyStatusDataUnit dataUnit, PamDataUnit dataUnit2)

    • getOutputDataBlocks

      public ArrayList<PamDataBlock> getOutputDataBlocks()
      Get the full list of output datablocks - used in logger forms so they can all be mapped easily once created.
      Returns:
      the outputDataBlocks

    • getCompatibleDataUnits

      public ArrayList<Class<? extends PamDataUnit>> getCompatibleDataUnits()
      A list of data block class types which are compatible as parent data blocks for the PamProcess. This can return null, e.g. in the case of Acquisition process.
      Returns:
      a list of PamDataBlock sub class types which can be used as parent data blocks for the process.

    • isMultiplex

      public boolean isMultiplex()
      Get whether multiplex data blocks are allowed.
      Returns:
      true if multiplex data blocks is enabled

    • setMultiplex

      public void setMultiplex(boolean isMultiplex)
      Set whether multiplex data blocks are allowed.
      Parameters:
      true - if multiplex data blocks is enabled

    • isExternalProcess

      public boolean isExternalProcess()
      Check whether the process can accept parent data blocks from other PamControlledUnits
      Returns:
      true to accept external data blocks from other PamControlledUnits.

    • setExternalProcess

      public void setExternalProcess(boolean isExternalProcess)
      Set whether the process can accept parent data blocks from other PamControlledUnits

    • getMuiltiplexDataBlock

      public PamDataBlock getMuiltiplexDataBlock(int block)
      Get a multiplex data block.
      Parameters:
      block - - datablock index
      Returns:
      a multiplex data block.

    • getNumMuiltiplexDataBlocks

      public int getNumMuiltiplexDataBlocks()
      Get the number of multiplex datablocks.
      Returns:
      the number of multiplex data blocks.

    • addMultiPlexDataBlock

      public void addMultiPlexDataBlock(PamDataBlock pamDataBlock)
      Adds the process as an observer to the data block.
      Parameters:
      pamDataBlock - - the datablock to add.

    • removeMultiPlexDataBlock

      public void removeMultiPlexDataBlock(PamDataBlock pamDataBlock)
      Remove the process from a data block and remove datablock from list of multiplex datablocks.
      Parameters:
      pamDataBlock - - the data block to remove.

    • removeAllMultiPlexDataBlocks

      public void removeAllMultiPlexDataBlocks(ArrayList<PamDataBlock> pamDataBlocks)
      Remove a list of multiplex data blocks.
      Parameters:
      pamDataBlocks - -data blocks to remove.

    • receiveSourceNotification

      public void receiveSourceNotification(int type, Object object)
      Description copied from interface: PamObserver
      Receive a notification from the data source - typically a change in DAQ status. See the constants listed in AcquisitionProcess for potential change types.
      Specified by:
      receiveSourceNotification in interface PamObserver
      Parameters:
      type - the type of change
      object - generic object added here so that we can include anything in the future

    • getLastSourceNotificationType

      public int getLastSourceNotificationType()
      Returns:
      the lastSourceNotificationType

    • getLastSourceNotificationObject

      public Object getLastSourceNotificationObject()
      Returns:
      the lastSourceNotificationObject

    • dumpBufferStatus

      public void dumpBufferStatus(String message, boolean sayEmpties)
      Say the status of any buffers, particularly in output buffers of data blocks, but can add bespoke info for other internal buffers for some processes.
      Parameters:
      message -
      sayEmpties - include info even if a buffer is empty.