⚡️📈🚚 Update crab measurment logic, incorporate into web ui and database

Author: CexyNature

apps/web/alembic/versions/9a2b7c1d4e6f_add_media_measurement_mode.py

@@ -0,0 +1,36 @@
+"""add media measurement_mode
+
+Revision ID: 9a2b7c1d4e6f
+Revises: f8e9a1b2c3d4
+Create Date: 2026-03-23
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "9a2b7c1d4e6f"
+down_revision: Union[str, None] = "f8e9a1b2c3d4"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("media") as batch:
+        batch.add_column(
+            sa.Column(
+                "measurement_mode",
+                sa.Enum("isotropic", "homography", name="mediameasurementmode", native_enum=False),
+                nullable=False,
+                server_default="homography",
+            )
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("media") as batch:
+        batch.drop_column("measurement_mode")
+

apps/web/alembic/versions/f8e9a1b2c3d4_add_calibration_table.py

@@ -0,0 +1,77 @@
+"""add calibration table; media.active_calibration_id
+
+Revision ID: f8e9a1b2c3d4
+Revises: e2f3a4b5c6d7
+Create Date: 2026-03-23
+
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "f8e9a1b2c3d4"
+down_revision: Union[str, None] = "e2f3a4b5c6d7"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "calibration",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("source_media_id", sa.Uuid(), nullable=False),
+        sa.Column("frame_index", sa.Integer(), nullable=True),
+        sa.Column("time_seconds", sa.Float(), nullable=True),
+        sa.Column("corners_json", sa.Text(), nullable=False),
+        sa.Column("reference_edge_index", sa.Integer(), nullable=False),
+        sa.Column("reference_length_mm", sa.Float(), nullable=False),
+        sa.Column("ref_width_px", sa.Integer(), nullable=True),
+        sa.Column("ref_height_px", sa.Integer(), nullable=True),
+        sa.Column("mm_per_px", sa.Float(), nullable=False),
+        sa.Column("label", sa.String(length=512), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["source_media_id"],
+            ["media.id"],
+            name=op.f("fk_calibration_source_media_id_media"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_calibration")),
+    )
+    op.create_index(op.f("ix_calibration_source_media_id"), "calibration", ["source_media_id"], unique=False)
+
+    # SQLite cannot ALTER TABLE ADD CONSTRAINT; keep column + FK + index in one batch_alter_table.
+    with op.batch_alter_table("media") as batch:
+        batch.add_column(
+            sa.Column(
+                "active_calibration_id",
+                sa.Uuid(),
+                nullable=True,
+            )
+        )
+        batch.create_foreign_key(
+            op.f("fk_media_active_calibration_id_calibration"),
+            "calibration",
+            ["active_calibration_id"],
+            ["id"],
+            ondelete="SET NULL",
+        )
+        batch.create_index(
+            op.f("ix_media_active_calibration_id"),
+            ["active_calibration_id"],
+            unique=False,
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("media") as batch:
+        batch.drop_constraint(op.f("fk_media_active_calibration_id_calibration"), type_="foreignkey")
+        batch.drop_index(op.f("ix_media_active_calibration_id"))
+        batch.drop_column("active_calibration_id")
+
+    op.drop_index(op.f("ix_calibration_source_media_id"), table_name="calibration")
+    op.drop_table("calibration")

apps/web/crabspy_web.egg-info/PKG-INFO

@@ -39,24 +39,21 @@ PYTHONPATH=apps/web uvicorn crabspy_web.app:app --reload --app-dir apps/web
 
 Environment variables (optional):
 
-- `CRABSPY_DATA_DIR` — root for `uploads/`, `db/`, `exports/`, `cache/`, and `config/` (default: `<repo>/data`).
-- `CRABSPY_DATABASE_URL` — SQLAlchemy URL. If unset, the app uses `data/config/database_url` (one line) when present, otherwise SQLite at `CRABSPY_DATA_DIR/db/project.sqlite`. When this env var **is** set, it always wins and the Settings → Database form is read-only.
+- `CRABSPY_DATA_DIR` — root for `uploads/`, `db/`, `exports/`, `cache/` (default: `<repo>/data`).
+- `CRABSPY_DATABASE_URL` — SQLAlchemy URL (default: SQLite under `CRABSPY_DATA_DIR/db/project.sqlite`).
 
-**Project databases (Postgres-ready):** use one SQLite file per study or campaign, e.g. `data/db/coastal_site_2025.sqlite`, with URL `sqlite:////absolute/path/to/data/db/coastal_site_2025.sqlite` (four slashes after `sqlite:` for absolute paths on Unix). Switch in the UI under **Database** (`/settings/database`) or by editing `data/config/database_url`. For PostgreSQL: `postgresql+psycopg://user:pass@host:5432/dbname` after `pip install -e ".[postgres]"`.
+## Phase 3b — annotations and backup
 
-**Web UI:** register draft media and export CSV from [`/media/`](http://127.0.0.1:8000/media/) (see nav). Edit or delete a row via **Edit** on the list. On startup the app applies Alembic migrations to the active database automatically.
+Annotations are stored relationally (`annotation`, `annotation_point`) with normalized coordinates. The web UI supports **points and polylines** on **video** and **image** viewers; `POST /media/{id}/annotations` accepts the same JSON schema.
 
-**Storage paths:** `storage_path` is a string pointing at your files (e.g. on an external SSD or NAS). The app does not copy or move originals; it only records the path. Optional future feature: copy uploads into `data/uploads/` for self-contained projects.
+- **Optional label** — Text field on the view page; stored on the annotation row.
+- **Reference dimensions** — When the browser knows intrinsic size (`videoWidth` / `videoHeight` or image `naturalWidth` / `naturalHeight`), the client sends `ref_width_px` and `ref_height_px` together so exports can compute pixel-space lengths. Omit if metadata is not ready yet.
+- **CSV export** — `GET /media/export_annotations.csv` includes per-vertex rows plus `path_length_norm`, `path_length_px` (when refs are set), and `edge_length_norm` / `edge_length_px` for each segment.
 
-**Viewing in the browser (Phase 3a):** For each media row, **View** opens `/media/<uuid>/view` (image via `<img>`, video via `<video controls>`). The file is served at `/media/<uuid>/file` with a guessed MIME type. Relative paths resolve under `CRABSPY_DATA_DIR` (must stay inside that directory after normalization); absolute paths are read as-is. Starlette’s `FileResponse` supports HTTP range requests for seeking in video.
+**Backup (recommended before migrations or risky edits):**
 
-**Video seek:** On the view page, use **Time** (seconds or `MM:SS` / `HH:MM:SS`) or **Frame** (0-based index; requires **Frame rate** on the media row). Deep links: `?t=12.5` (seconds) or `?f=300` (frame index). If both are present, `f` wins when frame rate is set; otherwise `t` is used.
-
-**Video annotation spike (Phase 3b prep):** On the media **View** page for video-like rows, use **Add annotation points** to overlay clicks on the video (normalized 0–1 coordinates, letterbox-aware). Points are stored in the `video_spike_annotation` table via `POST /media/<uuid>/video-spike` (JSON body: `x_norm`, `y_norm`, `time_seconds`, optional `frame_index`) and `POST /media/<uuid>/video-spike/<point_id>/delete`. This is a thin vertical slice to validate overlay + persistence before the full annotation schema.
-
-**CI:** GitHub Actions runs `pytest tests/web` on push and pull requests (see [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml)).
-
-**Bulk import:** [`/media/import`](http://127.0.0.1:8000/media/import) accepts a UTF-8 CSV (headers in row 1). Required: a path column (`storage_path`, `path`, or `video_path`). Optional: `collected_at` / `date_collected` / `date`, `sample_code`, `site_name`, `location_name`, `notes`, `original_filename`, plus `camera_id`, `deployment_time`, `deployment_type`, `latitude`/`lat`, `longitude`/`lon`/`lng`. Dates accept ISO-8601 or `YYYY-MM-DD` (and a few common formats). Rows with path, date, sample, site, and location name set are stored as `ready_for_processing`; others as `draft`. Optional camera/deployment/geo fields can be empty without blocking readiness. Duplicate `storage_path` values already in the database are skipped.
+1. **Annotations CSV** — Download from the [Media](http://127.0.0.1:8000/media/) page (“Annotations backup”) or open `GET /media/export_annotations.csv` (flattened rows, UTF-8). This is portable and version-control friendly.
+2. **Full database copy** — With the app **stopped** (and no other process holding the file), copy the active SQLite file (default: `CRABSPY_DATA_DIR/db/project.sqlite`, plus `-wal`/`-shm` if present) to a safe location. Restores the whole project, including media rows and uploads paths.
 
 ## Docker
 
@@ -70,20 +67,12 @@ Then open `http://127.0.0.1:8000` and `http://127.0.0.1:8000/api/health`.
 
 ## Alembic
 
-Configuration lives under `apps/web/alembic.ini`. Migrations are in `apps/web/alembic/versions/`.
-
-The running app calls `alembic upgrade head` on startup for the resolved database URL (so a fresh clone usually only needs `pip install` and `uvicorn`). You can still run migrations manually:
+Configuration lives under `apps/web/alembic.ini`. After installing the package:
 
 ```bash
 cd apps/web
-export CRABSPY_DATABASE_URL=sqlite:////absolute/path/to/project.sqlite   # optional override
+alembic revision --autogenerate -m "init"
 alembic upgrade head
 ```
 
-To generate a new revision after changing models:
-
-```bash
-cd apps/web
-alembic revision --autogenerate -m "describe change"
-alembic upgrade head
-```
+(Autogenerate requires SQLAlchemy models to be wired in `alembic/env.py`.)

apps/web/crabspy_web.egg-info/SOURCES.txt

@@ -12,19 +12,25 @@ crabspy_web/db/__init__.py
 crabspy_web/db/migrate.py
 crabspy_web/db/session.py
 crabspy_web/models/__init__.py
+crabspy_web/models/annotation.py
 crabspy_web/models/base.py
+crabspy_web/models/calibration.py
 crabspy_web/models/media.py
-crabspy_web/models/video_spike.py
 crabspy_web/routers/__init__.py
 crabspy_web/routers/health.py
 crabspy_web/routers/media.py
 crabspy_web/routers/pages.py
 crabspy_web/routers/settings.py
-crabspy_web/schemas/video_spike.py
+crabspy_web/schemas/annotation.py
+crabspy_web/schemas/calibration.py
 crabspy_web/services/__init__.py
+crabspy_web/services/annotation.py
+crabspy_web/services/annotation_geometry.py
+crabspy_web/services/calibration_math.py
+crabspy_web/services/calibration_measure.py
+crabspy_web/services/calibration_service.py
 crabspy_web/services/csv_export.py
 crabspy_web/services/media_csv_import.py
 crabspy_web/services/media_files.py
 crabspy_web/services/media_form_utils.py
-crabspy_web/services/media_readiness.py
-crabspy_web/services/video_spike.py
+crabspy_web/services/media_readiness.py

apps/web/crabspy_web/models/__init__.py

@@ -2,14 +2,17 @@
 
 from crabspy_web.models.annotation import Annotation, AnnotationKind, AnnotationPoint
 from crabspy_web.models.base import Base
-from crabspy_web.models.media import Media, MediaKind, MediaProcessingStatus
+from crabspy_web.models.calibration import Calibration
+from crabspy_web.models.media import Media, MediaKind, MediaMeasurementMode, MediaProcessingStatus
 
 __all__ = [
     "Base",
     "Annotation",
     "AnnotationKind",
     "AnnotationPoint",
+    "Calibration",
     "Media",
     "MediaKind",
+    "MediaMeasurementMode",
     "MediaProcessingStatus",
 ]

apps/web/crabspy_web/models/calibration.py

@@ -0,0 +1,67 @@
+"""Scale calibration from a reference rectangle (quadrat) on one video frame or image."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, Float, ForeignKey, Integer, String, Text, Uuid, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from crabspy_web.models.base import Base
+
+
+class Calibration(Base):
+    """Known-length edge of a quadrilateral in the image plane; defines mm per pixel for this project."""
+
+    __tablename__ = "calibration"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4,
+    )
+    # Media on which the quadrat was drawn (frame_index / time apply to this clip).
+    source_media_id: Mapped[uuid.UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("media.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+
+    frame_index: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    time_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+    # JSON array of 4 {"x_norm","y_norm"} in [0,1], clockwise order
+    corners_json: Mapped[str] = mapped_column(Text, nullable=False)
+
+    # Which edge (0–3): edge i connects corner i to corner (i+1)%4 and has length reference_length_mm.
+    reference_edge_index: Mapped[int] = mapped_column(Integer, nullable=False)
+
+    reference_length_mm: Mapped[float] = mapped_column(Float, nullable=False)
+
+    ref_width_px: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    ref_height_px: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # reference_length_mm / edge_length_px on that reference edge (isotropic scale).
+    mm_per_px: Mapped[float] = mapped_column(Float, nullable=False)
+
+    label: Mapped[str | None] = mapped_column(String(512), nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+    source_media: Mapped["Media"] = relationship(
+        "Media",
+        foreign_keys=[source_media_id],
+        back_populates="calibrations_defined",
+    )

apps/web/crabspy_web/models/media.py

@@ -10,13 +10,14 @@
     DateTime,
     Enum,
     Float,
+    ForeignKey,
     Integer,
     String,
     Text,
     Uuid,
     func,
 )
-from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from crabspy_web.models.base import Base
 
@@ -34,6 +35,11 @@ class MediaKind(str, enum.Enum):
     unknown = "unknown"
 
 
+class MediaMeasurementMode(str, enum.Enum):
+    isotropic = "isotropic"
+    homography = "homography"
+
+
 def _enum_values(enum_cls: type[enum.Enum]) -> list[str]:
     return [member.value for member in enum_cls]
 
@@ -60,6 +66,12 @@ class Media(Base):
         nullable=False,
         default=MediaKind.unknown,
     )
+    measurement_mode: Mapped[MediaMeasurementMode] = mapped_column(
+        Enum(MediaMeasurementMode, values_callable=_enum_values, native_enum=False),
+        nullable=False,
+        default=MediaMeasurementMode.homography,
+        server_default=MediaMeasurementMode.homography.value,
+    )
 
     # Study metadata (required before processing when status is ready_for_processing — enforced in services).
     collected_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
@@ -96,3 +108,21 @@ class Media(Base):
         server_default=func.now(),
         onupdate=func.now(),
     )
+
+    # Use this calibration's mm/px when interpreting carapace polylines on this media (may point to any calibration row).
+    active_calibration_id: Mapped[uuid.UUID | None] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("calibration.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+
+    active_calibration: Mapped["Calibration | None"] = relationship(
+        "Calibration",
+        foreign_keys=[active_calibration_id],
+    )
+    calibrations_defined: Mapped[list["Calibration"]] = relationship(
+        "Calibration",
+        foreign_keys="Calibration.source_media_id",
+        back_populates="source_media",
+    )