Merge desktop and api changes

.github/workflows/build-installers.yml

@@ -0,0 +1,106 @@
+name: Build Installers
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        include:
+          - os: windows-latest
+            requirements_tf: requirements_tf.txt
+            architecture: windows-x64
+          - os: macos-latest
+            requirements_tf: requirements_tf_mac.txt
+            architecture: macos-arm64
+
+    steps:
+    - name: Checkout repo
+      uses: actions/checkout@v6
+
+    - name: Write release version
+      shell: bash
+      run: |
+        VERSION="${GITHUB_REF_NAME#v}"
+        echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+
+    - name: Get data from private repo
+      uses: actions/checkout@v6
+      with:
+        repository: luomus/bird-identification-app-data
+        token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+        path: private-data
+
+    - name: Move data to correct places (Windows)
+      if: startsWith(matrix.os, 'windows-')
+      run: |
+        Remove-Item -Recurse -Force app\models
+        Move-Item private-data\default-models app\models
+        Expand-Archive -Path private-data\InstallForge.zip -DestinationPath app
+
+    - name: Move data to correct places (macOS)
+      if: startsWith(matrix.os, 'macos-')
+      run: |
+        rm -rf app/models
+        mv private-data/default-models app/models
+
+    - name: Install create-dmg (macOS)
+      if: startsWith(matrix.os, 'macos-')
+      run: |
+        brew install create-dmg
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.9'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install ..
+        pip install -r requirements.txt
+        pip install -r ${{ matrix.requirements_tf }}
+        pip install pyinstaller
+      working-directory: ./app
+
+    - name: Set correct version numbers
+      shell: bash
+      run: |
+        python replace_version.py "${VERSION}" "${{ matrix.architecture }}"
+      working-directory: ./app
+
+    - name: Build executable with PyInstaller
+      run: |
+        pyinstaller app.spec --noconfirm
+      working-directory: ./app
+
+    - name: Build Windows installer with InstallForge
+      if: startsWith(matrix.os, 'windows-')
+      run: |
+        .\ifbuildx86.exe -i ..\..\app.ifp
+      working-directory: ./app/InstallForge/bin
+
+    - name: Build macOS Disk Image with create-dmg
+      if: startsWith(matrix.os, 'macos-')
+      run: |
+        ./build_dmg.sh
+      working-directory: ./app
+
+    - name: Upload installer (Windows)
+      if: startsWith(matrix.os, 'windows-')
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ matrix.architecture }}-installer
+        path: .\app\dist\sirkku-*-setup.exe
+
+    - name: Upload installer (macOS)
+      if: startsWith(matrix.os, 'macos-')
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ matrix.architecture }}-installer
+        path: ./app/dist/sirkku-*.dmg

.gitignore

@@ -2,9 +2,21 @@
 input/*
 !input/readme.txt
 
-models/model_v3.5.keras
-models/model*.keras
-
+models/*
+!models/readme.txt
+!models/Pred_adjustment
+!models/classes.csv
+!models/license_birdnet.txt
+!models/BirdNET_GLOBAL_6K_V2.4_Model_FP32.tflite
+
+app/models/*
+!app/models/.gitkeep
+!app/models/default
+app/models/default/*
+!app/models/default/.gitkeep
+app/custom_models/
+
+app/InstallForge/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -33,12 +45,13 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+api/config/*_local.json
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
-*.spec
+#*.spec
 
 # Installer logs
 pip-log.txt
@@ -167,4 +180,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
+
+run/*
+api/config/uvicorn_start

README.md

@@ -2,14 +2,21 @@
 
 This repository provides tools for automated bird species detection from audio recordings and for generating quality control reports. It supports local processing and API-based workflows and is built on an AI model developed at the University of Jyväskylä as part of the [Muuttolintujen kevät -project](https://www.jyu.fi/en/research/muuttolintujen-kevat).
 
+## Project Structure
+
+- `shared/` — Shared code: classifier and functions
+- `api/` — HTTP API (FastAPI)
+- `cli/` — Command-line scripts for local analysis and report generation
+- `app/` — Desktop application
+
 ## Features
 
 - Analyzes audio recordings (WAV, MP3, FLAC) to detect bird species, either locally or via API
-  - Files are divided into smaller chunks based on chunk_size parameter, because the model has a limit on the input size. There chunks are then divided into segments of clip_dur seconds (currently fixed to 3 seconds), and overlap parameter defines how much of each segment is overlapped with the next segment.
+- Files are divided into smaller chunks based on chunk_size parameter, because the model has a limit on the input size. There chunks are then divided into segments of clip_dur seconds (currently fixed to 3 seconds), and overlap parameter defines how much of each segment is overlapped with the next segment.
 - Uses species distribution and temporal modeling to improve detection accuracy
 - Handles batch processing of multiple audio files
 - Generates reports with species statistics and sample audio clips to help verifying the results
-- Desktop application in development
+- Desktop application for users who prefer a graphical interface
 
 ## Setup
 
@@ -26,115 +33,19 @@ This repository provides tools for automated bird species detection from audio r
 - `git clone`
 - `cd bird-identification`
 - Place models to the `/models` folder: BirdNET and Muuttolintujen kevät
-- `docker compose up --build; docker compose down;`
-- Access the running docker container:
-  - `docker exec -ti bird-identification bash`
-  - Run the scripts, see below
+- `docker compose up --build # start both cli and api`
+- `docker compose up cli --build # start only cli`
+- `docker compose up api --build # start only api`
+- Desktop app has another setup, see [app/README.md](app/README.md)
 
 ### Running unit tests
 
-Test can be run from the host machine using Docker Compose:
+From the host machine:
 
 - `docker compose run --rm test`
 
-Test can also be run from within the container:
-
-- `docker exec -ti bird-identification bash`
-- `pytest /app/tests -v`
-
 ## Usage
 
-### Identifying species locally
-
-This analyzes audio files and generates tabular text files containing the identifications, one file for each audio file.
-
-- Place audio files to a folder under `/input`, for example `/input/my_backyard_2025-01`.
-- Place `metadata.yaml` file in the same folder. This contains information that is shared by all the files. Example format:
-
-```yaml
-lat: 60.123
-lon: 24.123 
-day_of_year: 152 # Note: this will be overridden if audio file names include a date
-```
-
-- Run the script with `python main.py --dir <subfolder>`
-- Optional parameters:
-  - `--thr`: Detection threshold as a decimal number between 0<>1, default 0.5
-  - `--noise`: Include noise in the output, default False
-  - `--sdm`: Use species distribution model to adjust confidence values, default False
-  - `--skip`: Skip audio files that already have a corresponding result file, default False
-  - `--overlap`: Overlap of segments to be analyzed in seconds, default 1.
-  - `--chunk_size`: Audio files are cut into chunks for analysis. This defines the size in seconds, default 600.
-
-#### Note
-
-- Expects that
-  - Audio filenames are in format `[part1].[extension]`
-  - Extension is `wav`, `mp3` or `flac`, case-insensitive
-- If classification stops with message "Killed", try restarting the Docker container. It's unclear what causes this issue.
-- The model and/or classifier has limitations:
-  - Segments can't be too long. 10 minutes seem to work fine, 30 minutes are too long.
-  - Overlap can't be too high. 1 second works fine, 2 seconds doesn't. Longer overlap leads to "Killed" message.
-
-### Generating validation report
-
-This reads tabular files containing species identifications, and generates an HTML report with example audio files for validation, and statistics and charts of the species.
-
-- First do species identification, see above. You can also use BirdNET to do the identifications (use csv export format.)
-- Validation report generation expects that:
-  - Data files are in the same directory as the audio files and in format `[part1].[part2].results.csv`
-  - Data files have columns: `Start (s), End (s), Scientific name, Common name, Confidence, [Optional columns]`
-- Run the script with `python main_report.py --dir <subfolder>`
-- Optional parameters:
-  - `--thr`: Detection threshold as a decimal number between 0<>1, default 0.5
-  - `--padding`: Padding in seconds for example audio files, default 1.
-  - `--examples`: Number of example audio files to pick for each species, minimum 5, default 5.
-
-### Identifying species using API
-
-Submit data to endpoint `/classify`.
-
-A bare minimum call with mandatory `latitude` and `longitude` parameters looks like this:
-
-```bash
-curl -X POST "http://localhost:8000/classify?latitude=60.1699&longitude=24.9384" \
-  -H "accept: application/json" \
-  -H "Content-Type: multipart/form-data" \
-  -F "file=@<path_to_audio_file>"
-```
-
-Call with all parameters:
-
-```bash
-curl -X POST "http://localhost:8000/classify?latitude=60.1699&longitude=24.9384&threshold=0.5&include_sdm=True&include_noise=True&day_of_year=1&chunk_size=500&overlap=1" \
-  -H "accept: application/json" \
-  -H "Content-Type: multipart/form-data" \
-  -F "file=@<path_to_audio_file>"
-```
-
-#### Note
-
-- Day of year can be set as a parameter, but if not, today's date is used.
-
-## Todo
-
-- Analysis
-  - Include inference details in the analysis result file, or at least identify the inference file?
-  - Refactor to handle settings in a centralized way, so that adding new parameters is easier
-  - Add clip_dur as a parameter
-  - Include both sdm and non-sdm predictions in the output
-  - Add taxon MX codes to the output
-  - Check why comparison-audio files are sometimes split into 5, 6 or 7 segments
-- Report
-  - If data from one day only, don't create date histogram
-  - Include inference metadata into the report, so that it can be shared independently. But what to do if there are multiple inference files?
-  - Species commonness: how many % of observations from that area (+- 100 km) and time (+-10 days) are this species
-  - Normalize x-axis for all temporal charts. Get first and last time from the original data when it's loaded?
-  - Histograms are not made for species with only few detections. However, <img> tag is generated for these on the result service. Would be elegant not to have broken image links, though they are not visible for users.
-- Misc
-  - Organizing the repos: continue with this repo, include baim features. Then rethink whether this tool and analysis (Bart) tool should be bundled together. And how to manage web interface vs. desktop app.
-  - Error handling when functions return None
-  - More unit testing
-  - Handle file paths in a more consistent ways (directory path, file name, datetime from filename)
-
-
+- For command line tool, see [cli/README.md](cli/README.md)
+- For API, see [api/README.md](api/README.md)
+- For desktop app, see [app/README.md](app/README.md)

api/Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.9-slim
+
+WORKDIR /app
+
+# Install TensorFlow separately with increased timeout
+# The model requires TensorFlow 2.14.0
+COPY api/requirements-tf.txt .
+RUN pip install --no-cache-dir --timeout=1000 -r requirements-tf.txt
+
+RUN apt-get update
+RUN apt-get install libexpat1 -y
+RUN apt-get install curl -y
+
+COPY api/requirements.txt .
+
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy shared package and api package
+COPY shared/ /app/shared/
+COPY api/ /app/api/
+
+EXPOSE 8000
+
+CMD ["uvicorn", "api.api:app", "--host", "0.0.0.0", "--port", "8000"]

api/README.md

@@ -0,0 +1,25 @@
+# Identifying species using API
+
+Submit data to endpoint `/classify`.
+
+A bare minimum call with mandatory `latitude` and `longitude` parameters looks like this:
+
+```bash
+curl -X POST "http://localhost:8000/classify?latitude=60.1699&longitude=24.9384" \
+  -H "accept: application/json" \
+  -H "Content-Type: multipart/form-data" \
+  -F "file=@<path_to_audio_file>"
+```
+
+Call with all parameters:
+
+```bash
+curl -X POST "http://localhost:8000/classify?latitude=60.1699&longitude=24.9384&threshold=0.5&include_sdm=True&include_noise=True&day_of_year=1&chunk_size=500&overlap=1" \
+  -H "accept: application/json" \
+  -H "Content-Type: multipart/form-data" \
+  -F "file=@<path_to_audio_file>"
+```
+
+#### Note
+
+- Day of year can be set as a parameter, but if not, today's date is used.