QSC logo Quantitative Science Consulting

WildObserve™

User Guide

Some features come with a paid plan, and are marked here with the plans that include them. Everything else is in the free Community plan. See Plans for what each includes.

Short videos of the main steps are also on YouTube, in the WildObserve Instructions playlist.

This guide names the Mac's menus. On Linux, the same items are in the window: Projects… at the top left, Models… with the buttons in the header, About at the top right, and License in the menu under your name.

1. Installing and signing in

What you need

A Windows version is coming. WildObserve™ processes any number of images on every plan; how fast depends on your computer.

Installing on a Mac

  1. Download WildObserve™ from the WildObserve™ page (Download for Mac).
  2. Open the downloaded WildObserve.dmg, and drag WildObserve to your Applications folder.
  3. Open WildObserve from Applications. The first launch takes longer while it prepares the AI models for your Mac.

To update, WildObserve™ tells you when a new version is out (in About). Download it the same way, and drag it to Applications to replace the old one. Your accounts and projects are kept. If macOS says WildObserve is in use, quit it first: see Troubleshooting.

Installing on Linux

  1. Download WildObserve™ from the WildObserve™ page (Download for Linux). You get WildObserve-amd64.deb.
  2. Open a terminal in the folder you downloaded it to (usually Downloads), and install it with the command below. apt also installs what WildObserve needs, such as GTK and WebKitGTK.
    sudo apt install ./WildObserve-amd64.deb
  3. Open WildObserve from the app menu, or run wildobserve in a terminal.

To update, WildObserve™ tells you when a new version is out (in About). Close WildObserve, download the new version, and install it with the same command; it replaces the old one. To remove WildObserve, run sudo apt remove wildobserve. Either way, your accounts and projects are kept.

Using an NVIDIA graphics card on Linux

With an NVIDIA graphics card, WildObserve™ processes images several times faster than on the processor alone. It needs NVIDIA's driver, version 580 or later, and NVIDIA's CUDA 13 and cuDNN 9 libraries (about 2 GB), which don't come with WildObserve. On Ubuntu 22.04, this installs the libraries from NVIDIA's apt repository, without touching your driver:

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
# Take only these libraries from NVIDIA's repository, never its drivers:
printf 'Package: *\nPin: origin developer.download.nvidia.com\nPin-Priority: 100\n' \
  | sudo tee /etc/apt/preferences.d/nvidia-cuda-libraries-only
sudo apt update
sudo apt install cuda-cudart-13-0 libcublas-13-0 libcurand-13-0 cuda-nvrtc-13-0 libcudnn9-cuda-13

On Ubuntu 24.04, write ubuntu2404 instead of ubuntu2204 in the first line. Restart if your driver was updated. While images are processed, the header says what they're processed on: CUDA is the graphics card, and CPU the processor. If it says CPU, WildObserve's log says why (~/.local/state/WildObserve/logs/wildobserve.log).

Your account

The first time you open WildObserve™, you create the administrator account: your name, your email address, and a password, then Create account and sign in. Or choose Set up with Google to use your Google account instead. The administrator can then add the other people who use WildObserve™ on that computer (People).

After that, sign in with your email address and password, or with Sign in with Google. Tick Stay signed in on this computer to skip signing in next time. If you forget your password, click Forgot your password? on the sign-in screen.

2. Projects and image folders

A project is a folder that keeps the reviews, results, and settings for a set of camera-trap images, a survey or a study, say. Your images stay where they are: WildObserve™ reads them in place, and never copies, moves, or changes them.

Making a project

  1. In the menu bar, choose Project > Projects… (on Linux, click Projects… at the top left), then New project… (the first time, this is where WildObserve™ starts).
  2. Give it a name, and choose where to keep it (Keep it in).
  3. Under Image folders, click Add a folder… and choose a folder of images. Subfolders are included, and each folder of images becomes a deployment. You can add more folders later.
  4. Click Make project. WildObserve™ finds the images, reads their capture times and camera details, and groups them into capture events.

The window's header shows the project's name and how many images it has, how many are processed, and how many are reviewed.

Switching projects

Project > Projects… lists your projects. Click Open to switch to one. Open a project folder… opens a project that isn't on the list, such as one copied from another computer. Remove from list takes a project off the list; its folder, and everything in it, stays.

Image folders

Click Images… in the header to manage the project's folders:

If a folder is in iCloud Drive or another cloud service, make it available offline first: images that are only online download as WildObserve reads them, which is slow.

Copies of an image (the same file in two folders) are noticed and processed, reviewed, and exported once. They're listed under Duplicates. For images processed before WildObserve checked for copies, click Find duplicates among … images processed earlier in Images….

3. Processing images

Click Process … images in the header. For each image, WildObserve™:

The header shows progress and the time left. Pause stops after the current image. Click the button again, now or after reopening WildObserve™, to carry on where it stopped. You can review while processing continues.

While images are processed, a Mac doesn't go to sleep. On Linux, closing the window quits WildObserve and stops processing until you open it again, and the computer can still go to sleep, so for a long run turn off Automatic Suspend in Settings > Power.

Processing uses your computer's own hardware: a Mac's AI hardware, or on Linux an NVIDIA graphics card or the processor. Nothing is sent anywhere.

4. Deployments and capture events

Deployments

A deployment is a camera at one place for a while: usually one folder of images, or one memory card. Click Deployments… in the header to see them, and for each:

Capture events

A camera usually takes several pictures each time it's triggered. WildObserve™ groups a deployment's images taken close together into a capture event: by default, those no more than 60 seconds apart. Change the gap at the top of Deployments….

Under the image you're reviewing, the capture event's bar says which event it is and what's been seen in it, and the filmstrip shows its pictures, with their boxes. Click a frame, or press [ and ], to open the frame beside it. A frame that isn't in the list you're working through opens too; ← goes back to the list. If WildObserve grouped pictures wrongly, Split here starts a new event at this image, and Join with previous joins this event to the one before.

Capture times come from the images' EXIF data. Images without one use the file's date instead, which copying, downloading, or syncing the files can change. If capture events look far too big, see Troubleshooting.

5. Reviewing images

The review screen has the filter panel on the left (the lists, the filters, and the images in the list), the image in the middle with its boxes and species, and the capture event's bar and filmstrip below it. To give the image more room, hide the filter panel with ‹ at its top right (› brings it back), and the capture event's panel with ^ at its right end.

Lists

Each list button shows a set of images. Click a list to turn it on, and again to turn it off. With several on, you see the images that are in all of them: Reviewed with Uncertain shows the reviewed images marked uncertain. Lists no image can be in together (To review and Reviewed, say) don't stay on together. With none on, you see every image.

ListWhat it holds
To reviewEvery image not reviewed yet.
Has detectionsImages to review with a box at the threshold.
Likely emptyImages to review with no box at the threshold. You can mark them empty together.
People & vehiclesImages to review with a person or vehicle.
Close callsImages whose species suggestions are least sure, closest call first.
New species?Images where SpeciesNet names an animal not labeled in this project yet.
FlaggedImages the production rules flagged, each with why (Rules).
ReviewedImages reviewed already.
Saved by rulesImages the production rules saved by themselves.
UncertainImages a reviewer marked uncertain.
DuplicatesCopies of images added earlier (shown only when there are some).

Under the lists, filters narrow any list to a place or camera, to dates (From and To, by the camera's corrected clock), or to a species. Show boxes scoring ≥ …% sets the threshold: boxes the detector is less sure of than that are hidden (50% to start).

Boxes

Species

Select an animal box to see its species suggestions under the image, each with a score. Click one to use it. A tag says where it came from:

When the models are sure, WildObserve™ fills in the species for you, to confirm or change. When your Project Model and SpeciesNet disagree, it fills in nothing and asks you to pick. You can also type a species in the species field, from the project's species list. Apply to all animals gives every animal in the image the selected box's species, for a herd, say.

With a box selected, you can also record its count (one box can stand for a group), sex, life stage, and behavior. Notes are about the whole image. All of them are exported.

Saving

Save & next (Enter) saves the image as reviewed and opens the next one. On an image reviewed already, it's Confirm & next. ← and → move between images. If you edited the image, moving on saves it, as Save & next does; if you didn't, it stays as it was. Tick Uncertain (U) when you're not sure: the image is saved, listed under Uncertain, and left out of your Project Model's training.

6. Reviewing faster

Species keys

Click Species list in the header for the species offered when you label boxes. Give the common ones a key: in the review, pressing it names the selected box, or with none selected, every animal box in the image. The keys show under the image as a reminder. Import a list adds species from a CSV file, one per line: its name, then optionally its scientific name and key, for example Raccoon,Procyon lotor,R.

Marking empty images together

Turn on Likely empty, then click Mark … as empty…. WildObserve™ says what it will save, and how sure it is: how many images the detector found nothing in, and the highest score among the rest. Click Mark them empty. With Skip bursts with boxes ticked, images in a capture event where another picture has a box are left for you to check, since the animal may be in them too, missed. Undo puts the images back to review.

Naming whole capture events

When you can see that a run of pictures shows one species, tick their images in the list (Shift-click ticks a run), type the species, and click Name their events…. WildObserve™ says what it will do: how many animal boxes it will name, in how many images and capture events. It leaves alone images with no animal box (to review one by one, since the animal may be there, missed) and images reviewed already, and it lists any species the suggestions prefer instead. Confirm, and the images are saved as reviewed. Undo puts them back.

7. Fixed objects

A rock, a stump, or a branch can look like an animal to the detector, picture after picture. WildObserve™ finds the places where it keeps finding a box at one camera, in 5 capture events or more on 2 days or more, and asks you about them in Deployments… > Fixed objects…. Say which are fixed objects: their boxes are then hidden, in the images to review and in those still to come from that camera, so those images can be marked empty. Nothing is hidden until someone says so, since an animal resting in one place can look the same.

To mark one yourself, select its box in an image and click Fixed object. The note under the image says how many boxes at that place are hidden, with Undo. An image with hidden boxes says so above it; click that to see them. Change your mind any time in Fixed objects….

8. Dashboard and timed sessions

Click Dashboard in the header for the project's progress: what the images hold, the species found on reviewed images (with their images, boxes, capture events, and deployments), and each deployment's progress. Click a species to list its images. Occupancy… opens occupancy and abundance.

To time yourself reviewing, click Start a timed session, review as you usually do, and stop it when you're done. The session's clock is in the header, with Pause, Resume, and Stop. The Dashboard lists each session with how many capture events you reviewed, and how many an hour.

9. Occupancy and abundance

From your reviewed images, WildObserve™ estimates each species' occupancy: the share of sites it uses, allowing for the times it was there but no camera saw it (MacKenzie et al. 2002). It also estimates abundance with the Royle–Nichols model (Royle & Nichols 2003): the average number of animals per site that could be seen, a relative index that rests on the model's assumptions. The models are fitted on your computer, the way R's unmarked package fits them (Fiske & Chandler 2011). Click Dashboard, then Occupancy…. It's in every plan.

What it needs

Settings

The results

Under Table, a row per species: the sites it was seen at, its Occupancy, the chance of seeing it in an occasion at a site it uses (Seen in 7 days, for week-long occasions), and Animals per site. Each comes with its 95% interval (lower and upper). The Notes column says when to be careful: a species seen at very few sites, a model that didn't settle, or an estimate at its limit. Warnings above the table are about the whole survey. Under Plots, choose one of six:

Hover over a plot for its numbers. Save as SVG… and Save as PNG… save it, for a report or a paper.

Site covariates

Occupancy and detection can depend on what you know about each place: its habitat, elevation, or distance to water, or whether the camera faces a trail. Click Site covariates…, then Save as CSV… for a file listing every place. Add a column for each covariate in Excel or Numbers, save it as CSV, and click Import a CSV file…. A column of numbers is numeric; any other column is a category. Then tick the covariates that occupancy and detection depend on. Each species gets an effect for each, with its interval, on the logit scale: per standard deviation for a number, and beside the first level for a category. With few sites, use few covariates: with many at once, chance effects can look real.

Saving the results

References

10. The AI models

WildObserve™ uses three kinds of model to suggest species, plus MegaDetector to find animals, people, and vehicles in the first place.

SpeciesNet

A general species model from Google, the same for everyone, on every plan. Its suggestions have no tag.

Your Project Model Researcher, Lab, and Organization

Each project's own model, trained on your computer from the boxes you label in that project. It starts once you've labeled a few examples each of two species, and retrains by itself as you review, so it keeps learning your species, cameras, and places. Its suggestions are tagged project. Images marked uncertain, and saves made by the production rules, aren't used to train it.

In Project > Models…, Your Project Model shows what it knows. Improve now retrains it at once. Versions… lists every version it trained, with how well each did on labels held out from its training, which species it finds, and which it mixes up. Use this version goes back to an earlier one, and Use the newest returns to letting it update. Export your Project Model saves it as a model package.

Production models Lab and Organization

A production model is the model a project relies on when no one is reviewing: the production rules, notifications, and email alerts go by it. Unlike your Project Model, it changes only when an administrator chooses another. Its suggestions are tagged production.

It can be the project's own Project Model, or a model imported as a model package. We can train one for you from your complete set of labeled images, tested on cameras it never saw and calibrated so its scores mean what they say (see Plans). To use one:

  1. In Project > Models…, under Model store, click Import a model package… and choose the package (a zip file). WildObserve™ checks it before adding it. Imported models are available to every project on the computer.
  2. Under This project's production model, choose it, say why, and click Use it. Each change is logged with who made it and why.

11. Exporting your data

Click Export… in the header. An export holds every reviewed image: its boxes and species, who reviewed it, and whether each box came from the detector or a person. You can also include images not reviewed yet, with the models' predictions only, and images marked uncertain. The formats:

Formats that need locations offer Edit deployments… to fill them in. Exports are files on your computer; where they go next is up to you.

12. Watched folders, rules, and alerts Lab and Organization

Watched folders

In Images…, tick Watch for new images under a folder, a folder your camera images sync or copy into, say. Its new images are then added and processed as they arrive, and the folder shows when WildObserve™ last looked. A project with watched folders keeps watching while another project is open.

On a Mac, closing the window while a folder is watched, or while images are being added or processed, keeps WildObserve™ working in the background, with an icon in the menu bar. Its menu says what WildObserve is doing, opens the window again, or quits. Once the work is done and nothing is watched, it quits by itself. To keep watching after your Mac restarts, turn on Open WildObserve when you log in in About.

On Linux, folders are watched while WildObserve™ is open. Closing the window quits it; when you open it again, it adds whatever arrived in the meantime.

Production rules

Click Rules… in the header for what WildObserve™ decides by itself once images are processed, as they arrive in watched folders too. An administrator sets them for each project.

Changing the rules looks again at the images still to review.

Notifications (Mac)

With Notify me when one turns up ticked in Rules, a species of concern in an image a watched folder brought in the last day raises a Mac notification, once per capture event. Clicking it opens WildObserve at that image, switching to its project if another is open. The first time, macOS asks whether WildObserve may send notifications; you can change that later in System Settings > Notifications. Notifications never leave your computer.

Email alerts

Email alerts tell people away from the computer when a species of concern turns up in a watched folder. They go through your own mail server, never ours. Set them up in Rules… > Alerts by email…:

  1. Mail server, once for every project on the computer. Fill in for sets the server, port, and security for Gmail, iCloud Mail, Yahoo Mail, or Fastmail. Enter your mail account's user name (usually its email address) and password. Most mail accounts need an app password for this, made in the account's security settings: in Gmail, turn on 2-Step Verification, then make one under App passwords (Google's help). Outlook.com doesn't allow it, and Microsoft 365 only where your IT turns on SMTP sign-in; a mail-sending service such as Amazon SES works too. Click Save mail server. The password is kept in your Mac's Keychain, or on Linux in a file only your user account can read.
  2. This project: list the addresses alerts go to, and turn on Send alerts for this project. Optionally, Attach the image: a smaller copy with a box around what was found, and none of the original's metadata. You can also set how long to wait before another alert about the same species at the same deployment.
  3. Send a test to check it all works.

An alert goes for images a watched folder brings after alerts are turned on, once per capture event. Adding an archive, or changing the rules, never sets off alerts about old images. Lately lists the alerts sent, held back, or not sent, with why. What alerts contain is in the Privacy Policy.

13. People, licenses, and settings

People

Click your name at the top right for your account: Change password and Sign out. Administrators also find People there: everyone who uses WildObserve™ on this computer. Add a person with their email address, name, and a password, as a reviewer or an administrator. Reviewers review images; administrators can also manage people, the rules, alerts, and the models a project uses. A turned-off account can't sign in, and its reviews keep its name.

Licenses

The free Community plan needs no license. For a paid plan, choose WildObserve > License… in the menu bar (on Linux, License in the menu under your name) and enter your license key under Activate with a license key. On a computer that can't go online, choose the license file you received instead (Choose license file…; its name ends in .wolicense).

About

WildObserve > About WildObserve (on Linux, About at the top right) has:

14. Keyboard shortcuts

In the review, when you're not typing in a field:

KeyDoes
EnterSave & next
← →Previous and next image
[ ]Previous and next frame of the capture event
1 2 3Animal, person, or vehicle: the selected box's class, or the next box you draw
Species keysName the selected box, or every animal box, that species (set in Species list)
B or 0Empty: remove all boxes
DeleteDelete the selected box
UUncertain, on or off
EscDeselect the box; with none selected, undo edits
+ -Zoom in and out (also a pinch, or Ctrl- or ⌘-scroll)
Space + dragMove around a zoomed-in image

15. Troubleshooting

macOS says WildObserve is in use when I try to replace or delete it

It's still running, probably in the background for a watched folder. Click the WildObserve icon in the menu bar and choose Quit, or press ⌘Q with its window in front. Then replace it. If you have several WildObserve disk images open, eject the old ones first, so you drag the new version.

A folder says "Not found"

Its drive isn't connected, or the folder was moved or renamed. Connect the drive, or in Images…, click Moved? and Find it… to point WildObserve™ at where it is now. Your reviews are kept.

Moving a project to another computer

Copy the project's folder, and your image folders, to the other computer. There, choose Project > Projects… > Open a project folder… (on Linux, Projects… at the top left) and open the copy. Then in Images…, use Moved? to point each image folder at its new place.

Capture events are far too big

Images with no capture time in their EXIF data use the file's date instead, and copying, downloading, or syncing files often gives many of them the same date, so they chain into one huge event. WildObserve™ warns about this when you name capture events. Check Deployments…: the event gap, and each camera's clock.

The test email fails

The user name and password are your mail account's, not WildObserve's, and most accounts need an app password rather than your usual one (see Email alerts). If the server says it didn't accept them, make a new app password and try again. Check the port and security too: 465 with SSL/TLS, or 587 with STARTTLS.

Notifications don't appear (Mac)

In System Settings > Notifications > WildObserve, allow notifications. Notifications come only for species of concern in images a watched folder brought in the last day, once per capture event.

No administrator can sign in

First try Forgot your password? on the sign-in screen. If that doesn't work, quit WildObserve, open Terminal, and run the command below with the administrator's email address. It asks for a new password.

/Applications/WildObserve.app/Contents/MacOS/WildObserve --reset-password you@example.org

On Linux, close WildObserve and run this in a terminal instead:

wildobserve --reset-password you@example.org

Getting help

In WildObserve > About WildObserve (on Linux, About), click Save diagnostic report, and email it to info@qsc.earth with a description of the problem.

Your privacy

WildObserve™ runs on your computer. Your images, their metadata, and your annotations stay there, and we never receive them. It goes online only to check for updates, activate a license, sign you in with Google if you choose to, and send email alerts if you opt in. The Privacy Policy has the details.

See also Plans, the Terms of Service, and the Privacy Policy.