Skip to content

Latest commit

 

History

History
executable file
·
309 lines (251 loc) · 18.1 KB

README.md

File metadata and controls

executable file
·
309 lines (251 loc) · 18.1 KB
Raw

status Project Status: Active The project has reached a stable, usable state and is being actively developed. GitHub DOI GitHub last commit

Simplifying camera trap image analysis for ecologists

EcoAssist is an open-source application designed to streamline the work of ecologists dealing with camera trap images. It's an AI platform that enables annotation, training, and deployment of custom models for automatic species detection, offering ecologists a way to save time reviewing images and focus on conservation efforts.

The MegaDetector model is preloaded. This model can find out which images contain an animal and filter out the empties. Unfortunately, MegaDetector does not identify the animals, it just finds them. If you want a model that can identify species for your specific ecosystem or project, you'll have to train it yourself. Or outsource it to Addax Data Science.

Recently, I joined forces with Smart Parks. We’re working on expanding the software to become a standalone and robust platform for camera trap image analysis to be used by ecologists worldwide. We'll test the setup with a pilot study for the Desert Lion Conservation Project in Namibia. If you feel like contributing to the development of EcoAssist, see the sponsor section below.

You can also help me by letting me know about any improvements, bugs, or new features so that I can keep EcoAssist up-to-date. You can raise an issue or email me. An e-mail just to say hi and tell me about your project is also very much appreciated!







Quick links

  1. Demo
  2. Overview
  3. Main features
  4. Teasers
  5. Users
  6. Current focus
  7. Sponsor
  8. Tutorial
  9. Requirements
  10. Download
  11. Test your installation
  12. Update
  13. GPU support
  14. Bugs
  15. Cite
  16. Uninstall
  17. Contributors
  18. Similar software

Demo

Overview

Main features

  • Runs on Windows, Mac, and Linux
  • No admin rights required
  • After installation completely offline
  • Use MegaDetector to filter out empty images or videos
  • Integration with Timelapse
  • English 🇬🇧 & Español 🇪🇸
  • Train models using the YOLOv5 architecture
  • Deploy models on images or videos
  • Built in function to annotate images based on labelImg
  • GPU acceleration for NVIDIA and Apple Silicon
  • Post-process your data to
    • separate
    • visualise
    • crop
    • label
    • export to .csv

Teasers

Camera trap images taken from the Missouri camera trap database and the WCS Camera Traps dataset.

Users

Are you also a user and not on this map? Let me know!

Current focus

Together with Smart Parks, I'm working on expanding the software. Our current focus is:

  • Implementing a human-in-the-loop feature for result verification.
  • Improving the annotation process to make it more robust.
  • Testing the setup with a real-world use case for the Desert Lion Conservation project.
  • Set up personalized assistance to support ecologists in effectively using EcoAssist for their projects.
  • Exploring the possibility of providing optimized hardware support.

Tutorial

Peter has written a detailed tutorial on Medium that provides a step-by-step guide on annotating, training, evaluating, deploying, and postprocessing data with EcoAssist. You can find it here. With EcoAssist I tried to make training a model as easy as possible. However, for an acruate model, some machine learning expertise will still be beneficial. If you want to outsource it, you can hire Peter via his company Addax Data Science to train a custom model for you.

Requirements

Except a minimum of 8 GB RAM, there are no hard system requirements for EcoAssist since it is largely hardware-agnostic. However, please note that machine learning can ask quite a lot from your computer in terms of processing power. Although it will run on an old laptop only designed for text editing, it’s probably not going to train any accurate models, while deploying models can take ages. Generally speaking, the faster the machine, the more reliable the results. GPU acceleration is a big plus.

Download

EcoAssist will install quite a lot of dependencies, so don't panic if the installation takes 10-20 minutes and generates lots of textual feedback as it does so. Please note that some antivirus, VPN, proxy servers or other protection software might interfere with the installation. If you're having trouble, please disable this protection software for the duration of the installation.

Opening EcoAssist for the first time will take a bit longer than usual due to script compiling. Have patience, all subsequent times will be better.

Windows
  1. EcoAssist requires Git and a conda distribution to be installed on your device. See below for instructions on how to install them. During installation, you can leave all parameters at their default values.
    • You can install Git from gitforwindows.org.
    • EcoAssist will work with Miniforge, Mambaforge, Anaconda, or Miniconda. Miniforge is recommended, however, Mambaforge, Anaconda or Miniconda will suffice if you already have that installed. To install Miniforge, simply download and execute the Miniforge installer. If you see a "Windows protected your PC" warning, you may need to click "More info" and "run anyway".
  2. Download the EcoAssist installation file and double-click it. If that doesn't work, you can drag and drop it in a command prompt window and press enter.
  3. If you've executed it with admin rights, it will be installed for all users. If you don't have admin rights, you will be prompted if you'd still like to enter an admin password, or proceed with the non-admin install - which will make EcoAssist available for your user only.
  4. When the installation is finished, there will be a shortcut file in your Downloads folder. You are free to move this file to a more convenient location. EcoAssist will open when double-clicked.

If you're having trouble with permissions issues, you can choose to run it inside a Windows Subsystem for Linux (WSL) environment. See the steps here.

macOS
  1. EcoAssist requires you to have a recent version of Xcode Developer Tools. You can donwload and install it from the Mac App Store.
  2. Download and open this file. Some computers can be quite reluctant when having to open command files downloaded from the internet. You can circumvent trust issues by opening it with right-click > open > open. If that still doesn't work, you can change the file permissions by opening a new terminal window and copy-pasting the following commands.
chmod 755 $HOME/Downloads/install.command
bash $HOME/Downloads/install.command
  1. If you're an Apple Silicon user (M1/M2), go for a nice walk because this may take about 30 minutes to complete. Some of the software packages are not yet adopted to the Apple Silicon processor. There is a workaround, but it takes some time. Some packages need Homebrew to install. Homebrew will be automatically installed (if not already present), but you'll need to provide a sudo password. If you don't know the sudo password, you can skip this by pressing Ctrl+D. EcoAssist will still work fine without it, but the annotation and human-in-the-loop feature will not work.
  2. When the installation is done, you'll find a EcoAssist.command file in your Applications folder. The app will open when double-clicked. You are free to move this file to a more convenient location. If you want EcoAssist in your dock, manually change EcoAssist.command to EcoAssist.app, then drag and drop it in your dock and change it back to EcoAssist.command. Not the prettiest solution, but it works...

If you're having trouble opening EcoAssist, you might have to reinstall Xcode. This sometimes happens after upgrading your MacOS version. More information in this issue.

Linux
  1. Download this file.
  2. Change the permission of the file and execute it by running the following commands in a new terminal window. If you don't have root privileges, you might be prompted for a password to install libxcb-xinerama0. This package is required for the labelImg software on some Linux versions. If you don't know the sudo password, you can skip this by pressing Ctrl+D when you are prompted for the password. EcoAssist will still work fine without it, but you might have problems with the labelImg software. The rest of the installation can be done without root privileges.
chmod 755 $HOME/Downloads/install.command
bash $HOME/Downloads/install.command
  1. During the installation, a file called EcoAssist will be created on your desktop. The app will open when double-clicked. You are free to move this file to a more convenient location.

Test your installation

You can quickly verify its functionality by following the steps below.

  1. Choose a local copy of this (unzipped) folder at step 1
  2. Check 'Process all images in the folder specified'
  3. Click the 'Deploy model' button and wait for the prcess to complete
  4. Select the test-images folder again as 'Destination folder'
  5. Check 'Export results to csv files'
  6. Click the 'Post-process files' button

If all went well, there should be a file called results_files.csv with the following content.

absolute_path relative_path data_type n_detections max_confidence
/.../test-images empty.jpg img 0 0.0
/.../test-images person.jpg img 2 0.875
/.../test-images mutiple_categories.jpg img 2 0.899
/.../test-images animal.jpg img 1 0.844
/.../test-images vehicle.jpg img 1 0.936

Update

To update to the latest version, you'll have to repeat the download procedure. It will replace all the old EcoAssist files with the new ones. It's all automatic, you don't have to do anything. Don't worry, it won't touch your conda distribution or your Git installation. Just the ecoassistcondaenv environment.

GPU support

EcoAssist will automatically run on NVIDIA or Apple Silicon GPU if available. The appropriate CUDAtoolkit and cuDNN software is already included in the EcoAssist installation for Windows and Linux. If you have NVIDIA GPU available but it doesn't recognise it, make sure you have a recent driver installed, then reboot. An MPS compatible version of Pytorch is included in the installation for Apple Silicon users. Please note that applying machine learning on Apple Silicon GPU's is still under beta version. That means that you might run into errors when trying to run on GPU. My experience is that deployment runs smoothly on GPU, but training throws errors. Training on CPU will of course still work. The progress window and console output will display whether EcoAssist is running on CPU or GPU.

Bugs

If you encounter any bugs, please raise an issue in this repository or send me an email.

Cite

Please use the following citations if you used EcoAssist in your research.

EcoAssist

Link to paper

@article{van_Lunteren_EcoAssist_2023,
  author = {van Lunteren, ehallein},
  doi = {10.21105/joss.05581},
  journal = {Journal of Open Source Software},
  month = aug,
  number = {88},
  pages = {5581},
  title = {{EcoAssist: A no-code platform to train and deploy custom YOLOv5 object detection models}},
  url = {https://joss.theoj.org/papers/10.21105/joss.05581},
  volume = {8},
  year = {2023}
}
MegaDetector

Link to paper

@article{Beery_Efficient_2019,
  title     = {Efficient Pipeline for Camera Trap Image Review},
  author    = {Beery, Sara and Morris, Dan and Yang, Siyu},
  journal   = {arXiv preprint arXiv:1907.06772},
  year      = {2019}
}
Ultralytics

If you used the training function.

@software{Jocher_YOLOv5_2020,
  title = {{YOLOv5 by Ultralytics}},
  author = {Jocher, Glenn},
  year = {2020},
  doi = {10.5281/zenodo.3908559},
  url = {https://github.com/ultralytics/yolov5},
  license = {AGPL-3.0}
}

Uninstall

All files are located in one folder, called EcoAssist_files. You can uninstall EcoAssist by simply deleting this folder. Please be aware that it's hidden, so you'll probably have to adjust your settings before you can see it (find out how to: macOS, Windows, Linux). If you're planning on updating EcoAssist, there is no need to uninstall it first. It will do that automatically. More about updating here.

Location on Windows 
# All users
─── 📁Program Files
    └── 📁EcoAssist_files

# Single user
─── 📁Users
    └── 📁<username>
        └── 📁EcoAssist_files
Location on macOS 
─── 📁Applications
    └── 📁.EcoAssist_files
Location on Linux 
─── 📁home
    └── 📁<username>
        └── 📁.EcoAssist_files

Contributors

This is an open-source project, so please feel free to fork this repo and submit fixes, improvements or add new features. For more information, see the contribution guidelines.

Thank you for your contributions!

Similar software

As far as I know, there are three other software packages capable of deploying the MegaDetector model. These packages are all set up slightly different and have different features.