Updates for Docker tags and README

Author: bluemellophone

.github/workflows/docker-publish.yaml

@@ -58,7 +58,8 @@ jobs:
       # Push bleeding-edge image ("<branch name>" tag) to registries
       - name: Bleeding Edge Docker Hub (Default Option)
         run: |
-          echo "IMAGE_TAG=${GITHUB_REF_NAME}" >> $GITHUB_ENV
+          TAG=$(echo ${GITHUB_REF_NAME} | sed 's/\//-/')
+          echo "IMAGE_TAG=${TAG}" >> $GITHUB_ENV
 
       # Push nightly image ("nightly" tag) to registries
       - name: Nightly Docker Hub

README.rst

@@ -46,45 +46,56 @@ 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.
+* 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
 --------------