Updates for Docker build

Author: bluemellophone

.github/workflows/docker-publish.yaml

@@ -55,25 +55,24 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      # Push tagged image (version tag + latest) to registries
-      - name: Tagged Docker Hub
-        if: ${{ github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v') }}
-        run: |
-          VERSION=$(echo ${GITHUB_REF} | sed 's#.*/v##')
-          echo "IMAGE_TAG=${VERSION}" >> $GITHUB_ENV
-
-      # Push bleeding-edge image (main tag) to registries
-      - name: Bleeding Edge Docker Hub
-        if: github.ref == 'refs/heads/main'
+      # Push bleeding-edge image ("<branch name>" tag) to registries
+      - name: Bleeding Edge Docker Hub (Default Option)
         run: |
-          echo "IMAGE_TAG=main" >> $GITHUB_ENV
+          echo "IMAGE_TAG=${GITHUB_REF_NAME}" >> $GITHUB_ENV
 
-      # Push nightly image (nightly tag) to registries
+      # Push nightly image ("nightly" tag) to registries
       - name: Nightly Docker Hub
         if: github.event_name == 'schedule'
         run: |
           echo "IMAGE_TAG=nightly" >> $GITHUB_ENV
 
+      # Push tagged image ("<symantic version>" tag) to registries
+      - name: Tagged Docker Hub
+        if: ${{ github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v') }}
+        run: |
+          VERSION=$(echo ${GITHUB_REF} | sed 's#.*/v##')
+          echo "IMAGE_TAG=${VERSION}" >> $GITHUB_ENV
+
       # Build images
       - name: Build Batbot
         run: |

ISSUES.rst

@@ -2,4 +2,9 @@
 Known Issues
 ============
 
-N/A
+TODO:
+- Fix CI/CD docker build
+- Add API documentation, tutorials, and examples
+- Create example notebooks with Google colab
+- Crate discord / discourse community board
+- [BatAI] Upload training scripts with MLFlow support, database export with celery

README.rst

@@ -41,6 +41,51 @@ Development Environment
     # Run batbot
     batbot --help
 
+Spectrogram Extraction
+----------------------
+
+Here are the steps for extracting the compressed spectrogram:
+
+- Create the STFT
+  - Load the original waveform at the original sample rate
+  - Resample waveform to 250kHz
+  - Convert to a STFT spectrogram (fft=512, method=blackmanharris, window=256, hop=16)
+  - Convert complex power STFT to amplitude STFT (dB)
+- Normalize the STFT
+  - Trim STFT to minimum and maximum frequencies (5kHz to 120kHz)
+  - Subtract the per-freqency median dB (reduce any spectral bias / shift)
+  - Set global dynamic range to -80 dB from the global maximum amplitude
+  - Calculate the global median non-minimum dB (greater than -80dB)
+  - Calculate the median absolute deviation (MAD)
+  - Autogain the dynamic range to (5 * MAD) below the global amplitude median, if necessary
+- Quantize the STFT
+  - Quantize the floating-point amplitude STFT to a 16-bit integer representation spanning the full dynamic range (65,536 bins)
+  - Vertically flip the spectrogram (low frequencies on bottom) and convert to a C-contiguous array
+- Find Candidate Chirps
+  - Create a 12ms sliding window with a 3ms stride
+  - Keep the time windows that show a substantial right-skew across 10% of the frequency range
+  - Add any user-provided time windows (annotations) to the found candidates windows
+  - Merge any overlapping time windows into a set of contiguous time ranges
+  - Tighten the candidate time ranges (and separate as needed) by repeating the same skew-based filter with a smaller sliding window and stride
+- Extract Chirp Metrics
+  - *for each candidate chirp*
+  - *Start*: First, find the peak amplitude location.
+  - Step 1 - Normalize the chirp to the full 16-bit range.  Calculate a histogram and identify the most common dB and standard deviation.  Scale the amplitude values using an inverted PDF, weighting each value by its inverse probability of being noise (values below the most common dB are set to zero)
+  - Step 2 - Apply a median filter and re-normalize
+  - Step 3 - Apply a morphological open operation
+  - Step 4 - Blur the chirp (k=5) and re-normalize
+  - Step 5 - Find contours using the "marching squares" algorithm and select the one that contains the peak amplitude.  Extract the convex hull of the contour and smooth the resulting outline
+  - Step 6 - Extract a segmentation mask for the contour
+  - Step 7 - Locate the harmonic (doubling the frequency) and echo (right edge of the contour to the end of the chirp time range) regions.  Remove any overlapping noise from the chirp contour.
+  - Step 8 - Locate the start, end, and characteristic frequency points (peak amplitude) and calculate an optimization cost grid for the contour using the masked amplitudes.
+  - Step 9 - Solve a minimum distance optimization using A* that also maximizes the amplutide values from start to end points.
+  - Step 10 - Smooth the contour path, extract the contour's slope, then identify the knee, heel, and other defining attributes.
+  - *End*: Finally, if any of the above steps fails, or the chirp's attributes do not make semantic sense, then skip the candidate chirp.
+- Create Output
+  - Collect all valid chirps regions and metadata, create a compressed spectrogram
+  - Write the 16-bit spectrogram as a series of 8-bit JPEGs image chunks (max width per chunk 50k pixels)
+  - Write the file and chirp metadata to a JSON file.
+
 How to Install
 --------------
 

batbot/spectrogram/__init__.py

@@ -831,7 +831,7 @@ def calculate_astar_grid_and_endpoints(
     costs = segment.copy()
     segmentmask_ = np.logical_not(segmentmask)
     costs[segmentmask_] = 0
-    write_contour_debug_image(costs, index, 7, 'costs', output_path=output_path)
+    write_contour_debug_image(costs, index, 8, 'costs', output_path=output_path)
 
     ys, xs = np.where(costs > 0)
     points = np.stack([ys, xs], axis=1, dtype=np.float32)
@@ -880,7 +880,7 @@ def calculate_astar_grid_and_endpoints(
         cv2.circle(canvas, begin[::-1], 5, (0, value, 0), -1)
         cv2.circle(canvas, end[::-1], 5, (0, 0, value), -1)
 
-        write_contour_debug_image(canvas, index, 7, 'endpoints', output_path=output_path)
+        write_contour_debug_image(canvas, index, 8, 'endpoints', output_path=output_path)
 
     costs = segment.astype(np.float32)
     segmentmask_ = segmentmask.astype(np.float32)
@@ -1261,7 +1261,7 @@ def calculate_harmonic_and_echo_flags(
 
 @lp
 def compute_wrapper(
-    wav_filepath, annotations=None, output_folder='.', bitdepth=16, debug=False, **kwargs
+    wav_filepath, annotations=None, output_folder='.', bitdepth=16, debug=True, **kwargs
 ):
     """
     Compute the spectrograms for a given input WAV and saves them to disk.
@@ -1396,12 +1396,12 @@ def compute_wrapper(
             original, index, segmentmask, harmonic, echo, canvas, output_path=debug_path
         )
 
-        # Step 8 - Remove harmonic and echo from segmentation
+        # Remove harmonic and echo from segmentation
         segment = remove_harmonic_and_echo(
             segment, index, harmonic, echo, threshold, output_path=debug_path
         )
 
-        # Step 7 - Calculate the A* cost grid and start/end points
+        # Step 8 - Calculate the A* cost grid and start/end points
         costs, grid, begin, end, boundary = calculate_astar_grid_and_endpoints(
             segment, index, segmentmask, peak, canvas, output_path=debug_path
         )
@@ -1414,15 +1414,15 @@ def compute_wrapper(
         if not significant:
             continue
 
-        # Step 8 - Extract optimal path from start to end using the cost grid
+        # Step 9 - Extract optimal path from start to end using the cost grid
         path = extract_contour_path(grid, begin, end, canvas, index, output_path=debug_path)
 
-        # Step 9 - Extract contour keypoints
+        # Step 10 - Extract contour keypoints
         path_smoothed, (knee, fc, heel), slopes = extract_contour_keypoints(
             path, canvas, index, peak, output_path=debug_path
         )
 
-        # Step 10 - Collect chirp metadata
+        # Step 11 - Collect chirp metadata
         metadata = {
             'curve.(khz,ms)': [
                 (