SYNTHETIC Embeddings example
============================

These 24 RGB PNGs are computer-drawn geometric shapes: eight circles, eight
squares and eight triangles. Each image is 64 by 64 pixels. There are no
biological specimens, experimental conditions or human annotations here.
The labels describe only the generated shapes. The example demonstrates
loading crops, making embeddings and inspecting a label scorecard; its
scores are not a scientific benchmark or evidence of biological accuracy.

Try it in spaCR
--------------
The embedding dependencies must be installed. For a Python installation,
run `python -m pip install "spacr[embeddings]"` in the spaCR environment if
the app asks for torch and timm. This example does not bundle Python packages.

1. Enable Show alpha features, then open Embeddings.
2. Click Load synthetic demo. This opens these crops and their aligned
   labels, selects the Foundation model "DINOv2 (Cell-DINO when
   installed)" with Project to three (one pass) and a batch size of 8, and
   selects the CPU for embedding. The line under the controls says whether
   official Cell-DINO or the open DINOv2 ViT-S/14 will run.
3. Press Embed. The preview should contain 24 rows with finite values.
   The label scorecard reports retrieval performance for the drawn shapes.
4. To try the classifier workflow, choose Use for, then Classifier, then
   Run. Treat the result as a functional demonstration on this tiny set.

The images and labels are bundled with spaCR and require no data download.
Pretrained DINOv2 weights (about 90 MB) are separate: the normal model
loader may download them on first use, then reuse its cache. No Cell-DINO
weights are included or required; Meta grants them by request. The example
does not train a backbone. For real cells, Load cell example opens the
example plate's annotated single-cell crops the same way.

Open the files manually
----------------------
In Embeddings, select the crop-folder source, choose the crops/ directory,
clear any selection filters, set the crop limit to at least 24 and press
Load crops. Select the Foundation model "DINOv2 (Cell-DINO when installed)"
and Project to three (one pass). Open Labels… and select
labels.csv, then press Embed. The built-in demo button explicitly uses CPU;
manual loading follows the application's normal device selection.

labels.csv has crop_filename and label columns. Rows match the alphabetical
order of the zero-padded PNG filenames exactly, with one row per crop.
Keep that row order: the current Labels action reads labels by crop order,
not by joining the crop_filename column. Do not filter or reorder one input
without making the corresponding change to the other.

Rebuild
-------
From the source checkout, run:
    python tools/build_embeddings_example_dataset.py
The generator uses fixed geometric formulas and no network or random state.
It writes spacr/resources/data/embeddings_synthetic_example.tar.gz.
