Skip to content

Conversation

mohamedelabbas1996
Copy link
Contributor

@mohamedelabbas1996 mohamedelabbas1996 commented May 10, 2025

Summary

This PR introduces support for multiple candidate images to represent a taxon, enhancing how taxa are visually represented. It also adds API endpoints to feature and unfeature occurrences.

List of Changes

  • Introduced the ability to feature and unfeature occurrences via API.
  • Featured occurrences are now returned in both the taxon list and taxon detail API responses.
  • Added a new images field to the taxon serializer that returns representative image URLs for each taxon, including:
    • External reference image (cover_image_url)
    • Most recently featured occurrence image
    • Highest determination score occurrence image

Related Issues

Closes #832

Detailed Description

This update allows users and downstream consumers (e.g. UI) to identify and display a representative visual summary of a taxon based on project data. These additions support feature parity for image-based navigation and selection, including:

  • Backend support for toggling an occurrence as featured.
  • Enhanced queryset methods and annotations to retrieve relevant images based on taxon-level context.
  • A unified image format in the response schema to simplify frontend consumption.

How to Test the Changes

  1. Feature or unfeature an occurrence using:
    • POST /api/v2/occurrences/{id}/feature/
    • DELETE /api/v2/occurrences/{id}/feature/
  2. Fetch the taxon list or detail endpoints and verify:
    • The occurrence appears in featured_occurrences if featured.
    • The images field contains valid URLs for:
      • external_reference
      • most_recently_featured
      • highest_determination_score

Screenshots

TBD

Deployment Notes

  • Run migrations

Checklist

  • I have tested these changes appropriately.
  • I have added and/or modified relevant tests.
  • I updated relevant documentation or comments.
  • I have verified that this PR follows the project's coding standards.
  • Any dependent changes have already been merged to main.

Copy link

netlify bot commented May 10, 2025

Deploy Preview for antenna-preview canceled.

Name Link
🔨 Latest commit f93ea6d
🔍 Latest deploy log https://app.netlify.com/projects/antenna-preview/deploys/68279ef4130bac0008e3c817

Copy link

netlify bot commented May 10, 2025

Deploy Preview for antenna-ood canceled.

Name Link
🔨 Latest commit f93ea6d
🔍 Latest deploy log https://app.netlify.com/projects/antenna-ood/deploys/68279ef4f097a600086dfb6e

@mohamedelabbas1996 mohamedelabbas1996 self-assigned this May 10, 2025
@mihow
Copy link
Collaborator

mihow commented May 10, 2025

Thanks for starting this @mohamedelabbas1996. My instinct is saying that we should rename this intermediate model to ProjectTaxon and use it for all metadata about a Taxon even if that species hasn't been observed in the project yet. Then move the tags many2many to ProjectTaxon.

@mohamedelabbas1996
Copy link
Contributor Author

mohamedelabbas1996 commented May 11, 2025

Thanks for starting this @mohamedelabbas1996. My instinct is saying that we should rename this intermediate model to ProjectTaxon and use it for all metadata about a Taxon even if that species hasn't been observed in the project yet. Then move the tags many2many to ProjectTaxon.

@mihow Thanks so much for the suggestion. My concern is around representing taxa that haven't yet been observed in a project. I'm not sure it's even allowed in the Django ORM to have a ManyToManyField where one side (like the project) is null. I believe both foreign keys must be non-null by definition.

@mihow mihow mentioned this pull request May 12, 2025
5 tasks
@mihow
Copy link
Collaborator

mihow commented May 14, 2025

Possible images to represent a Taxon or Cluster

Update Taxon detail & list serializers:

images: {
  external_reference: {title: "External reference image", caption: null, sizes: {"original", url},
  most_recently_featured:  {url, title: "Selected occurrence", caption: null,  sizes: {"original", url},},
  highest_determination_score: {url, title: "Most confident prediction", caption: null,  sizes: {"original", url},},
}

All future image fields:

images: {
  external_reference_image: null, (rename cover_image_url on Taxon model)
  most_recent_featured: null, (manually selected occurrence)
  # most_similar: null, (center of cluster)
  highest_determination_score: null, (comes from `best_detection`)
  # highest_determination_ood_score: null,
  # most_recently_detected: null,
}

Notes about selecting determination score:

occurrence
determination = Cluster (comes from best_prediction())
determination_score (comes from best_prediction(filters=algorithm_type=='classification')
determination_ood_score

@mohamedelabbas1996 mohamedelabbas1996 force-pushed the feat/add-example-occurrences-for-taxa branch from 9e03dc7 to b56277d Compare May 16, 2025 02:19
@annavik
Copy link
Member

annavik commented May 16, 2025

Hey @mohamedelabbas1996, thank you for starting on this! I tested a bit and tried to render this information as well. Some questions:

  • Can we return full URL:s for crops so I don't have to modify URL:s frontend side in order to make rendering work?
  • Can we include the external reference image caption as part of the image object? Currently caption is null, even if copyright info is present in DB.
  • How can I add "featured occurrences"? Do we have endpoints available?
  • Can we sync this branch with deployments/ood.antenna.insectai.org, we are a bit out of date here. Let me know if you need any help with the FE conflicts :)
Screenshot 2025-05-16 at 14 07 01

@annavik
Copy link
Member

annavik commented May 16, 2025

Me and @mohamedelabbas1996 tried to sync this with OOD branch, but there are backend migration problems now. TBC!

@mihow
Copy link
Collaborator

mihow commented May 16, 2025

@mohamedelabbas1996 @annavik I fixed the migration & code conflicts. I left the existing cover_image_url query & API field there for the moment. I think we still want a single alias field that selects from the available images, to use in the list view & search views.

@mihow
Copy link
Collaborator

mihow commented Jun 25, 2025

@mihow consider hiding example occurrences that are not verified or are too low confidence (for cover images)

@mihow mihow force-pushed the deployments/ood.antenna.insectai.org branch from a011a5f to 3528f27 Compare August 21, 2025 02:22
@mihow mihow added this to the Post Panama feature integration milestone Aug 27, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Automatically pick best representative occurrence for Taxon
3 participants