pumaguard 21.post108

No project description provided

PumaGuard

Introduction

Please visit http://pumaguard.rtfd.io/ for more information.

Get PumaGuard

GitHub Codespaces

If you do not want to install any new software on your computer you can use GitHub Codespaces, which provide a development environment in your browser.

Local Development Environment

You can set up a local development environment using either uv (recommended for speed) or poetry.

Using uv (Recommended)

uv is an extremely fast Python package installer and resolver.

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or on Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Create a virtual environment and install dependencies:

uv venv
source .venv/bin/activate  # On Linux/macOS
# or
.venv\Scripts\activate  # On Windows

# Install with development dependencies
uv pip install -e ".[dev,extra-dev]"

Or use uv sync for automatic environment management:

uv sync --extra dev --extra extra-dev

Using Poetry

Alternatively, you can use poetry:

sudo apt install python3-poetry
poetry install

Running the scripts on colab.research.google.com

Google Colab offers runtimes with GPUs and TPUs, which make training a model much faster. In order to run the training script in Google Colab, do the following from the terminal:

git clone https://github.com/PEEC-Nature-Youth-Group/pumaguard.git
cd pumaguard
scripts/train.py --help

For example, if you want to train the model from row 1 in the notebook,

scripts/train.py --notebook 1

Web UI

PumaGuard includes a modern Flutter-based web interface for monitoring and configuration.

Starting the Web UI

Using uv:

uv run pumaguard-webui --host 0.0.0.0 --port 5000

Using poetry:

poetry run pumaguard-webui --host 0.0.0.0 --port 5000

The web interface will be accessible at http://your-server-ip:5000 or http://pumaguard.local:5000 (if mDNS is enabled).

mDNS/Zeroconf Support

PumaGuard supports automatic server discovery via mDNS (also known as Bonjour or Zeroconf). This allows clients to connect using a friendly hostname like pumaguard.local instead of needing to know the IP address.

Setup mDNS on the server:

• Linux: Install Avahi

  sudo apt install avahi-daemon avahi-utils
  sudo systemctl enable avahi-daemon
  sudo systemctl start avahi-daemon
  

• macOS: Built-in, no setup needed

• Windows: Install Bonjour Print Services

Using mDNS:

Once mDNS is set up, your server will be automatically discoverable at:

http://pumaguard.local:5000

You can customize the hostname:

pumaguard-webui --mdns-name my-server
# Accessible at: http://my-server.local:5000

Or disable mDNS:

pumaguard-webui --no-mdns

For detailed mDNS setup instructions including Docker/container configurations, see docs/MDNS_SETUP.md.

Running the server

The pumaguard-server watches a folder and classifies new files as they are added to that folder.

Basic Usage

Using uv:

uv run pumaguard-server FOLDER

Using poetry:

poetry run pumaguard-server FOLDER

Where FOLDER is the folder to watch.

Common Command-Line Options

All PumaGuard commands support these global options:

• --log-file PATH - Specify a custom log file location (default: ~/.cache/pumaguard/pumaguard.log)
• --settings PATH - Load settings from a specific YAML file (default: ~/.config/pumaguard/settings.yaml)
• --debug - Enable debug logging
• --model-path PATH - Specify where models are stored
• --version - Show version information

Examples:

# Use custom log file location
uv run pumaguard --log-file /var/log/pumaguard.log server FOLDER

# Combine custom settings and log file
uv run pumaguard --settings my-config.yaml --log-file /tmp/debug.log server FOLDER

# Enable debug logging
uv run pumaguard --debug server FOLDER

For more details on configuration and XDG directory support, see docs/XDG_MIGRATION.md.

Training new models

For reproducibility, training new models should be done via the train script and all necessary data, i.e. images, and the resulting weights and history should be committed to the repository.

1. Get a TPU instance on Colab or run the script on your local machine.

2. Open a terminal and run

   git clone https://github.com/PEEC-Nature-Youth-Group/pumaguard.git
   cd pumaguard
   

3. Get help on how to use the script

   On Colab, run

   ./scripts/pumaguard --help
   ./scripts/pumaguard train --help
   

   On your local machine with uv:

   sudo apt install nvidia-cudnn
   uv sync --extra dev --extra extra-dev
   uv run pumaguard --help
   uv run pumaguard train --help
   

   Or with poetry:

   sudo apt install nvidia-cudnn
   poetry install
   poetry run pumaguard --help
   poetry run pumaguard train --help
   

4. Train the model from scratch

   ./scripts/pumaguard train --no-load --settings pumaguard-models/model_settings_6_pre-trained_512_512.yaml