Frequently asked questions
Short answers, with a link to the full explanation. Select a question to open it.
Getting started
Which workflow should I use?#
Use a project if you want AddaxAI to do the interpreting: counts, rates, charts and maps. Use a folder run if you would rather do that part yourself in another program, Timelapse or R for example. Then AddaxAI only finds and names the animals, and hands you the results as tables and files for that program to read.
Both run the same AI, so the detections and species are the same either way. If you are unsure, start with a folder run: it can become a project later without losing anything. See choose a workflow.
Is it free?#
Yes. AddaxAI is open source under the MIT licence, so it is free to use, also for commercial work.
The models are separate. Each comes with its own licence and those differ, and many are Creative Commons non-commercial. Making sure a licence fits what you do is your responsibility, so read it before you use that model commercially. Every licence is listed in the model zoo.
Which systems does it run on?#
Windows, macOS (Apple Silicon) and Linux. Intel Macs are not supported.
Does it work on video?#
Yes. AddaxAI handles both photos and videos.
My computer warns that the app is unsafe, or blocks it#
That warning is normal for a newly released app and does not mean anything is wrong. On Windows click More info, then Run anyway. On macOS click Open, or allow it under System Settings > Privacy & Security. Work computers are often locked down harder, so if yours blocks the app completely, ask whoever manages it to allow it. See installation.
Setup downloads fail or never finish#
The first launch downloads the models and the software they run in. In mainland China the network blocks those downloads; you can route them through mirrors instead, see install in mainland China. On a work network, a policy or a certificate check can stop them, and both have a fix: see install on locked-down computers and networks. On your own computer the antivirus can stop setup too: see antivirus on your own computer.
How do I start over with a clean install?#
Three ways, from small to big. Your photos, videos and exported results are never inside the folders below, so none of these touch them.
Setup failed and you want a clean retry. Open Help > Reset application and type RESET. It removes the models and the analysis environment and closes the app. Open it again and setup runs from the start. Your projects stay, unless you tick the box to remove the database too.
You want the app itself gone. Uninstall it as described under installation, and answer Yes when it asks to delete your data. Then install the newest version.
You still have version 6. Open Help > Remove old AddaxAI. That works also when setup has not finished yet. Or delete the folder by hand: C:\Users\<your user name>\AddaxAI_files on Windows, /Applications/AddaxAI_files on macOS. Version 6 and version 7 keep their data apart, so removing one never touches the other.
Privacy and data
Does my data get uploaded anywhere?#
No. Everything runs on your own computer and your photos and videos never leave it.
AddaxAI does go online, but only to fetch things it needs: the models and the software they run in, the list of available models when it starts, a check for a new version, and a GBIF lookup when you ask it to add a species, which sends the name you typed and nothing else.
Do I need an internet connection?#
Only the first time you use a model. AddaxAI then downloads the model and the software it runs in, which can be several gigabytes. After that the analysis runs offline. At start it still tries to reach the model list and the update check, but both fail quietly, so the app works without a connection.
If your internet is limited, run one small analysis from start to finish while you still have a good connection, using the models you plan to work with. That pulls down everything they need, so you will not find a model missing when you are offline.
Does AddaxAI change my photos?#
No. It reads your images and videos and never writes to them.
It does write new files. A hidden .addaxai folder goes inside the folder you analysed, and the save step writes whatever outputs you asked for. Species folders, images with boxes drawn on them and blurred versions are all copies, and those copies carry the labels in their metadata. Whatever you pick in the save step, your originals are never overwritten, moved or deleted. They stay exactly as they were. See where your files live.
Requirements
Do I need a GPU?#
No. AddaxAI runs on any computer. It is faster with an NVIDIA GPU or Apple Silicon, but a GPU is not required.
How long does an analysis take?#
It depends on your hardware, on how many files you have, and on whether they are photos or videos. A machine with an NVIDIA GPU or Apple Silicon is many times faster than one without.
For real numbers per hardware type, see the MegaDetector benchmark timings. Those numbers are for the detection model only. The classification model and the embedding model add time on top, but the benchmarks still give a good indication. Video is slower than photos, because AddaxAI takes several frames out of every clip and runs the models on each one.
It does not use my GPU. What can I do?#
On Windows and Linux AddaxAI uses an NVIDIA GPU automatically, so if it is not being used, the driver is usually the reason. Install the latest driver from NVIDIA's site. For an RTX 50-series card you need version 555 or newer, otherwise the card runs far below its speed.
Some cards are too old for the AI models we ship and cannot be used even with the latest driver. On Windows that is the GTX 900 series and older, and the matching Quadro M cards. On Linux the GTX 10 series and Quadro P cards are also too old. AddaxAI detects this, notes it in the log, and runs on the processor instead. Everything still works, just slower.
Understanding the results
What is the difference between a detection and an observation?#
A detection is one box on one photo. An observation is one species within one event, with a count. One deer that triggers the camera 40 times gives 40 detections but a single observation. See detections, events and observations.
Why are labels and counts not the same thing?#
Labels answer which species. Counts answer how many animals. You can correct every label in an event and that still does not say whether one deer walked past or four, so the number is a separate job. That is why they are checked on different pages, tracked separately, and why "labels verified" and "counts confirmed" on the dashboard usually show different numbers. It works best to do the labels first and the counts after, so you are not counting animals whose species still has to be corrected. See confirm the counts.
Why does my folder run have no counts?#
Confirming counts is a project feature, and that is deliberate. A folder run is for people who do their own interpretation, and counting rules differ from study to study: how you group animals, what counts as one visit, how you handle a herd. AddaxAI is not going to make those calls for you, so a folder run neither counts nor suggests counts. It still groups photos into events behind the scenes, and hands you the raw tables to work from. See choose a workflow.
Some photos have no date. What happens to them?#
They are still analysed, so you keep the detections and the species, and they still count in your species totals. But they drop out of anything that needs a date: trap nights, and the trend and activity charts. They are also never grouped with other files.
AddaxAI never invents a date by itself, but you can supply one, either in the filename or from your computer's file dates. See dates, times and timezones.
What is the difference between Animal and Animalia?#
Both mean "an animal we could not name", but they come from different steps, so they are counted separately.
"Animal" means the species model never put a name on the box. That happens when your project runs without a species model, or when the box scored too low for the species model to look at it at all.
"Animalia" means the species model did look, and was sure enough that something living was there, but not sure enough at any level from species up to class. So the label rolled all the way up to the kingdom. See how labels get cleaned up.
You only see the two names apart when you display scientific names. With common names both read "Animal". In an export the common_name column reads "Animal" for both and the scientific_name column separates them, so pick the column that matches how you want to group. If you just want one bucket of unidentified animals, add them up. If you can tell the species yourself, relabel them on the Labels page.
Using AddaxAI
Can I correct the AI?#
Yes. You can check and relabel any detection, and your version always wins over the AI's. Reprocessing and threshold changes leave your corrections alone.
One thing does wipe them: re-running the AI on the folder, which analyses everything again from scratch. The app warns you first. See confidence and verification.
Can I analyse a single video or a few files?#
No. AddaxAI works per folder: you choose a folder and it analyses every image and video in it, subfolders included. It cannot take a single file, so dropping one video on the folder picker gives you "This is a file, not a folder". Put the files you want analysed in a folder of their own and choose that folder.
Can a project sort my photos into species folders?#
Yes. On the Export page, "Image copies" writes copies of your images into species folders, with the same options a folder run has: nested by taxonomy or one folder per species, boxes drawn on, people blurred. You pick the deployments, and you can narrow it to one species, to the files you liked or verified, or to a date range. The species goes into the image metadata too, so programs like digiKam and Lightroom show it as a tag.
The copies are a snapshot of your labels at that moment. Correct more, then export again into the same folder to replace them. See exports.
Which species can it recognise?#
It depends on the model. Each one covers a region or a group of animals. The model zoo lists the full species list of every model, and you can search it by species name.
Can I add a species the model does not know?#
Yes, but only in your own data. Type the name in the relabel picker and add it as a new label, then give it a taxonomy so it sits in the right place in the tree and behaves like any other label. What it does not do is teach the model. The label lives in your database, in that project, and the model will never predict it by itself, so you keep assigning it by hand. See species names and taxonomy.
Why do some images have no boxes during review?#
The detector runs at a low threshold and keeps everything. The review grid then hides detections below your chosen confidence, so an image can look empty even though it has a weak detection. Lower the threshold to see them.
What is the difference between the detection models?#
MegaDetector v5a is the default and the most tested, and it is the one its developer recommends, so leave it alone unless you have a good reason. v5b is an alternative whose performance depends on your dataset. The MegaDetector v1000 models trade accuracy for speed: Cedar is about twice as fast for 1% less accuracy, Spruce is 13 times faster for 14% less. See the model zoo.
Can several people work on the same project?#
Not on one database at the same time, but you can split the checking by deployment. Each team member gets an AddaxAI bundle with their own deployments, checks the labels, and sends a bundle back. See split the checking over a team.
Can I add many sites or deployments at once?#
Yes. Save your spreadsheet as a CSV file and use "Import from CSV" on the Sites page or the Process page. Import your sites first, because a deployment refers to a site by its name. This is not the same as the CSV files AddaxAI writes when you export results. See build a project.
Can I move my work to another computer?#
Yes. Export the project as an AddaxAI bundle with the photos included, and import it on the other computer. To move every project at once, back up the database and restore it there. See work as a team and moving to another computer.
Can I undo a big mistake?#
Often yes. AddaxAI copies your database every day and before every update, and you can roll back to one of those copies. See back up and restore.
The analysis fails because AddaxAI cannot write to the folder#
AddaxAI saves a hidden .addaxai folder next to your files, so it needs to be able to write there. It never changes your photos and videos themselves. See where your files live.
On a Mac this almost always means the drive is formatted for Windows (NTFS). macOS can read such a drive but not write to it. Check it in Finder: select the drive, choose File > Get Info, and look at Format. Then pick one of these:
- Install an NTFS driver, such as Paragon NTFS for Mac. Seagate offers one for its own drives. Then run the analysis again, nothing needs to be copied.
- Copy the folder to your computer's own disk and analyse it there.
Do not reformat the drive to make it writable. That erases everything on it.
On any system the same message appears for a folder your user account may not write to, such as a shared or network folder. Ask whoever manages it for write access, or copy the folder somewhere you can write.
The app says the previous run did not finish. Where are my results?#
The run was interrupted, by a crash, a power cut or the app closing. Its results never reached the database, so they are not in any backup either, and restoring one will not bring them back.
What does survive is the detection progress. While MegaDetector works through your photos it saves where it got to every few hundred images. Open the folder again and click "Re-run analysis". If there is progress to pick up, the window says how far detection got and offers "Continue" next to "Start over". Continue skips the photos that were already detected; the steps after detection (species classification, counting) run again from the start. Videos are not covered: their detection always starts over.
Continue is only offered when the detection settings (detector, image size, augmentation) are the same as in the interrupted run. Your photos and backups are untouched either way.
I deleted the AddaxAI files from my folder, but it still says the folder is already analysed#
That is expected. The results of a folder run live in the AddaxAI database, not in your folder. The files the app writes next to your photos (the tables, the recognition file for Timelapse, the media copies) are copies made from that database, so deleting them does not delete the run. When you pick the same folder again, the app finds the run and opens it.
That is useful more often than not. Click "Skip analysis" to open the stored results, and save the outputs again from the save step. The recognition file is back in seconds, without running the AI again. Click "Re-run analysis" to throw the stored results away and start over.
To forget the run completely, open "Analyse a folder", click "Show recent runs" before picking a folder, and delete the run there.
Getting help
Something went wrong, or I found a bug#
Open Help > Export diagnostic report and email the zip to peter@addaxdatascience.com, with what you were trying to do, what you expected, and what actually happened. A screenshot or a short screen recording helps a lot. See troubleshooting.
How do I cite AddaxAI?#
Cite the paper: van Lunteren, P. (2023). AddaxAI: A no-code platform to train and deploy custom YOLOv5 object detection models. Journal of Open Source Software, 8(88), 5581. doi.org/10.21105/joss.05581.
Please cite the models you used too. Their citation and licence are listed in the model zoo.