whale-shark-id-resnet18

Whale-Shark Individual ID — C/CUDA-first MVP

Real-time local detection/tracking/feature extraction for photos and video with immediate global catalog API lookup (known / unknown / review). CPU fallback always works; CUDA backend is optional and isolated.

Architecture

photo/video -> decode/input adapter -> detection interface -> tracker + evidence accumulator
            -> flank crop/normalize -> embedding interface -> catalog retrieval (cosine)
            -> calibrated thresholds -> known / unknown / review
live frames -> wsi_stream_push_frame -> provisional ID or UNKNOWN -> more frames -> confirmed ID / UNKNOWN / REVIEW
global catalog API (wsi_catalog_api_t) owns full catalog; local wsi_catalog_index_t is an optional cache.

Requirements

• CMake >=3.16, GCC >=11, C11, libm
• No PyTorch/OpenCV/FAISS/model weights required for smoke path
• Optional: CUDA Toolkit 12.8 + driver (/usr/local/cuda/bin/nvcc, sm_75 for GTX 1650 4GB)

Build

CPU-only (always works)

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DWSI_ENABLE_CUDA=OFF
cmake --build build -j2
ctest --test-dir build --output-on-failure
./build/wsi_tests
./build/wsi_demo
./build/wsi_demo --photo /tmp/test8.ppm   # P6 or P3 PPM, maxval <=255

CUDA (only if toolkit present; falls back gracefully)

export PATH=/usr/local/cuda/bin:$PATH
cmake -S . -B build-cuda -DCMAKE_BUILD_TYPE=Release \
  -DWSI_ENABLE_CUDA=ON \
  -DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc \
  -DCUDAToolkit_ROOT=/usr/local/cuda
cmake --build build-cuda -j2
ctest --test-dir build-cuda --output-on-failure
./build-cuda/wsi_demo

If CUDA is unavailable the project still builds and tests via src/wsi_cuda_unavailable.c; wsi_cuda_backend_available() returns 0 and wsi_cuda_backend_self_test() returns WSI_ERR_BACKEND_UNAVAILABLE.

API Surface (C11)

// Core
wsi_frame_alloc / wsi_frame_load_ppm (P6/P3) / wsi_frame_free
wsi_cpu_detect / wsi_cpu_crop_normalize / wsi_cpu_embed   // deterministic 16-D baseline
wsi_catalog_build / wsi_catalog_free / wsi_catalog_save / wsi_catalog_load / wsi_catalog_search
wsi_retrieve(const wsi_catalog_t*, query, dim, evidence_frames, config, result) // cosine top-k
wsi_process_photo / wsi_process_frame_sequence / wsi_process_video
wsi_stream_init / wsi_stream_push_frame (provisional) / wsi_stream_finish / wsi_stream_free
wsi_cuda_backend_available / wsi_cuda_backend_name / wsi_cuda_backend_self_test // isolated .cu
wsi_search_config_default / wsi_search_mutate_one / wsi_evaluate_fixture / wsi_hill_climb

Initialize owned output structs (wsi_frame_t, wsi_catalog_index_t, wsi_stream_t) to zero before first use; their allocation/build APIs replace and free any existing owned state.

Key structs expose real-time contract:

typedef struct {
  size_t track_count; size_t processed_frames;
  double end_to_end_latency_ms; double frame_rate; double api_latency_ms;
  size_t working_memory_bytes;
  wsi_track_result_t tracks[WSI_MAX_TRACKS]; // each: track_id, evidence_frames, evidence_start_frame/end_frame,
} wsi_pipeline_result_t;                     // retrieval {decision, identity, similarity, runner_up, candidates[]},
                                             // confidence, provisional, api_latency_ms, frame_rate, ...
typedef struct {
  wsi_catalog_search_fn search; void *ctx; size_t timeout_ms; // must honor timeout, return error on timeout
} wsi_catalog_api_t;

• search returning non-WSI_OK, malformed ranked candidates, or candidates below local thresholds fails closed to WSI_DECISION_UNKNOWN.
• A stream snapshot below min_evidence_frames emits either a threshold-qualified provisional ID or UNKNOWN; non-stream photo results remain REVIEW when evidence is insufficient.
• provisional=1 for wsi_stream_push_frame snapshots, 0 for final wsi_stream_finish.

Smoke Test (no weights)

tests/test_wsi.c exercises:

1. Retrieval decisions (known / unknown / review via cosine + thresholds)
2. Photo path (1 frame -> REVIEW) and video/frame-sequence (3 frames -> one track with 3 evidence frames -> KNOWN)
3. Live API streaming with an immediate provisional ID, then confirmed KNOWN; API error and below-threshold forced-ID responses fail closed to UNKNOWN
4. Catalog build/search/save/load, including a truncated-file error path
5. CPU detector/crop/embed + PPM load
6. CUDA kernel self-test when a device is available, or explicit unavailable status on CPU-only hosts
7. Autoresearch mutation and resumable log

Run: ctest --test-dir build --output-on-failure

Autoresearch Hill Climbing

Deterministic synthetic fixture + 4 adversarial markers (partial-flank near-duplicate, turbidity color-shift, new-identity opposite-side, glare/compression distractor), identity-safe.

wsi_search_config_t base; wsi_search_config_default(&base);
wsi_search_options_t opts = {.iterations=5, .seed=42, .dataset_split="synthetic-identity-safe-v1",
  .build_revision="test-rev", .backend="cpu", .log_path="/tmp/hill.jsonl", .best_path="/tmp/hill.best"};
wsi_search_summary_t summary;
wsi_hill_climb(&base, &opts, &summary);

Each iteration mutates exactly one parameter (known_threshold, review_threshold, margin_threshold, min_evidence_frames, tracker_iou_threshold) by a fixed step. Objective:

objective = 10*known_correct + 3*unknown_decisions + 1*unknown_rejected
            -100*false_merges -0.25*review_count

Candidates with false_merges>0 or not beating best objective are rejected (safety gate). JSONL log is appended; best file is only overwritten on improvement; prior best is loaded from best_path or from log_path for resumability.

Example log line:

{"seed":42,"split":"synthetic-identity-safe-v1","build":"test-rev","backend":"cpu",
 "known_threshold":0.98,"review_threshold":0.95,"margin_threshold":0.05,
 "min_evidence_frames":2,"tracker_iou_threshold":0.2,
 "known_correct":2,"unknown_rejected":4,"unknown_decisions":3,"review_count":1,
 "false_merges":0,"objective":32.75,"latency_ms":-1,"vram_mb":-1,"accepted":1}

Limitations (honest)

• Embedder is a 4x4 grayscale spatial descriptor (16-D L2-normalized), not a learned whale-shark spot embedder. No claim of biological recognition; evaluate on labeled data before any such claim.
• Detector is a luminance foreground box, not a trained shark detector.
• No real whale-shark accuracy reported; fixture metrics are synthetic.
• Adversarial suite is synthetic (4 markers), reported separately from field images.
• Latency/VRAM in fixture metrics are -1 (no meaningful measurement in dependency-free fixture); real measurements require instrumented runs with CLOCK_MONOTONIC and CUDA events.
• No huge model weights downloaded; compact detector ONNX not included.

Project Layout

include/wsi/wsi.h           // core C ABI
include/wsi/wsi_cpu.h        // CPU detector/embed
include/wsi/wsi_cuda.h       // isolated CUDA backend ABI
include/wsi/wsi_research.h   // adversarial fixture + hill climb
src/wsi.c                    // retrieve, tracker, evidence, stream, PPM
src/wsi_cpu.c                // deterministic CPU ops
src/wsi_cuda_backend.cu      // isolated cosine kernel self-test
src/wsi_cuda_unavailable.c   // CPU fallback
src/wsi_research.c           // fixture, evaluate, mutate, hill climb with resumable JSONL
tests/test_wsi.c             // deterministic smoke tests
examples/wsi_demo.c          // photo + video/sequence + CUDA status demo
CMakeLists.txt

License

Research MVP; no model weights included.