{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "vision_alone-01",
   "metadata": {},
   "source": "# Extract vision features from images\n\n`VisionModel.extract()` accepts a `{stimulus_id: image}` mapping independently of `BaseData` and always returns `VisualRepresentations`. Indexing by a module name or integer returns one `VisualRepresentation`; boolean-mask indexing always returns a `VisualRepresentations` collection, including zero or one match.\n\nThis workflow requires a configured model from the [vision-model notebook](vision_models). Model construction may require network access; the documentation build does not execute these cells."
  },
  {
   "cell_type": "markdown",
   "id": "vision_alone-02",
   "metadata": {},
   "source": [
    "## Prepare a bounded image mapping"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vision_alone-03",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import torch\n",
    "\n",
    "import vneurotk as vtk\n",
    "\n",
    "rng = np.random.default_rng(0)\n",
    "images = {f\"image-{index}\": rng.integers(0, 256, (64, 64, 3), dtype=np.uint8) for index in range(4)}\n",
    "device = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n",
    "model = vtk.VisionModel(\n",
    "    \"facebook/dinov2-base\",\n",
    "    backend=\"transformers\",\n",
    "    device=device,\n",
    ")\n",
    "model.set_selector(module_name=\"layernorm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vision_alone-04",
   "metadata": {},
   "source": [
    "## Extract selected representations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vision_alone-05",
   "metadata": {},
   "outputs": [],
   "source": [
    "representations = model.extract(images, batch_size=4)\n",
    "representations.meta"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vision_alone-06",
   "metadata": {},
   "source": [
    "## Inspect arrays and provenance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vision_alone-07",
   "metadata": {},
   "outputs": [],
   "source": [
    "first = representations[0]\n",
    "array = representations.numpy(first.module_name)\n",
    "provenance = first.provenance\n",
    "provenance.backend, provenance.model_id, array.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vision_alone-08",
   "metadata": {},
   "source": [
    "`ExtractionProvenance` records locally available revision and preprocessing metadata, selector configuration, dtype, device, dependency versions, and the VneuroTK writer version. Unknown values stay `\"unknown\"`; provenance discovery does not make registry requests.\n",
    "\n",
    "An optional digest can be supplied when the caller has computed it over the ordered stimulus content:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vision_alone-09",
   "metadata": {},
   "outputs": [],
   "source": [
    "with_digest = model.extract(\n",
    "    images,\n",
    "    batch_size=4,\n",
    "    stimulus_content_hash=\"sha256:<caller-computed-digest>\",\n",
    ")\n",
    "with_digest[0].provenance.stimulus_content_hash"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vision_alone-10",
   "metadata": {},
   "source": [
    "## Select modules and stimuli"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vision_alone-11",
   "metadata": {},
   "outputs": [],
   "source": [
    "one_module = representations[representations.meta[\"module_name\"] == first.module_name]\n",
    "first_again = one_module[0]\n",
    "first_two_stimuli = representations.select(list(representations.stim_ids[:2]))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vision_alone-12",
   "metadata": {},
   "source": "## Related documentation\n\n- [Configure vision models and backends](vision_models)\n- [Integrate extraction with neural data](vision_union)\n- [Vision API](../api/vision.md)"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}