{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Usage Guide"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# only use this next line if in a notebook\n",
    "%matplotlib ipympl\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "from mpl_image_segmenter import ImageSegmenter\n",
    "from mpl_image_segmenter.example_images import color_image_stack, gray_image_stack"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# load a sample image\n",
    "\n",
    "gray_image_stack = gray_image_stack()\n",
    "color_image_stack = color_image_stack()\n",
    "example_color_image = color_image_stack[0]\n",
    "example_gray_image = gray_image_stack[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Single class - Single Gray Image\n",
    "\n",
    "\n",
    "A single grayscale image (shape `(Y, X)`) and only class in the segmentation mask is the simplest use case.\n",
    "\n",
    "\n",
    "You can click and drag to select regions. Scroll to zoom and middle click to pan are provided by the [mpl-pan-zoom](https://mpl-pan-zoom.rtfd.io/) library.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-output"
    ]
   },
   "outputs": [],
   "source": [
    "segmenter = ImageSegmenter(\n",
    "    example_gray_image,\n",
    "    figsize=(7, 7),\n",
    ")\n",
    "display(segmenter)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Erasing\n",
    "\n",
    "To start erasing instead of selecting set `segmenter.erasing = True`. Run the following cell then try to lasso an area you have already selected"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "segmenter.erasing = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Looking at the mask.\n",
    "\n",
    "The mask is accessible via {obj}`.ImageSegmenter.mask`. `0` is used as the value of unselected regions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "segmenter.mask"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Single class - Single Color Image\n",
    "\n",
    "If you have a RGB(A) image, i.e. with shape `(Y, X, 3)` or `(Y, X, 4)` then you must pass `color_image=True` to the `ImageSegmenter` constructor in order to have the shapes behave approriately.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "ImageSegmenter(example_color_image, color_image=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Multiple classes\n",
    "\n",
    "You can use multiple classes in the mask with the `classes` argument. It accepts either an integer, or an iterable class names as string.\n",
    "\n",
    "\n",
    "You can change which class is currently being drawn on the mask using the `.current_class` attribute. This can always be set to an `integer`, or if you are using named classes you can also set it to the name of the class you want to draw.\n",
    "\n",
    "\n",
    "```{warning}\n",
    "The class index is *NOT* zero indexed. This is because class `0` is always the background.\n",
    "```\n",
    "\n",
    "**colors**\n",
    "\n",
    "By default the `tab10` color set will be used, and if that is not enough the xkcd color named colors will be used. Or you can pass a list of colors via the `mask_colors` argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "segmenter = ImageSegmenter(example_gray_image, classes = [\"class1\", \"class2\", \"class3\"])\n",
    "# segmenter = ImageSegmenter(gray_image, classes = 3)\n",
    "\n",
    "# set the class \n",
    "segmenter.current_class = 1 # same as setting to `class1`\n",
    "segmenter.current_class = \"class2\" # same as setting to 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Image Stacks\n",
    "\n",
    "For both gray and color images you can pass in an array-like stack of images (i.e. shape `(N, Y, X, [3])` and then switch which image is currently active using the `image_index` property."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "segmenter = ImageSegmenter(gray_image_stack)\n",
    "segmenter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# change which image is displayed\n",
    "segmenter.image_index = 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# The mask will now be multidimensional as well\n",
    "\n",
    "segmenter.mask.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## pre-seedng a mask\n",
    "\n",
    "You can also load an existing mask. You will need to ensure that it does not have values greater than `nclasses` and that it has the same shape as the image. There are currently no safegaurds for this and when there are exceptions in a matplotlib callback they can be hard to see in the notebook - so be careful!\n",
    "\n",
    "\n",
    "If you run the below cell the image should show up with the premade mask already applied!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-output"
    ]
   },
   "outputs": [],
   "source": [
    "from mpl_image_segmenter.example_images import example_mask_stack\n",
    "mask = example_mask_stack()\n",
    "preloaded = ImageSegmenter(gray_image_stack, classes=3, mask=mask)\n",
    "display(preloaded)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Styling\n",
    "\n",
    "\n",
    "### imshow parameters\n",
    "\n",
    "You can modify the display of the image using any kwargs accepted the [imshow](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.imshow.html) command. For example set the colormap with the `cmap` argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(1,2)\n",
    "gray = ImageSegmenter(example_gray_image, cmap=\"gray\", ax=axs[0])\n",
    "plasma = ImageSegmenter(example_gray_image, cmap=\"plasma\",ax=axs[1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## LassoSelector line\n",
    "\n",
    "You can change the appearance of the LassoSelector line using the `props` kwarg.  So to make the line very thick and red:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "props = {\"color\": \"red\", \"linewidth\": 10}\n",
    "seg = ImageSegmenter(\n",
    "    example_gray_image, figsize=(5, 5), cmap=\"gray\", props=props\n",
    ")\n",
    "display(seg)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.0"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}