Add user-drawn bounding boxes, annotation review workflow, and image collections

[garland3]

Summary

This issue proposes features that transform VISTA from a read-only ML
results viewer into an interactive annotation and review platform with
full audit trails. A core principle throughout: every action that creates,
modifies, or finalizes data must be logged with who, what, and when.

Feature 1: Bounding Box Class Definitions (Project Level)

Currently, ImageClass supports whole-image classification only. We need
a separate class/label taxonomy specifically for spatial annotations
(bounding boxes, and potentially polygons/points in the future).

Requirements:

• Define bounding box classes at the project level (name, description, color)
• Each class gets a distinct color for rendering overlays
• Classes are reusable across all images in the project
• CRUD API and management UI similar to existing ClassManager

What exists today: ImageClass model and ClassManager.js component
handle whole-image labels. MLAnnotation has an unstructured class_name
string field with no project-level definition.

Feature 2: User-Drawn Bounding Boxes

Today, bounding boxes only come from external ML pipelines via the
MLAnnotation model. Users cannot create, edit, or delete boxes through
the UI.

Requirements:

• Drawing tool in ImageView: click-and-drag to create bounding boxes
• Assign each box to a bounding box class (from Feature 1)
• Store full audit metadata: creator, creation time, last editor, edit time
• Edit existing boxes (resize, move, re-classify, delete)
• Boxes are distinct from ML-generated annotations (separate model/table)
  so the provenance is always clear (human vs. machine)
• All edits (create, modify, delete) are logged as discrete events in an
  audit trail, not just overwritten in place

What exists today: BoundingBoxOverlay.js renders ML boxes as a
read-only overlay. The coordinate system and scaling logic can be reused.

Feature 3: Annotation Review Workflow

There is no review or approval mechanism in VISTA today. Annotations
(from AI or humans) are final once submitted.

Requirements:

• Each annotation (user-drawn or ML-generated) can be reviewed
• Review actions: approve, reject, or flag for revision
• Each review is a recorded event: reviewer, timestamp, action, optional
  comment
• A reviewer must perform an explicit action (click/button) to confirm
  they actually examined the annotation -- no silent auto-approval
• During review, reviewers CAN edit annotations: add, remove, or modify
  whole-image labels, bounding box positions, and bounding box labels.
  Every such edit is logged as part of the review record so there is a
  clear trail of what changed and who changed it during review.
• Review status visible on each annotation in the UI
• Ability to filter/sort annotations by review status
• Track review coverage: how many annotations in a project/collection
  have been reviewed vs. pending

What exists today: Nothing -- ImageComment provides free-text
comments but no structured review workflow.

Feature 4: Image Collections Within Projects

Projects currently contain a flat list of images. There is no way to
organize subsets of images for batch annotation, review, or comparison.

Requirements:

• Create named collections within a project
• Add/remove images to/from collections (an image can belong to multiple
  collections)
• Filter the image gallery by collection
• Track who added each image and when
• Collections serve as work units for annotation and review tasks

What exists today: ImageGallery.js supports search, sort, and
pagination but no sub-grouping. Multi-select exists in the UI but has
no bulk operations.

Feature 5: Collection Locking and Review-Required Status

Collections need lifecycle management to support real workflows: preparing
training data for ML, conducting inspection events, and finalizing results.
Once work is done and reviewed, it must be possible to lock everything down
so the record is authoritative.

Collection Locking

• A collection can be locked, making it read-only
• When locked, the UI clearly indicates the locked state and prevents
  edits (no adding/removing images, no creating/modifying/deleting
  annotations or labels within that collection's scope)
• Locking and unlocking are explicit actions that require authorization
  and are logged (who locked/unlocked, when, and optionally why)
• Unlocking requires explicit approval -- it is not a casual toggle.
  The intent is that a locked collection represents finalized work
  (e.g., a completed inspection, a validated training dataset) and
  reopening it is a deliberate decision with a paper trail

Review-Required Status

• A collection (or individual image within a collection) can be marked
  as review required
• This status is visible in the gallery and collection views so
  reviewers can see what needs their attention
• Progress tracking: how many images/annotations in a review-required
  collection have been reviewed vs. still pending
• When all items in a review-required collection are reviewed, the
  collection can be locked to finalize

Interaction with ML Pipelines and Edits During Review

• When a collection is in an active review state, the API enforces a
  hard block on:
  • Uploading new ML results against images in that collection
  • Modifying or adding whole-image class labels
  • Creating, editing, or deleting bounding boxes (outside of the
    review workflow itself -- reviewers can still make edits as part
    of their review, which are logged accordingly)
• Blocked requests return a clear error message explaining that the
  collection is under review and must be moved out of review status
  before these changes can be made
• The workflow is: exit review state, make the changes, re-enter review.
  Each of these state transitions is logged.
• ML results uploaded before review starts remain visible and
  reviewable. The restriction applies only to new submissions while
  review is active.
• All blocked attempts are logged (who tried what, when, and which
  collection blocked it).

Audit Trail (Cross-Cutting Concern)

Every state change across the system must be logged to maintain a
complete paper trail:

• Annotation created, modified, deleted (with before/after state)
• Review actions (approve, reject, request revision) with reviewer
  and timestamp
• Edits made during review (label changes, box adjustments) attributed
  to the reviewer
• Collection created, images added/removed
• Collection locked/unlocked with reason
• Collection marked as review-required / review completed
• ML upload attempts (successful or blocked) during review periods

The goal is that for any annotation or collection, you can reconstruct
the full history: who created it, who reviewed it, what changed during
review, when it was finalized, and whether it was ever reopened.

Implementation Notes

• Backend follows existing patterns: SQLAlchemy models in core/models.py,
  Pydantic schemas in core/schemas.py, routers in routers/, Alembic
  migrations
• Frontend follows existing component patterns under src/components/
• New database tables will require Alembic migrations
• The drawing tool is the most complex frontend work -- likely needs a
  canvas-based interaction layer on top of ImageDisplay.js
• Review workflow should be generic enough to apply to both user-drawn
  and ML-generated annotations
• The audit log could be a single audit_events table with a polymorphic
  design (entity_type, entity_id, action, actor, timestamp, details JSON)
  or separate per-entity history tables -- TBD during design
• Collection locking enforcement needs to happen at the API level (not
  just the UI) to prevent bypassing via direct API calls

[garland3]

Most of this was implemented in PR #53 (bounding box annotations, collections, review workflow, audit trail). The remaining work -- collection lifecycle phases, human-in-the-loop ML correction, and certification workflow -- is being tracked in Discussion #58 as a broader architectural RFC.

[garland3]

Reopening -- the collections work from the feature branch was never merged to main. PR #53 was an unrelated proxy config fix. Issue #56 is still open work. The broader lifecycle design (phases, certification, ML workflow) is being discussed in Discussion #58.