mirror of
https://github.com/macaodha/batdetect2.git
synced 2026-05-22 22:32:18 +02:00
124 lines
3.4 KiB
Markdown
124 lines
3.4 KiB
Markdown
# Getting started
|
||
|
||
If you want to run BatDetect2 on your recordings,
|
||
start with the command-line route below.
|
||
|
||
You do not need to write Python code for a standard first run.
|
||
|
||
BatDetect2 also has a Python interface,
|
||
but that is mainly for users writing their own analysis scripts.
|
||
|
||
- Use the command-line route if you want to run an existing model or train your own model by typing commands in a terminal window.
|
||
- Use the Python route only if you already want to work in scripts or notebooks.
|
||
|
||
```{note}
|
||
If you are looking for the previous BatDetect2 workflow based on `batdetect2 detect` or `batdetect2.api`, go to {doc}`legacy/index`.
|
||
New docs default to the current `predict` CLI and `BatDetect2API` workflow.
|
||
```
|
||
|
||
If you want to try BatDetect2 before installing anything locally:
|
||
|
||
- [Hugging Face demo (UK species)](https://huggingface.co/spaces/macaodha/batdetect2)
|
||
- [Google Colab notebook](https://colab.research.google.com/github/macaodha/batdetect2/blob/master/batdetect2_notebook.ipynb)
|
||
|
||
## The simplest route for most users
|
||
|
||
1. Install BatDetect2.
|
||
2. Use a model checkpoint.
|
||
3. Run the first tutorial on a folder of recordings.
|
||
|
||
If that is what you want,
|
||
you can ignore the Python sections for now.
|
||
|
||
## Install BatDetect2
|
||
|
||
We recommend `uv` for both workflows.
|
||
|
||
`uv` is a tool that helps install Python software cleanly,
|
||
without mixing it into the rest of your machine.
|
||
|
||
- Use `uv tool` to install the CLI.
|
||
- Use `uv add` to add `batdetect2` as a dependency in a Python project.
|
||
|
||
Install `uv` first by following their
|
||
[installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
|
||
|
||
## Install the CLI
|
||
|
||
The following installs `batdetect2` in its own small environment and makes the
|
||
`batdetect2` command available on your machine.
|
||
|
||
```bash
|
||
uv tool install batdetect2
|
||
```
|
||
|
||
If you need to upgrade later:
|
||
|
||
```bash
|
||
uv tool upgrade batdetect2
|
||
```
|
||
|
||
Verify the CLI is available:
|
||
|
||
```bash
|
||
batdetect2 --help
|
||
```
|
||
|
||
Run your first workflow:
|
||
|
||
Go to {doc}`tutorials/run-inference-on-folder` for a complete first run.
|
||
|
||
## Choose a model checkpoint
|
||
|
||
The current command-line and Python workflows expect an explicit checkpoint path.
|
||
|
||
A checkpoint is the saved model file that BatDetect2 will use for prediction.
|
||
|
||
You can use:
|
||
|
||
- a checkpoint you trained yourself, or
|
||
- a checkpoint distributed with your installation or repository checkout.
|
||
|
||
In this repository checkout, an example pretrained checkpoint is available at:
|
||
|
||
```text
|
||
src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
|
||
```
|
||
|
||
Use that path in the tutorial commands if you want a concrete starting point from this source tree.
|
||
|
||
## Python route for users writing code
|
||
|
||
If you are using BatDetect2 from Python code, add it to your Python project:
|
||
|
||
```bash
|
||
uv add batdetect2
|
||
```
|
||
|
||
This keeps your project settings and installed packages in sync.
|
||
|
||
### Alternative with `pip`
|
||
|
||
If you prefer `pip`, create and activate a virtual environment first:
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
Then install from PyPI:
|
||
|
||
```bash
|
||
pip install batdetect2
|
||
```
|
||
|
||
## What's next
|
||
|
||
- Run your first workflow on a folder of recordings:
|
||
{doc}`tutorials/run-inference-on-folder`
|
||
- If you write code and want the Python route:
|
||
{doc}`tutorials/integrate-with-a-python-pipeline`
|
||
- For common practical tasks, go to {doc}`how_to/index`
|
||
- For detailed command help, go to {doc}`reference/cli/index`
|
||
- To understand outputs and trade-offs, go to {doc}`explanation/index`
|