> For the complete documentation index, see [llms.txt](https://docs.animl.camera/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.animl.camera/fundamentals/uploading-images.md).

# Uploading images

How to upload images to Animl in bulk from your desktop

## Overview

In addition to linking and ingesting images in real-time from wireless camera traps, Animl supports directly uploading camera trap images in bulk from your computer. The process is simple: you package your images in a Zip file, upload them to your *Project* via the bulk upload interface, and then Animl takes over and does the rest. Behind the scenes, Animl is marshaling hundreds of parallelized computers to make your machine learning processing jobs as fast and reliable as possible.

<figure><img src="https://1711533052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fxw73AVobf0HNxaSw60iW%2Fuploads%2FFSd3GMXAHxbW6ilsVhhZ%2FScreenshot%202023-09-14%20at%203.16.39%20PM.png?alt=media&amp;token=399bcbff-ed30-4434-b877-3cd5319f0f73" alt=""><figcaption><p>Animl Bulk Upload interface</p></figcaption></figure>

## Before you begin

### Requirements

Animl is highly flexible and can consume images from most camera trap types, but there are a few requirements to be mindful of:

1. The maximum file-size of **the Zip file can not exceed 50 GB**. If your dataset is larger than 50 GB, you'll have to break it in smaller batches and zip and upload them individually.
2. Animl only processes `.jpg` and `.png` files it finds within the Zip file. It doesn't support video or any other file type.
3. The maximum file size for each individual image file is 8 MB.
4. Each image must have two fields present it its [Exif metadata](https://en.wikipedia.org/wiki/Exif): a `DateTimeOriginal` field indicating when the image was created, and a `SerialNumber` field indicating what camera took the image. Nearly all images should have `DateTimeOriginal` fields, but some common camera trap manufactures and models do not provide `SerialNumbers` (see table below for list of known camera traps that do not support `SerialNumbers`).

| Camera traps with serial numbers | Camera traps without serial numbers |
| -------------------------------- | ----------------------------------- |
| Reconyx - Hyperfire              | Reconyx - MR5 Microfire             |
| Buckeye X80 / UWS                | Cuddelink / Cuddeback               |
|                                  | Browning / Prometheus               |
|                                  | Bushnell                            |
|                                  | Exodus                              |
|                                  | Little Acorn                        |
|                                  | RidgeTec                            |
|                                  | SpyPoint                            |

{% hint style="info" %}
If you're trying to upload images from a camera make that is not listed below and you're not sure whether or not your images' metadata contain `SerialNumbers`, the best way to check is with Phil Harvey's Exiftool (<https://exiftool.org/>).
{% endhint %}

If you are uploading images from camera(s) without Serial Numbers, please read the below information on the Serial Number Override feature.

### Serial Number Override

If your images *do not* include a camera `Serial Number` field in their Exif metadata, Animl has no way of knowing which Camera the images belong to, so you will have to manually provide this information by adding your own "serial number" to the the Serial Number Override input field.

"Serial number" is in quotes because it can be any string you'd like to use to uniquely identify that particular Camera. The only requirements are that the value can't contain spaces or special characters, and it must be unique to your Project. If a Camera already exists in your Project with the same "Serial Number", the images will be grouped together and associated with that existing Camera. There's nothing wrong with that per se, and in fact it may be desirable (for example, if you're uploading a fresh batch of images from a camera you've already uploaded some images from).

Additionally, it's important to note that ***the value you provide in the Serial Number override field will be applied to ALL images in the Zip file.*** So if you have images from multiple cameras, some or all of which do not have `Serial Numbers`, ***you'll have to zip up and upload images from each camera separately***, each with separate & unique Serial Number Override values.

{% hint style="info" %}
This is not a requirement if all of your images are from cameras that include Serial Numbers. If that's the case, a single Zip file can contain images from multiple cameras and Animl will sort them and associate them with the correct cameras automatically.
{% endhint %}

### Check your Automation Rules!

Before uploading a batch, it's worth double checking that you *Project*'s [*Automation Rules*](/fundamentals/automation-rules.md) are configured appropriately for your data processing needs. All images you upload will be processed according to the *Automation Rules* you've configured, and if you don't have any *Automation Rules* configured, Animl will save the images to your Project but it will not make any machine learning predictions.

## How to Upload Images

1. Zip up your photos.
   1. Remember that if you are using the [Serial Number Override](#serial-number-override), that override will apply to all images in the zip file, so don't include images from more than one camera in your zip folder.
2. Click the "Bulk upload images" icon on the left sidebar.

   <figure><img src="https://1711533052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fxw73AVobf0HNxaSw60iW%2Fuploads%2F4uQ6pfPuoPi0RB797Eli%2FScreenshot%202026-08-06%20152310.png?alt=media&amp;token=d9609f45-900d-4c2c-b032-7ca65e7e85b7" alt=""><figcaption></figcaption></figure>
3. Choose your file or drag and drop
4. If your images do not contain serial numbers in their exif data, use the serial number override. If they do, ignore this step.
5. Click Upload

{% embed url="<https://www.youtube.com/watch?v=xKUiPAifs70&list=PLSprRV1-SBDc&index=28>" %}

### Upload stages and processing time

The upload and batch processing stages involve the following messages and meanings:

* **Step 1: Uploading file** - the Zip file is being uploaded from your computer to Animl's backend.
* **Step 2: Preprocessing** - the file is unzipped, the files within it are validated, the parallelized computers that will support the machine learning processing are deployed, and the images are saved to the Animl database.
* **Step 3: Processing** - the images are being processed by the pipeline of machine learning models you've defined in your *Automation Rules.*
* **Step 4: Cleaning up** - the processing computers are shut down. Once you reach this step, your images and their predicted label are ready for your review; you don't have to wait until it's finished cleaning up!

{% hint style="info" %}
**Important Note**: You do not have to keep your browser open the whole time!

You can close your browser after Step 1 is complete (*i.e. when the status changes to "Preprocessing"*) which is when the Zip file is fully uploaded to the backend.

However, please wait until Step 4 (*i.e. when the status changes to "Cleaning up"*) to review your images).
{% endhint %}

### Upload Speeds

The amount of time it takes to upload your file will depend on the speed of your internet connection. For reference, with an upload speed of 360 Mbps, a 10 GB zip file would take under 4 minutes to upload. If you're curious, you can estimate the upload time for your files with a file upload time calculator (<https://www.uploadtimecalculator.com/>).

Once the file has been uploaded, the remaining processing time depends on (a) how many images are in your batch, (b) how many ML models you are invoking in your processing pipeline, and (c) how many other users are also processing batches of images at the moment.

If no one else is using the bulk upload functionality and you're only requesting predictions from one model (Megadetector, for example), ***Animl can process \~11-12 images per second, meaning processing a batch of 100k images should take about 2.5 hours to complete.***

## Other Upload Information

### Viewing results

Once your upload has finished processing, you can close out of the bulk upload model and view the images and predicted labels. If the images are not immediately present in the Animl user interface, you may have to click the "Refresh data" button at the bottom of the Filters Panel.

<figure><img src="https://1711533052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fxw73AVobf0HNxaSw60iW%2Fuploads%2FW5MaHh5HmOdEqlcATHX9%2FScreenshot%202023-09-14%20at%2010.13.15%20PM.png?alt=media&amp;token=3aacc658-e484-4083-8829-655e736ea78f" alt=""><figcaption><p>Refresh data button</p></figcaption></figure>

### Dealing with errors

If the warning icon to the right of the bulk upload entry turns red, it means that one or more errors occurred while processing your images. To download a complete CSV of all of the errors that occurred, click the warning icon and open the CSV in a spreadsheet editor to view each image attempt and the reason it failed.

<figure><img src="https://1711533052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fxw73AVobf0HNxaSw60iW%2Fuploads%2FxvmtcueDYNV791lntfSe%2FScreenshot%202023-09-14%20at%209.09.12%20PM.png?alt=media&amp;token=c6882b42-a9cb-404a-848a-35cd160599b1" alt=""><figcaption><p>Click the error warning icon to download a CSV of the image errors that occurred during upload and processing</p></figcaption></figure>

Errors can occur for a number of reasons, and some can be ignored (for example, `Duplicate Image` errors). Certain errors, however, may be remediable. For example, if the errors indicate that certain images failed to be saved because they had `Unknown serial number` errors, you can attempt to re-upload them using the [Serial number override feature](#serial-number-override).

### Upload Estimates

Another thing to note is that during the machine learning processing stage (Step 3), Animl provides an estimate of the number of images it's processed, but this number is not always accurate (especially on batches of relatively few images), and at times it may even appear to reverse progress briefly before continuing to grow again. Despite not being perfectly accurate all of the time, it's still a very useful indicator of progress.