1. Getting started

The app reviews the detections of one clustering run at a time. Nothing leaves your computer: the files are read in the browser.

1. Results ZIP. Drop the *_annotation.zip written by the pipeline on the setup screen (or pick the CSVs one by one under "upload files individually"). detections.csv is all it needs; mosaic_annotations.csv (the pipeline's order) and run_parameters.json are used when present, and the mosaic pages are not needed. A YOLO dataset (one labels/*.txt per image, with the class names in classes.txt or a data.yaml; the app's own export included) is accepted too. Its boxes are taken as finished labels, so it exports without padding.
2. Original frames (required). Drop the raw shadowgraph images of the run, or their folder, on the second zone of the setup screen, or choose them there. Every thumbnail is cut from its frame, once, the group on screen first, and kept in this browser, so once they are all cut the next visit of the same run needs the ZIP only (a visit closed earlier asks for the frames again and carries on). The frames also give Frame View, where boxes can be moved, resized and drawn on the image. The files are referenced in place, so a full run loads instantly; other files in the folder are skipped, the pipeline's cluster_*.png mosaic pages too. A frame name found twice (the raw frames and the pipeline's copies with the boxes drawn in) keeps the file nearest the folder chosen, and the status says so.
3. Session file (optional). If you continue work whose browser copy is gone, pick the session JSON you saved earlier (see Saving your work). It is applied once the ZIP is loaded.
4. Press Load & initialize interface.

When a previous session is found in this browser, a dialog offers to restore it before anything is loaded. It names the ZIP the session belongs to. To continue another day, see Saving your work.

2. Two views

The Clusters / Frames toggle in the top bar switches between them; the ← Clusters button in the frame toolbar goes back. The numbers in the top bar are the whole run: detections, confirmed, rejected, open, plus flagged and deleted when there are any. The theme button at the right end (☀︎ or ☾) switches between the light and the dark theme; it follows the system until you choose.

• Cluster View lists the groups on the left, purest cluster first when the ZIP has run_parameters.json, with a count and a progress bar each; the selected group's thumbnails fill the middle, and the inspector on the right shows the focused particle. Show all groups at the bottom of the list stacks every group on one page instead; the same button, now One group at a time, goes back. Hide empty clusters (classes), under the switch at the top, leaves out the groups with no thumbnail left, all relabeled to another class or deleted; the number next to it says how many there are. This is where a run is triaged quickly.
• Frame View shows the original image with every box drawn on it. This is where geometry is corrected and missed particles are added.

The two stay in step. Select a thumbnail and press F (or Show on frame in the inspector) to open its frame zoomed on that box; select a box on a frame and press F to find its thumbnail. Any decision made in one view shows in the other at once.

3. Reviewing clusters

• Decide. A click selects a thumbnail and shows it in the inspector; its decision does not change. Click the selected thumbnail again to cycle it: unlabeled → confirmed → rejected. With the keyboard, arrows move the focus, C confirms and X rejects the focused thumbnail and step to the next one, Space cycles it, U resets.
• Relabel. Right-click a thumbnail (or press R) for the class picker; 1–9 assign the n-th class directly. A relabeled detection is confirmed at the same time.
• Flag (W) parks an uncertain particle with an amber outline and moves it to the for_review group, first in the group list. Its class does not change. It stays open and batch buttons skip it. A decision there (C, X, U), or W again, sends it back to its group.
• Delete (Delete, the inspector button, or the selection toolbar) removes a wrong detection from the dataset: it leaves every view and every export, but stays in the record. The Deleted filter shows them; U brings one back. A box drawn by hand is removed for good (undo works).
• Whole groups. Confirm all visible / Reject all visible / Reset visible above the thumbnails act on the group on the stage, restricted by the filter. With groups stacked (by hand or by a filter) they act on every group shown, after asking; each group also has its own buttons.
• Select many. Shift+drag a rectangle, Shift+click thumbnails one by one, Shift+arrows to extend, or Ctrl/Cmd+A for all visible, then confirm, reject, relabel, flag or delete the selection.
• Filter with the Show bar (All, Open, Confirmed, Rejected, Relabeled, Flagged, Recent, Drawn, Edited, Deleted) and the class next to it. A filter looks through every group: the groups with a match are stacked, showing only their matches, and the list on the left gives each group's number of matches. A thumbnail that stops matching (confirmed under Open) is only dimmed where it is; choose the filter again to tidy up. Back to All, one group at a time again. Navigation and batch actions only touch what matches, in both views; with the groups stacked, the arrows and the step after C / X go on from a group's last match to the next group. A filter puts the focus on the first match of the group you are in (another group only when yours has none). N jumps to the next detection without a decision.
• Group by class. The switch at the top of the group list regroups the thumbnails by their class after relabels, open ones first, so the work can be checked class by class. A decision tints a tile where it is; Sort by status re-sorts each class (open, flagged, confirmed, rejected, deleted) when you want it. A relabeled tile moves to its new class; a renamed class keeps its place. Boxes drawn by hand are tiles under their class in both groupings, cut out of their frame.
• Thumbnails move. Every thumbnail is a tile of its own, so a relabeled one moves to the section of its new class in either grouping, and the counts follow. A class added by hand gets a section of its own.
• Numbers. Cluster headers keep the pipeline's count and show what was decided and how many were moved out or in by relabels. The class strip, the Class names panel and the pickers count what is in each class now, after relabels and rejections. Classes with the same name are one class everywhere.
• Undo with Ctrl/Cmd+Z, batch actions included. The ⟲ button lists recent decisions; click one to jump to it.

The inspector on the right shows the focused particle in its original frame, centred on its box, with its cluster, class and status. The Zoom slider goes from the wide surroundings to the box alone. Drag the box to move it, or drag a corner or an edge to resize it; the thumbnail is recut and marked as edited, and Ctrl/Cmd+Z undoes it. Double-click the picture to open Frame View there. Without frames, the inspector shows the thumbnail instead.

4. Editing on the frame

Frame View needs the original frames. The toolbar holds three tools:

• Select (V): click a box to select it; drag its body to move it, drag a corner or edge to resize. Boxes stay inside the image.
• Draw (B): drag a rectangle on the image. On release the box takes the active class, the highlighted chip of the class strip; with none active, a class picker appears next to it. The new box is confirmed with that class.
• Pan (H): drag to move around. In any tool, Ctrl/Cmd+wheel or a pinch zooms at the cursor; + - 0 zoom in, out and fit.

With a box selected, C X U W confirm, reject, reset and flag it, a right-click or R relabels it, a click on a chip of the bottom class strip relabels it too, and Delete removes a drawn box, or takes a model detection out of the dataset (Deleted filter, U restores). Esc cancels a drag or a drawing in progress and returns to Select. Ctrl/Cmd+Z undoes moves, resizes, drawings, deletions and relabels.

The border colour of a box is its class; the fill tint is its status. Class labels appear once a box is large enough on screen, and always on hover. The frame list on the left shows per-frame progress and follows the active filter, as do the boxes on the image. Above it, choose a class (only the frames that have it; its boxes stand out) and the order: by name, most detections or most open first. A box you moved or resized carries a ✎ badge on its thumbnail, which is then cut from the frame with the new geometry.

Wrong boxes. X rejects a detection: it leaves the training export but stays in the CSV as "rejected", so the record shows what was reviewed (tick Leave rejected detections out of the CSV exports for a clean CSV). Delete removes it from the dataset altogether: out of every view and export, kept in the record, found again with the Deleted filter and restored with U. Boxes you drew yourself are removed by Delete. Boxes that are too tight around fine appendages are padded on export (10 % per side by default, see Exporting) or resized here.

5. Classes and names

• Every cluster starts as class_N; the pipeline's reject cluster, where it puts poor detections (marked in run_parameters.json), is low_quality. These names become the YOLO class names, so rename them.
• Rename inline by double-clicking a chip of the bottom class strip, or in the Classes dialog (top bar) for a bulk pass.
• Add a class with the + Add class chip or from any class picker; a class nobody uses can be deleted from its chip.
• Attributes besides the class: image quality, orientation, or any set you name. The inspector lists each set's values: click one to give it to the focused particle, or to the whole selection; click it again to take it off; + types a new value. A thumbnail with attributes has a ◆ mark. Classes ▸ Attributes adds, renames and deletes sets and values (a renamed value is renamed on the particles that have it; a deleted one is taken off them, after asking). The list is kept in this browser for every run and saved with the session; the values go into the CSV exports, the GBIF workbook and, beside the YOLO labels, an attributes.csv. The filter offers them next to the class.
• GBIF names. In the Classes dialog, every name box searches GBIF's taxonomy (the Catalogue of Life, as on gbif.org) as you type: Daphn lists Daphnia, Daphnidae and the other taxa starting with it, plankton groups first, ranks such as the infraorder Cladoceromorpha included. Names the Catalogue of Life lacks (the copepod orders Calanoida, Cyclopoida, Harpacticoida) come from GBIF's old backbone, marked GBIF backbone; GBIF files such records under the nearest higher taxon it knows. Pick one with the mouse or ↑ ↓ Enter: the class takes that name, and its rank, kingdom and higher taxonomy are filled in. Enter without a pick keeps the name as typed; Check looks such a name up later, and Edit types a taxon by hand. The class pickers search GBIF the same way. Together with the Run metadata section this feeds the Darwin Core export used for the GBIF hand-off.

6. Saving your work

• In this browser, automatically. Two seconds after an edit (and when the tab closes) the session is written to the browser's storage. The indicator in the command bar confirms it. On the next visit the app offers to restore it. The browser keeps one copy for all runs and all tabs: work in one tab at a time (a second tab that starts annotating makes both download their work as files, and says so). Start Fresh in that dialog downloads the copy as a file before clearing it.
• As a file, when you want a copy. Session ▸ Save session… downloads a JSON named after the run and the date. It starts with a summary you can read in any editor: run, time, counts, and the list of images that carry annotations. Keep these files: they are your backup and the way to move work to another computer.
• As a file, continuously (Chrome and Edge). Session ▸ Also write to a file on disk… lets you pick a file once; every automatic save is then also written there, and the next visit offers to resume writing to it.
• Getting it back. If the browser copy is gone, choose the file in the session file box of the setup screen before loading the ZIP, or use Session ▸ Load session… once the run is open. Files saved by earlier versions of the app load the same way.

Continuing another day (same computer, same browser): nothing to save before leaving. Open the page, choose Restore Session in the dialog that names your run, then choose the results ZIP again (a browser never keeps files between visits). The frames are asked for again only if the thumbnails were not all cut last time; otherwise they serve Frame View only. Load, and you are where you stopped. On another computer or in another browser, or after clearing the browser's data, pick your last saved session file in the session file box instead. A saved file is a snapshot: what you did after saving it is only in the browser until you save again (or use Also write to a file on disk).

Files the app downloads by itself. Whenever work could be lost, the app first downloads it, named after the run it belongs to (which may be another run than the one open: an old copy left in this browser, for instance). One you do not need can be deleted.

• …_session_<date>.json: Session ▸ Save session…, and each tab's work when a second tab starts annotating.
• …_browser-copy_<time>.json: the browser's copy before it is dropped (Start Fresh, Cancel when another run's ZIP is chosen).
• …_session_before-transfer.json: the previous run's session, before its decisions are transferred to a new run.

A new run of the pipeline. A session belongs to one run, because decisions are attached to the detection numbers of that run. When you load a session with another ZIP, the app offers to transfer it: each decision goes to the particle found again on the same image at the same place, classes travel by name, boxes you drew are re-created, and a report lists what could not be matched (particles the new run did not find, images no longer in it), which simply stay open. Decisions already made in the new run are never changed, and the previous session is left untouched (a browser copy is downloaded as a file first). Sessions saved by older versions do not record positions: the report then asks for the previous run's ZIP.

7. Exporting

Everything is under Export ▾ in the top bar; Export options… opens the padding, the CSV option and the preview:

• CSV: every detection with its original cluster, final class, status, edited geometry, a user_drawn flag and a column per attribute set in use. Preview shows it in the page; the ZIP variant writes one CSV per image.
• YOLO ZIP: one label file per image plus classes.txt and data.yaml. Only confirmed detections are written, drawn boxes included. Coordinates are normalised with each frame's own size and clipped to the image. To train, copy the frames into an images/ folder beside labels/; data.yaml finds it from any working directory. A frame that still has open detections would teach those particles as background, so finish a frame before training on it (the preview and data.yaml count such frames). With attributes in use, attributes.csv gives each label line its attributes (training ignores it).
• GBIF Darwin Core Excel: the workbook the GBIF app imports, built in the browser from the confirmed detections, the taxa and the run metadata (Classes dialog) of the run that is open; each attribute of a detection is a row of its measurements-or-facts sheet. identifiedBy is the name typed under Run metadata ▸ Identified by.

The padding slider (Export dialog, or Pad in the frame toolbar) grows every exported box by a percentage of its own size without changing the data, 10 % per side by default because the pipeline's boxes often cut fine antennae (0 % for a YOLO dataset loaded as input); Frame View previews it with the original as a dashed outline. The export section also says how many decisions changed since the last export.

8. Keyboard shortcuts

Also available at any time behind the ? button or the ? key. Tab and Shift+Tab move from group to group in the list.