You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.rst
+92-4Lines changed: 92 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,94 @@ Kitware BatBot
9
9
10
10
.. sectnum::
11
11
12
+
Development Environment
13
+
-----------------------
14
+
15
+
.. code-block:: bash
16
+
# Find repo on host machine
17
+
cd~/code/batbot
18
+
19
+
# Build Docker image
20
+
docker build -t kitware/batbot:latest .
21
+
22
+
# Start Docker container using image
23
+
docker run \
24
+
-it \
25
+
--rm \
26
+
--entrypoint bash \
27
+
--name batbot \
28
+
-v $(pwd):/code \
29
+
kitware/batbot:latest
30
+
31
+
########################
32
+
# Inside the container #
33
+
########################
34
+
35
+
# Activate Python environment
36
+
source /venv/bin/activate
37
+
38
+
# Install local version
39
+
pip install -e .
40
+
41
+
# Run batbot
42
+
batbot --help
43
+
44
+
Spectrogram Extraction
45
+
----------------------
46
+
47
+
Here are the steps for extracting the compressed spectrogram:
48
+
49
+
* Create the STFT
50
+
51
+
* Load the original waveform at the original sample rate
52
+
* Resample waveform to 250kHz
53
+
* Convert to a STFT spectrogram (fft=512, method=blackmanharris, window=256, hop=16)
54
+
* Convert complex power STFT to amplitude STFT (dB)
55
+
56
+
* Normalize the STFT
57
+
58
+
* Trim STFT to minimum and maximum frequencies (5kHz to 120kHz)
59
+
* Subtract the per-freqency median dB (reduce any spectral bias / shift)
60
+
* Set global dynamic range to -80 dB from the global maximum amplitude
61
+
* Calculate the global median non-minimum dB (greater than -80dB)
62
+
* Calculate the median absolute deviation (MAD)
63
+
* Autogain the dynamic range to (5 * MAD) below the global amplitude median, if necessary
64
+
65
+
* Quantize the STFT
66
+
67
+
* Quantize the floating-point amplitude STFT to a 16-bit integer representation spanning the full dynamic range (65,536 bins)
68
+
* Vertically flip the spectrogram (low frequencies on bottom) and convert to a C-contiguous array
69
+
70
+
* Find Candidate Chirps
71
+
72
+
* Create a 12ms sliding window with a 3ms stride
73
+
* Keep the time windows that show a substantial right-skew across 10% of the frequency range
74
+
* Add any user-provided time windows (annotations) to the found candidates windows
75
+
* Merge any overlapping time windows into a set of contiguous time ranges
76
+
* Tighten the candidate time ranges (and separate as needed) by repeating the same skew-based filter with a smaller sliding window and stride
77
+
78
+
* Extract Chirp Metrics
79
+
80
+
* *for each candidate chirp*
81
+
* *Start*: First, find the peak amplitude location.
82
+
* 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)
83
+
* Step 2 - Apply a median filter and re-normalize
84
+
* Step 3 - Apply a morphological open operation
85
+
* Step 4 - Blur the chirp (k=5) and re-normalize
86
+
* 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
87
+
* Step 6 - Extract a segmentation mask for the contour
88
+
* 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.
89
+
* 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.
90
+
* Step 9 - Solve a minimum distance optimization using A* that also maximizes the amplutide values from start to end points.
91
+
* Step 10 - Smooth the contour path, extract the contour's slope, then identify the knee, heel, and other defining attributes.
92
+
* *End*: Finally, if any of the above steps fails, or the chirp's attributes do not make semantic sense, then skip the candidate chirp.
93
+
94
+
* Create Output
95
+
96
+
* Collect all valid chirps regions and metadata, create a compressed spectrogram
97
+
* Write the 16-bit spectrogram as a series of 8-bit JPEGs image chunks (max width per chunk 50k pixels)
98
+
* Write the file and chirp metadata to a JSON file.
The code base has been formatted by `Black <https://black.readthedocs.io/en/stable/>`_. Furthermore, try to conform to ``PEP8``. You should set up your preferred editor to use ``flake8`` as its Python linter, but pre-commit will ensure compliance before a git commit is completed. This will use the ``flake8`` configuration within ``setup.cfg``, which ignores several errors and stylistic considerations. See the ``setup.cfg`` file for a full and accurate listing of stylistic codes to ignore.
0 commit comments