/EcoAssist

A no-code platform to train and deploy YOLOv5 object detection and the MegaDetector model

Primary LanguagePythonMIT LicenseMIT

DOI status

Introduction

EcoAssist is an application designed to make life easier for people who want to work with object detection models. Thanks to the people at Ultralytics, it's possible to create models which can locate objects of your interest in images. The only problem is that you need to know a bit of coding before you can use it. That is where EcoAssist comes in handy. It's a no-code interface which makes it easy for everybody. Annotate, train, and deploy your models without a single line of code.

I initially created EcoAssist with the aim of assisting ecological projects (hence the name), but it will handle any kind of object. If you’re not an ecologist and not interested in animals, you’ll just have to input images of your object of interest (blood cells, traffic signs, plant diseases - whatever you want) and ignore the references to the MegaDetector model. The rest will be exactly the same.

I've written this application in my free evenings and would really appreciate it if people would let me know when it's used, and what for. You can contact me at petervanlunteren@hotmail.com. Please also help me to keep improving EcoAssist and let me know about any improvements, bugs, or new features so that I can keep it up-to-date.

Demo

Main features

  • Runs on Windows, Mac, and Linux (no admin rights required)
  • English 🇬🇧 & Español 🇪🇸
  • Train your model using the YOLOv5 architecture
  • Deploy your model on images or videos
  • Annotate your data using the labelImg software
  • GPU acceleration for NVIDIA and Apple Silicon
  • Post-process your data to
    • separate
    • visualise
    • crop
    • label
    • export to .csv

Extra features for ecologists

EcoAssist comes with the MegaDetector model preloaded. This model is trained to find animals, people, and vehicles in camera trap images - and does this really well. That means that you can deploy MegaDetector to find the images or videos which contain an animal, and filter out the empties. There's also a possibility to further process the images in Timelapse.

Unfortunately, MegaDetector does not identify the animals, it just finds them. There is no model that can identify all species on earth. If you want a species classifier for your specific ecosystem or project, you'll have to train it yourself. In EcoAssist you can easily transfer knowledge from MegaDetector to your own species classifier to save you tremendous amounts of data and time.

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!

Quick links

  1. Requirements
  2. Download
  3. Test your installation
  4. Update
  5. GPU support
  6. Bugs
  7. Cite
  8. Uninstall
  9. Code contributors

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 installation

  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. Just keep track of the destination directories (for example, C:\Program Files\Git and C:\ProgramData\miniforge3). You'll have to specify these paths later on.
    • You can install Git from gitforwindows.org.
    • EcoAssist will work with Anaconda, Miniconda or Miniforge. Miniforge is recommended, however, 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. Enter the paths to the installations from step 1 when prompted, or just drag and drop the installation folders into the console window.
  5. 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.

Mac installation

  1. 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. In order to make MegaDetector work on Apple Silicon computers, the guys at Ecologize had to re-build the model with slightly different results. The bounding boxes appear to be the same to around two decimal places in both location and confidence, which is good, but not exactly the same. Please keep in mind that this is an unvalidated version of MegaDetector, and they don't exactly know how it compares to the validated version since it is much less tested.
  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...

Linux installation

  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 files and packages with the new ones. It's all automatic, you don't have to do anything.

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 citation

@software{van_Lunteren_EcoAssist_2022,
  title     = {{EcoAssist: A no-code platform to train and deploy YOLOv5 object detection and the MegaDetector model}},
  author    = {van Lunteren, Peter},
  year      = {2022},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.7223363},
  url       = {https://github.com/PetervanLunteren/EcoAssist}
}

MegaDetector citation

If you used the MegaDetector model to analyse images or retrain your model.

@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 citation

If you trained or retrained a model.

@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.

# windows (all users)
─── 📁Program Files
    └── 📁EcoAssist_files

# windows (single user)
─── 📁Users
    └── 📁<username>
        └── 📁EcoAssist_files

# mac
─── 📁Applications
    └── 📁.EcoAssist_files

# linux
─── 📁home
    └── 📁<username>
        └── 📁.EcoAssist_files

Code contributors

Please feel free to fork this repo and submit fixes, improvements or add new features.