Major restructure of pgmatlab for v2

- Move code into object-oriented structure, whilst keeeping
loadPamguardBinaryFile, loadPamguardBinaryFolder and loadPamguardMultiFile
the same.
- Add a testing suite to compare the new v2 code with the
'legacy' v1 code.
- Integrate the testing suite into GitHub actions for an automated
testing and distribution workflow.

Author: sullivan-james

.github/workflows/build-package.yml

@@ -0,0 +1,36 @@
+# This workflow will automatically create a ZIP file
+# of the distribution files, and add them to a GitHub
+# release. It only runs, on creation of the GitHub
+# release.
+
+name: Build Package
+
+on:
+  release:
+    types: [published]
+    
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Zip code to distribute
+      run: |
+        zip -r "pgmatlab-${{ github.event.release.tag_name }}.zip" pgmatlab/* LICENSE README.md
+
+    - name: Upload code to distribute
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist-files
+        path: "pgmatlab-${{ github.event.release.tag_name }}.zip"
+
+    - name: Append distribution code to release
+      uses: softprops/action-gh-release@v2
+      with:
+        files: "pgmatlab-${{ github.event.release.tag_name }}.zip"

.github/workflows/matlab-testing.yml

@@ -0,0 +1,38 @@
+name: MATLAB Testing
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the "main" branch
+  push:
+    branches: [ "dev" ]
+  pull_request:
+    branches: [ "dev" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build:
+    # The type of runner that the job will run on
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        matlab-version: [r2020a, r2021a, r2022a, r2023a, r2025a]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+        
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up MATLAB
+        uses: matlab-actions/setup-matlab@v2.1.2
+        with:
+          version: ${{ matrix.matlab-version }}
+
+      - name: Run MATLAB Tests
+        uses: matlab-actions/run-tests@v2.1.2
+        with:
+          select-by-folder: tests

pgmatlab/.MATLABDriveTag

@@ -0,0 +1,15 @@
+
+classdef BeamFormer < StandardAnnotation
+    methods
+        function obj = BeamFormer(); end
+        function [data, selState] = read(obj, fid, data, fileInfo, anLength, anVersion); 
+            [data, selState] = read@StandardAnnotation(obj, fid, data, fileInfo, anLength, anVersion);
+            
+            data.hydrophones = fread(fid, 1, 'uint32');
+            data.arrayType = fread(fid, 1, 'int16');
+            data.localisationContent = fread( fid, 1, 'uint32');
+            data.nAngles = fread(fid, 1, 'int16');
+            data.angles = fread(fid, data.nAngles, 'float32');
+        end
+    end
+end

pgmatlab/Array/.MATLABDriveTag

@@ -0,0 +1,23 @@
+
+classdef Bearing < StandardAnnotation
+    methods
+        function obj = Bearing(); end
+        function [data, selState] = read(obj, fid, data, fileInfo, anLength, anVersion); 
+            [data, selState] = read@StandardAnnotation(obj, fid, data, fileInfo, anLength, anVersion);
+            
+            data.algorithmName = readJavaUTFString(fid);
+            data.version = annotationVersion;
+            data.hydrophones = fread(fid, 1, 'uint32');
+            data.arrayType = fread(fid, 1, 'int16');
+            data.localisationContent = fread( fid, 1, 'uint32');
+            data.nAngles = fread(fid, 1, 'int16');
+            data.angles = fread(fid, data.nAngles, 'float32');
+            data.nErrors = fread(fid, 1, 'int16');
+            data.errors = fread(fid, data.nErrors, 'float32');
+            if (annotationVersion >= 2) 
+                nAng = fread(fid, 1, 'int16');
+                data.refAngles = fread(fid, nAng, 'float32')
+            end
+        end
+    end
+end

pgmatlab/core/annotations/@BeamFormer/BeamFormer.m

@@ -0,0 +1,14 @@
+classdef ClickClsFr < StandardAnnotation
+    methods
+        function obj = ClickClsFr(); end
+        function [data, selState] = read(obj, fid, data, fileInfo, anLength, anVersion); 
+            [data, selState] = read@StandardAnnotation(obj, fid, data, fileInfo, anLength, anVersion);
+            
+            nclassifications = fread(fid, 1, 'int16');
+            for i = 1:nclassifications
+                data.classify_set(i) = fread(fid, 1, 'int16');
+            end
+        end
+    end
+end
+

pgmatlab/core/annotations/@Bearing/Bearing.m

@@ -0,0 +1,64 @@
+classdef DL < StandardAnnotation
+    properties
+        name = 'dlclassification';
+    end
+
+    methods (Access = private)
+        function modeldata =  readModelData(~, fid)
+            
+            modeltype = fread(fid, 1, 'char'); % bye in Java
+
+            isbinary = fread(fid, 1, 'char'); % bye in Java
+            isbinary = isbinary~=0; % boolean is stored as byte in Java
+            scale = fread(fid, 1, 'float'); % the scale for prediciton results - short in Java
+            nspecies = fread(fid, 1, 'int16'); % the scale for prediciton results - short in Java
+            
+            % read prediciton results
+            tempdata=-1*ones(length(nspecies),1);
+            for j=1:nspecies
+                tempdata(j) = fread(fid, 1, 'int16')/scale;
+            end
+            
+            % get the class name IDs
+            nclass = fread(fid, 1, 'int16'); % the number of class names.classnames
+            classnames=-1*ones(length(nclass),1);
+            for j=1:nclass
+                classnames(j) = fread(fid, 1, 'int16');
+            end
+            
+            switch (modeltype)
+                
+                case 0 % generic deep learning annotation
+                    modeldata.predictions = tempdata;
+                    modeldata.classID = classnames;
+                    modeldata.isbinary = isbinary;
+                    modeldata.type = modeltype;
+                case 1 % Sound Spot classifier. 
+                    % Sound spot
+                    modeldata.predictions = tempdata;
+                    modeldata.classID = classnames;
+                    modeldata.isbinary = isbinary;
+                    modeldata.type = modeltype;
+
+                case 2 % dummy result
+                    modeldata.predictions = []; 
+                    modeldata.type = 'dummy'; 
+            end
+        end
+    end
+
+    methods
+        function obj = DL(); end
+        function [data, selState] = read(obj, fid, fileInfo, anLength, anVersion); 
+            nummodels = fread(fid, 1, 'int16'); % short in Java
+
+            % disp(['Num models: ' num2str(nummodels)])
+            % read the data from each model.
+            % data = zeros(1, nummodels);
+            for i=1:nummodels
+                data(i) = obj.readModelData(fid);
+            end
+        end
+    end
+end
+

pgmatlab/core/annotations/@ClickClsFr/ClickClsFr.m

@@ -0,0 +1,51 @@
+classdef MatchCls < StandardAnnotation
+    methods
+        function obj = MatchCls(); end
+        function [data, selState] = read(obj, fid, data, fileInfo, anLength, anVersion); 
+            [data, selState] = read@StandardAnnotation(obj, fid, data, fileInfo, anLength, anVersion);
+            
+            if (anVersion==1)
+                    %the threshold value. This is used to classify the clicks.
+                threshold = fread(fid, 1, 'double');
+            
+                %the maximum correlation between the match template and the click
+                matchcorr = fread(fid, 1, 'double');
+                
+                %the max correlation value between the reject template and the click.
+                rejectcorr = fread(fid, 1, 'double');
+                
+                data = [threshold matchcorr rejectcorr]; 
+                
+            end
+
+            % new version with multiple templates. 
+            if (anVersion==2)
+                %read the number of templates there are
+                ntemplates = fread(fid, 1, 'int16'); % short in Java
+
+                n=1; 
+                data=zeros(ntemplates,3); % pre allocate the data array, 
+                for i=1:ntemplates
+                    
+                    %the threshold value. This is used to classify the clicks.
+                    threshold = fread(fid, 1, 'double');
+                    
+                    %the maximum correlation between the match template and the click
+                    matchcorr = fread(fid, 1, 'double');
+                    
+                    %the max correlation value between the reject template and the click.
+                    rejectcorr = fread(fid, 1, 'double');
+                    
+                    data(n,1)   =   threshold;
+                    data(n,2)   =   matchcorr;
+                    data(n,3)   =   rejectcorr;
+                    n=n+1; 
+                    
+                end
+            end
+        end
+    end
+end
+
+
+

pgmatlab/core/annotations/@DL/DL.m

@@ -0,0 +1,15 @@
+classdef RWUDP < StandardAnnotation
+    methods
+        function obj = RWUDP(); end
+        function [data, selState] = read(obj, fid, data, fileInfo, anLength, anVersion); 
+            [data, selState] = read@StandardAnnotation(obj, fid, data, fileInfo, anLength, anVersion);
+            
+            data.label = readJavaUTFString(fid);
+            data.method = readJavaUTFString(fid);
+            data.score = fread(fid, 1, 'float32');
+        end
+    end
+end
+
+
+