.. _citizen-science-interface: ======================================= 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! πŸš€ .. contents:: Table of Contents :local: --------------- 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. .. figure:: /images/tutorial_cs/01_registration_screen.png :alt: 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. .. figure:: /images/tutorial_cs/02_login_screen.png :alt: 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. .. figure:: /images/tutorial_cs/03_project_selection.png :alt: 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. .. figure:: /images/tutorial_cs/04_project_dashboard.png :alt: 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. .. figure:: /images/tutorial_cs/05_upload_page.png :alt: 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**. .. figure:: /images/tutorial_cs/06a_deployment_details.png :alt: 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. .. figure:: /images/tutorial_cs/07_setting_location.png :alt: 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 :ref:`tutorial-add-deployments`). 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." .. figure:: /images/tutorial_cs/06b_deployment_extra_metadata.png :alt: 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. .. figure:: /images/tutorial_cs/08_selecting_files.png :alt: 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 :ref:`administration-classification-project-ai-configuration`. To learn more about the automatic pipeline workflow see the :ref:`tutorial-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. .. figure:: /images/tutorial_cs/09_deployment_summary.png :alt: 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). .. figure:: /images/tutorial_cs/10_observations_view.png :alt: 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**. .. figure:: /images/tutorial_cs/11_filtering_observations.png :alt: 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. .. figure:: /images/tutorial_cs/12_image_viewer.png :alt: 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. .. figure:: /images/tutorial_cs/13_sequence_navigation.png :alt: 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 + /`` .. figure:: /images/tutorial_cs/14_keyboard_shortcuts.png :alt: 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. .. figure:: /images/tutorial_cs/15_image_filters.png :alt: 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: 1. **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. 2. **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. 3. **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. .. figure:: /images/tutorial_cs/16_bulk_classification.png :alt: 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 :ref:`tutorial-create-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. .. figure:: /images/tutorial_cs/17_creating_team.png :alt: Defining a new team's area of interest on the map 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. .. figure:: /images/tutorial_cs/18_profile_page.png :alt: The user profile page 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: .. code-block:: text 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: 1. Collects the three knots ``K0`` (frame 0), ``Km`` (frame 5), ``K1`` (frame 10). 2. Linearly fills frames 1-4 between ``K0`` and ``Km``. 3. Linearly fills frames 6-9 between ``Km`` and ``K1``. 4. 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``): .. code-block:: typescript 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: .. list-table:: :header-rows: 1 :widths: 30 70 * - 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: .. list-table:: :header-rows: 1 :widths: 30 70 * - 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 :ref:`configuration-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 :ref:`configuration-frame-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//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 :ref:`configuration-frame-hypertable`.