Citizen Science Interface

Tutorial by Jakub W. Bubnicki (OSCF)

Welcome to the Trapper Citizen Science platform! This guide will provide a comprehensive walkthrough of the essential features of our interface, from registering a new account and uploading your first set of camera trap images to classifying wildlife and managing your projects. Let’s get started! 🚀

Getting Started 

If you’re new to Trapper, your first step is to create an account. If you already have one, you can jump straight to the login section.

Registration / Creating a New Account 

Welcome aboard! Creating an account is simple and will get you into the action in no time.

On the main login page, click the Create an account button. This will take you to the registration form.
Fill in your details, which typically include your First name, Last name, E-mail, and a secure Password.
You will need to review and agree to the Terms of Service and Privacy Policy before proceeding.
Click the final Create an account button to submit your information.

Important

After registering, check your email inbox for a verification link to activate your account. You won’t be able to log in until you’ve completed this step.

Note

If you already have an account in the Trapper Expert module, you can log in to the Citizen Science interface using the same e-mail and password — no separate registration is required. If you still cannot access a project, contact your project administrator to grant the necessary permissions.

Trapper account registration screen — The registration form for new users.

Logging In 

Once your account is activated, you can sign in.

Navigate to the Trapper login page.
Enter your E-mail and Password.
Click the Sign in button.

Note

You also have the option to sign in using a Google or Microsoft account (third-party authentication services). Please note that these social login options must be configured in advance by an administrator in the Trapper Expert admin panel.

Trapper login screen — The main login screen with fields for email and password.

The Main Dashboard 

After logging in, you’ll land on the Citizen Science project selection page. This is your mission control, where you can see all the projects you’re a part of. To begin working, simply click on the project you wish to access.

Project selection dashboard — Your central hub for accessing different research projects.

Once you enter a project, you’ll see the project’s dashboard, which gives you a quick statistical overview, including the number of locations, deployments, media files, recordings, and camera traps. You can also see a bar chart that visualizes the distribution of species identified, providing an immediate insight into the biodiversity captured.

Project-specific dashboard with statistics — A summary of your project’s data at a glance.

Uploading Camera Trap Media 

Uploading your images and videos is the first step in analyzing your data. Our uploader is designed to capture all the necessary metadata for a successful deployment.

Step 1: Start a New Upload 

From the main navigation menu, go to the Upload section. This will take you to the upload form.

The main upload page — The starting point for adding new media.

Step 2: Add Deployment Details 

A deployment refers to a single session of a camera trap at a specific location.

Important

A deployment is the period during which a camera trap is installed at a given location and actively recording, typically without being moved or significantly altered. Ecologically, a deployment represents a continuous sampling event, capturing all wildlife activity within the camera’s detection zone for the defined time span. Each deployment is uniquely identified by its combination of location, time interval, and camera setup, and is fundamental for linking collected media and metadata to ecological analyses such as species occurrence, activity patterns, and habitat use. Read more

Deployment name: Give your deployment a unique and descriptive name (e.g., bialowieza_lcm_2025).
Date range: Click the date field to open a calendar and select the start and end dates of the deployment. For this example, you might select August 1st to September 23rd, 2025.
Bait type: Specify if any bait was used. For most scientific studies, this will be none.

Filling in deployment name and date range — Defining the basic information for your deployment.

Step 3: Set the Location 

Accurate location data is crucial. You can either select an existing location or create a new one.

Click Create a new location.
Location name: Enter a name for the new camera trap site (e.g., bialowieza_loc1).
Set Coordinates: Click on the map to place a pin at the exact location of your camera. You can see the map of the Białowieża Forest area and zoom in for greater precision. The latitude and longitude will be filled in automatically.

Creating a new location and pinning it on the map — Pinpointing your camera’s location for accurate spatial analysis.

Note

By default, the Deployment name (code) is combined with the Location name to create a unique deployment identifier in the following format:

{deployment_name}-{project_id}-{user_id}-{location_name}.

Custom deployment names and IDs can be provided via the Expert module - either by creating deployments manually or by importing a CSV file in the Camtrap DP format (see the tutorial section 4. Add deployments to TRAPPER). The only requirement is that each deployment ID be unique within its project. Deployments added in this way will then be available in the upload form for users who have the appropriate permissions to select and use them.

Step 4: Enter Camera and Additional Metadata (Optional but Recommended)

While optional, providing detailed metadata enriches your data and makes it far more valuable for scientific analysis. More data is always better!

Here are some of the key fields you can fill in:

Camera model: Enter the make and model of your camera (e.g., browning_btc6).
Camera ID: A unique identifier for the physical camera unit (e.g., camera1). This helps track specific devices.
Camera interval: The delay between triggered events in seconds (e.g., 0).
Camera height: The height of the camera from the ground in meters (e.g., 1.2).
Camera tilt: The vertical angle of the camera. Use 0 for parallel to the ground, or a positive/negative value for angled down/up (e.g., “-10” for a slight downward tilt).
Camera heading: The compass direction the camera is facing (e.g., 270 for West).
Detection distance: The estimated effective range of the camera’s sensor in meters (e.g., 20m).
Feature type: The type of feature the camera is monitoring (e.g., Road dirt, Water source, Carcass).
Habitat: A description of the habitat type (e.g., mixed forest, riparian zone).
Timestamp issues: Check this box if you know there was a problem with the camera’s clock.
Comments: A free-text field at the bottom of the page for any other relevant notes. This is the perfect place for observations like “Camera was knocked by a boar on Sept 15th” or “Battery change performed on Sept 10th.”

Entering detailed optional metadata for the camera and deployment — Adding rich metadata makes your data more robust and useful for analysis.

Important

Data Standardization: All the deployment metadata fields in Trapper, from camera settings to location data, are fully compatible with the Camera Trap Data Package (Camtrap DP) standard. This ensures that your data is structured, interoperable, and ready for sharing with global biodiversity platforms. You can learn more at the official Camtrap DP website: https://camtrap-dp.tdwg.org/

Step 5: Upload Your Files 

Now it’s time to add your media!

Click the Drag & drop or choose file to upload area.
Navigate to the folder on your computer containing your images or videos.
Select all the files you want to upload and confirm. You can select multiple files at once.
A progress bar will appear showing the status of your upload. Wait for it to complete.

Selecting files from a local folder — Choosing the images and videos for your deployment.

Note

Automatic AI Processing: Once your files are successfully uploaded, they automatically enter an AI data processing pipeline. This pipeline, which may include object detection and species identification models, is configured in the project’s Classification Project settings. For more details on configuring this pipeline, please see the Classification project administration. To learn more about the automatic pipeline workflow see the Automatic AI Pipeline Workflow.

Viewing Your Data 

Deployment Summary 

Once the upload and initial processing finish, you will be redirected to the Deployment Summary page. There you can view:

A data panel displaying all entered metadata, including the deployment ID, location, coordinates, date range, and deployment owner.
A gallery of the images you uploaded. The system will display “Classification in progress…” while the AI analyzes your media.
An interactive map showing the deployment location; you can zoom in and out to examine it in greater detail.
Additional information, such as extra metadata fields, comments, and options to mark images as private or to flag an incomplete deployment.
Statistics about the processed data, including resources processed by object detection and species models, resources you classified, and resources classified by other experts.

The deployment summary page after a successful upload — A complete overview of your newly created deployment.

The Images / Media View 

The Images tab (or Media, when working with both images and videos) lets you browse and filter all media files available in this project. Each row represents a single media file and its associated observations (no detections, animals, humans, or vehicles).

A list of all animal observations — Browse every animal detection identified by the AI.

You can use the advanced filters at the top to narrow down the results by Deployment, Species, Shared by team, Observation type (e.g., Animal, Human, Vehicle), Sex, Age, and Classified by me.

Filtering observations to show only Red Deer — Quickly find the exact data you’re looking for.

The Image Viewer 

Clicking on any observation in the list opens the Image Viewer. This powerful tool allows you to:

View the image with AI-generated bounding boxes and labels.
Zoom in and out for a closer look.
Adjust contrast, brightness, and saturation using the image filter tools to enhance visibility, especially in nighttime shots.
Easily navigate between other images in the same sequence using the thumbnails at the bottom.
View video files and play them directly in the viewer.

Viewing a single observation in the image viewer — Inspect individual detections in detail.

The Classification Interface 

The Classification module is where you, the expert, can review, correct, and validate the AI’s work. This is the heart of the platform, designed for both precision and efficiency.

Navigating Your Data 

The interface organizes media into sequences.

Note

What is a sequence? A sequence is an ecological event. It’s a group of images or videos that captures a continuous event, like an animal or group of animals passing in front of the camera. The system automatically groups media into a sequence if they are captured within a specific time of each other (e.g., 5 minutes). This allows you to analyze a single event instead of many separate photos, which is crucial for tasks like counting unique individuals. Read more

The interface provides efficient navigation at multiple levels: single objects, individual media files, and whole ecological events (sequences).

Single-object navigation: jump directly between annotated objects (click a bounding box or use keyboard shortcuts) to inspect or edit individual detections.
Single-media navigation: move through images or videos using the next/previous controls or by selecting thumbnails in the sequence strip.
Event/sequence navigation: navigate entire ecological events via the sequence strip, select multiple frames for group actions, or jump directly to a specific sequence or resource by entering its ID.

The sequence navigation bar with thumbnails — The sequence strip at the top allows for efficient navigation through ecological events.

Important

Keyboard Shortcuts: To maximize your efficiency, the interface supports a variety of keyboard shortcuts for common actions like navigating between objects and images, zooming, and applying classifications. To see the available list of keyboard shortcuts, use the following keys: Ctrl + /

The keyboard shortcuts help dialog — Access the full list of keyboard shortcuts to speed up your workflow.

The Interactive Canvas and On-the-Fly Filters 

The main image viewer is more than just a picture frame; it’s an interactive canvas. This is your workspace for all annotation tasks. You can:

Draw new bounding boxes by clicking and dragging.
Select existing boxes to edit them.
Resize and move boxes for a perfect fit.
Zoom and pan to inspect details anywhere on the image.

To help with classification, especially in challenging lighting conditions, you can use on-the-fly image filters. Sliders for Contrast, Brightness, and Saturation are available directly in the interface. Adjusting these can reveal details in dark infrared shots or correct overexposed daytime images, ensuring you never miss an important visual cue.

Adjusting brightness and contrast on a nighttime image — Enhance your media in real time to make classification easier and more accurate. The empty bounding box labeled `animal` is shown for demonstration purposes only.

Flexible Annotation Modes 

To accommodate different workflows and maximize speed, the interface supports multiple annotation modes:

Single Object Annotation: The most precise method. Click on a single bounding box. This will highlight it and open the classification form for that specific object.
All Objects on Image Annotation: To classify everything in the current view at once, you can select all objects on the image and apply a single classification to them.
Group Classification (Bulk Mode): This is the most efficient method for sequences with the same species. In the sequence thumbnail strip at the top, you can select multiple images. The interface will enter “Group classification mode”. Any classification you make will be applied to all objects in all the selected images. This is a massive time-saver.

Group classification mode with multiple thumbnails selected — Classify entire parts of a sequence in a single action to dramatically speed up your workflow.

The Project-Specific Classification Form 

When you select an object to classify, a form appears. This form is dynamic and project-specific.

Important

The fields you see (e.g., species, sex, age, number of individuals, behavior) are not hard-coded. They can be customized for each project by a project manager in the Trapper Expert module using a feature called the Classificator object. Some standardized fields are required for all classificators (for example observation_type and species), while others are optional (for example age and sex). All predefined fields conform to the Camtrap DP standard. Read more

The Classificator also allows you to define custom fields and assign a data type (e.g., string, integer, float, boolean) and validation rules. These settings enable automatic input validation in the UI to help ensure consistent, high-quality data. See the tutorial section 1. Create a Classificator for details.

For example, a project studying wolves might include custom metadata fields for howling_activity (boolean) and health_status (string | enum), while a project on roe deer might include fields for antler_development (boolean). This flexibility ensures that the data you collect is tailored to your research questions while remaining standardized for interoperability: all fields can be mapped to the Camtrap DP schema (e.g. custom fields can be exported as observationTags) so datasets are consistent, shareable, and machine‑readable across projects and platforms.

Managing Teams & Profile 

Creating a Team 

Collaboration is key! You can create teams to work on projects together. To share data and annotation efforts.

Go to the Teams section and click to create a new one.
Give your team a name and a description.
Use the map tools to draw a polygon defining your team’s primary area of interest. This helps organize your research efforts. You can also upload a GeoJSON or GPX file to define the area.

Note

Teams are a flexible self-organization tool for Trapper users — whether researchers, hunters, NGO staff, national park personnel, or volunteers — to coordinate fieldwork, share data and responsibilities, and organise annotation efforts. Teams support local collaboration while project permissions remain governed by administrators.

Organize your collaborative work by creating teams.

Profile and Settings 

You can manage your personal information, change your password, change theme (light vs dark mode) and set your preferred language by clicking on your profile icon.

General: Update your email, username, first name, last name, phone number, institution, and write a short bio about yourself.
Change password: Update your password for security.
Multiple factor authentication: Enable two-factor authentication for added security.
Delete account: You have the option to delete your account.
Language: The interface supports multiple languages to accommodate our global community of users. You can switch between English, Swedish, Polish, and German.

Keep your personal information up to date.

You’re now ready to master the Trapper Citizen Science Interface. Happy trapping! 📸🌲

Expert-Mode Video Annotation with Interpolation Tools 

For video classifications, the citizen-science interface offers an expert-mode annotation panel that adds a per-frame timeline, piecewise-linear bounding-box interpolation, occurrence-aware track navigation, and bulk delete / merge actions on top of the standard single-bbox annotation flow.

This section is grounded in the live frontend source — chiefly [classification-hotkeys.service.ts](https://gitlab.com/trapper-project/trapper-frontend/-/blob/main/libs/classification-hotkeys/src/lib/classification-hotkeys/classification-hotkeys.service.ts) and [resource-annotator.component.ts](https://gitlab.com/trapper-project/trapper-frontend/-/blob/main/libs/resource-annotator/src/lib/resource-annotator/resource-annotator.component.ts) — so it stays correct as the UI evolves only when those files change.

Modifier-key convention 

The shortcut tables below use meta for the platform-aware modifier that classification-hotkeys.service.ts resolves at runtime:

meta = Cmd on macOS.
meta = Ctrl on Windows / Linux.

So a binding written meta+i means Cmd+I on a Mac and Ctrl+I elsewhere. Where Shift / Alt are involved, the order is meta+shift+... / meta+alt+...; the actual press order on the keyboard does not matter.

Two scopes 

Shortcuts split into two scopes:

VIDEO scope — only active when a video classification is open. Frame transport, keyframe management, interpolation, occurrence navigation, and merge live here.
BASE scope — always active in both video and image classifications. Bbox selection, classification / sequence navigation, save, and the in-app shortcut help live here.

Both scopes are activated together when video annotation is in use, so a video user has access to every binding listed below.

The in-app cheat sheet is always accessible via meta+/ and reflects the current build; this page is the offline reference.

What “object” means here 

The frontend uses the term object for what the AI worker calls a detected object (a multi-frame track of one individual). An object has a sparse bboxes array indexed by frame number — most entries are null (no observation on that frame), some are filled with [x, y, w, h] numbers. A contiguous run of non-null entries is an occurrence: the animal entered the frame, did something, and exited.

A single tracked individual can have multiple occurrences — for example, an animal that walks behind a tree and re-emerges produces two runs of non-null entries with a null gap between them.

How interpolation works 

Interpolation is explicit, never automatic. The frontend never fills in bboxes on its own; it only does so when you press one of the two interpolation hotkeys.

The math is linear independently on x, y, w, h (interpolateBbox in resource-annotator.component.ts:135-148). The fill algorithm (fillInterpolatedBboxes at resource-annotator.component.ts:1521-1576) is piecewise: it collects every existing non-null bbox in the active range as a knot, then interpolates only the null slots strictly between consecutive knot pairs. Existing bboxes are preserved — never overwritten — even if they sit between two knots that would otherwise imply a different value.

Concretely, if the selected object’s bboxes array looks like:

frame:  0   1    2   3   4   5    6    7    8   9   10
bbox:  K0   .    .   .   .  Km    .    .    .   .   K1
                             ^                        ^
                             └─ existing intermediate knot
                                                      └─ keyframe
                                                         (or current
                                                          frame)

…and you trigger meta+i with the keyframe at frame 0 and the current frame at frame 10, the algorithm:

Collects the three knots K0 (frame 0), Km (frame 5), K1 (frame 10).
Linearly fills frames 1-4 between K0 and Km.
Linearly fills frames 6-9 between Km and K1.
Leaves Km itself untouched.

This is what the source comment calls “fill gaps between existing knots” (resource-annotator.component.ts:1534-1537). Adding a manually-edited bbox in the middle of a previously-interpolated run is therefore the way to correct interpolation drift: the new bbox becomes a knot, and re-running interpolation re-shapes the adjacent segments around it. There is no separate “promote to keyframe” gesture — any non-null entry is a knot.

Validation:

The frame range must be at least 2 frames wide, otherwise the command errors with “endFrame - startFrame must be ≥ 2” (resource-annotator.component.ts:1529-1532).
At least two knots must exist in the range — typically one at the keyframe and one at the current frame (resource-annotator.component.ts:1546-1551). The error reads: “Need a bbox at both the keyframe and the current frame.”

Two flavours of interpolation 

meta+i (interpolate since keyframe) — fills between the most recent keyframe (a frame the user explicitly marked with meta+k) and the current frame. Use after marking the start of a clean run and scrubbing to the end of it.
meta+shift+i (interpolate since previous occurrence) — fills between the end of the previous occurrence of the same object and the current frame. Use when the object reappears after a gap and you want to bridge the two runs.

The keyframe is a separate marker from the bboxes themselves. It is toggled by meta+k: pressing on an unmarked frame sets the keyframe; pressing on the already-marked keyframe clears it. meta+shift+k always clears, regardless of state.

Occurrence-aware navigation 

Four navigation actions move the playhead relative to the selected object’s runs of non-null bboxes (resource-annotator.component.ts:1815-1908). All four require exactly one object selected; with zero or more than one selected they error.

meta+shift+g — first frame of object: Jumps to the first frame anywhere in the timeline where the selected object has a non-null bbox (object.bboxes.findIndex(b => b !== null)). Useful for “rewind to the very start of this animal’s appearance”.
meta+h — previous occurrence: Jumps to the end of the previous run — the last frame before the current run’s start gap. If the playhead is inside a run that has no preceding run, falls back to jumping to the start of the current run, so the action always does something visible.
meta+j — next occurrence: Mirror of the previous: jumps to the start of the next run. If the playhead is inside the last run, falls back to jumping to the end of the current run.
meta+l — go to keyframe: Jumps to the frame currently set as the keyframe (via meta+k). Does nothing if no keyframe is set.

The “occurrence” / “run” model is implemented by two helpers (resource-annotator.component.ts:1842-1851):

isRunStart(bboxes, f) = bboxes[f] != null && (f === 0 || bboxes[f - 1] == null)
isRunEnd(bboxes, f)   = bboxes[f] != null && (f === bboxes.length - 1 || bboxes[f + 1] == null)

Frame transport, save, selection 

The frame-transport, save, and selection bindings round out day-to-day annotation:

Shortcut	Action
`space`	Toggle video playback (play / pause).
`shift+right` / `shift+left`	Step forward / back one frame.
`meta+shift+right` / `meta+shift+left`	Step forward / back ten frames.
`right` / `left`	Next / previous classification (different object on the same media or moves to the next media if the queue advances).
`meta+right` / `meta+left`	Next / previous sequence.
`meta+down` / `meta+up`	Select next / previous bbox on the current frame.
`meta+a`	Select all bboxes.
`meta+shift+a`	Select the entire current sequence.
`meta+alt+d`	Deselect bboxes.
`escape`	Deselect (or cancel current edit).
`meta+escape`	Clear sequence selection.
`meta+s`	Save the classification.
`meta+shift+down`	Move keyboard focus into the first form field of the attributes panel.

Track lifecycle: keyframes, deletion, merge 

Within a single object’s timeline:

Shortcut	Action
`meta+k`	Toggle keyframe at the current frame.
`meta+shift+k`	Clear keyframe (idempotent — does nothing if no keyframe).
`meta+i`	Interpolate from keyframe to current frame.
`meta+shift+i`	Interpolate from previous occurrence’s end to current frame.
`meta+d`	Delete this object’s bbox on the current frame only.
`meta+shift+d`	Delete this object’s bboxes from the keyframe forward.
`meta+shift+alt+d`	Delete the object’s entire bbox track (every frame).
`meta+shift+m`	Open the merge modal — pick a different object whose track this one should be appended onto. The selected object’s bboxes from the current frame onward are copied into the chosen previous object, then the selected object is deleted (`mergeObjects()` at `resource-annotator.component.ts:1733-1767`).

There is no track-splitting hotkey in the current frontend. A treatAsNewIndividual function exists in the source (resource-annotator.component.ts:1625-1655) but is not bound to a hotkey or surfaced in any UI control, so the operation is effectively unavailable to end users today. Treat one continuous track as two individuals only via the AI pipeline upstream (re-run with a different tracker; see Trackers) or by editing the resulting msgpack offline.

In-app help 

meta+/ opens the Hotkeys dialog with the current build’s shortcut bindings auto-rendered from classification-hotkeys.service.ts. If anything in this section disagrees with that dialog, trust the dialog — the table here is a best-effort offline mirror.

Todo

Add screenshots: expert-mode annotation panel layout, timeline showing keyframe + filled (interpolated) frames + null gaps, merge-objects modal, in-app hotkeys dialog.

What happens to your edits 

When you press meta+s (or autosave triggers), the frontend:

Walks every object’s full bboxes array — every non-null entry, whether you placed it manually, it came from the AI tracker, or it was filled by a prior interpolation run — and emits one row per non-null frame.
Encodes the rows into the AggregateFramesPayload msgpack format documented in Frame-level data and USE_FRAMES_HYPERTABLE, zstd-compresses, and uploads the blob with the rest of the classification payload (classification-view.component.ts:935-992).

Two consequences are worth knowing:

Interpolation is materialised before save. The backend never re-interpolates; whatever shape your timeline has when you press save is the shape the database stores. Re-running interpolation later requires editing in the frontend again.
No per-frame attribute overrides. The classification form’s attribute values (species, sex, age, behaviour, …) are stored once per object, not per frame. The frontend has no per-frame attribute editing surface. Per-frame AI metrics (confidence, distance) are read-only and come from the AI pipeline.

If your edits don’t seem to make it to analytics queries, check:

The Celery worker is running (./profiles/<profile>/logs.sh celery).
The USE_FRAMES_HYPERTABLE flag in your profile .env — with the flag off, edits land in the msgpack file but the hypertable index is not built.
The upsert_frames_from_msgpack task hasn’t queued behind a long backlog (Flower at http://localhost:5555).

For deeper background on the per-frame storage architecture, see Frame-level data and USE_FRAMES_HYPERTABLE.