{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"contentcontainer med left\" style=\"margin-left: -50px;\">\n",
    "<dl class=\"dl-horizontal\">\n",
    "  <dt>Title</dt> <dd> ImageStack Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Bokeh</dd>\n",
    "  <dt>Backends</dt>\n",
    "    <dd><a href='../bokeh/ImageStack.ipynb'>Bokeh</a></dd>\n",
    "    <dd><a href='../matplotlib/ImageStack.ipynb'>Matplotlib</a></dd>\n",
    "    <dd><a href='../plotly/ImageStack.ipynb'>Plotly</a></dd>\n",
    "</dl>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import holoviews as hv\n",
    "hv.extension('plotly')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "``ImageStack`` facilitates the representation of a regularly spaced 2D grid within a continuous domain of color space values (RGB(A)). The grid's structure aligns closely with that of an Image element. In its simplest form, the grid can be defined through an array with dimensions of ``NxMxL``, where ``L`` represents the number of channels. Alternatively, explicit and uniformly spaced x/y-coordinate arrays can also define the ``ImageStack``.\n",
    "\n",
    "The core methods for constructing an ``ImageStack`` are:\n",
    "\n",
    "1. Creating using coordinates and channel values:\n",
    "   ```\n",
    "   ImageStack((X, Y, L1, L2, ..., LL), vdims=[\"l1\", \"l2\", ... \"ll\"])\n",
    "   ```\n",
    "   Here, ``X`` is a 1D array with ``M`` elements, ``Y`` is a 1D array with ``N`` elements, and ``L1``, ``L2``, ..., ``LL`` represent 2D arrays with dimensions ``NxM``.\n",
    "\n",
    "2. Creation through a composite array and bounds specification:\n",
    "   ```\n",
    "   ImageStack(Z, bounds=(x0, y0, x1, y1))\n",
    "   ```\n",
    "   In this scenario, ``Z`` is a 3D array with dimensions ``NxMxL``, and the bounds parameter defines the (left, bottom, right, top) corners of the grid.\n",
    "\n",
    "For comprehensive information, refer to the [Gridded Datasets](../../../user_guide/09-Gridded_Datasets.ipynb) user guide.\n",
    "\n",
    "*Note* The `datashader` library must be installed to use ``ImageStack`` with the plotly backend."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.arange(0, 3)\n",
    "y = np.arange(5, 8)\n",
    "a = np.array([[np.nan, np.nan, 1], [np.nan] * 3, [np.nan] * 3])\n",
    "b = np.array([[np.nan] * 3, [1, 1, np.nan], [np.nan] * 3])\n",
    "c = np.array([[np.nan] * 3, [np.nan] * 3, [1, 1, 1]])\n",
    "\n",
    "img_stack = hv.ImageStack((x, y, a, b, c), kdims=[\"x\", \"y\"], vdims=[\"a\", \"b\", \"c\"])\n",
    "img_stack"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Slicing, sampling, etc. on an ``ImageStack`` all operate in this continuous space, whereas the corresponding operations on a ``Raster`` work on the raw array coordinates.\n",
    "\n",
    "Here we take slices up to x=0.5 and y=7, which is out of bounds for the red."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img_stack[:0.5, :7]"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}