Create a classification project¶

Before you begin¶

• A Research Project you own or manage
• At least one Collection with Resources
• AI Providers registered, if you want automatic processing — see Register & sync AI providers

Quick start¶

The minimum steps to get a working Classification Project where annotators can start classifying resources:

1. Create or pick a Research Project¶

Research → Research projects, then the + icon. Fill in name, acronym (max 10 characters), and the sampling design fields — see Your first research project for the full field list. Your request goes to an admin for approval; once approved, you're the owner.

2. Add a Collection¶

A Collection groups Resources, typically one ingestion session. Resources join a Collection at upload time (via trapper-tools or the Citizen Science Upload wizard); there's no admin-UI action to reattach already-uploaded Resources to a different Collection after the fact.

If you need to create an empty Collection ahead of an upload: Storage → Collections → +, set name/owner/status, save. Then link it to your Research Project from the Research Project's edit page (scroll to Research project collections inline at the bottom, add a row).

3. Build a Classificator¶

Media classification → Classificators → + — see Your first research project for the full step-by-step.

4. Create the Classification Project¶

Media classification → Classification projects → +, fill in at minimum:

• Name and Research project
• Classificator (from step 3)
• Owner (typically yourself)

Set the AI models if you want automatic processing (see AI Models below). Save.

5. Attach collections and build sequences¶

A Classification Project does not have a direct Collections field in its own form — instead, create a separate Classification projects collection row linking the two: Media classification → Classification projects collections → +, pick Project + Collection.

Then, from that same page's action dropdown, run (Re)build sequences for selected collections — without this step the classify view cannot step through bursts of resources.

See Your first research project, step 7.

6. Assign annotators¶

On the Classification Project's edit page, two inline tables at the bottom handle this:

• Project roles (Admin / Expert / Collaborator) — pick a user and a role from those three.
• Citizen Science members — pick a user who should see this project in the Citizen Science frontend.

For bulk role assignment, use the Set roles for selected users admin action — see Users & roles.

Verify it worked¶

Open the project page in the Citizen Science frontend (or the Expert classify view). You should see the attached collections with counts, AI Classifications populated on resources once the pipeline finishes (watch Flower at http://localhost:5555), and the classification form rendered with your Classificator's fields.

Advanced configuration¶

The admin edit page (/admin/media_classification/classificationproject/<id>/change/) is divided into the following sections.

Basic fields¶

AI Models¶

Four FK dropdowns — each is filtered to show only providers of the matching provider_type:

Prediction Job Configuration¶

This is the main AI tuning section. It renders as a set of expandable accordion panels — one per job type (Detection, Classification, Distance Calibration, Distance Estimation). Each panel is collapsed by default; click the header to expand.

The configuration is stored as a single JSON field (prediction_config) shaped:

{
  "detection": {
    "common": { ... },
    "spec": { ... },
    "model_config_overrides": { ... }
  },
  "classification": { ... },
  "distance_calibration": { ... },
  "distance_estimation": { ... }
}

Only job types you explicitly configure are stored — the rest use worker defaults.

Common fields (all job types)¶

These fields appear in every job type panel under the Common section:

Detection¶

The Detection panel has one additional sub-section: Tracker.

Tracker controls which multi-object tracker is applied to stitch per-frame bounding boxes into continuous object tracks across video frames:

Spec — Settings:

This is the only user-editable DetectionSpec field — the schema's pose_model_id and ship_keypoints fields are driven by the project's pose-model assignment, not by this form.

Model Config Overrides — see Model Config Overrides below.

Classification¶

The Classification panel has one additional sub-section: Majority Voting.

Majority Voting controls how many frames must confirm a detection before the tracker promotes it to a stable classification:

Spec — Settings:

Model Config Overrides — see Model Config Overrides below.

Distance Calibration¶

Calibration fits an affine or piecewise-linear mapping from the depth model's raw output (relative inverse depth) to real-world metres, using reference points you provide on a set of calibration images. See Distance estimation for the full workflow.

Spec — Fit Method:

Spec — Depth Sampling:

Spec — Alignment:

Spec — Marker Processing:

Model Config Overrides — see Model Config Overrides below.

Distance Estimation¶

Estimation applies the fitted calibration model to every resource in the project, producing a per-frame distance series for each tracked object.

Spec — Distance Clipping:

Spec — Depth Sampling:

Spec — SAM Segmentation:

FastSAM optionally runs a segmentation mask inside each bounding box before depth sampling, improving accuracy by excluding background pixels near the object boundary.

Spec — Alignment Stabilisation:

Temporal RANSAC alignment stabilises the depth map across frames to reduce jitter from camera movement between shots.

Spec — Depth Map Smoothing:

Spec — Distance Smoothing (Hampel + EMA):

Post-hoc smoothing applied to the resulting per-frame distance series to remove outliers and smooth rapid jumps.

Spec — Kalman Filter:

Per-object Kalman filter applied to depth percentile values to reduce noise in the raw depth signal before distance conversion.

Model Config Overrides — see Model Config Overrides below.

Model Config Overrides¶

Each job type panel has a Model Config Overrides section at the bottom with two parts:

• Manifest defaults (read-only) — the model's default_config from the AI Manager manifest, shown as a reference. For example, a detection model might show {"image_size": 960, "confidence_threshold": 0.25}, and a classifier might show {"num_classes": 38, "crop_size": 182}. These are the values the worker uses unless you override them below.
• JSON textarea — a free-form dict layered on top of the manifest defaults at inference time. Only keys you add here are overridden; the rest continue to use the manifest values.

Keys are whatever the predictor accepts, for example:

{
  "confidence_threshold": 0.15,
  "image_size": 1280,
  "iou_threshold": 0.45
}

Leave the JSON textarea blank to use the model's own defaults from the manifest unchanged.

Video & Sampling¶

Confidence Thresholds¶

Visual-only flags shown in the classify view to alert annotators — they do not block any workflow or change how data is stored.

Citizen Science¶

Controls how the project and its data appear in the Citizen Science frontend.

Blurring¶

Automatic blurring of detected humans and vehicles, for privacy compliance.

Troubleshooting¶

Next steps¶

• Run & re-run the AI pipeline
• Distance estimation
• Configure trackers