Initial Commit

.gitattributes

@@ -0,0 +1,3 @@
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.ts filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,7 @@
+api_keys.json
+.admin_key
+__pycache__/
+*.pyc
+*.pyo
+.env
+.venv/

Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.12-slim
+
+# System libraries required by OpenCV and PyTorch
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libglib2.0-0 \
+        libgl1 \
+        libsm6 \
+        libxrender1 \
+        libxext6 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python dependencies before copying the rest of the code
+# so this layer is cached as long as requirements.txt doesn't change.
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code and assets
+COPY . .
+
+# HF Spaces runs containers as uid 1000 (non-root)
+RUN useradd -m -u 1000 appuser \
+    && chown -R appuser /app
+USER appuser
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,66 @@
+---
+title: SW Fish Identifier
+emoji: 🐟
+colorFrom: blue
+colorTo: teal
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# SW Fish Identifier
+
+Upload a photo and SWClassifier will detect every fish in it, segment their outline,
+and identify the species — returning both the common name and scientific name.
+
+## Pipeline
+
+| Step | Model | Notes |
+|---|---|---|
+| Detection | YOLO v8 nano | Bounding boxes |
+| Segmentation | FPN ResNet-18 | Per-fish polygon mask |
+| Classification | BEiT v2 Base + FAISS kNN | 775 species |
+
+## API
+
+The Space exposes a REST API alongside the web UI.
+
+### Identify fish in an image
+
+```
+POST /api/v1/predict
+X-API-Key: <your-key>
+Content-Type: multipart/form-data
+
+file=<image>
+```
+
+**Response**
+
+```json
+{
+  "detections": [
+    {
+      "bbox": { "x1": 120, "y1": 45, "x2": 380, "y2": 290, "confidence": 0.91 },
+      "polygon": [[120, 180], [135, 170], "..."],
+      "predictions": [
+        { "name": "Wahoo", "taxon": "Acanthocybium solandri", "accuracy": 0.87, "species_id": "..." }
+      ]
+    }
+  ],
+  "image_size": { "width": 1280, "height": 720 },
+  "timing": { "detect_ms": 210, "segment_ms": 85, "classify_ms": 430, "total_ms": 730 }
+}
+```
+
+Full interactive docs available at `/docs`.
+
+## Configuration (Space Secrets)
+
+| Secret | Description |
+|---|---|
+| `SW_API_KEYS` | Comma-separated list of valid API keys |
+| `SW_ADMIN_KEY` | Key required to create / revoke API keys via `/api/v1/keys` |
+
+Set these under **Settings → Variables and Secrets** in the Space dashboard.
+If not set, keys are auto-generated at startup (lost on container restart).

app.py

@@ -0,0 +1,413 @@
+"""
+SW Identifier — FastAPI server
+
+Routes
+------
+GET  /                      SPA frontend
+POST /predict               Internal SPA endpoint (no auth)
+POST /api/v1/predict        Public API  (requires X-API-Key header)
+GET  /api/v1/keys           List API keys  (requires X-Admin-Key header)
+POST /api/v1/keys           Create API key (requires X-Admin-Key header)
+DELETE /api/v1/keys/{key}   Revoke API key (requires X-Admin-Key header)
+GET  /docs                  OpenAPI / Swagger UI
+"""
+import csv
+import io
+import json
+import logging
+import os
+import secrets
+import sys
+import time
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from typing import List, Optional
+
+import numpy as np
+from PIL import Image
+from fastapi import APIRouter, Depends, FastAPI, File, HTTPException, Security, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse
+from fastapi.security import APIKeyHeader
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+# ── paths ─────────────────────────────────────────────────────────────────────
+BASE             = os.path.dirname(os.path.abspath(__file__))
+DETECTOR_PATH    = os.path.join(BASE, "detector",             "model.pt")
+SEGMENTATOR_PATH = os.path.join(BASE, "segmentator",          "model.ts")
+CLASSIFIER_CKPT  = os.path.join(BASE, "classification_model", "model.ckpt")
+DATABASE_PATH    = os.path.join(BASE, "classification_model", "database.pt")
+STATIC_DIR       = os.path.join(BASE, "static")
+TAXONS_CSV       = os.path.join(BASE, "taxons.csv")
+KEYS_FILE        = os.path.join(BASE, "api_keys.json")
+
+sys.path.insert(0, BASE)
+
+# ── logging ───────────────────────────────────────────────────────────────────
+logging.basicConfig(level=logging.WARNING)
+log = logging.getLogger("sw.app")
+
+# ── common name lookup ────────────────────────────────────────────────────────
+def _load_common_names(path: str) -> dict:
+    mapping = {}
+    with open(path, newline="", encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            taxon  = row["taxon"].strip()
+            common = row["common_name"].strip()
+            if taxon:
+                mapping[taxon] = common or taxon
+    return mapping
+
+COMMON_NAMES: dict = _load_common_names(TAXONS_CSV)
+
+# ── API key store ─────────────────────────────────────────────────────────────
+def _load_keys() -> list:
+    if os.path.exists(KEYS_FILE):
+        with open(KEYS_FILE, encoding="utf-8") as f:
+            return json.load(f)
+    return []
+
+def _save_keys(keys: list) -> None:
+    with open(KEYS_FILE, "w", encoding="utf-8") as f:
+        json.dump(keys, f, indent=2)
+
+def _valid_key_set() -> set:
+    # Prefer env var (comma-separated) — required for stateless deployments
+    # like HF Spaces where the filesystem is ephemeral.
+    env = os.environ.get("SW_API_KEYS", "").strip()
+    if env:
+        return {k.strip() for k in env.split(",") if k.strip()}
+    return {k["key"] for k in _load_keys()}
+
+def _new_key(name: str) -> dict:
+    return {
+        "key":        "fsh_" + secrets.token_urlsafe(32),
+        "name":       name,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+# Ensure at least one key exists on startup; print it once to console.
+def _bootstrap_keys() -> None:
+    # Skip file-based bootstrap when keys are supplied via env var.
+    if os.environ.get("SW_API_KEYS", "").strip():
+        return
+    keys = _load_keys()
+    if not keys:
+        k = _new_key("default")
+        _save_keys([k])
+        print("\n" + "═" * 60)
+        print("  No API keys found — generated a default key:")
+        print(f"  {k['key']}")
+        print("  Store this somewhere safe; it won't be shown again.")
+        print("═" * 60 + "\n")
+
+# Admin key — set SW_ADMIN_KEY env var, or one is auto-generated once.
+_ADMIN_KEY_FILE = os.path.join(BASE, ".admin_key")
+
+def _get_admin_key() -> str:
+    env = os.environ.get("SW_ADMIN_KEY")
+    if env:
+        return env
+    if os.path.exists(_ADMIN_KEY_FILE):
+        with open(_ADMIN_KEY_FILE) as f:
+            return f.read().strip()
+    key = "fadm_" + secrets.token_urlsafe(32)
+    with open(_ADMIN_KEY_FILE, "w") as f:
+        f.write(key)
+    print("\n" + "═" * 60)
+    print("  Admin key (manage API keys):")
+    print(f"  {key}")
+    print("  Stored in .admin_key  — keep it out of version control.")
+    print("═" * 60 + "\n")
+    return key
+
+ADMIN_KEY: str = ""   # set during lifespan
+
+# ── model globals ─────────────────────────────────────────────────────────────
+detector    = None
+segmentator = None
+classifier  = None
+
+# ── lifespan ──────────────────────────────────────────────────────────────────
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global detector, segmentator, classifier, ADMIN_KEY
+
+    _bootstrap_keys()
+    ADMIN_KEY = _get_admin_key()
+
+    from ultralytics import YOLO
+    log.warning("Loading detector …")
+    detector = YOLO(DETECTOR_PATH)
+
+    log.warning("Loading segmentator …")
+    from segmentator.inference import Inference as Segmentator
+    segmentator = Segmentator(SEGMENTATOR_PATH)
+
+    log.warning("Loading classifier …")
+    from classification_model.inference import EmbeddingClassifier
+    classifier = EmbeddingClassifier({
+        "log_level": "WARNING",
+        "dataset": {"path": DATABASE_PATH},
+        "model": {
+            "checkpoint_path":     CLASSIFIER_CKPT,
+            "backbone_model_name": "beitv2_base_patch16_224.in1k_ft_in22k_in1k",
+            "embedding_dim":       512,
+            "num_classes":         775,
+            "arcface_s":           64.0,
+            "arcface_m":           0.2,
+            "pooling_type":        "attention",
+            "device":              "cpu",
+        },
+        "use_knn":                True,
+        "arcface_min_score":      0.1,
+        "centroid_fallback_score": 0.1,
+        "topk_centroid":          5,
+        "topk_neighbors":         10,
+        "topk_arcface":           5,
+        "centroid_threshold":     0.7,
+        "neighbor_threshold":     0.8,
+        "use_albumentations":     False,
+    })
+
+    log.warning("All models ready.")
+    yield
+    log.warning("Shutting down.")
+
+# ── Pydantic response models ──────────────────────────────────────────────────
+class BoundingBox(BaseModel):
+    x1:         int
+    y1:         int
+    x2:         int
+    y2:         int
+    confidence: float
+
+class Prediction(BaseModel):
+    name:       str           # common name
+    taxon:      str           # scientific name
+    accuracy:   float         # confidence 0–1
+    species_id: str
+
+class Detection(BaseModel):
+    bbox:        BoundingBox
+    polygon:     Optional[List[List[int]]]  # [[x,y], ...] in original image coords
+    predictions: List[Prediction]
+
+class ImageSize(BaseModel):
+    width:  int
+    height: int
+
+class Timing(BaseModel):
+    detect_ms:   int
+    segment_ms:  int
+    classify_ms: int
+    total_ms:    int
+
+class PredictResponse(BaseModel):
+    detections: List[Detection]
+    image_size: ImageSize
+    timing:     Timing
+
+# ── shared pipeline ───────────────────────────────────────────────────────────
+async def _run_pipeline(raw: bytes) -> PredictResponse:
+    try:
+        image_rgb = np.array(Image.open(io.BytesIO(raw)).convert("RGB"))
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Cannot decode image: {exc}")
+
+    h, w = image_rgb.shape[:2]
+    t_start = time.perf_counter()
+
+    # 1. Detection
+    t0 = time.perf_counter()
+    yolo_out = detector.predict(
+        source=image_rgb, imgsz=640, conf=0.25, iou=0.45,
+        device="cpu", verbose=False, save=False,
+    )
+    detect_ms = (time.perf_counter() - t0) * 1000
+    boxes_raw = yolo_out[0].boxes.data.cpu().numpy() if yolo_out else []
+
+    detections: List[Detection] = []
+    seg_ms_total = 0.0
+    cls_ms_total = 0.0
+
+    for box in boxes_raw:
+        x1 = max(0, int(box[0])); y1 = max(0, int(box[1]))
+        x2 = min(w, int(box[2])); y2 = min(h, int(box[3]))
+        confidence = float(box[4])
+        if x2 <= x1 or y2 <= y1:
+            continue
+
+        crop_rgb = image_rgb[y1:y2, x1:x2]
+
+        # 2. Segmentation
+        polygon_coords = None
+        masked_crop    = crop_rgb
+        t0 = time.perf_counter()
+        try:
+            seg_results = segmentator.predict(crop_rgb)
+            if seg_results:
+                poly = seg_results[0]
+                polygon_coords = [[int(px) + x1, int(py) + y1] for px, py in poly.points]
+                masked_crop    = poly.mask_polygon(crop_rgb)
+        except Exception as exc:
+            log.warning("Segmentator error: %s", exc)
+        seg_ms_total += (time.perf_counter() - t0) * 1000
+
+        # 3. Classification
+        pred_list: List[Prediction] = []
+        t0 = time.perf_counter()
+        try:
+            preds = classifier(masked_crop)
+            for p in (preds or [])[:3]:
+                pred_list.append(Prediction(
+                    name       = COMMON_NAMES.get(p.name, p.name),
+                    taxon      = p.name,
+                    accuracy   = round(float(p.accuracy), 4),
+                    species_id = str(p.species_id),
+                ))
+        except Exception as exc:
+            log.warning("Classifier error: %s", exc)
+        cls_ms_total += (time.perf_counter() - t0) * 1000
+
+        detections.append(Detection(
+            bbox        = BoundingBox(x1=x1, y1=y1, x2=x2, y2=y2,
+                                      confidence=round(confidence, 3)),
+            polygon     = polygon_coords,
+            predictions = pred_list,
+        ))
+
+    total_ms = (time.perf_counter() - t_start) * 1000
+    return PredictResponse(
+        detections = detections,
+        image_size = ImageSize(width=w, height=h),
+        timing     = Timing(
+            detect_ms   = round(detect_ms),
+            segment_ms  = round(seg_ms_total),
+            classify_ms = round(cls_ms_total),
+            total_ms    = round(total_ms),
+        ),
+    )
+
+# ── auth dependencies ─────────────────────────────────────────────────────────
+_api_key_header   = APIKeyHeader(name="X-API-Key",   auto_error=True)
+_admin_key_header = APIKeyHeader(name="X-Admin-Key", auto_error=True)
+
+def _require_api_key(key: str = Security(_api_key_header)):
+    if key not in _valid_key_set():
+        raise HTTPException(status_code=401, detail="Invalid or missing API key.")
+    return key
+
+def _require_admin_key(key: str = Security(_admin_key_header)):
+    if key != ADMIN_KEY:
+        raise HTTPException(status_code=401, detail="Invalid admin key.")
+    return key
+
+# ── app & middleware ──────────────────────────────────────────────────────────
+app = FastAPI(
+    title       = "SW Identifier API",
+    description = "Fish detection, segmentation, and species classification.",
+    version     = "1.0.0",
+    lifespan    = lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins     = ["*"],
+    allow_methods     = ["GET", "POST", "DELETE"],
+    allow_headers     = ["*"],
+)
+
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+# ── SPA routes ────────────────────────────────────────────────────────────────
+@app.get("/", response_class=HTMLResponse, include_in_schema=False)
+async def root():
+    with open(os.path.join(STATIC_DIR, "index.html"), encoding="utf-8") as fh:
+        return fh.read()
+
+@app.post("/predict", include_in_schema=False)
+async def predict_spa(file: UploadFile = File(...)):
+    """Internal endpoint used by the SPA — no auth required."""
+    if not file.content_type.startswith("image/"):
+        raise HTTPException(status_code=400, detail="Upload must be an image file.")
+    return await _run_pipeline(await file.read())
+
+# ── public API v1 ─────────────────────────────────────────────────────────────
+api = APIRouter(prefix="/api/v1", tags=["SW Identifier API"])
+
+@api.post(
+    "/predict",
+    response_model = PredictResponse,
+    summary        = "Identify fish in an image",
+    description    = (
+        "Upload an image. Returns every detected fish with its bounding box, "
+        "segmentation polygon, and ranked species predictions.\n\n"
+        "Requires an `X-API-Key` header."
+    ),
+)
+async def predict_api(
+    file: UploadFile = File(..., description="Image file (JPEG, PNG, WEBP, …)"),
+    _key: str        = Depends(_require_api_key),
+):
+    if not file.content_type.startswith("image/"):
+        raise HTTPException(status_code=400, detail="Upload must be an image file.")
+    return await _run_pipeline(await file.read())
+
+
+# ── key management ────────────────────────────────────────────────────────────
+class KeyRecord(BaseModel):
+    key:        str
+    name:       str
+    created_at: str
+
+class CreateKeyRequest(BaseModel):
+    name: str = "unnamed"
+
+@api.get(
+    "/keys",
+    response_model = List[KeyRecord],
+    summary        = "List API keys",
+    description    = "Requires `X-Admin-Key` header.",
+)
+async def list_keys(_admin: str = Depends(_require_admin_key)):
+    return _load_keys()
+
+@api.post(
+    "/keys",
+    response_model = KeyRecord,
+    status_code    = 201,
+    summary        = "Create a new API key",
+    description    = "Requires `X-Admin-Key` header.",
+)
+async def create_key(
+    body:   CreateKeyRequest  = CreateKeyRequest(),
+    _admin: str               = Depends(_require_admin_key),
+):
+    keys = _load_keys()
+    k = _new_key(body.name)
+    keys.append(k)
+    _save_keys(keys)
+    return k
+
+@api.delete(
+    "/keys/{key}",
+    status_code = 204,
+    summary     = "Revoke an API key",
+    description = "Requires `X-Admin-Key` header.",
+)
+async def revoke_key(key: str, _admin: str = Depends(_require_admin_key)):
+    keys = _load_keys()
+    remaining = [k for k in keys if k["key"] != key]
+    if len(remaining) == len(keys):
+        raise HTTPException(status_code=404, detail="Key not found.")
+    _save_keys(remaining)
+
+app.include_router(api)
+
+# ── entry point ───────────────────────────────────────────────────────────────
+if __name__ == "__main__":
+    import uvicorn
+    port = int(os.environ.get("PORT", 7860))
+    uvicorn.run("app:app", host="0.0.0.0", port=port, reload=False)

classification_model/__MACOSX/._database.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:06af3c007f4209f0aaf82b962a2f10ed05f4b91d38839358ebf4dcf7d92adaf8
+size 212

classification_model/__MACOSX/._model.ckpt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:06af3c007f4209f0aaf82b962a2f10ed05f4b91d38839358ebf4dcf7d92adaf8
+size 212

classification_model/database.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e027ddba847b91c2ecfba617c604722b3a0fbd19d064e7fd09448d4e228082c0
+size 143400638

classification_model/inference.py

@@ -0,0 +1,2029 @@
+# -*- coding: utf-8 -*-
+"""
+Standalone Interpreter for Lightning-trained Fish Classification Models.
+
+This module provides a self-contained classifier for loading and using models
+trained with lightning_train.py. All necessary classes are included in this file
+to enable standalone deployment without additional module dependencies.
+
+Features:
+- Load PyTorch Lightning checkpoints
+- Support for both ViT and CNN backbones
+- Multiple pooling strategies (Attention, GeM, Hybrid)
+- FAISS-based nearest neighbor search (can be disabled)
+- Centroid-based class filtering
+- Automatic input size detection
+- Robust error handling and validation
+- Configurable kNN classifier (enable/disable)
+
+Usage:
+    config = {
+        'log_level': 'INFO',
+        'dataset': {'path': 'path/to/embeddings.pt'},
+        'model': {
+            'checkpoint_path': 'path/to/model.ckpt',
+            'backbone_model_name': 'maxvit_base_tf_224',
+            'embedding_dim': 512,
+            'num_classes': 639,
+            'arcface_s': 64.0,
+            'arcface_m': 0.2,
+            'pooling_type': 'attention',
+            'input_size': 224,  # Optional, auto-detected if not provided
+            'device': 'cuda'
+        },
+        # Optional inference parameters
+        'use_knn': True,  # Enable/disable kNN classifier (default: True)
+        'use_albumentations': False,  # Use albumentations transforms (default: False, uses torchvision)
+        'arcface_min_score': 0.1,
+        'centroid_fallback_score': 0.1,
+        'topk_centroid': 5,
+        'topk_neighbors': 10,
+        'topk_arcface': 5,
+        'centroid_threshold': 0.7,
+        'neighbor_threshold': 0.8
+    }
+    
+    # Initialize classifier
+    classifier = EmbeddingClassifier(config)
+    
+    # Optional: warmup for stable performance
+    classifier.warmup(num_iterations=5)
+    
+    # Single image inference
+    results = classifier(image_array)  # np.ndarray [H, W, 3]
+    
+    # Batch inference
+    results = classifier([img1, img2, img3])  # List[np.ndarray]
+    
+    # Get model information
+    info = classifier.get_model_info()
+    
+    # Context manager usage (recommended)
+    with EmbeddingClassifier(config) as classifier:
+        results = classifier(image_array)
+    # Auto cleanup on exit
+
+Security Warning:
+    This module uses torch.load() which relies on pickle and can execute arbitrary code.
+    Only load checkpoints from trusted sources. The module attempts to use weights_only=True
+    first for safety, but falls back to weights_only=False if needed. Always verify checksums
+    and only load files from trusted sources in production environments.
+
+Performance Notes:
+    - Memory usage scales with number of classes and database size
+    - Expected inference time: ~10-50ms per image (depending on backbone and device)
+    - FAISS indices are pre-built for faster search but require memory
+    - Large batches are automatically split into chunks (MAX_BATCH_SIZE) to prevent OOM errors
+    - For optimal performance, keep batch sizes <= 32 images
+"""
+
+import logging
+import time
+import math
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Tuple, Union, Optional, Literal
+
+import faiss
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from PIL import Image
+from scipy.stats import entropy
+from sklearn.metrics import pairwise_distances
+from torchvision import transforms
+import timm
+from timm.models.vision_transformer import VisionTransformer
+
+# Optional: Albumentations support (install with: pip install albumentations)
+try:
+    import albumentations as A
+    from albumentations.pytorch import ToTensorV2
+    ALBUMENTATIONS_AVAILABLE = True
+except ImportError:
+    ALBUMENTATIONS_AVAILABLE = False
+    A = None
+    ToTensorV2 = None
+
+
+# Constants
+SUPPORTED_VIT_BACKBONES = ['vit', 'beit', 'deit', 'maxvit', 'maxxvit', 'eva', 'dino', 'swin']
+DEFAULT_IMAGE_SIZE = 224
+GEM_POOLING_DEFAULT_P = 3.0
+ATTENTION_HIDDEN_DIVISOR = 4
+ATTENTION_HIDDEN_MIN = 128
+NUMERICAL_EPSILON = 1e-6
+WEIGHT_NORMALIZATION_EPSILON = 1e-10
+MAX_BATCH_SIZE = 32  # Maximum batch size to prevent OOM
+DEFAULT_WARMUP_ITERATIONS = 5
+DEFAULT_ARCFACE_MIN_SCORE = 0.1
+DEFAULT_CENTROID_FALLBACK_SCORE = 0.1
+DEFAULT_TOPK_CENTROID = 5
+DEFAULT_TOPK_NEIGHBORS = 10
+DEFAULT_TOPK_ARCFACE = 5
+DEFAULT_CENTROID_THRESHOLD = 0.7
+DEFAULT_NEIGHBOR_THRESHOLD = 0.8
+DEFAULT_USE_KNN = True
+DEFAULT_RERANK_MODE = 'hybrid'  # 'hybrid', 'weighted_fusion', or 'rrf'
+DEFAULT_ARCFACE_WEIGHT = 0.6  # Weight for ArcFace in weighted fusion
+DEFAULT_KNN_WEIGHT = 0.4  # Weight for kNN in weighted fusion
+DEFAULT_RRF_K = 60  # Constant for Reciprocal Rank Fusion
+DEFAULT_USE_ALBUMENTATIONS = False  # Use albumentations for transforms (if available)
+
+
+# Setup Logger
+logger = logging.getLogger("EmbeddingClassifier")
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(
+        "[%(asctime)s] [%(levelname)s] - %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+
+@dataclass
+class PredictionResult:
+    """Result of a single prediction."""
+    name: str
+    species_id: int
+    distance: float
+    accuracy: float  # Average similarity score (kept for backward compatibility)
+    image_id: Optional[str]
+    annotation_id: Optional[str]
+    drawn_fish_id: Optional[str]
+    
+    @property
+    def average_similarity(self) -> float:
+        """Alias for accuracy field (which is actually average similarity)."""
+        return self.accuracy
+
+
+# =============================================================================
+# Pooling Layers
+# =============================================================================
+
+class GeMPooling(nn.Module):
+    """
+    Generalized Mean Pooling (GeM).
+    
+    Popular in image retrieval tasks. Provides a learnable pooling between
+    average pooling (p=1) and max pooling (p→∞).
+    
+    Reference: "Fine-tuning CNN Image Retrieval with No Human Annotation" (Radenović et al.)
+    """
+    def __init__(self, p: float = GEM_POOLING_DEFAULT_P, eps: float = NUMERICAL_EPSILON, learnable: bool = True):
+        super().__init__()
+        if learnable:
+            self.p = nn.Parameter(torch.ones(1) * p)
+        else:
+            self.register_buffer('p', torch.ones(1) * p)
+        self.eps = eps
+        self.learnable = learnable
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Args:
+            x: Feature map [B, C, H, W]
+        Returns:
+            Pooled features [B, C]
+        """
+        # Clamp both min and max for numerical stability
+        x_clamped = x.clamp(min=self.eps, max=1e4)
+        return F.adaptive_avg_pool2d(
+            x_clamped.pow(self.p),
+            1
+        ).pow(1.0 / self.p.clamp(min=1e-2)).squeeze(-1).squeeze(-1)
+    
+    def __repr__(self):
+        return f"GeMPooling(p={self.p.item():.2f}, learnable={self.learnable})"
+
+
+class ViTAttentionPooling(nn.Module):
+    """
+    Attention Pooling for Vision Transformer output of shape [B, N, D].
+    Computes a weighted sum of patch embeddings based on learned attention.
+    """
+    def __init__(self, in_features: int, hidden_features: Optional[int] = None):
+        super().__init__()
+        if hidden_features is None:
+            hidden_features = max(in_features // ATTENTION_HIDDEN_DIVISOR, ATTENTION_HIDDEN_MIN)
+
+        self.attention_net = nn.Sequential(
+            nn.Linear(in_features, hidden_features),
+            nn.Tanh(),
+            nn.Linear(hidden_features, 1)
+        )
+
+    def forward(
+        self, 
+        x: torch.Tensor, 
+        object_mask: Optional[torch.Tensor] = None, 
+        return_attention_map: bool = False
+    ) -> Tuple[torch.Tensor, Optional[torch.Tensor]]:
+        """
+        Args:
+            x: ViT output [B, N, D]
+            object_mask: Not used for ViT, kept for interface compatibility
+            return_attention_map: Whether to return attention weights
+        
+        Returns:
+            pooled: Pooled features [B, D]
+            weights: Optional attention weights [B, N, 1]
+        """
+        attention_scores = self.attention_net(x)  # [B, N, 1]
+        weights = F.softmax(attention_scores, dim=1)  # [B, N, 1]
+        pooled = (x * weights).sum(dim=1)  # [B, D]
+
+        if return_attention_map:
+            return pooled, weights
+        return pooled, None
+
+        
+class AttentionPooling(nn.Module):
+    """
+    Attention-based pooling for CNN feature maps.
+    Weighs spatial features based on learned attention, optionally focusing
+    on regions within a provided object mask.
+    """
+    def __init__(self, in_channels: int, hidden_channels: Optional[int] = None):
+        super().__init__()
+        if hidden_channels is None:
+            hidden_channels = max(in_channels // ATTENTION_HIDDEN_DIVISOR, 32)
+
+        self.attention_conv = nn.Sequential(
+            nn.Conv2d(in_channels, hidden_channels, kernel_size=1, bias=False),
+            nn.ReLU(inplace=True),
+            nn.Conv2d(hidden_channels, 1, kernel_size=1, bias=False)
+        )
+
+    def forward(
+        self, 
+        x: torch.Tensor, 
+        object_mask: Optional[torch.Tensor] = None, 
+        return_attention_map: bool = False
+    ) -> Tuple[torch.Tensor, Optional[torch.Tensor]]:
+        """
+        Args:
+            x: Feature map [B, C, H, W]
+            object_mask: Optional binary mask [B, 1, H', W'] or [B, H', W']
+            return_attention_map: Whether to return attention weights
+        
+        Returns:
+            pooled: Pooled features [B, C]
+            weights: Optional attention map [B, 1, H, W]
+        """
+        x_for_attn = x
+
+        if object_mask is not None:
+            B, _, H_feat, W_feat = x.shape
+            object_mask_for_x = object_mask.float().to(x.device)
+            if object_mask_for_x.ndim == 3:
+                object_mask_for_x = object_mask_for_x.unsqueeze(1)
+
+            if object_mask_for_x.shape[2] != H_feat or object_mask_for_x.shape[3] != W_feat:
+                object_mask_for_x_resized = F.interpolate(
+                    object_mask_for_x, size=(H_feat, W_feat), mode='nearest'
+                )
+            else:
+                object_mask_for_x_resized = object_mask_for_x
+
+            x_for_attn = x * object_mask_for_x_resized
+
+        attention_scores = self.attention_conv(x_for_attn)
+        weights = torch.sigmoid(attention_scores)
+
+        final_weights_for_pooling = weights
+        if object_mask is not None:
+            B_w, _, H_attn, W_attn = weights.shape
+            object_mask_for_weights = object_mask.float().to(weights.device)
+            if object_mask_for_weights.ndim == 3:
+                object_mask_for_weights = object_mask_for_weights.unsqueeze(1)
+            mask_downsampled_for_weights = F.interpolate(
+                object_mask_for_weights, size=(H_attn, W_attn), mode='nearest'
+            )
+            final_weights_for_pooling = weights * mask_downsampled_for_weights
+
+        weighted_features = x * final_weights_for_pooling
+        sum_weighted_features = weighted_features.sum(dim=(2, 3))
+        sum_weights = final_weights_for_pooling.sum(dim=(2, 3)).clamp(min=NUMERICAL_EPSILON)
+        pooled = sum_weighted_features / sum_weights
+
+        if return_attention_map:
+            return pooled, final_weights_for_pooling
+        return pooled, None
+
+
+class HybridPooling(nn.Module):
+    """
+    Hybrid pooling combining GeM and Attention pooling.
+    Concatenates GeM-pooled features with attention-pooled features.
+    """
+    def __init__(
+        self,
+        in_channels: int,
+        gem_p: float = GEM_POOLING_DEFAULT_P,
+        attention_hidden: Optional[int] = None,
+        output_mode: Literal['concat', 'add'] = 'concat',
+    ):
+        super().__init__()
+        self.gem = GeMPooling(p=gem_p, learnable=True)
+        self.attention = AttentionPooling(in_channels, attention_hidden)
+        self.output_mode = output_mode
+        
+        if output_mode == 'add':
+            # Learnable weights for combining
+            self.gem_weight = nn.Parameter(torch.tensor(0.5))
+            self.attn_weight = nn.Parameter(torch.tensor(0.5))
+
+    def forward(
+        self, 
+        x: torch.Tensor, 
+        object_mask: Optional[torch.Tensor] = None,
+        return_attention_map: bool = False
+    ) -> Tuple[torch.Tensor, Optional[torch.Tensor]]:
+        gem_out = self.gem(x)
+        attn_out, attn_map = self.attention(x, object_mask, return_attention_map=True)
+        
+        if self.output_mode == 'concat':
+            pooled = torch.cat([gem_out, attn_out], dim=1)
+        else:
+            w_gem = torch.sigmoid(self.gem_weight)
+            w_attn = torch.sigmoid(self.attn_weight)
+            pooled = w_gem * gem_out + w_attn * attn_out
+        
+        if return_attention_map:
+            return pooled, attn_map
+        return pooled, None
+    
+    @property
+    def output_features(self) -> int:
+        """Returns output feature dimension multiplier."""
+        return 2 if self.output_mode == 'concat' else 1
+
+
+# =============================================================================
+# ArcFace Head
+# =============================================================================
+
+class ArcFaceHead(nn.Module):
+    """
+    ArcFace loss head for metric learning.
+    Implements the additive angular margin penalty.
+    
+    Reference: "ArcFace: Additive Angular Margin Loss for Deep Face Recognition"
+    """
+    def __init__(
+        self, 
+        embedding_dim: int, 
+        num_classes: int, 
+        s: float = 32.0, 
+        m: float = 0.10
+    ):
+        super().__init__()
+        self.embedding_dim = embedding_dim
+        self.num_classes = num_classes
+        self.s = s
+        self.m = m
+
+        self.weight = nn.Parameter(torch.FloatTensor(num_classes, embedding_dim))
+        nn.init.xavier_uniform_(self.weight)
+
+        # Buffers for constants
+        self.register_buffer('cos_m', torch.tensor(math.cos(m)))
+        self.register_buffer('sin_m', torch.tensor(math.sin(m)))
+        self.register_buffer('th', torch.tensor(math.cos(math.pi - m)))
+        self.register_buffer('mm', torch.tensor(math.sin(math.pi - m) * m))
+        self.register_buffer('eps', torch.tensor(NUMERICAL_EPSILON))
+
+    def set_margin(self, new_m: float):
+        """Dynamically update the margin 'm' and its related constants."""
+        self.m = new_m
+        self.cos_m.data = torch.tensor(math.cos(new_m), device=self.cos_m.device)
+        self.sin_m.data = torch.tensor(math.sin(new_m), device=self.sin_m.device)
+        self.th.data = torch.tensor(math.cos(math.pi - new_m), device=self.th.device)
+        self.mm.data = torch.tensor(math.sin(math.pi - new_m) * new_m, device=self.mm.device)
+
+    def forward(
+        self, 
+        normalized_emb: torch.Tensor, 
+        labels: Optional[torch.Tensor] = None
+    ) -> torch.Tensor:
+        """
+        Args:
+            normalized_emb: L2-normalized embeddings [B, D]
+            labels: Optional class labels [B] (required during training)
+        
+        Returns:
+            Scaled logits [B, num_classes]
+        """
+        normalized_w = F.normalize(self.weight, dim=1)
+        cosine = F.linear(normalized_emb, normalized_w)
+
+        if labels is not None:
+            cosine_sq = cosine ** 2
+            sine = torch.sqrt((1.0 - cosine_sq).clamp(min=self.eps.item()))
+            phi = cosine * self.cos_m - sine * self.sin_m
+            phi = torch.where(cosine > self.th, phi, cosine - self.mm)
+
+            output = cosine.clone()
+            idx = labels.to(dtype=torch.long, device=cosine.device).view(-1, 1)
+            src = phi.gather(1, idx).to(dtype=output.dtype)
+            output.scatter_(1, idx, src)
+            output *= self.s
+        else:
+            output = cosine * self.s
+
+        return output
+
+
+# =============================================================================
+# Model Classes
+# =============================================================================
+
+class StableEmbeddingModelViT(nn.Module):
+    """
+    Embedding model for Vision Transformer backbones.
+    
+    Supports various ViT architectures from timm including:
+    - BEiT v2, DeiT, ViT
+    - MaxViT, MaxxViT
+    - EVA, DINOv2
+    - Swin Transformer
+    """
+    def __init__(
+        self,
+        embedding_dim: int = 128,
+        num_classes: int = 1000,
+        pretrained_backbone: bool = True,
+        freeze_backbone_initially: bool = False,
+        backbone_model_name: str = 'beitv2_base_patch16_224.in1k_ft_in22k_in1k',
+        custom_backbone: Optional[VisionTransformer] = None,
+        attention_hidden_channels: Optional[int] = None,
+        arcface_s: float = 64.0,
+        arcface_m: float = 0.5,
+        add_bn_to_embedding: bool = False,
+        embedding_dropout_rate: float = 0.11,
+        pooling_type: str = 'attention',
+    ):
+        super().__init__()
+        self.embedding_dim = embedding_dim
+        self.num_classes = num_classes
+        self.pooling_type = pooling_type
+
+        if custom_backbone:
+            self.backbone = custom_backbone
+            logger.info("Using custom ViT backbone.")
+        else:
+            logger.info(f"Loading ViT backbone: {backbone_model_name}")
+            self.backbone: VisionTransformer = timm.create_model(
+                backbone_model_name,
+                pretrained=pretrained_backbone,
+                num_classes=0
+            )
+
+        self.backbone_out_features = self._infer_backbone_embedding_dim()
+        self.backbone_feature_extractor = self.backbone.forward_features
+        
+        if freeze_backbone_initially:
+            self.freeze_backbone()
+        
+        # Pooling layer
+        if pooling_type == 'attention':
+            self.pooling = ViTAttentionPooling(
+                in_features=self.backbone_out_features,
+                hidden_features=attention_hidden_channels
+            )
+        else:
+            # For ViT, we'll use global average pooling
+            self.pooling = None
+        
+        # Embedding layers
+        embedding_layers = [nn.Linear(self.backbone_out_features, embedding_dim)]
+        if add_bn_to_embedding:
+            embedding_layers.append(nn.BatchNorm1d(embedding_dim))
+        if embedding_dropout_rate > 0.0:
+            embedding_layers.append(nn.Dropout(embedding_dropout_rate))
+            
+        self.embedding_fc = nn.Sequential(*embedding_layers)
+        self.arcface_head = ArcFaceHead(embedding_dim, num_classes, s=arcface_s, m=arcface_m)
+        
+        logger.info(f"StableEmbeddingModelViT initialized")
+        logger.info(f"  Embedding Dim: {embedding_dim}, Num Classes: {num_classes}")
+        logger.info(f"  ArcFace s: {arcface_s}, m: {arcface_m}")
+        logger.info(f"  Backbone out features: {self.backbone_out_features}")
+        logger.info(f"  Pooling type: {pooling_type}")
+
+    def _tokens_and_grid_from_features(self, features: torch.Tensor):
+        """Normalize backbone features into token tensor [B, N, D] + optional grid."""
+        if features.ndim == 4:
+            B, C, H, W = features.shape
+            tokens = features.flatten(2).transpose(1, 2).contiguous()
+            return tokens, (H, W)
+
+        if features.ndim == 3:
+            tokens = features
+            if hasattr(self.backbone, "cls_token") and tokens.shape[1] > 1:
+                tokens = tokens[:, 1:, :]
+
+            if hasattr(self.backbone, "patch_embed") and hasattr(self.backbone.patch_embed, "grid_size"):
+                gs = self.backbone.patch_embed.grid_size
+                if isinstance(gs, (tuple, list)) and len(gs) == 2 and int(gs[0]) * int(gs[1]) == tokens.shape[1]:
+                    return tokens, (int(gs[0]), int(gs[1]))
+
+            N = tokens.shape[1]
+            s = int(round(math.sqrt(N)))
+            if s * s == N:
+                return tokens, (s, s)
+
+            return tokens, None
+
+        raise ValueError(f"Unsupported backbone output shape: {tuple(features.shape)}")
+
+    def freeze_backbone(self):
+        """Freeze all backbone parameters."""
+        logger.info("Freezing backbone parameters.")
+        for param in self.backbone.parameters():
+            param.requires_grad = False
+
+    def unfreeze_backbone(self, specific_layer_keywords=None, verbose=False):
+        """Unfreeze backbone parameters, optionally filtering by keywords."""
+        logger.info(f"Unfreezing backbone parameters... (Keywords: {specific_layer_keywords})")
+        unfrozen_count = 0
+        for name, param in self.backbone.named_parameters():
+            if specific_layer_keywords is None or any(kw in name for kw in specific_layer_keywords):
+                param.requires_grad = True
+                unfrozen_count += 1
+                if verbose:
+                    logger.info(f"  Unfroze: {name}")
+        logger.info(f"Total parameters unfrozen: {unfrozen_count}")
+
+    def _infer_backbone_embedding_dim(self) -> int:
+        """Infer backbone output dimension."""
+        for attr in ("num_features", "embed_dim"):
+            v = getattr(self.backbone, attr, None)
+            if isinstance(v, int) and v > 0:
+                return int(v)
+
+        def _infer_input_hw() -> int:
+            cfg = getattr(self.backbone, "default_cfg", None) or {}
+            inp = cfg.get("input_size", None)
+            if isinstance(inp, (tuple, list)) and len(inp) == 3:
+                return int(inp[1])
+            name = str(getattr(self.backbone, "name", "") or "")
+            for s in (512, 384, 256, 224):
+                if name.endswith(f"_{s}"):
+                    return s
+            return 224
+
+        self.backbone.eval()
+        orig_device = next(self.backbone.parameters()).device
+        self.backbone.to("cpu")
+        with torch.no_grad():
+            hw = _infer_input_hw()
+            dummy = torch.randn(1, 3, hw, hw)
+            features = self.backbone.forward_features(dummy)
+        self.backbone.to(orig_device)
+
+        if features.ndim == 4:
+            return int(features.shape[1])
+        if features.ndim == 3:
+            return int(features.shape[-1])
+        raise ValueError(f"Unsupported output shape: {tuple(features.shape)}")
+
+    def forward(
+        self, 
+        x: torch.Tensor, 
+        labels: Optional[torch.Tensor] = None, 
+        object_mask: Optional[torch.Tensor] = None, 
+        return_softmax: bool = False, 
+        return_attention_map: bool = True
+    ):
+        """
+        Forward pass.
+        
+        Args:
+            x: Input images [B, 3, H, W]
+            labels: Optional class labels [B]
+            object_mask: Optional object mask (ignored for ViT)
+            return_softmax: Return softmax probabilities instead of logits
+            return_attention_map: Return attention visualization map
+        
+        Returns:
+            emb_norm: L2-normalized embeddings [B, D]
+            logits/probs: Class logits or probabilities [B, num_classes]
+            attn_map: Optional attention map for visualization
+        """
+        features = self.backbone_feature_extractor(x)
+        tokens, grid = self._tokens_and_grid_from_features(features)
+        
+        if self.pooling is not None:
+            pooled, attn_weights = self.pooling(tokens, object_mask=object_mask, return_attention_map=True)
+        else:
+            # Global average pooling
+            pooled = tokens.mean(dim=1)
+            attn_weights = None
+
+        emb_raw = self.embedding_fc(pooled)
+        emb_norm = F.normalize(emb_raw, p=2, dim=1)
+        logits = self.arcface_head(emb_norm, labels)
+
+        vis_attn_map = None
+        if return_attention_map and attn_weights is not None and grid is not None:
+            try:
+                B, N, _ = attn_weights.shape
+                H, W = grid
+                if H * W == N:
+                    vis_attn_map = attn_weights.permute(0, 2, 1).reshape(B, 1, H, W)
+            except Exception:
+                vis_attn_map = None
+
+        output_attn = vis_attn_map if return_attention_map else None
+        
+        if return_softmax:
+            probabilities = F.softmax(logits, dim=1)
+            return emb_norm, probabilities, output_attn
+        return emb_norm, logits, output_attn
+
+        
+class StableEmbeddingModel(nn.Module):
+    """
+    Embedding model for CNN backbones (ConvNeXt, EfficientNet, ResNet, etc.).
+    """
+    def __init__(
+        self,
+        embedding_dim: int = 256,
+        num_classes: int = 1000,
+        pretrained_backbone: bool = True,
+        freeze_backbone_initially: bool = False,
+        backbone_model_name: str = 'convnext_tiny',
+        custom_backbone=None,
+        backbone_out_features: int = 768,
+        attention_hidden_channels: Optional[int] = None,
+        arcface_s: float = 32.0,
+        arcface_m: float = 0.11,
+        add_bn_to_embedding: bool = True,
+        embedding_dropout_rate: float = 0.0,
+        pooling_type: str = 'attention',
+    ):
+        super().__init__()
+        self.embedding_dim = embedding_dim
+        self.num_classes = num_classes
+        self.backbone_out_features = backbone_out_features
+        self.pooling_type = pooling_type
+
+        if custom_backbone:
+            self.backbone = custom_backbone
+            self.backbone_feature_extractor = self.backbone
+            logger.info("Using custom backbone.")
+        elif 'convnext' in backbone_model_name:
+            logger.info(f"Loading backbone from timm: {backbone_model_name}")
+            self.backbone = timm.create_model(
+                backbone_model_name,
+                pretrained=pretrained_backbone,
+                features_only=True,
+                out_indices=(-1,)
+            )
+            self.backbone_feature_extractor = lambda x: self.backbone(x)[-1]
+            
+            dummy_input = torch.randn(1, 3, 224, 224)
+            with torch.no_grad():
+                out = self.backbone_feature_extractor(dummy_input)
+            self.backbone_out_features = out.shape[1]
+            logger.info(f"  Detected backbone output channels: {self.backbone_out_features}")
+            
+        else:
+            try:
+                logger.info(f"Attempting to load generic backbone from timm: {backbone_model_name}")
+                self.backbone = timm.create_model(
+                    backbone_model_name,
+                    pretrained=pretrained_backbone,
+                    num_classes=0,
+                    global_pool=''
+                )
+                self.backbone_feature_extractor = self.backbone.forward_features
+                
+                dummy_input = torch.randn(1, 3, 224, 224)
+                with torch.no_grad():
+                    out = self.backbone_feature_extractor(dummy_input)
+                self.backbone_out_features = out.shape[1]
+                logger.info(f"  Detected backbone output channels: {self.backbone_out_features}")
+            except Exception as e:
+                raise ValueError(f"Unsupported backbone: {backbone_model_name}. Error: {e}")
+
+        if freeze_backbone_initially:
+            self.freeze_backbone()
+
+        # Pooling layer
+        if pooling_type == 'attention':
+            self.pooling = AttentionPooling(
+                in_channels=self.backbone_out_features,
+                hidden_channels=attention_hidden_channels
+            )
+            pooling_out_features = self.backbone_out_features
+        elif pooling_type == 'gem':
+            self.pooling = GeMPooling(p=3.0, learnable=True)
+            pooling_out_features = self.backbone_out_features
+        elif pooling_type == 'hybrid':
+            self.pooling = HybridPooling(
+                in_channels=self.backbone_out_features,
+                attention_hidden=attention_hidden_channels,
+                output_mode='concat'
+            )
+            pooling_out_features = self.backbone_out_features * 2
+        else:  # 'avg'
+            self.pooling = nn.AdaptiveAvgPool2d(1)
+            pooling_out_features = self.backbone_out_features
+
+        # Embedding layers
+        embedding_layers = [nn.Linear(pooling_out_features, embedding_dim)]
+        if add_bn_to_embedding:
+            embedding_layers.append(nn.BatchNorm1d(embedding_dim))
+        if embedding_dropout_rate > 0.0:
+            embedding_layers.append(nn.Dropout(embedding_dropout_rate))
+
+        self.embedding_fc = nn.Sequential(*embedding_layers)
+        self.arcface_head = ArcFaceHead(embedding_dim, num_classes, s=arcface_s, m=arcface_m)
+
+        logger.info(f"StableEmbeddingModel initialized")
+        logger.info(f"  Embedding Dim: {embedding_dim}, Num Classes: {num_classes}")
+        logger.info(f"  ArcFace s: {arcface_s}, m: {arcface_m}")
+        logger.info(f"  Backbone out features: {self.backbone_out_features}")
+        logger.info(f"  Pooling type: {pooling_type}")
+
+    def freeze_backbone(self):
+        """Freeze all backbone parameters."""
+        logger.info("Freezing backbone parameters.")
+        for param in self.backbone.parameters():
+            param.requires_grad = False
+
+    def unfreeze_backbone(self, specific_layer_keywords=None, verbose=False):
+        """Unfreeze backbone parameters."""
+        logger.info(f"Unfreezing backbone parameters... (Keywords: {specific_layer_keywords})")
+        unfrozen_count = 0
+        for name, param in self.backbone.named_parameters():
+            if specific_layer_keywords is None or any(kw in name for kw in specific_layer_keywords):
+                param.requires_grad = True
+                unfrozen_count += 1
+                if verbose:
+                    logger.info(f"  Unfroze: {name}")
+        logger.info(f"Total parameters unfrozen: {unfrozen_count}")
+
+    def forward(
+        self, 
+        x: torch.Tensor, 
+        labels: Optional[torch.Tensor] = None, 
+        object_mask: Optional[torch.Tensor] = None, 
+        return_softmax: bool = False, 
+        return_attention_map: bool = True
+    ):
+        """
+        Forward pass.
+        
+        Args:
+            x: Input images [B, 3, H, W]
+            labels: Optional class labels [B]
+            object_mask: Optional object mask for attention guidance
+            return_softmax: Return softmax probabilities instead of logits
+            return_attention_map: Return attention visualization map
+        
+        Returns:
+            emb_norm: L2-normalized embeddings [B, D]
+            logits/probs: Class logits or probabilities [B, num_classes]
+            attn_map: Optional attention map for visualization
+        """
+        features = self.backbone_feature_extractor(x)
+        
+        attn_map = None
+        if self.pooling_type == 'attention':
+            pooled, attn_map = self.pooling(features, object_mask=object_mask, return_attention_map=return_attention_map)
+        elif self.pooling_type == 'hybrid':
+            pooled, attn_map = self.pooling(features, object_mask=object_mask, return_attention_map=return_attention_map)
+        elif self.pooling_type == 'gem':
+            pooled = self.pooling(features)
+        else:  # avg
+            pooled = self.pooling(features).squeeze(-1).squeeze(-1)
+        
+        emb_raw = self.embedding_fc(pooled)
+        emb_norm = F.normalize(emb_raw, p=2, dim=1)
+        logits = self.arcface_head(emb_norm, labels)
+
+        output_attn = attn_map if return_attention_map else None
+
+        if return_softmax:
+            probabilities = F.softmax(logits, dim=1)
+            return emb_norm, probabilities, output_attn
+        return emb_norm, logits, output_attn
+
+
+# =============================================================================
+# Embedding Classifier
+# =============================================================================
+
+class EmbeddingClassifier:
+    """
+    Main classifier for inference using embedding-based approach.
+    
+    This classifier loads a trained model and uses FAISS for fast nearest neighbor search
+    combined with centroid-based filtering for efficient classification.
+    
+    Configuration example:
+        config = {
+            'log_level': 'INFO',
+            'dataset': {'path': 'embeddings.pt'},
+            'model': {
+                'checkpoint_path': 'model.ckpt',
+                'backbone_model_name': 'maxvit_base_tf_224',
+                'embedding_dim': 512,
+                'num_classes': 639,
+                'arcface_s': 64.0,
+                'arcface_m': 0.2,
+                'pooling_type': 'attention',
+                'device': 'cuda'
+            },
+            'use_knn': True  # Enable/disable kNN classifier (default: True)
+        }
+    """
+    
+    def __init__(self, config: Dict):
+        # Validate configuration
+        self._validate_config(config)
+        
+        logger.setLevel(getattr(logging, config.get('log_level', 'INFO').upper()))
+        
+        # Load dataset
+        self._load_data(config["dataset"]["path"])
+        self.dim = self.db_embeddings.shape[1]
+        self._prepare_centroids()
+
+        logger.info("Initializing EmbeddingClassifier...")
+
+        # Setup device
+        self.device = config["model"].get("device", "cpu")
+        
+        # Load inference configuration
+        self.use_knn = config.get('use_knn', DEFAULT_USE_KNN)
+        self.arcface_min_score = config.get('arcface_min_score', DEFAULT_ARCFACE_MIN_SCORE)
+        self.centroid_fallback_score = config.get('centroid_fallback_score', DEFAULT_CENTROID_FALLBACK_SCORE)
+        self.default_topk_centroid = config.get('topk_centroid', DEFAULT_TOPK_CENTROID)
+        self.default_topk_neighbors = config.get('topk_neighbors', DEFAULT_TOPK_NEIGHBORS)
+        self.default_centroid_threshold = config.get('centroid_threshold', DEFAULT_CENTROID_THRESHOLD)
+        self.default_neighbor_threshold = config.get('neighbor_threshold', DEFAULT_NEIGHBOR_THRESHOLD)
+        self.default_topk_arcface = config.get('topk_arcface', DEFAULT_TOPK_ARCFACE)
+        
+        # Reranking configuration
+        self.rerank_mode = config.get('rerank_mode', DEFAULT_RERANK_MODE)
+        self.arcface_weight = config.get('arcface_weight', DEFAULT_ARCFACE_WEIGHT)
+        self.knn_weight = config.get('knn_weight', DEFAULT_KNN_WEIGHT)
+        self.rrf_k = config.get('rrf_k', DEFAULT_RRF_K)
+        
+        # Transform configuration
+        self.use_albumentations = config.get('use_albumentations', DEFAULT_USE_ALBUMENTATIONS)
+        
+        logger.info(f"Inference config: use_knn={self.use_knn}, "
+                   f"arcface_min={self.arcface_min_score}, "
+                   f"centroid_fallback={self.centroid_fallback_score}, "
+                   f"topk_centroid={self.default_topk_centroid}, "
+                   f"topk_neighbors={self.default_topk_neighbors}, "
+                   f"topk_arcface={self.default_topk_arcface}")
+        logger.info(f"Reranking config: mode={self.rerank_mode}, "
+                   f"arcface_weight={self.arcface_weight}, "
+                   f"knn_weight={self.knn_weight}, "
+                   f"rrf_k={self.rrf_k}")
+        
+        # Load model
+        self._load_model(config["model"])
+        
+        # Validate embedding dimensions match
+        model_embedding_dim = config["model"]["embedding_dim"]
+        if self.dim != model_embedding_dim:
+            raise ValueError(
+                f"Embedding dimension mismatch: dataset has {self.dim}, "
+                f"but model expects {model_embedding_dim}"
+            )
+        
+        # Infer input size from model or use config/default
+        self.input_size = self._get_input_size(config["model"])
+
+        # Setup transforms based on configuration
+        self.transform = self._create_transforms()
+        
+        logger.info(f"Using {'Albumentations' if self.use_albumentations else 'torchvision'} transforms")
+
+        # Create ID to label mapping
+        self.id_to_label = {internal_id: self.keys[internal_id]['label'] for internal_id in self.keys}
+        
+        # Pre-build FAISS indices for better performance (only if kNN is enabled)
+        if self.use_knn:
+            self._prepare_faiss_indices()
+        else:
+            logger.info("kNN classifier is disabled - skipping FAISS index creation")
+        
+        logger.info("EmbeddingClassifier initialized successfully.")
+
+    def _create_transforms(self):
+        """Create image transforms based on configuration.
+        
+        Returns:
+            Transform pipeline (Albumentations or torchvision)
+        """
+        if self.use_albumentations:
+            if not ALBUMENTATIONS_AVAILABLE:
+                logger.warning("Albumentations requested but not installed. Falling back to torchvision.")
+                logger.warning("Install with: pip install albumentations")
+                self.use_albumentations = False
+            else:
+                logger.info("Creating Albumentations transform pipeline")
+                return A.Compose([
+                    A.Resize(self.input_size, self.input_size),
+                    A.Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225)),
+                    ToTensorV2(),
+                ])
+        
+        # Default: torchvision transforms
+        logger.info("Creating torchvision transform pipeline")
+        return transforms.Compose([
+            transforms.Resize((self.input_size, self.input_size), Image.Resampling.BILINEAR),
+            transforms.ToTensor(),
+            transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+        ])
+    
+    @staticmethod
+    def _safe_int_to_str(value) -> str:
+        """Safely convert value to string, handling tensors, numpy arrays, UUIDs, etc.
+        
+        Args:
+            value: Any value (tensor, numpy array, int, float, string/UUID, etc.)
+            
+        Returns:
+            String representation of the value
+        """
+        # Handle torch tensors
+        if hasattr(value, 'item'):
+            value = value.item()
+        # Handle numpy arrays
+        elif hasattr(value, 'tolist'):
+            value = value.tolist()
+        
+        # If already a string, return as is
+        if isinstance(value, str):
+            return value
+        
+        # Try to convert to int, fallback to str if it fails (e.g., UUIDs)
+        try:
+            return str(int(value))
+        except (ValueError, TypeError):
+            return str(value)
+    
+    def _validate_config(self, config: Dict) -> None:
+        """Validate configuration structure and required fields."""
+        if not isinstance(config, dict):
+            raise TypeError(f"Config must be a dictionary, got {type(config)}")
+        
+        # Check required keys
+        if "dataset" not in config:
+            raise ValueError("Config must contain 'dataset' key")
+        if "path" not in config["dataset"]:
+            raise ValueError("Config['dataset'] must contain 'path' key")
+        if "model" not in config:
+            raise ValueError("Config must contain 'model' key")
+        
+        required_model_keys = ["checkpoint_path", "backbone_model_name", "embedding_dim", "num_classes"]
+        for key in required_model_keys:
+            if key not in config["model"]:
+                raise ValueError(f"Config['model'] must contain '{key}' key")
+        
+        # Validate numeric parameters
+        if config["model"]["embedding_dim"] <= 0:
+            raise ValueError(f"embedding_dim must be positive, got {config['model']['embedding_dim']}")
+        if config["model"]["num_classes"] <= 0:
+            raise ValueError(f"num_classes must be positive, got {config['model']['num_classes']}")
+        
+        # Validate optional thresholds if present
+        for param in ["arcface_min_score", "centroid_fallback_score", "centroid_threshold", "neighbor_threshold"]:
+            if param in config and (config[param] < 0 or config[param] > 1):
+                raise ValueError(f"{param} must be between 0 and 1, got {config[param]}")
+        
+        logger.info("Configuration validated successfully")
+
+    def _get_input_size(self, model_config: Dict) -> int:
+        """Infer input size from model config or backbone."""
+        # Check if explicitly provided in config
+        if "input_size" in model_config:
+            return model_config["input_size"]
+        
+        # Try to infer from backbone name
+        backbone_name = model_config.get("backbone_model_name", "")
+        
+        # Check for common size patterns in backbone name
+        for size in [512, 384, 256, 224]:
+            if f"_{size}" in backbone_name or f"{size}" in backbone_name:
+                logger.info(f"Inferred input size {size} from backbone name")
+                return size
+        
+        # Try to get from model's default config
+        if hasattr(self.model, 'backbone') and hasattr(self.model.backbone, 'default_cfg'):
+            cfg = self.model.backbone.default_cfg
+            if 'input_size' in cfg:
+                input_size = cfg['input_size']
+                if isinstance(input_size, (tuple, list)) and len(input_size) == 3:
+                    size = input_size[1]  # Get height
+                    logger.info(f"Using input size {size} from model config")
+                    return size
+        
+        # Default fallback
+        logger.info(f"Using default input size {DEFAULT_IMAGE_SIZE}")
+        return DEFAULT_IMAGE_SIZE
+
+    def _load_model(self, model_config: Dict):
+        """Load model from Lightning checkpoint or regular PyTorch checkpoint."""
+        checkpoint_path = model_config["checkpoint_path"]
+        
+        # Validate checkpoint exists
+        if not Path(checkpoint_path).exists():
+            raise FileNotFoundError(f"Checkpoint not found: {checkpoint_path}")
+        
+        backbone_name = model_config.get("backbone_model_name", "maxvit_base_tf_224")
+        embedding_dim = model_config.get("embedding_dim", 512)
+        num_classes = model_config.get("num_classes", 639)
+        arcface_s = model_config.get("arcface_s", 64.0)
+        arcface_m = model_config.get("arcface_m", 0.2)
+        pooling_type = model_config.get("pooling_type", "attention")
+        
+        # Determine model class based on backbone
+        is_vit = any(x in backbone_name.lower() for x in SUPPORTED_VIT_BACKBONES)
+        
+        model_cls = StableEmbeddingModelViT if is_vit else StableEmbeddingModel
+        
+        # Create model
+        if is_vit:
+            self.model = model_cls(
+                embedding_dim=embedding_dim,
+                num_classes=num_classes,
+                backbone_model_name=backbone_name,
+                arcface_s=arcface_s,
+                arcface_m=arcface_m,
+                pooling_type=pooling_type,
+                pretrained_backbone=False,  # We'll load from checkpoint
+            )
+        else:
+            self.model = model_cls(
+                embedding_dim=embedding_dim,
+                num_classes=num_classes,
+                backbone_model_name=backbone_name,
+                arcface_s=arcface_s,
+                arcface_m=arcface_m,
+                pooling_type=pooling_type,
+                pretrained_backbone=False,  # We'll load from checkpoint
+            )
+        
+        # Load checkpoint
+        # WARNING: torch.load uses pickle which can execute arbitrary code.
+        # Only load checkpoints from trusted sources!
+        # TODO: Add checksum verification for production use
+        logger.warning(f"Loading checkpoint with weights_only=False (security risk). "
+                      f"Only load from trusted sources: {checkpoint_path}")
+        try:
+            checkpoint = torch.load(checkpoint_path, map_location=torch.device('cpu'), weights_only=True)
+        except Exception as e:
+            logger.warning(f"Failed to load with weights_only=True: {e}. Falling back to weights_only=False")
+            checkpoint = torch.load(checkpoint_path, map_location=torch.device('cpu'), weights_only=False)
+        
+        # Handle Lightning checkpoint format
+        if 'state_dict' in checkpoint:
+            state_dict = checkpoint['state_dict']
+            # Remove 'model.' prefix if present (from Lightning)
+            new_state_dict = {}
+            for k, v in state_dict.items():
+                if k.startswith('model.'):
+                    new_state_dict[k[6:]] = v
+                else:
+                    new_state_dict[k] = v
+            state_dict = new_state_dict
+        else:
+            state_dict = checkpoint
+        
+        # Load state dict with error handling
+        try:
+            self.model.load_state_dict(state_dict, strict=True)
+            logger.info(f"Model loaded successfully from {checkpoint_path}")
+        except RuntimeError as e:
+            logger.warning(f"Strict loading failed: {str(e)[:200]}")
+            result = self.model.load_state_dict(state_dict, strict=False)
+            if result.missing_keys:
+                logger.warning(f"Missing keys in checkpoint: {result.missing_keys[:5]}")
+            if result.unexpected_keys:
+                logger.warning(f"Unexpected keys in checkpoint: {result.unexpected_keys[:5]}")
+            logger.info(f"Model loaded with strict=False from {checkpoint_path}")
+        
+        self.model.to(self.device)
+        self.model.eval()
+        
+        # Log model info
+        total_params = sum(p.numel() for p in self.model.parameters())
+        trainable_params = sum(p.numel() for p in self.model.parameters() if p.requires_grad)
+        logger.info(f"Model loaded and moved to {self.device}")
+        logger.info(f"Total parameters: {total_params:,}, Trainable: {trainable_params:,}")
+        
+        return self.model
+
+    def _load_data(self, dataset_path: str) -> None:
+        """Load embeddings database."""
+        # Validate dataset file exists
+        if not Path(dataset_path).exists():
+            raise FileNotFoundError(f"Dataset file not found: {dataset_path}")
+        
+        try:
+            logger.info(f"Loading dataset from {dataset_path}")
+            try:
+                data = torch.load(dataset_path, weights_only=True)
+            except Exception as e:
+                logger.warning(f"Failed to load dataset with weights_only=True: {e}. Using weights_only=False")
+                data = torch.load(dataset_path, weights_only=False)
+        except Exception as e:
+            raise RuntimeError(f"Failed to load dataset from {dataset_path}: {e}")
+        
+        # Validate required keys
+        required_keys = ['embeddings', 'labels', 'image_ids', 'annotation_ids', 'drawn_fish_ids', 'labels_keys']
+        for key in required_keys:
+            if key not in data:
+                raise ValueError(f"Dataset missing required key: '{key}'")
+        
+        # Optimize: direct conversion to float32 numpy array
+        self.db_embeddings = np.asarray(data['embeddings'], dtype=np.float32)
+        
+        self.db_labels = np.array(data['labels'])
+        self.image_ids = data['image_ids']
+        self.annotation_ids = data['annotation_ids']
+        self.drawn_fish_ids = data['drawn_fish_ids']
+        self.keys = data['labels_keys']
+        
+        # Validate array lengths match
+        n_embeddings = len(self.db_embeddings)
+        if not (len(self.db_labels) == len(self.image_ids) == len(self.annotation_ids) == len(self.drawn_fish_ids) == n_embeddings):
+            raise ValueError(
+                f"Array length mismatch: embeddings={n_embeddings}, labels={len(self.db_labels)}, "
+                f"image_ids={len(self.image_ids)}, annotation_ids={len(self.annotation_ids)}, "
+                f"drawn_fish_ids={len(self.drawn_fish_ids)}"
+            )
+        
+        self.label_to_species_id = {
+            v['label']: v['species_id'] for v in self.keys.values()
+        }
+        
+        # Calculate memory usage
+        embeddings_size_mb = self.db_embeddings.nbytes / (1024 * 1024)
+        
+        logger.info(f"Dataset loaded from {dataset_path}")
+        logger.info(f"  Embeddings shape: {self.db_embeddings.shape}")
+        logger.info(f"  Embeddings memory: {embeddings_size_mb:.2f} MB")
+        logger.info(f"  Unique labels: {len(np.unique(self.db_labels))}")
+
+    def __call__(self, img: Union[np.ndarray, List[np.ndarray]]):
+        """
+        Perform inference on image(s).
+        
+        Args:
+            img: Single image as np.ndarray or list of images
+        
+        Returns:
+            List of prediction results for each image
+        """
+        if isinstance(img, np.ndarray):
+            return self.inference_numpy(img)
+        elif isinstance(img, list) and all(isinstance(i, np.ndarray) for i in img):
+            return self.inference_numpy_batch(img)
+        else:
+            raise TypeError("Input must be np.ndarray or List[np.ndarray].")
+
+    def _preprocess_image(self, img: np.ndarray, img_index: int = 0) -> np.ndarray:
+        """Preprocess a single image to RGB uint8 format.
+        
+        Args:
+            img: Input image array
+            img_index: Index of image in batch (for error messages)
+            
+        Returns:
+            Preprocessed RGB image as uint8 array
+        """
+        # Validate input
+        if img.ndim not in [2, 3]:
+            raise ValueError(f"Image {img_index} must be 2D or 3D array, got shape {img.shape}")
+        if img.ndim == 3 and img.shape[2] not in [1, 3, 4]:
+            raise ValueError(f"Image {img_index} must have 1, 3, or 4 channels, got {img.shape[2]}")
+        
+        # Check for empty/invalid images
+        if img.size == 0 or min(img.shape[:2]) == 0:
+            raise ValueError(f"Image {img_index} has invalid dimensions: {img.shape}")
+        
+        # Convert grayscale to RGB if needed
+        if img.ndim == 2 or (img.ndim == 3 and img.shape[2] == 1):
+            img = np.stack([img.squeeze()] * 3, axis=-1)
+        elif img.shape[2] == 4:  # RGBA
+            img = img[:, :, :3]
+        
+        # Ensure correct dtype and range
+        if img.dtype != np.uint8:
+            max_val = img.max()
+            if max_val == 0:
+                logger.warning(f"Image {img_index} is completely black (all zeros)")
+                img = np.zeros(img.shape, dtype=np.uint8)
+            elif max_val <= 1.0:
+                img = (img * 255).astype(np.uint8)
+            else:
+                img = img.astype(np.uint8)
+        
+        return img
+    
+    def inference_numpy(self, img: np.ndarray):
+        """Inference on a single numpy image."""
+        try:
+            img = self._preprocess_image(img, img_index=0)
+            
+            # Apply transforms based on type
+            if self.use_albumentations and ALBUMENTATIONS_AVAILABLE:
+                # Albumentations expects numpy array in HWC format
+                transformed = self.transform(image=img)
+                tensor = transformed['image'].unsqueeze(0).to(self.device)
+            else:
+                # torchvision expects PIL Image
+                pil_img = Image.fromarray(img)
+                tensor = self.transform(pil_img).unsqueeze(0).to(self.device)
+            
+            return self._inference_batch_tensor(tensor)[0]
+        except Exception as e:
+            logger.error(f"Failed to process image: {e}", exc_info=True)
+            raise RuntimeError(f"Image processing failed: {e}")
+
+    def inference_numpy_batch(self, imgs: List[np.ndarray]):
+        """Inference on a batch of numpy images."""
+        if not imgs:
+            raise ValueError("Empty image list provided")
+        
+        if len(imgs) > MAX_BATCH_SIZE:
+            logger.info(f"Large batch detected ({len(imgs)} images). "
+                       f"Will be processed in chunks of {MAX_BATCH_SIZE}.")
+        
+        try:
+            processed_tensors = []
+            for i, img in enumerate(imgs):
+                img = self._preprocess_image(img, img_index=i)
+                
+                # Apply transforms based on type
+                if self.use_albumentations and ALBUMENTATIONS_AVAILABLE:
+                    # Albumentations expects numpy array
+                    transformed = self.transform(image=img)
+                    processed_tensors.append(transformed['image'])
+                else:
+                    # torchvision expects PIL Image
+                    pil_img = Image.fromarray(img)
+                    processed_tensors.append(self.transform(pil_img))
+            
+            tensors = torch.stack(processed_tensors).to(self.device)
+            return self._inference_batch_tensor(tensors)
+        except Exception as e:
+            logger.error(f"Failed to process image batch: {e}", exc_info=True)
+            raise RuntimeError(f"Batch image processing failed: {e}")
+
+    def _inference_batch_tensor(self, tensors: torch.Tensor):
+        """Internal inference on tensor batch."""
+        batch_size = tensors.shape[0]
+        
+        # Validate batch size to prevent OOM
+        if batch_size > MAX_BATCH_SIZE:
+            logger.warning(f"Batch size {batch_size} exceeds MAX_BATCH_SIZE={MAX_BATCH_SIZE}. "
+                         f"Processing in chunks to prevent OOM.")
+            # Process in chunks
+            all_results = []
+            for i in range(0, batch_size, MAX_BATCH_SIZE):
+                chunk = tensors[i:i + MAX_BATCH_SIZE]
+                chunk_results = self._inference_batch_tensor(chunk)
+                all_results.extend(chunk_results)
+            return all_results
+        
+        with torch.no_grad():
+            embeddings, archead_logits, _ = self.model(tensors, return_softmax=False)
+            
+        # Get top-5 ArcFace predictions
+        k_arcface = min(5, archead_logits.shape[1])
+        top_probabilities, top_indices = torch.topk(archead_logits, k_arcface)
+        
+        # Store top-5 ArcFace predictions with their scores
+        topk_arcface = []
+        for i in range(len(top_indices)):
+            batch_top5 = []
+            for rank in range(k_arcface):
+                pred_id = top_indices[i][rank].item()
+                pred_score = top_probabilities[i][rank].item()
+                batch_top5.append((pred_id, pred_score, rank))
+            topk_arcface.append(batch_top5)
+        
+        # Use kNN search if enabled
+        if self.use_knn:
+            knn_output = self.get_top_neighbors_from_embeddings(embeddings)
+            
+            # Log summary instead of full output (only if debug enabled)
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug(f"Inference: {len(knn_output)} predictions generated (kNN enabled)")
+        else:
+            # kNN disabled - use empty results
+            knn_output = [{} for _ in range(len(top_indices))]
+            
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug(f"Inference: kNN disabled, using only ArcFace predictions")
+
+        return self._postprocess_hybrid(knn_output, topk_arcface)
+
+    def _rerank_predictions(
+        self, 
+        arcface_predictions: List[Tuple[int, float, int]], 
+        knn_predictions: Dict,
+        mode: str = 'weighted_fusion'
+    ) -> List[Tuple[int, float, str]]:
+        """
+        Rerank predictions using different fusion strategies.
+        
+        Args:
+            arcface_predictions: List of (label_id, score, rank) from ArcFace
+            knn_predictions: Dict of {label_id: data} from kNN
+            mode: Reranking mode ('weighted_fusion', 'rrf', 'hybrid')
+            
+        Returns:
+            List of (label_id, final_score, source) tuples, sorted by final_score
+        """
+        combined_scores = {}
+        
+        if mode == 'weighted_fusion':
+            # Weighted Fusion: combine normalized scores with weights
+            # ArcFace scores are already softmax probabilities [0, 1]
+            for label_id, prob, rank in arcface_predictions:
+                combined_scores[label_id] = {
+                    'arcface_score': prob,
+                    'arcface_rank': rank,
+                    'knn_score': 0.0,
+                    'knn_rank': None
+                }
+            
+            # Add kNN scores (already normalized similarities [0, 1])
+            for idx, (label_id, data) in enumerate(
+                sorted(knn_predictions.items(), 
+                       key=lambda x: x[1]['similarity'] / x[1]['times'], 
+                       reverse=True)
+            ):
+                knn_score = data['similarity'] / data['times']
+                knn_score = max(0.0, min(1.0, knn_score))  # Clamp to [0, 1]
+                
+                if isinstance(label_id, (int, np.integer)):
+                    label_id_int = int(label_id)
+                else:
+                    # Find corresponding ID for string label
+                    label_id_int = None
+                    for k, v in self.id_to_label.items():
+                        if v == str(label_id):
+                            label_id_int = k
+                            break
+                    if label_id_int is None:
+                        continue
+                
+                if label_id_int not in combined_scores:
+                    combined_scores[label_id_int] = {
+                        'arcface_score': 0.0,
+                        'arcface_rank': None,
+                        'knn_score': knn_score,
+                        'knn_rank': idx
+                    }
+                else:
+                    combined_scores[label_id_int]['knn_score'] = knn_score
+                    combined_scores[label_id_int]['knn_rank'] = idx
+            
+            # Calculate weighted final scores
+            final_scores = []
+            for label_id, scores in combined_scores.items():
+                final_score = (
+                    self.arcface_weight * scores['arcface_score'] +
+                    self.knn_weight * scores['knn_score']
+                )
+                
+                # Determine source
+                if scores['arcface_rank'] is not None and scores['knn_rank'] is not None:
+                    source = 'both'
+                elif scores['arcface_rank'] is not None:
+                    source = 'arcface'
+                else:
+                    source = 'knn'
+                
+                final_scores.append((label_id, final_score, source))
+        
+        elif mode == 'rrf':
+            # Reciprocal Rank Fusion
+            for label_id, prob, rank in arcface_predictions:
+                rrf_score = 1.0 / (self.rrf_k + rank)
+                combined_scores[label_id] = {
+                    'rrf_score': rrf_score,
+                    'arcface_rank': rank
+                }
+            
+            # Add kNN RRF scores
+            for idx, (label_id, data) in enumerate(
+                sorted(knn_predictions.items(), 
+                       key=lambda x: x[1]['similarity'] / x[1]['times'], 
+                       reverse=True)
+            ):
+                if isinstance(label_id, (int, np.integer)):
+                    label_id_int = int(label_id)
+                else:
+                    label_id_int = None
+                    for k, v in self.id_to_label.items():
+                        if v == str(label_id):
+                            label_id_int = k
+                            break
+                    if label_id_int is None:
+                        continue
+                
+                knn_rrf = 1.0 / (self.rrf_k + idx)
+                
+                if label_id_int not in combined_scores:
+                    combined_scores[label_id_int] = {
+                        'rrf_score': knn_rrf,
+                        'knn_rank': idx
+                    }
+                else:
+                    combined_scores[label_id_int]['rrf_score'] += knn_rrf
+            
+            final_scores = [
+                (label_id, scores['rrf_score'], 
+                 'both' if 'arcface_rank' in scores and 'knn_rank' in scores else 
+                 'arcface' if 'arcface_rank' in scores else 'knn')
+                for label_id, scores in combined_scores.items()
+            ]
+        
+        else:  # 'hybrid' - original behavior
+            # Top-5 ArcFace first, then top-5 unique kNN
+            return None  # Will be handled separately
+        
+        # Sort by final score (descending)
+        final_scores.sort(key=lambda x: x[1], reverse=True)
+        return final_scores
+    
+    def _postprocess_hybrid(self, knn_results, topk_arcface) -> List[PredictionResult]:
+        """Combine top-5 ArcFace and top-5 unique kNN predictions.
+        
+        Args:
+            knn_results: kNN prediction results (list of dicts)
+            topk_arcface: List of lists with (label_id, score, rank) tuples for top-5 ArcFace
+            
+        Returns:
+            List of PredictionResult objects:
+            - Positions 1-5: Top-5 ArcFace predictions (with softmax probabilities)
+            - Positions 6-10: Top-5 unique kNN predictions (not in ArcFace top-5)
+        """
+        results = []
+        
+        for batch_idx in range(len(knn_results)):
+            arcface_top5 = topk_arcface[batch_idx]
+            knn_dict = knn_results[batch_idx]
+            
+            # Step 1: Apply softmax to ArcFace logits to get probabilities
+            arcface_scores = torch.tensor([score for _, score, _ in arcface_top5])
+            arcface_probs = F.softmax(arcface_scores, dim=0).cpu().numpy()
+            
+            # Update arcface_top5 with probabilities
+            arcface_top5_with_probs = [
+                (label_id, float(arcface_probs[idx]), rank)
+                for idx, (label_id, score, rank) in enumerate(arcface_top5)
+            ]
+            
+            # Step 2: Rerank predictions based on mode
+            if self.rerank_mode in ['weighted_fusion', 'rrf']:
+                reranked = self._rerank_predictions(
+                    arcface_top5_with_probs, 
+                    knn_dict, 
+                    mode=self.rerank_mode
+                )
+                
+                # Convert reranked results to PredictionResult objects
+                final_predictions = []
+                for label_id, final_score, source in reranked[:10]:  # Top-10
+                    label = self.id_to_label.get(label_id, str(label_id))
+                    species_id = self.label_to_species_id.get(label, -1)
+                    
+                    # Get additional info from kNN if available
+                    image_id = None
+                    annotation_id = None
+                    drawn_fish_id = None
+                    
+                    if label_id in [int(k) if isinstance(k, (int, np.integer)) else None 
+                                    for k in knn_dict.keys()]:
+                        for k, data in knn_dict.items():
+                            k_int = int(k) if isinstance(k, (int, np.integer)) else None
+                            if k_int == label_id and data.get('index') is not None:
+                                idx = data['index']
+                                try:
+                                    if 0 <= idx < len(self.image_ids):
+                                        # Convert to string, handling tensors/numpy
+                                        image_id = self._safe_int_to_str(self.image_ids[idx])
+                                        annotation_id = self._safe_int_to_str(self.annotation_ids[idx])
+                                        drawn_fish_id = self._safe_int_to_str(self.drawn_fish_ids[idx])
+                                except (IndexError, KeyError):
+                                    pass
+                                break
+                    
+                    final_predictions.append(PredictionResult(
+                        name=label,
+                        species_id=species_id,
+                        distance=final_score,
+                        accuracy=final_score,
+                        image_id=image_id,
+                        annotation_id=annotation_id,
+                        drawn_fish_id=drawn_fish_id,
+                    ))
+                
+                results.append(final_predictions)
+                continue
+            
+            # Step 3: Hybrid mode - original behavior (top-5 ArcFace + top-5 unique kNN)
+            arcface_predictions = []
+            arcface_label_ids = set()
+            
+            for idx, (label_id, score, rank) in enumerate(arcface_top5):
+                label = self.id_to_label.get(label_id, str(label_id))
+                arcface_label_ids.add(label_id)
+                
+                species_id = self.label_to_species_id.get(label)
+                if species_id is None:
+                    species_id = -1
+                
+                probability = float(arcface_probs[idx])  # Softmax probability [0, 1]
+                
+                arcface_predictions.append(PredictionResult(
+                    name=label,
+                    species_id=species_id,
+                    distance=score,              # Keep raw logit for reference
+                    accuracy=probability,        # Use softmax probability
+                    image_id=None,
+                    annotation_id=None,
+                    drawn_fish_id=None,
+                ))
+            
+            # Step 3: Create kNN predictions (exclude those already in ArcFace top-5)
+            knn_predictions = []
+            
+            for label_id, data in knn_dict.items():
+                # Handle label conversion
+                if isinstance(label_id, (int, np.integer)):
+                    label = self.id_to_label.get(int(label_id), str(label_id))
+                    label_id_int = int(label_id)
+                else:
+                    # Already a string label name
+                    label = str(label_id)
+                    # Try to find corresponding ID
+                    label_id_int = None
+                    for k, v in self.id_to_label.items():
+                        if v == label:
+                            label_id_int = k
+                            break
+                
+                # Skip if this label is already in ArcFace top-5
+                if label_id_int in arcface_label_ids:
+                    continue
+                
+                index = data.get("index")
+                
+                # Safely access arrays with bounds checking
+                image_id = None
+                annotation_id = None
+                drawn_fish_id = None
+                
+                if index is not None:
+                    try:
+                        if 0 <= index < len(self.image_ids):
+                            # Convert to string, handling tensors/numpy
+                            image_id = self._safe_int_to_str(self.image_ids[index])
+                            annotation_id = self._safe_int_to_str(self.annotation_ids[index])
+                            drawn_fish_id = self._safe_int_to_str(self.drawn_fish_ids[index])
+                    except (IndexError, KeyError) as e:
+                        logger.warning(f"Error accessing index {index}: {e}")
+                
+                species_id = self.label_to_species_id.get(label)
+                if species_id is None:
+                    species_id = -1
+                
+                # Calculate average similarity score (already normalized in [0, 1] from cosine similarity)
+                avg_similarity = data['similarity'] / data['times']
+                # Clamp to [0, 1] for safety
+                avg_similarity = max(0.0, min(1.0, avg_similarity))
+                
+                knn_predictions.append(PredictionResult(
+                    name=label,
+                    species_id=species_id,
+                    distance=data['similarity'],
+                    accuracy=avg_similarity,  # Normalized similarity score
+                    image_id=image_id,
+                    annotation_id=annotation_id,
+                    drawn_fish_id=drawn_fish_id,
+                ))
+            
+            # Step 4: Sort kNN predictions by average similarity (descending) and take top-5
+            knn_predictions.sort(key=lambda x: x.accuracy, reverse=True)
+            top5_knn = knn_predictions[:5]
+            
+            # Step 5: Combine: ArcFace top-5 first, then unique kNN top-5
+            final_predictions = arcface_predictions + top5_knn
+            
+            results.append(final_predictions)
+        
+        return results
+    
+    def _postprocess(self, class_results, top1_arcface) -> List[PredictionResult]:
+        """Convert raw results to PredictionResult objects with custom sorting.
+        
+        Args:
+            class_results: Raw prediction results
+            top1_arcface: List of (label_id, score) tuples for top-1 ArcFace predictions
+            
+        Returns:
+            List of sorted PredictionResult objects
+        """
+        results = []
+        for batch_idx, single_fish in enumerate(class_results):
+            fish_results = []
+            top1_result = None
+            top1_label_id = top1_arcface[batch_idx][0]
+            
+            for label_id, data in single_fish.items():
+                # Handle label conversion - label_id can be int or string
+                if isinstance(label_id, (int, np.integer)):
+                    label = self.id_to_label.get(int(label_id), str(label_id))
+                    label_id_int = int(label_id)
+                else:
+                    # Already a string label name
+                    label = str(label_id)
+                    # Try to find corresponding ID for comparison
+                    label_id_int = None
+                    for k, v in self.id_to_label.items():
+                        if v == label:
+                            label_id_int = k
+                            break
+                
+                index = data["index"]
+                
+                # Safely access arrays with bounds checking
+                image_id = None
+                annotation_id = None
+                drawn_fish_id = None
+                
+                if index is not None:
+                    try:
+                        if 0 <= index < len(self.image_ids):
+                            # Convert to string, handling tensors/numpy
+                            image_id = self._safe_int_to_str(self.image_ids[index])
+                            annotation_id = self._safe_int_to_str(self.annotation_ids[index])
+                            drawn_fish_id = self._safe_int_to_str(self.drawn_fish_ids[index])
+                        else:
+                            logger.warning(f"Index {index} out of bounds for arrays of length {len(self.image_ids)}")
+                    except (IndexError, KeyError) as e:
+                        logger.warning(f"Error accessing index {index}: {e}")
+                
+                species_id = self.label_to_species_id.get(label)
+                if species_id is None:
+                    logger.warning(f"Unknown label '{label}' not found in label_to_species_id mapping")
+                    species_id = -1  # Fallback for backward compatibility
+                
+                # Calculate average similarity score
+                avg_similarity = data['similarity'] / data['times']
+                
+                result = PredictionResult(
+                    name=label,
+                    species_id=species_id,
+                    distance=data['similarity'],
+                    accuracy=avg_similarity,  # Average similarity score
+                    image_id=image_id,
+                    annotation_id=annotation_id,
+                    drawn_fish_id=drawn_fish_id,
+                )
+                
+                # Check if this is the top-1 ArcFace prediction
+                is_arcface_top1 = (
+                    (label_id_int is not None and label_id_int == top1_label_id) or
+                    (data.get('source') == 'arcface' and data.get('arcface_rank') == 0)
+                )
+                
+                if is_arcface_top1:
+                    top1_result = result
+                else:
+                    fish_results.append(result)
+            
+            # Sort remaining results by average similarity (descending)
+            fish_results.sort(key=lambda x: x.accuracy, reverse=True)
+            
+            # Place top-1 ArcFace prediction first, then kNN results
+            if top1_result is not None:
+                final_results = [top1_result] + fish_results
+            else:
+                final_results = fish_results
+                if logger.isEnabledFor(logging.WARNING):
+                    logger.warning(f"Top-1 ArcFace prediction not found in results for batch {batch_idx}")
+            
+            results.append(final_results)
+        return results
+
+    def _prepare_centroids(self) -> None:
+        """Compute class centroids for efficient filtering."""
+        unique_labels = np.unique(self.db_labels)
+        self.label_to_centroid = {}
+        skipped_labels = []
+        
+        for label in unique_labels:
+            class_embs = self.db_embeddings[self.db_labels == label]
+            if len(class_embs) == 0:
+                logger.warning(f"Label {label} has no embeddings, skipping")
+                skipped_labels.append(label)
+                continue
+                
+            centroid = np.mean(class_embs, axis=0)
+            norm = np.linalg.norm(centroid)
+            
+            if norm < NUMERICAL_EPSILON:
+                logger.warning(f"Label {label} has zero-norm centroid, using unnormalized")
+                self.label_to_centroid[label] = centroid
+            else:
+                self.label_to_centroid[label] = centroid / norm
+
+        self.centroid_matrix = np.stack([self.label_to_centroid[label] for label in self.label_to_centroid])
+        self.centroid_labels = list(self.label_to_centroid.keys())
+        
+        if skipped_labels:
+            logger.warning(f"Skipped {len(skipped_labels)} labels with no embeddings")
+        logger.info(f"Prepared {len(self.centroid_labels)} class centroids")
+    
+    def _prepare_faiss_indices(self) -> None:
+        """Pre-build FAISS indices for each class for faster search."""
+        logger.info("Building FAISS indices for each class...")
+        self.class_indices = {}
+        unique_labels = np.unique(self.db_labels)
+        
+        for label in unique_labels:
+            # Use np.where directly to get indices (more memory efficient)
+            global_indices = np.where(self.db_labels == label)[0]
+            class_embs = self.db_embeddings[global_indices]
+            
+            if len(class_embs) > 0:
+                # Create FAISS index for this class
+                index = faiss.IndexFlatIP(self.dim)
+                index.add(class_embs)
+                
+                self.class_indices[label] = {
+                    'index': index,
+                    'global_indices': global_indices,
+                    'size': len(class_embs)
+                }
+        
+        logger.info(f"Built FAISS indices for {len(self.class_indices)} classes")
+
+    def get_top_neighbors_from_embeddings(
+        self,
+        query_embeddings: Union[np.ndarray, torch.Tensor],
+        topk_centroid: Optional[int] = None,
+        topk_neighbors: Optional[int] = None,
+        centroid_threshold: Optional[float] = None,
+        neighbor_threshold: Optional[float] = None
+    ) -> List[Dict[str, Dict[str, Union[float, int, None]]]]:
+        """
+        Find top neighbors using centroid filtering + FAISS search.
+        
+        Args:
+            query_embeddings: Query embeddings [B, D]
+            topk_centroid: Number of top centroids to consider (None = use default)
+            topk_neighbors: Number of neighbors to retrieve (None = use default)
+            centroid_threshold: Minimum similarity to centroid (None = use default)
+            neighbor_threshold: Minimum similarity to neighbor (None = use default)
+        
+        Returns:
+            List of dictionaries mapping labels to similarity scores
+        """
+        # Use default values if not specified
+        topk_centroid = self.default_topk_centroid if topk_centroid is None else topk_centroid
+        topk_neighbors = self.default_topk_neighbors if topk_neighbors is None else topk_neighbors
+        centroid_threshold = self.default_centroid_threshold if centroid_threshold is None else centroid_threshold
+        neighbor_threshold = self.default_neighbor_threshold if neighbor_threshold is None else neighbor_threshold
+        
+        # Validate parameters
+        if topk_centroid <= 0:
+            raise ValueError(f"topk_centroid must be positive, got {topk_centroid}")
+        if topk_neighbors <= 0:
+            raise ValueError(f"topk_neighbors must be positive, got {topk_neighbors}")
+        if not 0 <= centroid_threshold <= 1:
+            raise ValueError(f"centroid_threshold must be in [0, 1], got {centroid_threshold}")
+        if not 0 <= neighbor_threshold <= 1:
+            raise ValueError(f"neighbor_threshold must be in [0, 1], got {neighbor_threshold}")
+        
+        start_time = time.time()
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"Starting search over {len(query_embeddings)} embeddings")
+
+        if isinstance(query_embeddings, torch.Tensor):
+            query_embeddings = query_embeddings.cpu().numpy().astype("float32")
+
+        # Timing breakdown
+        timing = {'centroid': 0, 'faiss': 0, 'aggregation': 0}
+        
+        # Step 1: Vectorized centroid similarity computation for all queries
+        t0 = time.time()
+        # Embeddings are already L2-normalized, use matrix multiplication for cosine similarity
+        all_centroid_sims = np.dot(query_embeddings, self.centroid_matrix.T)  # [B, num_centroids]
+        timing['centroid'] = time.time() - t0
+        
+        results = []
+        for query_idx, query_emb in enumerate(query_embeddings):
+            centroid_sims = all_centroid_sims[query_idx]
+            top_centroid_indices = np.argsort(-centroid_sims)[:topk_centroid]
+
+            centroid_scores = {
+                self.centroid_labels[idx]: centroid_sims[idx]
+                for idx in top_centroid_indices if centroid_sims[idx] >= centroid_threshold
+            }
+            selected_classes = set(centroid_scores.keys())
+
+            if not selected_classes:
+                if logger.isEnabledFor(logging.DEBUG):
+                    max_sim = centroid_sims[top_centroid_indices[0]] if len(top_centroid_indices) > 0 else 0
+                    logger.debug(f"Query {query_idx}: No classes passed centroid threshold "
+                               f"(max similarity: {max_sim:.3f}, threshold: {centroid_threshold})")
+                results.append({})
+                continue
+
+            # Step 2: FAISS search using pre-built indices
+            t0 = time.time()
+            score_map = defaultdict(lambda: {'index': None, 'similarity': 0.0, 'times': 0, 'source': 'knn'})
+            
+            for label in selected_classes:
+                if label not in self.class_indices:
+                    if logger.isEnabledFor(logging.DEBUG):
+                        logger.debug(f"Label {label} not found in class_indices, skipping")
+                    continue
+                
+                class_data = self.class_indices[label]
+                class_index = class_data['index']
+                global_indices = class_data['global_indices']
+                
+                # Search within this class
+                k = min(topk_neighbors, class_data['size'])
+                distances, indices = class_index.search(query_emb.reshape(1, -1), k)
+                
+                # Aggregate results for this class
+                for rank, idx in enumerate(indices[0]):
+                    sim = float(distances[0][rank])
+                    if sim >= neighbor_threshold:
+                        original_idx = int(global_indices[idx])
+                        score_map[label]['similarity'] += sim
+                        score_map[label]['times'] += 1
+                        score_map[label]['source'] = 'knn'
+                        if score_map[label]['index'] is None:
+                            score_map[label]['index'] = original_idx
+            
+            timing['faiss'] += time.time() - t0
+
+            # Step 3: Add centroid-only predictions for classes without neighbors
+            t0 = time.time()
+            for label, sim in centroid_scores.items():
+                if label not in score_map:
+                    # Use actual centroid similarity instead of fixed fallback score
+                    centroid_sim = max(float(sim), self.centroid_fallback_score)
+                    score_map[label] = {
+                        'index': None, 
+                        'similarity': centroid_sim, 
+                        'times': 1,
+                        'source': 'knn'
+                    }
+            timing['aggregation'] += time.time() - t0
+
+            results.append(dict(score_map))
+
+        total_time = time.time() - start_time
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"Search completed in {total_time:.3f}s "
+                        f"(centroid: {timing['centroid']:.3f}s, "
+                        f"faiss: {timing['faiss']:.3f}s, "
+                        f"aggregation: {timing['aggregation']:.3f}s)")
+        
+        # Log performance metrics for production monitoring (only for larger batches)
+        if len(query_embeddings) > 5:
+            throughput = len(query_embeddings) / total_time if total_time > 0 else 0
+            logger.info(f"Batch search: {len(query_embeddings)} queries in {total_time:.3f}s "
+                       f"({throughput:.1f} queries/s)")
+        
+        return results
+    
+    def get_model_info(self) -> Dict:
+        """Return model configuration and statistics.
+        
+        Returns:
+            Dictionary with model information
+        """
+        info = {
+            'embedding_dim': self.dim,
+            'num_classes': len(self.keys),
+            'num_embeddings': len(self.db_embeddings),
+            'device': str(self.device),
+            'input_size': self.input_size,
+            'num_centroid_classes': len(self.centroid_labels) if self.use_knn else 0,
+            'inference_config': {
+                'use_knn': self.use_knn,
+                'arcface_min_score': self.arcface_min_score,
+                'centroid_fallback_score': self.centroid_fallback_score,
+                'topk_centroid': self.default_topk_centroid,
+                'topk_neighbors': self.default_topk_neighbors,
+                'topk_arcface': self.default_topk_arcface,
+                'centroid_threshold': self.default_centroid_threshold,
+                'neighbor_threshold': self.default_neighbor_threshold,
+            }
+        }
+        
+        if hasattr(self, 'model') and hasattr(self.model, 'backbone'):
+            info['backbone'] = self.model.backbone.__class__.__name__
+        
+        return info
+    
+    def warmup(self, num_iterations: int = DEFAULT_WARMUP_ITERATIONS) -> float:
+        """Warmup model with dummy data for stable performance.
+        
+        Args:
+            num_iterations: Number of warmup iterations
+            
+        Returns:
+            Average warmup time per iteration in seconds
+        """
+        logger.info(f"Warming up model with {num_iterations} iterations...")
+        dummy = torch.randn(1, 3, self.input_size, self.input_size).to(self.device)
+        
+        # Warmup iterations
+        times = []
+        for i in range(num_iterations):
+            start = time.time()
+            with torch.no_grad():
+                self.model(dummy, return_softmax=False)
+            times.append(time.time() - start)
+        
+        avg_time = np.mean(times)
+        logger.info(f"Warmup completed: avg={avg_time*1000:.2f}ms, "
+                   f"min={min(times)*1000:.2f}ms, max={max(times)*1000:.2f}ms")
+        return avg_time
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit with cleanup."""
+        self.cleanup()
+        return False  # Don't suppress exceptions
+    
+    def cleanup(self) -> None:
+        """Release resources and cleanup."""
+        logger.info("Cleaning up resources...")
+        
+        # Clear FAISS indices with error handling (only if kNN was enabled)
+        if self.use_knn and hasattr(self, 'class_indices'):
+            for label, data in self.class_indices.items():
+                try:
+                    if 'index' in data and data['index'] is not None:
+                        data['index'].reset()
+                except Exception as e:
+                    logger.warning(f"Failed to reset FAISS index for label {label}: {e}")
+            try:
+                self.class_indices.clear()
+            except Exception as e:
+                logger.warning(f"Failed to clear class_indices: {e}")
+        
+        # Move model to CPU and clear cache
+        if hasattr(self, 'model'):
+            try:
+                self.model.cpu()
+            except Exception as e:
+                logger.warning(f"Failed to move model to CPU: {e}")
+            
+            try:
+                if torch.cuda.is_available():
+                    torch.cuda.empty_cache()
+            except Exception as e:
+                logger.warning(f"Failed to empty CUDA cache: {e}")
+        
+        logger.info("Cleanup completed")
+    
+    def __del__(self):
+        """Destructor - logs warning if cleanup wasn't called.
+        
+        Note: Do not rely on __del__ for cleanup. Always use context manager
+        or explicitly call cleanup().
+        """
+        try:
+            # Check if resources are still allocated (only relevant if kNN was enabled)
+            if hasattr(self, 'use_knn') and self.use_knn:
+                if hasattr(self, 'class_indices') and self.class_indices:
+                    logger.warning("EmbeddingClassifier destroyed without cleanup(). "
+                                 "Use context manager or call cleanup() explicitly.")
+        except Exception:
+            # Silently ignore errors in destructor during interpreter shutdown
+            pass

classification_model/info.json

@@ -0,0 +1,12 @@
+{
+    "version": 10.0,
+    "num_of_class": 755,
+    "date": "29-01-2026",
+    "author": "Codahead@Andrew",
+    "database_size": 64445,
+    "samples_per_class": 100,
+    "val_samples": 18654,
+    "accuracy_arcface": 0.9498,
+    "accuracy_knn": 0.9552,
+    "top5_accuracy_arcface": 0.9922
+}

classification_model/model.ckpt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f562a378ac98328fed6847662d03963485ef3b46c6c0a67b6d1eaf469607b295
+size 346882574

classification_model/requirements.txt

@@ -0,0 +1,11 @@
+torch>=1.10.2
+torchvision>=0.11.3
+numpy>=1.19.2 
+opencv-python
+logging
+Pillow>=8.4.0
+faiss
+scipy
+joblib
+timm==1.0.15
+albumentations==2.0.8

detector/__MACOSX/._model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:27538dceef5d2857509477fa7ec98d74c1dc372523ca10a6069b25f530d05dfa
+size 641

detector/inference.py

@@ -0,0 +1,96 @@
+import time
+from typing import List, Tuple, Union
+
+import numpy as np
+import torch
+from ultralytics import YOLO
+
+logger = app_logger.getChild("models.detector.ultralytics")
+
+class YOLOInference(BaseInference):
+    def __init__(self, model_path: str, imsz: int = 640, 
+                 conf_threshold: float = 0.25, nms_threshold: float = 0.45, 
+                 device: str = "cpu"):
+        """
+        Initializing the YOLO class using the official Ultralytics SDK.
+        
+        Args:
+            model_path: Path to the model file (.pt, .onnx, or .torchscript).
+            imsz: Input image size for the model.
+            conf_threshold: Confidence threshold to filter out low-confidence boxes.
+            nms_threshold: IoU threshold for Non-Maximum Suppression.
+            device: Computing device ('cpu' or 'cuda').
+        """
+        super().__init__(config={"device": device})
+        
+        self.model_path = model_path
+        self.imsz = imsz
+        self.conf_threshold = conf_threshold
+        self.nms_threshold = nms_threshold
+        
+        self.load_model(model_path)
+
+    def load_model(self, model_path: str):
+        """
+        Loads the model into memory. Ultralytics handle various formats automatically.
+        """
+        logger.info(f"[load] Loading Ultralytics model from {model_path} on {self.device}")
+        # The YOLO class automatically handles weights and architecture configuration
+        self.model = YOLO(model_path)
+        self.model.to(self.device)
+
+    def predict(self, im_bgr: Union[np.ndarray, List[np.ndarray]]) -> List[List[YOLOResult]]:
+        """
+        Performs end-to-end inference including preprocessing, model forward pass, and NMS.
+
+        Args:
+            im_bgr: A single image or a list of images in BGR format (numpy arrays).
+
+        Returns:
+            A list of lists containing YOLOResult objects for each input image.
+        """
+        if isinstance(im_bgr, np.ndarray):
+            im_bgr = [im_bgr]
+            
+        start_time = time.time()
+        logger.debug(f"[infer] Starting detector inference on {len(im_bgr)} frame(s)")
+
+        final_results = []
+        
+        try:
+            # Ultralytics .predict() handles letterboxing, normalization, and NMS internally.
+            # It also automatically scales coordinates back to the original image size.
+            results = self.model.predict(
+                source=im_bgr,
+                imgsz=self.imsz,
+                conf=self.conf_threshold,
+                iou=self.nms_threshold,
+                device=self.device,
+                verbose=False,
+                save=False
+            )
+
+            for i, res in enumerate(results):
+                # res.boxes.data contains [x1, y1, x2, y2, confidence, class_id]
+                boxes_data = res.boxes.data.cpu().numpy()
+                
+                frame_results = []
+                for box in boxes_data:
+                    # box[:5] extract [x1, y1, x2, y2, confidence]
+                    # We pass the scaled coordinates and the original image to your YOLOResult wrapper
+                    frame_results.append(YOLOResult(box[:5], im_bgr[i]))
+                
+                final_results.append(frame_results)
+
+            return final_results
+
+        except Exception as e:
+            logger.error(f"Inference error occurred: {e}")
+            # Return empty lists to prevent the pipeline from breaking
+            return [[] for _ in range(len(im_bgr))]
+            
+        finally:
+            logger.info(
+                f"[infer] Detector inference completed in {(time.time() - start_time) * 1000:.2f} ms "
+                f"for {len(im_bgr)} frame(s)"
+            )

detector/info.json

@@ -0,0 +1,7 @@
+{
+    "version": 3,
+    "model": "YOLO26 nano",
+    "input_img_size": 640,
+    "date": "11-02-2025",
+    "author": "Codahead@Andrew"
+}

detector/model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5b786b334355fdb0c3faa9d375d70de24f3535ee6f11e9c3e26ec2e90810c03f
+size 131193007

requirements.txt

@@ -0,0 +1,18 @@
+# Web server
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+python-multipart>=0.0.9
+
+# ML / vision (already present in classification_model/requirements.txt)
+torch>=1.10.2
+torchvision>=0.11.3
+numpy>=1.19.2
+opencv-python
+Pillow>=8.4.0
+ultralytics
+faiss-cpu
+scipy
+scikit-learn
+timm==1.0.15
+shapely
+albumentations==2.0.8

segmentator/inference.py

@@ -0,0 +1,402 @@
+import time
+
+import cv2
+import numpy as np
+import torch
+import torch.nn.functional as F
+from PIL import Image
+from shapely.geometry import LinearRing, MultiPolygon, Polygon
+from torchvision import transforms
+
+        
+class Inference:
+    def __init__(self, model_path, image_size=416, threshold=0.5, poly_dict = True, max_points = 250):
+        self.model = torch.jit.load(model_path)
+        self.model.eval()
+        self.model.cpu()
+        
+        
+        self.max_points = max_points
+        self.IMAGE_SIZE = image_size
+        self.THRESHOLD = threshold
+        
+        self.loader = transforms.Compose([
+            transforms.Resize((self.IMAGE_SIZE, self.IMAGE_SIZE), Image.BILINEAR),
+            transforms.ToTensor(),
+            transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225])
+        ])
+
+    def preprocess(self, image: np.ndarray):
+        # Converting an image to a tensor and normalizing
+        pil_image = Image.fromarray(image)
+        input_tensor = self.loader(pil_image)
+        
+        return input_tensor
+    
+    def postprocess(self, logit, src_size):
+        height, width = src_size
+        #(1, img_size, img_size) -> (img_size, img_size)
+        pr_mask = logit[0].numpy()
+        pr_mask = resize_logits_mask_pil(pr_mask, width, height)
+        pr_mask = pr_mask > self.THRESHOLD
+        contours = bitmap_to_polygon(pr_mask)
+        poly, valid_state = full_fix_contour(contours)
+        poly = poly.astype(int)
+
+        return poly, valid_state
+
+    def predict(self, images):
+        # Checking the type of the input argument and casting to a list
+        if isinstance(images, np.ndarray):
+            images = [images]
+           
+        #insurance in case you somehow end up with an empty list
+        if len(images) == 0: return []
+        
+        # Preprocessing images and saving their sizes
+        _input = [self.preprocess(image) for image in images]
+        src_sizes = [image.shape[:2] for image in images] # HEIGHT - WIDTH
+        
+        _input = torch.stack(_input)
+        
+        # Processing a batch of images
+        return self.predict_batch(_input, src_sizes)
+    
+
+    def predict_batch(self, _input, src_sizes):
+        results = []
+        start_time = time.time()
+        
+        with torch.no_grad():
+            logits = self.model(_input).sigmoid()
+
+        for idx, src_size in enumerate(src_sizes):
+            logit = logits[idx]
+            poly, valid_state = self.postprocess(logit, src_size)
+            
+            if len(poly) != 0:
+                poly = approximate_to_max_point_cnt(poly, max_points=self.max_points)
+            else:
+                poly = [(0,0), (src_size[1],0), (src_size[1], src_size[0]), (0, src_size[0]), (0,0)]
+                
+            results.append(FishPolygon(poly))
+            
+            duration = time.time() - start_time
+
+        return results
+    
+    
+def bitmap_to_polygon(bitmap):
+    """Convert masks from the form of bitmaps to polygons.
+
+    Args:
+        bitmap (ndarray): masks in bitmap representation.
+
+    Return:
+        list[ndarray]: the converted mask in polygon representation.
+        bool: whether the mask has holes.
+    """
+    bitmap = np.ascontiguousarray(bitmap).astype(np.uint8)
+    # cv2.RETR_CCOMP: retrieves all of the contours and organizes them
+    #   into a two-level hierarchy. At the top level, there are external
+    #   boundaries of the components. At the second level, there are
+    #   boundaries of the holes. If there is another contour inside a hole
+    #   of a connected component, it is still put at the top level.
+    # cv2.CHAIN_APPROX_NONE: stores absolutely all the contour points.
+    outs = cv2.findContours(bitmap, cv2.RETR_CCOMP, cv2.CHAIN_APPROX_NONE)
+    contours = outs[-2]
+    hierarchy = outs[-1]
+    if hierarchy is None:
+        return [], False
+    # hierarchy[i]: 4 elements, for the indexes of next, previous,
+    # parent, or nested contours. If there is no corresponding contour,
+    # it will be -1.
+    contours = [c.reshape(-1, 2) for c in contours]
+    return sorted(contours, key=len, reverse = True)
+
+def poly_array_to_dict(polygon):
+    """
+    Converts an array of polygon points into a dictionary with labeled coordinates.
+
+    Args:
+        polygon (ndarray): An array of points representing the polygon. Each point is an array [x, y].
+
+    Returns:
+        dict: A dictionary where keys are labeled coordinates ('x1', 'y1', 'x2', 'y2', etc.) 
+              and values are the corresponding x and y coordinates from the input array.
+    """
+    polygons_dict = {}
+    
+    for i, point in enumerate(polygon):
+        # Add x coordinate with label 'x{i+1}'
+        polygons_dict[f"x{i + 1}"] = int(point[0])
+        
+        # Add y coordinate with label 'y{i+1}'
+        polygons_dict[f"y{i + 1}"] = int(point[1])
+    
+    return polygons_dict
+
+def is_contour_valid(contour):
+    """
+    Checks if a contour is valid (i.e., its lines do not intersect).
+
+    Args:
+        contour (ndarray): The contour represented as an array of points.
+
+    Returns:
+        bool: True if the contour is valid, False otherwise.
+    """
+    if len(contour) < 3:
+        # A contour must contain at least three points to be a polygon
+        return False
+    
+    polygon = Polygon(contour)
+    
+    # Check for self-intersection
+    if not polygon.is_valid:
+        return False
+    
+    # Check for intersection between the start and end points (to close the contour)
+    ring = LinearRing(contour)
+    if not ring.is_simple:
+        return False
+    
+    return True
+
+def fix_contour(contour):
+    """
+    Fixes a damaged contour (removes self-intersections).
+
+    Args:
+        contour (ndarray): The contour represented as an array of points.
+
+    Returns:
+        ndarray: The fixed contour.
+    """
+    polygon = Polygon(contour)
+    if polygon.is_valid:
+        return contour
+    
+    # Fix the contour using buffer(0)
+    fixed_polygon = polygon.buffer(0)
+    
+    if fixed_polygon.is_empty:
+        return np.array([])  # Return an empty array if the contour cannot be fixed
+    
+    # Check the type of the returned object
+    if isinstance(fixed_polygon, Polygon):
+        fixed_contour = np.array(fixed_polygon.exterior.coords)
+    elif isinstance(fixed_polygon, MultiPolygon):
+        # If it's a MultiPolygon, choose the polygon with the largest area
+        largest_polygon = max(fixed_polygon.geoms, key=lambda p: p.area)
+        fixed_contour = np.array(largest_polygon.exterior.coords)
+
+    return fixed_contour
+
+def full_fix_contour(poly):
+    """
+    Attempts to validate and fix a polygon contour. If the contour is valid, it returns the contour.
+    If the contour is invalid, it tries to fix it. If the fix is successful, it returns the fixed contour.
+
+    Args:
+        poly (ndarray): An array of polygons, where each polygon is represented as an array of points.
+
+    Returns:
+        tuple: A tuple containing the following:
+            - ndarray: The valid or fixed contour. If the contour cannot be fixed, an empty array is returned.
+            - str: A message indicating the status of the contour ("Empty Contour", "Fixed Contour", or "Can't fix").
+    """
+    if len(poly) == 0 or len(poly[0]) < 10:
+        return [], "Empty Contour"
+    
+    contour = poly[0]
+    
+    # Check the validity of the contour
+    if is_contour_valid(contour):
+        return contour, None
+    else:
+        # Attempt to fix the contour
+        fixed_contour = fix_contour(contour)
+        if fixed_contour.size > 0 and is_contour_valid(fixed_contour):
+            return fixed_contour, "Fixed Contour"
+        else:
+            return [], "Can't fix"
+
+def resize_logits_mask_pil(logits_mask, width, height):
+    """
+    Resize a logits mask to the specified output shape using PIL.
+
+    Parameters:
+        logits_mask (np.array): Input logits mask.
+        width (int): Desired width of the output shape.
+        height (int): Desired height of the output shape.
+
+    Returns:
+        np.array: Resized logits mask.
+    """
+    # Convert logits mask to float32 for PIL compatibility
+    mask_float32 = logits_mask.astype(np.float32)
+    
+    # Create PIL image from the numpy array
+    pil_image = Image.fromarray(mask_float32)
+    
+    # Resize the image
+    resized_pil_image = pil_image.resize((width, height), Image.BILINEAR)
+    
+    # Convert back to numpy array
+    resized_mask = np.array(resized_pil_image)
+    
+    return resized_mask
+
+def approximate_to_max_point_cnt(poly, epsilon=0.08, max_points = 400):
+    while(True):
+        approximations = cv2.approxPolyDP(poly, epsilon, False)
+        
+        if len(approximations) > max_points:
+            epsilon += 0.05 
+        else:
+            break
+    approximations = np.reshape(approximations, (-1, 2))
+    return approximations
+
+def convert_local_polygons_to_global(outputs, list_of_boxes):
+    for box_id, box in enumerate(list_of_boxes):
+        x, y = box[:2]
+        outputs[box_id] = [(point[0] + x, point[1] + y) for point in outputs[box_id]]
+        
+        
+class FishPolygon:
+    def __init__(self, points):
+        """
+        Initializes the Polygon.
+        
+        Args:
+            points (list): List of tuples representing the polygon points.
+        """
+        self.points = points
+        self.width, self.height = self.calculate_dimensions()
+    
+    def calculate_dimensions(self):
+        """
+        Calculates the width and height of the polygon's bounding box.
+        
+        Returns:
+            tuple: Width and height of the polygon's bounding box.
+        """
+        x_coords = [p[0] for p in self.points]
+        y_coords = [p[1] for p in self.points]
+        width = max(x_coords) - min(x_coords)
+        height = max(y_coords) - min(y_coords)
+        return width, height
+
+    def get_area(self):
+        """
+        Calculates the area of the polygon using the Shoelace formula.
+        
+        Returns:
+            float: Area of the polygon.
+        """
+        x = [p[0] for p in self.points]
+        y = [p[1] for p in self.points]
+        return 0.5 * abs(sum(x[i] * y[i+1] - y[i] * x[i+1] for i in range(-1, len(self.points)-1)))
+    
+    def get_centroid(self):
+        """
+        Calculates the centroid of the polygon.
+        
+        Returns:
+            tuple: Coordinates of the centroid (x, y).
+        """
+        x = [p[0] for p in self.points]
+        y = [p[1] for p in self.points]
+        area = self.get_area()
+        cx = sum((x[i] + x[i+1]) * (x[i] * y[i+1] - x[i+1] * y[i]) for i in range(-1, len(self.points)-1)) / (6 * area)
+        cy = sum((y[i] + y[i+1]) * (x[i] * y[i+1] - x[i+1] * y[i]) for i in range(-1, len(self.points)-1)) / (6 * area)
+        return (cx, cy)
+    
+    def draw_polygon(self, image, color=(0, 255, 0), thickness=2):
+        """
+        Draws the polygon on the image.
+        
+        Args:
+            image (numpy.ndarray): Image on which the polygon will be drawn.
+            color (tuple): Color of the polygon in (B, G, R) format.
+            thickness (int): Thickness of the polygon lines.
+        """
+        pts = np.array(self.points, np.int32)
+        pts = pts.reshape((-1, 1, 2))
+        cv2.polylines(image, [pts], isClosed=True, color=color, thickness=thickness)
+    
+    def get_mask(self):
+        """
+        Creates a mask for the polygon.
+        
+        Args:
+            image_shape (tuple): Shape of the image (height, width).
+        
+        Returns:
+            numpy.ndarray: Mask of the polygon.
+        """
+        mask = np.zeros((self.height, self.width), dtype=np.uint8)
+        pts = np.array(self.points, np.int32)
+        pts = pts.reshape((-1, 1, 2))
+        cv2.fillPoly(mask, [pts], 255)
+        return mask
+    
+    def mask_polygon(self, image):
+        """
+        Applies a mask to the polygon on the image.
+        
+        Args:
+            image (numpy.ndarray): Image on which the mask will be applied.
+        
+        Returns:
+            numpy.ndarray: Image with the polygon area masked.
+        """
+        mask = np.zeros_like(image)
+        pts = np.array(self.points, dtype=np.int32)
+        cv2.fillPoly(mask, [pts], (255, 255, 255))
+        masked_image = cv2.bitwise_and(image, mask)
+        return masked_image
+    
+    def move_to(self, x, y):
+        """
+        Moves the polygon to a new point (x, y).
+        
+        Args:
+            x (float): The x-coordinate of the new point.
+            y (float): The y-coordinate of the new point.
+        """
+        self.points = [(px + x, py + y) for px, py in self.points]
+        self.width, self.height = self.calculate_dimensions()
+    
+    def to_points_dict(self):
+        """
+        Converts the polygon points to a dictionary format.
+        
+        Returns:
+            dict: Dictionary with keys as 'x1', 'y1', 'x2', 'y2', etc.
+        """
+        points_dict = {}
+        for i, (x, y) in enumerate(self.points, start=1):
+            points_dict[f'x{i}'] = x
+            points_dict[f'y{i}'] = y
+        return points_dict
+    
+    def __repr__(self):
+        return f"Polygon(points={self.points}, width={self.width}, height={self.height})"
+    
+    def to_dict(self):
+        """
+        Converts the object to a dictionary.
+        
+        Returns:
+            dict: Dictionary with the key 'points'.
+        """
+        return {
+            'points': self.points,
+            'width': self.width,
+            'height': self.height,
+            'area': self.get_area(),
+            'centroid': self.get_centroid()
+        }

segmentator/info.json

@@ -0,0 +1,7 @@
+{
+    "version": 1,
+    "model": "FPN_resnet_18",
+    "input_img_size": 416,
+    "date": "31-07-2024",
+    "author": "Codahead@Andrew"
+}

segmentator/model.ts

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b1ef999b2096905b217a5bcd61801d5d3e6f9141ab141d68c85be5429f559f2e
+size 52491755

static/index.html

@@ -0,0 +1,707 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>SW — Fish Identifier</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --bg:      #0f1117;
+      --surface: #1a1d27;
+      --border:  #2d3147;
+      --accent:  #3b82f6;
+      --accent2: #10b981;
+      --warn:    #f59e0b;
+      --text:    #e2e8f0;
+      --muted:   #64748b;
+      --radius:  12px;
+      --shadow:  0 4px 24px rgba(0,0,0,.45);
+    }
+
+    body {
+      background: var(--bg);
+      color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      min-height: 100vh;
+      display: flex;
+      flex-direction: column;
+    }
+
+    header {
+      padding: 1rem 1.5rem;
+      border-bottom: 1px solid var(--border);
+      display: flex;
+      align-items: center;
+      gap: .75rem;
+      background: var(--surface);
+    }
+    header h1 {
+      font-size: 1.2rem;
+      font-weight: 700;
+      letter-spacing: -.02em;
+    }
+    header .badge {
+      font-size: .7rem;
+      background: var(--accent);
+      color: #fff;
+      border-radius: 4px;
+      padding: 2px 6px;
+      text-transform: uppercase;
+      letter-spacing: .06em;
+    }
+
+    main {
+      flex: 1;
+      display: grid;
+      grid-template-columns: 1fr 360px;
+      gap: 1rem;
+      padding: 1rem;
+      max-width: 1400px;
+      width: 100%;
+      margin: 0 auto;
+    }
+
+    /* ── Drop / canvas panel ── */
+    .canvas-panel {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      overflow: hidden;
+      position: relative;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 480px;
+    }
+
+    #drop-zone {
+      position: absolute;
+      inset: 0;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      gap: 1rem;
+      cursor: pointer;
+      transition: background .2s;
+      z-index: 1;
+    }
+    #drop-zone.drag-over { background: rgba(59,130,246,.08); }
+    #drop-zone.hidden    { display: none; }
+
+    .drop-icon {
+      width: 72px;
+      height: 72px;
+      border-radius: 50%;
+      background: rgba(59,130,246,.12);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .drop-icon svg { color: var(--accent); }
+
+    #drop-zone p   { color: var(--muted); font-size: .9rem; }
+    #drop-zone b   { color: var(--text); }
+
+    #file-input { display: none; }
+
+    /* canvas lives here */
+    #canvas-wrap {
+      position: relative;
+      display: none;
+      width: 100%;
+      height: 100%;
+    }
+    #canvas-wrap.visible { display: block; }
+
+    #base-canvas, #overlay-canvas {
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      transform: translate(-50%, -50%);
+    }
+    #overlay-canvas { pointer-events: none; }
+
+    .canvas-toolbar {
+      position: absolute;
+      top: .75rem;
+      right: .75rem;
+      display: flex;
+      gap: .5rem;
+      z-index: 10;
+    }
+    .canvas-toolbar button {
+      padding: .35rem .75rem;
+      border-radius: 6px;
+      border: 1px solid var(--border);
+      background: rgba(15,17,23,.8);
+      color: var(--text);
+      font-size: .8rem;
+      cursor: pointer;
+      backdrop-filter: blur(4px);
+      transition: border-color .15s;
+    }
+    .canvas-toolbar button:hover { border-color: var(--accent); }
+
+    /* ── Spinner overlay ── */
+    #spinner {
+      position: absolute;
+      inset: 0;
+      background: rgba(15,17,23,.7);
+      display: none;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      gap: 1rem;
+      z-index: 20;
+      border-radius: var(--radius);
+    }
+    #spinner.active { display: flex; }
+    .spin-ring {
+      width: 48px;
+      height: 48px;
+      border: 3px solid var(--border);
+      border-top-color: var(--accent);
+      border-radius: 50%;
+      animation: spin .8s linear infinite;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+
+    /* ── Results panel ── */
+    .results-panel {
+      display: flex;
+      flex-direction: column;
+      gap: .75rem;
+      overflow-y: auto;
+      max-height: calc(100vh - 100px);
+    }
+
+    .results-header {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: .75rem 1rem;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+    .results-header h2 { font-size: .95rem; font-weight: 600; }
+
+    .timing-bar {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: .65rem 1rem;
+      display: none;
+      gap: 1rem;
+      flex-wrap: wrap;
+    }
+    .timing-bar.visible { display: flex; }
+    .timing-item { display: flex; flex-direction: column; gap: 2px; }
+    .timing-label { font-size: .65rem; color: var(--muted); text-transform: uppercase; letter-spacing: .06em; }
+    .timing-value { font-size: .85rem; font-weight: 600; font-variant-numeric: tabular-nums; }
+
+    .no-results {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: 2rem 1rem;
+      text-align: center;
+      color: var(--muted);
+      font-size: .9rem;
+    }
+
+    .fish-card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      overflow: hidden;
+      transition: border-color .15s;
+    }
+    .fish-card:hover        { border-color: var(--accent); }
+    .fish-card.highlighted  { border-color: var(--accent2); }
+
+    .fish-card-header {
+      padding: .6rem .9rem;
+      display: flex;
+      align-items: center;
+      gap: .5rem;
+      cursor: pointer;
+      background: rgba(255,255,255,.02);
+    }
+    .fish-number {
+      width: 22px;
+      height: 22px;
+      border-radius: 50%;
+      background: var(--accent);
+      color: #fff;
+      font-size: .7rem;
+      font-weight: 700;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      flex-shrink: 0;
+    }
+    .fish-card-header h3 { font-size: .85rem; font-weight: 600; flex: 1; }
+    .conf-badge {
+      font-size: .7rem;
+      padding: 2px 6px;
+      border-radius: 4px;
+      background: rgba(59,130,246,.15);
+      color: var(--accent);
+    }
+
+    .fish-card-body { padding: .6rem .9rem .9rem; }
+
+    .prediction-row {
+      display: flex;
+      align-items: center;
+      gap: .5rem;
+      padding: .4rem 0;
+      border-bottom: 1px solid var(--border);
+    }
+    .prediction-row:last-child { border-bottom: none; }
+
+    .pred-rank {
+      width: 16px;
+      font-size: .7rem;
+      color: var(--muted);
+      text-align: center;
+      flex-shrink: 0;
+    }
+    .pred-name { flex: 1; font-size: .83rem; display: flex; flex-direction: column; gap: 1px; }
+    .pred-taxon { font-size: .7rem; color: var(--muted); font-style: italic; }
+    .pred-bar-wrap { width: 72px; background: var(--bg); border-radius: 4px; height: 6px; flex-shrink: 0; }
+    .pred-bar { height: 100%; border-radius: 4px; background: var(--accent2); }
+    .pred-pct { font-size: .75rem; color: var(--muted); width: 38px; text-align: right; flex-shrink: 0; }
+
+    .bbox-info {
+      margin-top: .5rem;
+      font-size: .72rem;
+      color: var(--muted);
+    }
+
+    /* Legend */
+    .legend {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: .65rem 1rem;
+      display: flex;
+      gap: 1rem;
+      align-items: center;
+      font-size: .78rem;
+      color: var(--muted);
+      flex-wrap: wrap;
+    }
+    .legend-item { display: flex; align-items: center; gap: .4rem; }
+    .legend-swatch { width: 14px; height: 4px; border-radius: 2px; }
+
+    @media (max-width: 800px) {
+      main { grid-template-columns: 1fr; }
+      .results-panel { max-height: none; }
+    }
+  </style>
+</head>
+<body>
+
+<header>
+  <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#3b82f6" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M6.5 12c.94-3.46 4.94-6 10.5-6s9.56 2.54 10.5 6c-.94 3.46-4.94 6-10.5 6S7.44 15.46 6.5 12z"/>
+    <circle cx="17" cy="12" r="2"/>
+  </svg>
+  <h1>SW Identifier</h1>
+  <span class="badge">Fish ID</span>
+</header>
+
+<main>
+  <!-- ── Left: canvas ── -->
+  <div class="canvas-panel" id="canvas-panel">
+    <div id="drop-zone">
+      <div class="drop-icon">
+        <svg width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+          <polyline points="16 16 12 12 8 16"/>
+          <line x1="12" y1="12" x2="12" y2="21"/>
+          <path d="M20.39 18.39A5 5 0 0 0 18 9h-1.26A8 8 0 1 0 3 16.3"/>
+        </svg>
+      </div>
+      <p><b>Drop an image</b> here or <b id="browse-link" style="color:var(--accent);cursor:pointer">browse</b></p>
+      <p>JPG, PNG, WEBP — any resolution</p>
+    </div>
+
+    <div id="canvas-wrap">
+      <canvas id="base-canvas"></canvas>
+      <canvas id="overlay-canvas"></canvas>
+      <div class="canvas-toolbar">
+        <button id="toggle-overlay" title="Toggle detection overlay">Overlay</button>
+        <button id="new-image-btn">New image</button>
+      </div>
+    </div>
+
+    <div id="spinner">
+      <div class="spin-ring"></div>
+      <span style="color:var(--muted);font-size:.85rem">Analysing…</span>
+    </div>
+  </div>
+
+  <!-- ── Right: results ── -->
+  <div class="results-panel">
+    <div class="results-header">
+      <h2>Detections</h2>
+      <span id="detection-count" style="font-size:.8rem;color:var(--muted)">—</span>
+    </div>
+
+    <div class="timing-bar" id="timing-bar">
+      <div class="timing-item">
+        <span class="timing-label">Detect</span>
+        <span class="timing-value" id="t-detect">—</span>
+      </div>
+      <div class="timing-item">
+        <span class="timing-label">Segment</span>
+        <span class="timing-value" id="t-segment">—</span>
+      </div>
+      <div class="timing-item">
+        <span class="timing-label">Classify</span>
+        <span class="timing-value" id="t-classify">—</span>
+      </div>
+      <div class="timing-item">
+        <span class="timing-label">Total</span>
+        <span class="timing-value" id="t-total">—</span>
+      </div>
+    </div>
+
+    <div id="results-body">
+      <div class="no-results">Drop an image to begin</div>
+    </div>
+
+    <div class="legend" id="legend" style="display:none">
+      <div class="legend-item">
+        <div class="legend-swatch" style="background:#3b82f6;height:2px;border:1px solid #3b82f6"></div>
+        Bounding box
+      </div>
+      <div class="legend-item">
+        <div class="legend-swatch" style="background:rgba(16,185,129,.5)"></div>
+        Segmentation
+      </div>
+    </div>
+  </div>
+</main>
+
+<input type="file" id="file-input" accept="image/*" />
+
+<script>
+(() => {
+  const dropZone   = document.getElementById('drop-zone');
+  const canvasWrap = document.getElementById('canvas-wrap');
+  const baseCanvas = document.getElementById('base-canvas');
+  const overlayCanvas = document.getElementById('overlay-canvas');
+  const spinner    = document.getElementById('spinner');
+  const fileInput  = document.getElementById('file-input');
+  const resultsBody = document.getElementById('results-body');
+  const timingBar  = document.getElementById('timing-bar');
+  const countEl    = document.getElementById('detection-count');
+  const legend     = document.getElementById('legend');
+  const panel      = document.getElementById('canvas-panel');
+
+  const baseCtx    = baseCanvas.getContext('2d');
+  const overlayCtx = overlayCanvas.getContext('2d');
+
+  let currentDetections = [];
+  let overlayVisible = true;
+  let imgNaturalW = 0, imgNaturalH = 0;
+  let displayW = 0, displayH = 0;
+  let scaleX = 1, scaleY = 1;
+
+  // ── Drag & drop ──────────────────────────────────────────────────────────
+  dropZone.addEventListener('dragover', e => {
+    e.preventDefault();
+    dropZone.classList.add('drag-over');
+  });
+  dropZone.addEventListener('dragleave', () => dropZone.classList.remove('drag-over'));
+  dropZone.addEventListener('drop', e => {
+    e.preventDefault();
+    dropZone.classList.remove('drag-over');
+    const file = e.dataTransfer.files[0];
+    if (file && file.type.startsWith('image/')) processFile(file);
+  });
+
+  document.getElementById('browse-link').addEventListener('click', () => fileInput.click());
+  dropZone.addEventListener('click', () => fileInput.click());
+  fileInput.addEventListener('change', () => {
+    if (fileInput.files[0]) processFile(fileInput.files[0]);
+  });
+
+  document.getElementById('toggle-overlay').addEventListener('click', () => {
+    overlayVisible = !overlayVisible;
+    overlayCanvas.style.display = overlayVisible ? '' : 'none';
+  });
+
+  document.getElementById('new-image-btn').addEventListener('click', reset);
+
+  // Paste support
+  document.addEventListener('paste', e => {
+    const items = e.clipboardData?.items;
+    if (!items) return;
+    for (const item of items) {
+      if (item.type.startsWith('image/')) {
+        processFile(item.getAsFile());
+        break;
+      }
+    }
+  });
+
+  // ── Core flow ─────────────────────────────────────────────────────────────
+  async function processFile(file) {
+    reset();
+    const objectUrl = URL.createObjectURL(file);
+    const img = new Image();
+    img.onload = async () => {
+      renderImage(img);
+      URL.revokeObjectURL(objectUrl);
+      await runPipeline(file);
+    };
+    img.src = objectUrl;
+  }
+
+  function renderImage(img) {
+    imgNaturalW = img.naturalWidth;
+    imgNaturalH = img.naturalHeight;
+
+    // Fit image into panel keeping aspect ratio
+    const panelW = panel.clientWidth  - 2;  // minus borders
+    const panelH = panel.clientHeight - 2;
+    const ratio  = Math.min(panelW / imgNaturalW, panelH / imgNaturalH, 1);
+    displayW = Math.round(imgNaturalW * ratio);
+    displayH = Math.round(imgNaturalH * ratio);
+    scaleX = displayW / imgNaturalW;
+    scaleY = displayH / imgNaturalH;
+
+    for (const c of [baseCanvas, overlayCanvas]) {
+      c.width  = displayW;
+      c.height = displayH;
+      c.style.width  = displayW + 'px';
+      c.style.height = displayH + 'px';
+    }
+
+    baseCtx.drawImage(img, 0, 0, displayW, displayH);
+    dropZone.classList.add('hidden');
+    canvasWrap.classList.add('visible');
+  }
+
+  async function runPipeline(file) {
+    spinner.classList.add('active');
+
+    const form = new FormData();
+    form.append('file', file);
+
+    try {
+      const resp = await fetch('/predict', { method: 'POST', body: form });
+      if (!resp.ok) {
+        const err = await resp.json().catch(() => ({ detail: resp.statusText }));
+        throw new Error(err.detail || resp.statusText);
+      }
+      const data = await resp.json();
+      currentDetections = data.detections;
+      renderOverlay(data.detections);
+      renderResults(data);
+    } catch (err) {
+      resultsBody.innerHTML = `<div class="no-results" style="color:#f87171">Error: ${err.message}</div>`;
+    } finally {
+      spinner.classList.remove('active');
+    }
+  }
+
+  // ── Canvas overlay ────────────────────────────────────────────────────────
+  function renderOverlay(detections) {
+    overlayCtx.clearRect(0, 0, overlayCanvas.width, overlayCanvas.height);
+
+    detections.forEach((det, idx) => {
+      const { bbox, polygon } = det;
+      const color = hue(idx);
+
+      // Segmentation polygon fill
+      if (polygon && polygon.length > 2) {
+        overlayCtx.beginPath();
+        overlayCtx.moveTo(polygon[0][0] * scaleX, polygon[0][1] * scaleY);
+        for (let i = 1; i < polygon.length; i++) {
+          overlayCtx.lineTo(polygon[i][0] * scaleX, polygon[i][1] * scaleY);
+        }
+        overlayCtx.closePath();
+        overlayCtx.fillStyle = color.fill;
+        overlayCtx.fill();
+        overlayCtx.strokeStyle = color.stroke;
+        overlayCtx.lineWidth = 1.5;
+        overlayCtx.stroke();
+      }
+
+      // Bounding box
+      const bx1 = bbox.x1 * scaleX;
+      const by1 = bbox.y1 * scaleY;
+      const bw  = (bbox.x2 - bbox.x1) * scaleX;
+      const bh  = (bbox.y2 - bbox.y1) * scaleY;
+
+      overlayCtx.strokeStyle = '#3b82f6';
+      overlayCtx.lineWidth = 2;
+      overlayCtx.strokeRect(bx1, by1, bw, bh);
+
+      // Label chip
+      const topName  = det.predictions[0]?.name || '?';
+      const topConf  = det.predictions[0]?.accuracy ?? 0;
+      const label    = `#${idx + 1} ${topName} ${(topConf * 100).toFixed(0)}%`;
+      const fontSize = Math.max(10, Math.round(11 * Math.min(scaleX, scaleY)));
+      overlayCtx.font = `600 ${fontSize}px -apple-system, sans-serif`;
+      const tw = overlayCtx.measureText(label).width;
+      const pad = 4;
+      const chipH = fontSize + pad * 2;
+      const chipY = Math.max(0, by1 - chipH - 2);
+
+      overlayCtx.fillStyle = '#3b82f6';
+      roundRect(overlayCtx, bx1, chipY, tw + pad * 2, chipH, 4);
+      overlayCtx.fill();
+
+      overlayCtx.fillStyle = '#fff';
+      overlayCtx.fillText(label, bx1 + pad, chipY + chipH - pad - 1);
+    });
+  }
+
+  function roundRect(ctx, x, y, w, h, r) {
+    ctx.beginPath();
+    ctx.moveTo(x + r, y);
+    ctx.lineTo(x + w - r, y);
+    ctx.quadraticCurveTo(x + w, y, x + w, y + r);
+    ctx.lineTo(x + w, y + h - r);
+    ctx.quadraticCurveTo(x + w, y + h, x + w - r, y + h);
+    ctx.lineTo(x + r, y + h);
+    ctx.quadraticCurveTo(x, y + h, x, y + h - r);
+    ctx.lineTo(x, y + r);
+    ctx.quadraticCurveTo(x, y, x + r, y);
+    ctx.closePath();
+  }
+
+  const PALETTE = [
+    { fill: 'rgba(16,185,129,.25)',  stroke: '#10b981' },
+    { fill: 'rgba(245,158,11,.25)',  stroke: '#f59e0b' },
+    { fill: 'rgba(239,68,68,.25)',   stroke: '#ef4444' },
+    { fill: 'rgba(168,85,247,.25)',  stroke: '#a855f7' },
+    { fill: 'rgba(236,72,153,.25)',  stroke: '#ec4899' },
+  ];
+  function hue(i) { return PALETTE[i % PALETTE.length]; }
+
+  // ── Results panel ─────────────────────────────────────────────────────────
+  function renderResults(data) {
+    const { detections, timing } = data;
+
+    // Timing bar
+    document.getElementById('t-detect').textContent   = timing.detect_ms   + ' ms';
+    document.getElementById('t-segment').textContent  = timing.segment_ms  + ' ms';
+    document.getElementById('t-classify').textContent = timing.classify_ms + ' ms';
+    document.getElementById('t-total').textContent    = timing.total_ms    + ' ms';
+    timingBar.classList.add('visible');
+
+    countEl.textContent = detections.length
+      ? `${detections.length} fish found`
+      : 'No fish detected';
+
+    legend.style.display = detections.length ? '' : 'none';
+
+    if (!detections.length) {
+      resultsBody.innerHTML = '<div class="no-results">No fish detected in this image</div>';
+      return;
+    }
+
+    resultsBody.innerHTML = '';
+    detections.forEach((det, idx) => {
+      const card = document.createElement('div');
+      card.className = 'fish-card';
+      card.dataset.idx = idx;
+
+      const topName = det.predictions[0]?.name || 'Unknown';
+      const detConf = (det.bbox.confidence * 100).toFixed(0);
+
+      card.innerHTML = `
+        <div class="fish-card-header">
+          <div class="fish-number">${idx + 1}</div>
+          <h3>${esc(topName)}</h3>
+          <span class="conf-badge">det ${detConf}%</span>
+        </div>
+        <div class="fish-card-body">
+          ${det.predictions.length
+            ? det.predictions.map((p, r) => predRow(p, r)).join('')
+            : '<span style="color:var(--muted);font-size:.8rem">No classification</span>'
+          }
+          <div class="bbox-info">
+            Box: ${det.bbox.x1},${det.bbox.y1} → ${det.bbox.x2},${det.bbox.y2}
+            &nbsp;·&nbsp;
+            ${det.bbox.x2 - det.bbox.x1}×${det.bbox.y2 - det.bbox.y1} px
+            ${det.polygon ? '&nbsp;·&nbsp;seg ✓' : ''}
+          </div>
+        </div>`;
+
+      card.querySelector('.fish-card-header').addEventListener('mouseenter', () => {
+        card.classList.add('highlighted');
+        highlightDetection(idx);
+      });
+      card.querySelector('.fish-card-header').addEventListener('mouseleave', () => {
+        card.classList.remove('highlighted');
+        renderOverlay(currentDetections);
+      });
+
+      resultsBody.appendChild(card);
+    });
+  }
+
+  function predRow(p, rank) {
+    const pct = (p.accuracy * 100).toFixed(1);
+    const bar = Math.round(p.accuracy * 100);
+    return `<div class="prediction-row">
+      <span class="pred-rank">${rank + 1}</span>
+      <span class="pred-name">${esc(p.name)}<span class="pred-taxon">${esc(p.taxon)}</span></span>
+      <div class="pred-bar-wrap"><div class="pred-bar" style="width:${bar}%"></div></div>
+      <span class="pred-pct">${pct}%</span>
+    </div>`;
+  }
+
+  function highlightDetection(idx) {
+    renderOverlay(currentDetections);
+    // draw a brighter ring around the selected detection
+    const det = currentDetections[idx];
+    if (!det) return;
+    const { bbox } = det;
+    overlayCtx.strokeStyle = '#facc15';
+    overlayCtx.lineWidth = 3;
+    overlayCtx.strokeRect(
+      bbox.x1 * scaleX - 2,
+      bbox.y1 * scaleY - 2,
+      (bbox.x2 - bbox.x1) * scaleX + 4,
+      (bbox.y2 - bbox.y1) * scaleY + 4,
+    );
+  }
+
+  function reset() {
+    currentDetections = [];
+    overlayVisible = true;
+    overlayCanvas.style.display = '';
+    overlayCtx.clearRect(0, 0, overlayCanvas.width, overlayCanvas.height);
+    baseCtx.clearRect(0, 0, baseCanvas.width, baseCanvas.height);
+    canvasWrap.classList.remove('visible');
+    dropZone.classList.remove('hidden');
+    resultsBody.innerHTML = '<div class="no-results">Drop an image to begin</div>';
+    timingBar.classList.remove('visible');
+    countEl.textContent = '—';
+    legend.style.display = 'none';
+    fileInput.value = '';
+  }
+
+  function esc(s) {
+    return String(s)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+})();
+</script>
+</body>
+</html>

taxons.csv

@@ -0,0 +1,776 @@
+common_name,taxon
+Flat needlefish,Ablennes hians
+Bream,Abramis brama
+Sergeant major,Abudefduf saxatilis
+Blackspot sergeant,Abudefduf sordidus
+Mud sunfish,Acantharchus pomotis
+white-cheeked blenny,Acanthemblemaria johnsoni
+Spinyhead blenny,Acanthemblemaria spinosa
+Wahoo,Acanthocybium solandri
+Australian sea bream,Acanthopagrus australis
+Bream,Acanthopagrus butcheri
+Yellowfin seabream,Acanthopagrus latus
+Scrawled cowfish,Acanthostracion quadricornis
+Doctorfish,Acanthurus chirurgus
+blue tang,Acanthurus coeruleus
+Palani,Acanthurus dussumieri
+Eastern Blue Groper,Achoerodus viridis
+lake sturgeon,Acipenser fulvescens
+European sturgeon,Acipenser sturio
+white sturgeon,Acipenser transmontanus
+Lesser guitarfish,Acroteriobatus annulatus
+Spotted eagle ray,Aetobatus narinari
+Bonefish,Albula vulpes
+Bleak,Alburnus alburnus
+Yellow-eye mullet,Aldrichetta forsteri
+African pompano,Alectis ciliaris
+Thresher shark,Alopias vulpinus
+Skipjack herring,Alosa chrysochloris
+Hickory shad,Alosa mediocris
+Alewife,Alosa pseudoharengus
+American shad,Alosa sapidissima
+leatherjacket,Aluterus monoceros
+Orange filefish,Aluterus schoepfii
+Scrawled filefish,Aluterus scriptus
+Shadow bass,Ambloplites ariommus
+Rock bass,Ambloplites rupestris
+White bullhead,Ameiurus catus
+Black bullhead,Ameiurus melas
+Yellow bullhead,Ameiurus natalis
+Brown bullhead,Ameiurus nebulosus
+Bowfin,Amia calva
+Barred grunter,Amniataba percoides
+Midas cichlid,Amphilophus citrinellus
+Clown anemonefish,Amphiprion ocellaris
+Orange clownfish,Amphiprion percula
+Barred surfperch,Amphistichus argenteus
+Redtail surfperch,Amphistichus rhodoterus
+Bay anchovy,Anchoa mitchilli
+European eel,Anguilla anguilla
+Speckled longfin eel,Anguilla reinhardtii
+American eel,Anguilla rostrata
+sargo,Anisotremus davidsonii
+Black margate,Anisotremus surinamensis
+Porkfish,Anisotremus virginicus
+freshwater drum,Aplodinotus grunniens
+Green jobfish,Aprion virescens
+Stripe eel,Aprognathodon platyventris
+sheepshead,Archosargus probatocephalus
+Sea bream,Archosargus rhomboidalis
+Coron meagre,Argyrosomus coronus
+Japanese meagre,Argyrosomus japonicus
+Hardhead catfish,Ariopsis felis
+White-spotted puffer,Arothron hispidus
+Star puffer,Arothron stellatus
+Australian salmon,Arripis trutta
+Bay trout,Arripis truttacea
+Oscar,Astronotus ocellatus
+topsmelt,Atherinops affinis
+jacksmelt,Atherinopsis californiensis
+White seabass,Atractoscion nobilis
+Alligator gar,Atractosteus spatula
+Yellowtail scad,Atule mate
+Trumpetfish,Aulostomus maculatus
+Gafftopsail catfish,Bagre marinus
+Silver perch,Bairdiella chrysoura
+Orange-lined triggerfish,Balistapus undulatus
+Gray triggerfish,Balistes capriscus
+Queen triggerfish,Balistes vetula
+titan triggerfish,Balistoides viridescens
+Java barb,Barbonymus gonionotus
+Barbel,Barbus barbus
+Garfish,Belone belone
+Silver perch,Bidyanus bidyanus
+Silver bream,Blicca bjoerkna
+Spanish hogfish,Bodianus rufus
+Bogue,Boops boops
+Blind shark,Brachaelurus waddi
+Gulf menhaden,Brevoortia patronus
+Atlantic menhaden,Brevoortia tyrannus
+Jolthead porgy,Calamus bajonado
+Central stoneroller,Campostoma anomalum
+Orangespotted filefish,Cantherhines pullus
+Sharpnose puffer,Canthigaster rostrata
+Yellow jack,Caranx bartholomaei
+Pacific crevalle jack,Caranx caninus
+Blue runner,Caranx crysos
+Crevalle jack,Caranx hippos
+Giant trevally,Caranx ignobilis
+horse-eye jack,Caranx latus
+black jack,Caranx lugubris
+Bluefin trevally,Caranx melampygus
+Brassy trevally,Caranx papuensis
+Bar jack,Caranx ruber
+Bigeye trevally,Caranx sexfasciatus
+Goldfish,Carassius auratus
+Crucian carp,Carassius carassius
+Prussian carp,Carassius gibelio
+Blacknose shark,Carcharhinus acronotus
+Narrowtooth shark,Carcharhinus brachyurus
+Spinner shark,Carcharhinus brevipinna
+Silky shark,Carcharhinus falciformis
+Finetooth shark,Carcharhinus isodon
+Bull shark,Carcharhinus leucas
+Blacktip shark,Carcharhinus limbatus
+Blacktip reef shark,Carcharhinus melanopterus
+Dusky shark,Carcharhinus obscurus
+Reef shark,Carcharhinus perezii
+sandbar shark,Carcharhinus plumbeus
+Spottail shark,Carcharhinus sorrah
+Sand tiger,Carcharias taurus
+White shark,Carcharodon carcharias
+river carpsucker,Carpiodes carpio
+Quillback,Carpiodes cyprinus
+Highfin carpsucker,Carpiodes velifer
+Longnose sucker,Catostomus catostomus
+White sucker,Catostomus commersonii
+Goldface tilefish,Caulolatilus chrysops
+Monkeyface prickleback,Cebidichthys violaceus
+Flier,Centrarchus macropterus
+Fat snook,Centropomus parallelus
+Common snook,Centropomus undecimalis
+Black sea bass,Centropristis striata
+Bluespotted grouper,Cephalopholis argus
+Graysby,Cephalopholis cruentata
+Coney,Cephalopholis fulva
+coral grouper,Cephalopholis miniata
+African hind,Cephalopholis taeniops
+Yellowface pikeblenny,Chaenopsis limbaughi
+Atlantic spadefish,Chaetodipterus faber
+Foureye butterflyfish,Chaetodon capistratus
+Saddle butterflyfish,Chaetodon ephippium
+snakehead,Channa argus
+Goldline snakehead,Channa aurolineata
+emperor snakehead,Channa marulioides
+Giant snakehead,Channa marulius
+Giant snakehead,Channa micropeltes
+Orangespotted Snakehead,Channa pseudomarulius
+Chevron snakehead,Channa striata
+Broadbanded moray,Channomuraena vittata
+Milkfish,Chanos chanos
+Tripletail wrasse,Cheilinus trilobatus
+Humphead wrasse,Cheilinus undulatus
+cigar wrasse,Cheilio inermis
+Bluefin gurnard,Chelidonichthys kumu
+Tub gurnard,Chelidonichthys lucerna
+Striped burrfish,Chilomycterus schoepfii
+Clown featherback,Chitala ornata
+Atlantic bumper,Chloroscombrus chrysurus
+Daisy parrotfish,Chlorurus sordidus
+Damselfish,Chromis chromis
+Green chromis,Chromis viridis
+Roman seabream,Chrysoblephus laticeps
+Tucanare peacock bass,Cichla monoculus
+Peacock cichlid,Cichla ocellaris
+Speckled pavon,Cichla temensis
+Stocky hawkfish,Cirrhitus pinnulatus
+Walking catfish,Clarias batrachus
+Sharptooth catfish,Clarias gariepinus
+Blunt-toothed African catfish,Clarias ngamensis
+creole wrasse,Clepticus parrae
+Woolly sculpin,Clinocottus analis
+Atlantic herring,Clupea harengus
+Pacific herring,Clupea pallasii
+Cobbler,Cnidoglanis macrocephalus
+European conger,Conger conger
+Redbreast tilapia,Coptodon rendalli
+Redbelly tilapia,Coptodon zillii
+Cisco,Coregonus artedi
+Lake whitefish,Coregonus clupeaformis
+Rainbow wrasse,Coris julis
+Common dolphinfish,Coryphaena hippurus
+colon goby,Coryphopterus dicrus
+Mottled sculpin,Cottus bairdii
+Goldsinny-wrasse,Ctenolabrus rupestris
+Grass carp,Ctenopharyngodon idella
+Shiner perch,Cymatogaster aggregata
+Sand seatrout,Cynoscion arenarius
+Spotted seatrout,Cynoscion nebulosus
+Weakfish,Cynoscion regalis
+Red shiner,Cyprinella lutrensis
+Spotfin shiner,Cyprinella spiloptera
+Blacktail shiner,Cyprinella venusta
+Common carp,Cyprinus carpio
+Common carp,Cyprinus carpio carpio
+Koi,Cyprinus rubrofuscus
+Flying gurnard,Dactylopterus volitans
+Common stingray,Dasyatis pastinaca
+Mackerel scad,Decapterus macarellus
+Dentex,Dentex dentex
+Painted sweetlips,Diagramma pictum
+European bass,Dicentrarchus labrax
+Spotted seabass,Dicentrarchus punctatus
+Galjoen,Dichistius capensis
+Balloonfish,Diodon holocanthus
+Porcupinefish,Diodon hystrix
+Sand perch,Diplectrum formosum
+annular sea bream,Diplodus annularis
+Blacktail,Diplodus capensis
+Zebra seabream,Diplodus cervinus
+Spottail pinfish,Diplodus holbrookii
+Puntazzo,Diplodus puntazzo
+white seabream,Diplodus sargus
+Twoband bream,Diplodus vulgaris
+gizzard shad,Dorosoma cepedianum
+Threadfin shad,Dorosoma petenense
+Sharksucker,Echeneis naucrates
+chain moray,Echidna catenata
+Spotted spoon-nose eel,Echiophis intertinctus
+Rainbow runner,Elagatis bipinnulata
+blind tassel-fish,Eleutheronema tetradactylum
+Squaretail mullet,Ellochelon vaigiensis
+Ladyfish,Elops saurus
+Black perch,Embiotoca jacksoni
+Striped seaperch,Embiotoca lateralis
+Blackbanded sunfish,Enneacanthus chaetodon
+Bluespotted sunfish,Enneacanthus gloriosus
+Banded sunfish,Enneacanthus obesus
+Globefish,Ephippion guttifer
+Rock hind,Epinephelus adscensionis
+Spotted cabrilla,Epinephelus analogus
+Orange-spotted grouper,Epinephelus coioides
+Blacktip grouper,Epinephelus fasciatus
+Brown-marbled grouper,Epinephelus fuscoguttatus
+Red hind,Epinephelus guttatus
+Goliath grouper,Epinephelus itajara
+flag cabrilla,Epinephelus labriformis
+Giant grouper,Epinephelus lanceolatus
+Malabar grouper,Epinephelus malabaricus
+Dusky grouper,Epinephelus marginatus
+Honeycomb grouper,Epinephelus merra
+Red grouper,Epinephelus morio
+Nassau grouper,Epinephelus striatus
+greasy grouper,Epinephelus tauvina
+Potato grouper,Epinephelus tukula
+Redfin pickerel,Esox americanus
+Redfin pickerel,Esox americanus vermiculatus
+Northern pike,Esox lucius
+Muskellunge,Esox masquinongy
+Tiger Musky,Esox masquinongy X Esox lucius
+Muskellunge,Esox masquinongy punctulatus
+Chain pickerel,Esox niger
+Queen snapper,Etelis oculatus
+Rainbow darter,Etheostoma caeruleum
+Fringed flounder,Etropus crossotus
+Silver jenny,Eucinostomus gula
+Kawakawa,Euthynnus affinis
+little tunny,Euthynnus alletteratus
+Golden topminnow,Fundulus chrysotus
+Banded killifish,Fundulus diaphanus
+Blackspotted topminnow,Fundulus olivaceus
+Atlantic cod,Gadus morhua
+Tiger shark,Galeocerdo cuvier
+Tope shark,Galeorhinus galeus
+Western mosquitofish,Gambusia affinis
+Threespine stickleback,Gasterosteus aculeatus
+White croaker,Genyonemus lineatus
+Yellowfin mojarra,Gerres cinereus
+nurse shark,Ginglymostoma cirratum
+Black bream,Girella elevata
+Blackfish,Girella tricuspidata
+Dhufish,Glaucosoma hebraicum
+Golden trevally,Gnathanodon speciosus
+California clingfish,Gobiesox rhessodon
+Gudgeon,Gobio gobio
+Quillfin blenny,Gobioclinus filamentosus
+Rock goby,Gobius paganellus
+Ruffe,Gymnocephalus cernua
+Dogtooth tuna,Gymnosarda unicolor
+Green moray,Gymnothorax funebris
+Goldentail moray,Gymnothorax miliaris
+Spotted moray,Gymnothorax moringa
+Margate,Haemulon album
+Tomtate,Haemulon aurolineatum
+smallmouth grunt,Haemulon chrysargyreum
+French grunt,Haemulon flavolineatum
+Sailors choice,Haemulon parra
+White grunt,Haemulon plumierii
+Bluestriped grunt,Haemulon sciurus
+Slippery dick,Halichoeres bivittatus
+Yellowhead wrasse,Halichoeres garnoti
+Clown wrasse,Halichoeres maculipinna
+Puddingwife,Halichoeres radiatus
+Rock wrasse,Halichoeres semicinctus
+Carp,Hampala macrolepidota
+Blackeye thicklip,Hemigymnus melapterus
+Black bream,Hephaestus fuliginosus
+Rio Grande cichlid,Herichthys cyanoguttatus
+Garden eel,Heteroconger longissimus
+Horn shark,Heterodontus francisci
+Port Jackson shark,Heterodontus portusjacksoni
+Kelp greenling,Hexagrammos decagrammus
+Whitespotted greenling,Hexagrammos stelleri
+Goldeye,Hiodon alosoides
+mooneye,Hiodon tergisus
+Flathead sole,Hippoglossoides elassodon
+Pacific halibut,Hippoglossus stenolepis
+angelfish,Holacanthus bermudensis
+Queen angelfish,Holacanthus ciliaris
+Squirrelfish,Holocentrus adscensionis
+Trahira,Hoplias malabaricus
+Greenbar snapper,Hoplopagrus guentherii
+Brown hoplo,Hoplosternum littorale
+Brassy minnow,Hybognathus hankinsoni
+Tigerfish,Hydrocynus vittatus
+Southern stingray,Hypanus americanus
+Atlantic stingray,Hypanus sabinus
+Northern hog sucker,Hypentelium nigricans
+Surf smelt,Hypomesus pretiosus
+Silver carp,Hypophthalmichthys molitrix
+Bighead carp,Hypophthalmichthys nobilis
+shy hamlet,Hypoplectrus guttavarius
+Snowy grouper,Hyporthodus niveatus
+Garibaldi,Hypsypops rubicundus
+Blue catfish,Ictalurus furcatus
+Channel catfish,Ictalurus punctatus
+Smallmouth buffalo,Ictiobus bubalus
+Bigmouth buffalo,Ictiobus cyprinellus
+Black buffalo,Ictiobus niger
+Black marlin,Istiompax indica
+Atlantic sailfish,Istiophorus albicans
+Sailfish,Istiophorus platypterus
+Shortfin mako,Isurus oxyrinchus
+Striped marlin,Kajikia audax
+Skipjack tuna,Katsuwonus pelamis
+Rock flagtail,Kuhlia rupestris
+Bermuda sea chub,Kyphosus sectatrix
+Blue-bronze chub,Kyphosus vaigiensis
+Orange river mudfish,Labeo capensis
+Smallmouth yellowfish,Labeobarbus aeneus
+Largescale yellowfish,Labeobarbus marequensis
+Bluestreak cleaner wrasse,Labroides dimidiatus
+Ballan wrasse,Labrus bergylta
+Cuckoo wrasse,Labrus mixtus
+Hogfish,Lachnolaimus maximus
+Smooth puffer,Lagocephalus laevigatus
+Oceanic puffer,Lagocephalus lagocephalus
+Pinfish,Lagodon rhomboides
+Opah,Lampris guttatus
+Barramundi perch,Lates calcarifer
+Spangled perch,Leiopotherapon unicolor
+Spot,Leiostomus xanthurus
+Spotted gar,Lepisosteus oculatus
+longnose gar,Lepisosteus osseus
+Shortnose gar,Lepisosteus platostomus
+Florida gar,Lepisosteus platyrhincus
+Redbreast sunfish,Lepomis auritus
+Green sunfish,Lepomis cyanellus
+Pumpkinseed,Lepomis gibbosus
+Warmouth,Lepomis gulosus
+Orangespotted sunfish,Lepomis humilis
+Bluegill,Lepomis macrochirus
+Dollar sunfish,Lepomis marginatus
+Longear sunfish,Lepomis megalotis
+Redear sunfish,Lepomis microlophus
+Redspotted sunfish,Lepomis miniatus
+Northern sunfish,Lepomis peltastes
+Spotted sunfish,Lepomis punctatus
+Bantam sunfish,Lepomis symmetricus
+Pacific staghorn sculpin,Leptocottus armatus
+Pink ear emperor,Lethrinus lentjan
+Spangled emperor,Lethrinus nebulosus
+Orange-striped emperor,Lethrinus obsoletus
+Asp,Leuciscus aspius
+Ide,Leuciscus idus
+Eurasian dace,Leuciscus leuciscus
+Leerfish,Lichia amia
+Dab,Limanda limanda
+Shanny,Lipophrys pholis
+White steenbras,Lithognathus lithognathus
+Sand steenbras,Lithognathus mormyrus
+Tripletail,Lobotes surinamensis
+Cape Hope squid,Loligo vulgaris
+Burbot,Lota lota
+Mutton snapper,Lutjanus analis
+Schoolmaster,Lutjanus apodus
+Mangrove red snapper,Lutjanus argentimaculatus
+amarillo snapper,Lutjanus argentiventris
+Twospot snapper,Lutjanus bohar
+blackfin snapper,Lutjanus buccanella
+Red snapper,Lutjanus campechanus
+Spanish flag,Lutjanus carponotatus
+Cubera snapper,Lutjanus cyanopterus
+Checkered snapper,Lutjanus decussatus
+Blackspot snapper,Lutjanus ehrenbergii
+Blackspot snapper,Lutjanus fulviflamma
+Blacktail snapper,Lutjanus fulvus
+Humpback snapper,Lutjanus gibbus
+Gray snapper,Lutjanus griseus
+Dog snapper,Lutjanus jocu
+John's snapper,Lutjanus johnii
+Bluestriped snapper,Lutjanus kasmira
+Mahogany snapper,Lutjanus mahogoni
+Onespot snapper,Lutjanus monostigma
+Dog snapper,Lutjanus novemfasciatus
+Caribbean red snapper,Lutjanus purpureus
+Blubberlip snapper,Lutjanus rivulatus
+Russell's snapper,Lutjanus russellii
+Emperor snapper,Lutjanus sebae
+Lane snapper,Lutjanus synagris
+Silk snapper,Lutjanus vivanus
+Striped shiner,Luxilus chrysocephalus
+Common shiner,Luxilus cornutus
+Trout cod,Maccullochella macquariensis
+Murray cod,Maccullochella peelii
+Golden perch,Macquaria ambigua
+Blue marlin,Makaira nigricans
+Mayan cichlid,Mayaheros urophthalmus
+Tarpon,Megalops atlanticus
+Oxeye,Megalops cyprinoides
+Haddock,Melanogrammus aeglefinus
+Black durgon,Melichthys niger
+Atlantic silverside,Menidia menidia
+southern kingcroaker,Menticirrhus americanus
+Gulf kingcroaker,Menticirrhus littoralis
+Northern kingfish,Menticirrhus saxatilis
+California corbina,Menticirrhus undulatus
+Whiting,Merlangius merlangus
+Six-spined leatherjacket,Meuschenia freycineti
+Atlantic croaker,Micropogonias undulatus
+Shoal bass,Micropterus cataractae
+Redeye bass,Micropterus coosae
+Smallmouth bass,Micropterus dolomieu
+Florida bass,Micropterus floridanus
+Alabama bass,Micropterus henshalli
+Largemouth bass,Micropterus nigricans
+Suwannee bass,Micropterus notius
+Spotted bass,Micropterus punctulatus
+Guadalupe bass,Micropterus treculii
+Spotted sucker,Minytrema melanops
+Ocean sunfish,Mola mola
+Centreboard leatherjacket,Monacanthus chinensis
+Diamond moonfish,Monodactylus argenteus
+White perch,Morone americana
+White bass,Morone chrysops
+Wiper,Morone chrysops X Morone saxatilis
+Yellow bass,Morone mississippiensis
+Striped bass,Morone saxatilis
+Silver redhorse,Moxostoma anisurum
+River redhorse,Moxostoma carinatum
+Black redhorse,Moxostoma duquesnei
+Golden redhorse,Moxostoma erythrurum
+Shorthead redhorse,Moxostoma macrolepidotum
+Greater redhorse,Moxostoma valenciennesi
+flathead grey mullet,Mugil cephalus
+White mullet,Mugil curema
+Yellowstripe goatfish,Mulloidichthys flavolineatus
+yellow goatfish,Mulloidichthys martinicus
+Red mullet,Mullus surmuletus
+Gummy shark,Mustelus antarcticus
+Starry smooth-hound,Mustelus asterias
+Smooth dogfish,Mustelus canis
+Spotted estuary smooth-hound,Mustelus lenticulatus
+Smooth-hound,Mustelus mustelus
+Black grouper,Mycteroperca bonaci
+finescale rockfish,Mycteroperca microlepis
+Scamp,Mycteroperca phenax
+Comb grouper,Mycteroperca rubra
+Tiger grouper,Mycteroperca tigris
+Yellowfin grouper,Mycteroperca venenosa
+Common eagle ray,Myliobatis aquila
+Bat ray,Myliobatis californica
+Sharptail eel,Myrichthys breviceps
+Goldspotted eel,Myrichthys ocellatus
+Blotcheye soldierfish,Myripristis berndti
+Bluespine unicornfish,Naso unicornis
+Tawny nurse shark,Nebrius ferrugineus
+lemon shark,Negaprion brevirostris
+Roosterfish,Nematistius pectoralis
+Round goby,Neogobius melanostomus
+Hornyhead chub,Nocomis biguttatus
+Bluehead chub,Nocomis leptocephalus
+River chub,Nocomis micropogon
+Golden shiner,Notemigonus crysoleucas
+Spotty,Notolabrus celidotus
+Banded parrotfish,Notolabrus fucicola
+crimson banded wrasse,Notolabrus gymnogenis
+Blue-throated parrotfish,Notolabrus tetricus
+Broadnose sevengill shark,Notorynchus cepedianus
+Emerald shiner,Notropis atherinoides
+spottail shiner,Notropis hudsonius
+Sand Shiner,Notropis stramineus
+Stonecat,Noturus flavus
+Saddle bream,Oblada melanurus
+Yellowtail snapper,Ocyurus chrysurus
+Leatherjacket,Oligoplites saurus
+Golden trout,Oncorhynchus aguabonita
+Cutthroat trout,Oncorhynchus clarkii
+Cutthroat trout,Oncorhynchus clarkii clarkii
+Pink salmon,Oncorhynchus gorbuscha
+Chum salmon,Oncorhynchus keta
+Coho salmon,Oncorhynchus kisutch
+Rainbow trout,Oncorhynchus mykiss
+Cutbow,Oncorhynchus mykiss X Color variant2
+Cutbow,Oncorhynchus mykiss X Oncorhynchus clarkii
+Sockeye salmon,Oncorhynchus nerka
+Chinook salmon,Oncorhynchus tshawytscha
+Spotted snake eel,Ophichthus ophis
+Lingcod,Ophiodon elongatus
+Atlantic thread herring,Opisthonema oglinum
+Oyster toadfish,Opsanus tau
+Threespot tilapia,Oreochromis andersonii
+Blue tilapia,Oreochromis aureus
+Longfin tilapia,Oreochromis macrochir
+Mozambique tilapia,Oreochromis mossambicus
+Nile tilapia,Oreochromis niloticus
+Pigfish,Orthopristis chrysoptera
+Hottentot seabream,Pachymetopon blochii
+axillary seabream,Pagellus acarne
+Pandora,Pagellus erythrinus
+Squirefish,Pagrus auratus
+Red porgy,Pagrus pagrus
+Bermuda lobster,Panulirus argus
+Palette surgeonfish,Paracanthurus hepatus
+Guapote,Parachromis dovii
+Jaguar guapote,Parachromis managuensis
+kelp bass,Paralabrax clathratus
+Spotted sand bass,Paralabrax maculatofasciatus
+barred sand bass,Paralabrax nebulifer
+Gulf flounder,Paralichthys albigutta
+California halibut,Paralichthys californicus
+Summer flounder,Paralichthys dentatus
+Southern flounder,Paralichthys lethostigma
+Blue cod,Parapercis colias
+Blue goatfish,Parupeneus cyclostomus
+Indian goatfish,Parupeneus indicus
+Manybar goatfish,Parupeneus multifasciatus
+Blackspot goatfish,Parupeneus spilurus
+Spotted tilapia,Pelmatolapia mariae
+Butterfish,Peprilus triacanthus
+Yellow perch,Perca flavescens
+Eurasian perch,Perca fluviatilis
+Australian bass,Percalates novemaculeatus
+Logperch,Percina caprodes
+Trout-perch,Percopsis omiscomaycus
+Eurasian minnow,Phoxinus phoxinus
+Redtail catfish,Phractocephalus hemioliopterus
+Pirapitinga,Piaractus brachypomus
+Congo barbaso,Pimelodus maculatus
+Bluntnose minnow,Pimephales notatus
+Fathead minnow,Pimephales promelas
+Bullhead minnow,Pimephales vigilax
+Golden spadefish,Platax boersii
+Longfin batfish,Platax teira
+European flounder,Platichthys flesus
+Starry flounder,Platichthys stellatus
+Bay flathead,Platycephalus bassensis
+Blue-spotted flathead,Platycephalus caeruleopunctatus
+Black flathead,Platycephalus fuscus
+Bartail flathead,Platycephalus indicus
+Thornback,Platyrhinoidis triseriata
+Blacksaddled coralgrouper,Plectropomus laevis
+Leopard coralgrouper,Plectropomus leopardus
+Spotted coralgrouper,Plectropomus maculatus
+Plaice,Pleuronectes platessa
+Striped eel-catfish,Plotosus lineatus
+Guppy,Poecilia reticulata
+Black drum,Pogonias cromis
+Pollack,Pollachius pollachius
+Pollock,Pollachius virens
+Paddlefish,Polyodon spathula
+Wreckfish,Polyprion americanus
+Gray angelfish,Pomacanthus arcuatus
+French angelfish,Pomacanthus paru
+Goldbelly damsel,Pomacentrus auriventris
+Smallspotted grunt,Pomadasys commersonnii
+Javelin grunter,Pomadasys kaakan
+blue fish,Pomatomus saltatrix
+sand goby,Pomatoschistus minutus
+White crappie,Pomoxis annularis
+black crappie,Pomoxis nigromaculatus
+striped catshark,Poroderma africanum
+Black river stingray,Potamotrygon motoro
+Rusty goby,Priolepis hipoliti
+Blue shark,Prionace glauca
+Northern searobin,Prionotus carolinus
+striped searobin,Prionotus evolans
+Mountain whitefish,Prosopium williamsoni
+Shovelnose guitarfish,Pseudobatos productus
+Günther's wrasse,Pseudolabrus guentheri
+Barred sorubim,Pseudoplatystoma fasciatum
+Winter flounder,Pseudopleuronectes americanus
+Spotted goatfish,Pseudupeneus maculatus
+Lionfish,Pterois volitans
+Leopard pleco,Pterygoplichthys gibbiceps
+Sacramento pikeminnow,Ptychocheilus grandis
+Columbia River dace,Ptychocheilus oregonensis
+Red piranha,Pygocentrus nattereri
+Flathead catfish,Pylodictis olivaris
+blackspotted snake eel,Quassiremus ascensionis
+Cobia,Rachycentron canadum
+roker,Raja clavata
+Indian mackerel,Rastrelliger kanagurta
+Cape stumpnose,Rhabdosargus holubi
+Goldlined seabream,Rhabdosargus sarba
+Catfish,Rhamdia quelen
+Whale shark,Rhincodon typus
+Patchy triggerfish,Rhinecanthus rectangulus
+Blacknose dace,Rhinichthys atratulus
+Longnose dace,Rhinichthys cataractae
+Western blacknose dace,Rhinichthys obtusus
+Cownose ray,Rhinoptera bonasus
+Atlantic sharpnose shark,Rhizoprionodon terraenovae
+vermilion snapper,Rhomboplites aurorubens
+Roach,Rutilus rutilus
+Greater soapfish,Rypticus saponaceus
+Dorado,Salminus brasiliensis
+marble trout,Salmo marmoratus
+Atlantic salmon,Salmo salar
+Brown trout,Salmo trutta
+Tiger trout,Salmo trutta X Salvelinus fontinalis
+Arctic char,Salvelinus alpinus
+Bull trout,Salvelinus confluentus
+Brook trout,Salvelinus fontinalis
+Dolly varden,Salvelinus malma
+Lake trout,Salvelinus namaycush
+Sauger,Sander canadensis
+Zander,Sander lucioperca
+Walleye,Sander vitreus
+Saugeye,Sander vitreus X Sander canadensis
+Striped bonito,Sarda orientalis
+Atlantic bonito,Sarda sarda
+Blackchin tilapia,Sarotherodon melanotheron
+Salpa,Sarpa salpa
+Shovelnose sturgeon,Scaphirhynchus platorynchus
+Rudd,Scardinius erythrophthalmus
+Blue parrotfish,Scarus coeruleus
+Blue-barred parrotfish,Scarus ghobban
+Rainbow parrotfish,Scarus guacamaia
+Striped parrotfish,Scarus iseri
+Dusky parrotfish,Scarus niger
+Common parrotfish,Scarus psittacus
+Princess parrotfish,Scarus taeniopterus
+Queen parrotfish,Scarus vetula
+Spotted scat,Scatophagus argus
+Red drum,Sciaenops ocellatus
+Spotted mackerel,Scomber australasicus
+Atlantic chub mackerel,Scomber colias
+Chub mackerel,Scomber japonicus
+Atlantic mackerel,Scomber scombrus
+Talang queenfish,Scomberoides commersonnianus
+Doublespotted queenfish,Scomberoides lysan
+King mackerel,Scomberomorus cavalla
+Narrowbarred mackerel,Scomberomorus commerson
+Spanish mackerel,Scomberomorus maculatus
+Cero,Scomberomorus regalis
+Pacific sierra,Scomberomorus sierra
+California scorpionfish,Scorpaena guttata
+Smallscaled scorpionfish,Scorpaena porcus
+Cabezon,Scorpaenichthys marmoratus
+Silver sweep,Scorpis lineolata
+Small-spotted catshark,Scyliorhinus canicula
+greater spotted dogfish,Scyliorhinus stellaris
+Brown rockfish,Sebastes auriculatus
+Copper rockfish,Sebastes caurinus
+Quillback rockfish,Sebastes maliger
+Black rockfish,Sebastes melanops
+Vermilion rockfish,Sebastes miniatus
+Blue rockfish,Sebastes mystinus
+Yelloweye rockfish,Sebastes ruberrimus
+Bigeye scad,Selar crumenophthalmus
+Atlantic moonfish,Selene setapinnis
+Lookdown,Selene vomer
+California sheephead,Semicossyphus pulcher
+Creek chub,Semotilus atromaculatus
+Fallfish,Semotilus corporalis
+Greater amberjack,Seriola dumerili
+Samsonfish,Seriola hippos
+Yellowtail amberjack,Seriola lalandi
+Almaco jack,Seriola rivoliana
+Yellow-belly bream,Serranochromis robustus
+Comber,Serranus cabrilla
+Painted comber,Serranus scriba
+Redeye piranha,Serrasalmus rhombeus
+Goldlined spinefoot,Siganus guttatus
+Foxface,Siganus vulpinus
+Spotted whiting,Sillaginodes punctatus
+Sand sillago,Sillago ciliata
+Wels,Silurus glanis
+Greenblotch parrotfish,Sparisoma atomarium
+Redband parrotfish,Sparisoma aurofrenatum
+Redtail parrotfish,Sparisoma chrysopterum
+Parrotfish,Sparisoma cretense
+redfin parrotfish,Sparisoma rubripinne
+Stoplight parrotfish,Sparisoma viride
+White musselcracker,Sparodon durbanensis
+Gilthead bream,Sparus aurata
+Northern puffer,Sphoeroides maculatus
+Southern puffer,Sphoeroides nephelus
+Bandtail puffer,Sphoeroides spengleri
+Checkered puffer,Sphoeroides testudineus
+Pacific barracuda,Sphyraena argentea
+Great barracuda,Sphyraena barracuda
+Pickhandle barracuda,Sphyraena jello
+Australian barracuda,Sphyraena novaehollandiae
+Yellowstriped barracuda,Sphyraena obtusata
+Blackfin barracuda,Sphyraena qenie
+European barracuda,Sphyraena sphyraena
+barracuda,Sphyraena viridensis
+Scalloped hammerhead,Sphyrna lewini
+Great hammerhead,Sphyrna mokarran
+Bonnethead,Sphyrna tiburo
+Smooth hammerhead,Sphyrna zygaena
+Black seabream,Spondyliosoma cantharus
+Spiny dogfish,Squalus acanthias
+Dusky damselfish,Stegastes adustus
+Longfin damselfish,Stegastes diencaeus
+Beaugregory,Stegastes leucostictus
+Bicolor damselfish,Stegastes partitus
+Cocoa damselfish,Stegastes variabilis
+Scup,Stenotomus chrysops
+Giant sea bass,Stereolepis gigas
+Atlantic needlefish,Strongylura marina
+Grey wrasse,Symphodus cinereus
+Corkwing wrasse,Symphodus melops
+East Atlantic peacock wrasse,Symphodus tinca
+Mandarinfish,Synchiropus splendidus
+Inshore lizardfish,Synodus foetens
+Atlantic lizardfish,Synodus saurus
+Blue-spotted fantail ray,Taeniura lymma
+Eel-tailed catfish,Tandanus tandanus
+Tautog,Tautoga onitis
+Cunner,Tautogolabrus adspersus
+Jarbua terapon,Terapon jarbua
+Bluehead,Thalassoma bifasciatum
+Saddle wrasse,Thalassoma duperrey
+moon wrasse,Thalassoma lunare
+Ornate wrasse,Thalassoma pavo
+Surge wrasse,Thalassoma purpureum
+Albacore,Thunnus alalunga
+Yellowfin tuna,Thunnus albacares
+Blackfin tuna,Thunnus atlanticus
+Pacific bluefin tuna,Thunnus orientalis
+Bluefin tuna,Thunnus thynnus
+Arctic grayling,Thymallus arcticus
+Grayling,Thymallus thymallus
+Snoek,Thyrsites atun
+Banded tilapia,Tilapia sparrmanii
+Tench,Tinca tinca
+Banded toadfish,Torquigener pleurogramma
+Archerfish,Toxotes jaculatrix
+Smallspotted dart,Trachinotus baillonii
+Snubnose pompano,Trachinotus blochii
+Florida pompano,Trachinotus carolinus
+Swallowtail dart,Trachinotus coppingeri
+Permit,Trachinotus falcatus
+Palometa,Trachinotus goodei
+Derbio,Trachinotus ovatus
+Mediterranean scad,Trachurus mediterraneus
+Yellowtail horse mackerel,Trachurus novaezelandiae
+Jack mackerel,Trachurus symmetricus
+European horse mackerel,Trachurus trachurus
+whitetip reef shark,Triaenodon obesus
+Leopard shark,Triakis semifasciata
+Atlantic cutlass fish,Trichiurus lepturus
+Hogchoker,Trinectes maculatus
+Bib,Trisopterus luscus
+Eastern fiddler ray,Trygonorrhina fasciata
+Houndfish,Tylosurus crocodilus
+Central mudminnow,Umbra limi
+lunartail grouper,Variola louti
+Wallago,Wallago attu
+Sargassum triggerfish,Xanthichthys ringens
+Swordfish,Xiphias gladius
+Pearly razorfish,Xyrichtys novacula
+Yellow tang,Zebrasoma flavescens
+Common cuttlefish,Sepia officinalis