Create a classification project¶
At a glance
Stand up a Classification Project — the schema, AI provider stack, and human annotators that turn uploaded Resources into approved classifications.
- Time: ~20 minutes
- Who: research project owners/managers setting up annotation workflows
- Prerequisites: AI providers registered (optional, only if you want automatic processing)
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
You'll create or pick: a Research Project, a Collection, a Classificator (the schema of attributes annotators fill in), and the Classification Project itself.
Steps¶
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 is a grouped set of Resources, typically one ingestion session. Resources join a Collection at upload time (via trapper-tools — the on-disk collection directory name becomes the Collection name — or the Citizen Science Upload wizard); there's no admin-UI action to attach already-uploaded Resources to a different Collection after the fact (the Collection.resources field is intentionally excluded from the admin form — exclude = ("resources", ...) in CollectionAdmin). If you need to create an empty Collection ahead of an upload, Storage → Collections → +, set name/owner/status, save — then point your upload at it.
Once the Collection exists, link it to your Research Project from the Research Project's own edit page: scroll to the Research project collections inline table at the bottom, and pick it from the Collection dropdown in a new row.
3. Build a Classificator¶
Media classification → Classificators → + — see Your first research project for the full step-by-step.
Fastest path if you already have an AI provider
Select the provider's row on the Media classification → Ai providers changelist and run the Create Classificator from AI Provider species mapping action — the resulting Classificator has the species list pre-populated.
4. Configure AI Providers (optional)¶
If the project will run automatic detection / species classification:
- Make sure the AI Manager has the model registered — run
sync_models_from_schemason the AI Manager andsync_ai_modelson the Expert (the admin wizard does this on first deploy). - Verify both providers are present and Is active on the Expert admin's Media classification → Ai providers changelist.
- If you want manual edits to
categoriesor thresholds to survive future syncs, untick Keep synced on that provider's edit page.
Full background: Register & sync AI providers.
5. Create the Classification Project¶
Media classification → Classification projects, then the + icon.
| Field | What it does | Recommended value |
|---|---|---|
| Name / Description | Identify the project | — |
| Research project | Parent from step 1 | — |
| Classificator | From step 3 | — |
| Owner | Who administers the project | Typically yourself |
| Object detection AI model | Detection-type provider | e.g. MegaDetector v6 |
| Species AI model | Classification-type provider | e.g. DeepFaune v1.3 |
| Required AI classification | Block annotators until AI has run on a resource | Enable for AI-first workflows |
| Citizen Science status | Not belong / Public project / Private project | Depends on who should see it in the CS frontend |
| Confidence warning thresholds | Visual-only flags, don't change workflow | Project-dependent |
| Blur humans / vehicles | Auto-blur on approved detections | Enable for projects on public sites |
| Exclude human / blank observations | Hide from the Citizen Science classifications queryset | Project-dependent |
| Hide classification attributes for non-animals | Simpler form when observation_type ≠ animal |
Project-dependent |
There's no "Collections" field here either — a Classification Project sees a Collection's resources once you create a separate Classification projects collection row linking the two (Media classification → Classification projects collections → +, pick Project + Collection). That same page's action dropdown also has (Re)build sequences for selected collections, needed before the classify view can step through bursts of resources — see Your first research project, step 7.
Save.
6. Assign annotators¶
On the Classification Project's own edit page, two separate 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 (no separate role here).
For project-wide bulk role assignment instead, 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 port 5555), and the classification form rendered with your Classificator's fields.
Troubleshooting¶
AI Classifications never appear
Check the Object detection / Species AI model fields are set and Is active on both providers, that the Classification projects collection row from step 5 exists and sequences have been built, and the Celery Flower dashboard for stuck/failed jobs.
Annotators see a blank/wrong form
The form is generated from the Classificator's attribute schema — re-check step 3, and that the project's Classificator field actually points at the one you edited (a common mix-up when a project has several similar Classificators).
Field reference¶
For the full set of fields (pipeline behaviour, privacy, video/frame handling, visibility filters) beyond what's covered in step 5 above:
Video & frame handling — video_support_enabled (accept video resources at all). Per-job-type AI Worker parameters (confidence thresholds, frame sampling, etc.) live in prediction_config, a JSON field shaped {job_type: {common: {...}, spec: {...}}} and validated against trapper-schemas — edit it via the Prediction Job Configuration section on the project's edit page, expanding the relevant job type (Detection / Classification / Distance Calibration / Distance Estimation).
target_fps isn't a Classification Project field
A field with this name exists, but on a different model — ProjectHypertablePopulation.target_fps, the frame-rate density used when populating the analytics hypertable (see Frame hypertable export), unrelated to AI inference sampling.
Privacy detail — blur_backup keeps an unblurred copy under protected/storage/.../backup/. blur_humans_and_vehicles_immediately applies blur as soon as the AI pipeline finishes, without waiting for human approval — irreversible unless blur_backup is on.