1 Wild Me ScoutBot¶
1.1 How to Install¶
pip install scoutbot
or, from source:
git clone https://github.com/WildMeOrg/scoutbot
cd scoutbot
pip install -e .
To then add GPU acceleration, you need to replace onnxruntime with onnxruntime-gpu:
pip uninstall -y onnxruntime
pip install onnxruntime-gpu
1.2 How to Run¶
You can run the tile-based Gradio demo with:
python app.py
or, you can run the image-based Gradio demo with:
python app2.py
To run with Docker:
docker run \
-it \
--rm \
-p 7860:7860 \
-e CONFIG=phase1 \
-e WIC_BATCH_SIZE=512 \
--gpus all \
--name scoutbot \
wildme/scoutbot:main \
python3 app2.py
To run with Docker Compose:
version: "3"
services:
scoutbot:
image: wildme/scoutbot:main
command: python3 app2.py
ports:
- "7860:7860"
environment:
CONFIG: phase1
WIC_BATCH_SIZE: 512
restart: unless-stopped
deploy:
resources:
reservations:
devices:
- driver: nvidia
device_ids: ["all"]
capabilities: [gpu]
and run docker compose up -d
.
1.3 How to Build and Deploy¶
1.3.1 Docker Hub¶
The application can also be built into a Docker image and is hosted on Docker Hub as wildme/scoutbot:latest
. Any time the main
branch is updated or a tagged release is made (see the PyPI instructions below), an automated GitHub CD action will build and deploy the newest image to Docker Hub automatically.
To do this manually, use the code below:
docker login
export DOCKER_BUILDKIT=1
export DOCKER_CLI_EXPERIMENTAL=enabled
docker buildx create --name multi-arch-builder --use
docker buildx build \
-t wildme/scoutbot:latest \
--platform linux/amd64 \
--push \
.
1.3.2 PyPI¶
To upload the latest ScoutBot version to the Python Package Index (PyPI), follow the steps below:
Edit
scoutbot/__init__.py:65
and setVERSION
to the desired versionVERSION = 'X.Y.Z'
Push any changes and version update to the
main
branch on GitHub and wait for CI tests to passgit pull origin main git commit -am "Release for Version X.Y.Z" git push origin main
Tag the
main
branch as a new release using the SemVer pattern (e.g.,vX.Y.Z
)git pull origin main git tag vX.Y.Z git push origin vX.Y.Z
Wait for the automated GitHub CD actions to build and push to PyPI and Docker Hub.
1.4 Tests and Coverage¶
You can run the automated tests in the tests/
folder by running:
pip install -r requirements.optional.txt
pytest
You may also get a coverage percentage by running:
coverage html
and open the coverage/html/index.html file in your browser.
1.5 Building Documentation¶
There is Sphinx documentation in the docs/
folder, which can be built by running:
cd docs/
pip install -r requirements.optional.txt
sphinx-build -M html . build/
1.6 Logging¶
The script uses Python’s built-in logging functionality called logging
. All print functions are replaced with log.info()
, which sends the output to two places:
the terminal window, and
the file scoutbot.log
1.7 Code Formatting¶
It’s recommended that you use pre-commit
to ensure linting procedures are run
on any code you write. See pre-commit.com for more information.
Reference pre-commit’s installation instructions for software installation on your OS/platform. After you have the software installed, run pre-commit install
on the command line. Now every time you commit to this project’s code base the linter procedures will automatically run over the changed files. To run pre-commit on files preemtively from the command line use:
pip install -r requirements.optional.txt
pre-commit run --all-files
The code base has been formatted by Brunette, which is a fork and more configurable version of Black. 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.
2 Changelog¶
2.1 Version 0.1.17¶
[BREAKING CHANGE] Added detection label mapping for the
phase1
output to rename the following species labels to be consistent with themvp
output labels:elephant_savanna
toelephant
dead_animalwhite_bones
towhite_bones
deadbones
towhite_bones
elecarcass_old
towhite_bones
gazelle_gr
togazelle_grants
gazelle_th
togazelle_thomsons
Added rounding to the WIC predicted confidence to 4 decimal points in the print and JSON outputs.
Added to the documentation the list of supported class labels for each model configuration.
Updated the documentation to highlight the list of recommended supported species for the MVP model (based on held-out validation data), and to add the build and deployment instructions.
Added platform detection code to detect macOS and reduce the batch size of WIC models with the MVP model to 1 (added to Known Issues).
Added three new environment variables to allow specifying the model configuration for the
WIC
,LOC
, andAGG
, respectively:WIC_CONFIG
,LOC_CONFIG
,AGG_CONFIG
. If unset, it uses the global config and behavior as specified by theCONFIG
environment variable. The TILE module does not have different settings dependent on the model configuration.Added a new environment variable to allow for faster but less accurate results:
FAST
. If unset, it uses the standard tile extraction behavior for grid1 and grid2. Turning this flag on will dramatically speed up inference by processing approximately half of the number of tiles per image.Added
CHANGELOG.rst
andISSUES.rst
.Modified documentation strings in a few places for clarity and correctness.
Updated both Gradio apps to support the Phase1 and MVP models and their respective configurations.
Updated tests to support the new ML configuration default settings.
2.2 Version 0.1.16¶
Alpha version of Scoutbot, with all Phase 1 and MVP functionality and pre-trained models included
3 Known Issues¶
Non-determinism and ONNX Runtime prediction failure on macOS when using MVP WIC model and a batch size greater than 1. The code will automatically recude the batch size to 1 for this configuration and applicable environments.