{
 "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> Image Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Bokeh</dd>\n",
    "  <dt>Backends</dt>\n",
    "    <dd><a href='./Image.ipynb'>Bokeh</a></dd>\n",
    "    <dd><a href='../matplotlib/Image.ipynb'>Matplotlib</a></dd>\n",
    "    <dd><a href='../plotly/Image.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",
    "from holoviews import opts\n",
    "hv.extension('bokeh')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Image represents a regularly sampled 2D grid of an underlying [continuous space](Continuous_Coordinates.ipynb) of intensity values, which will be colormapped on plotting. The grid of intensity values may be specified as a ``NxM`` sized array of values along with a bounds, but it may also be defined through explicit and regularly spaced x/y-coordinate arrays of shape ``M`` and ``N`` respectively. The two most basic supported constructors of an Image therefore include:\n",
    "\n",
    "    Image((X, Y, Z))\n",
    "\n",
    "where ``X`` is a 1D array of shape ``M``, ``Y`` is a 1D array of shape ``N`` and ``Z`` is a 2D array of shape ``NxM``, or equivalently:\n",
    "\n",
    "    Image(Z, bounds=(x0, y0, x1, y1))\n",
    "\n",
    "where ``Z`` is a 2D array of shape ``NxM`` defining the intensity values and the bounds define the (left, bottom, right, top) edges of four corners of the grid. Other gridded formats which support declaring of explicit x/y-coordinate arrays such as xarray are also supported. See the [Gridded Datasets](../../../user_guide/09-Gridded_Datasets.ipynb) user guide for all the other accepted data formats."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ls = np.linspace(0, 10, 200)\n",
    "xx, yy = np.meshgrid(ls, ls)\n",
    "\n",
    "bounds=(-1,-1,1,1)   # Coordinate system: (left, bottom, right, top)\n",
    "img = hv.Image(np.sin(xx)*np.cos(yy), bounds=bounds)\n",
    "img"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In recent versions of Bokeh, you can enable image hover to inspect the raw values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "opts.defaults(\n",
    "   opts.Image(tools=['hover']),\n",
    "   opts.Points (color='black', marker='x', size=20))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Slicing, sampling, etc. on an ``Image`` all operate in this continuous space, whereas the corresponding operations on a ``Raster`` work on the raw array coordinates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img + img[-0.5:0.5, -0.5:0.5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice how, because our declared coordinate system is continuous, we can slice with any floating-point value we choose. The appropriate range of the samples in the input numpy array will always be displayed, whether or not there are samples at those specific floating-point values. This also allows us to index by a floating value, since the ``Image`` is defined as a continuous space it will snap to the closest coordinate, to inspect the closest coordinate we can use the ``closest`` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "closest = img.closest((0.1,0.1))\n",
    "print('The value at position %s is %s' % (closest, img[0.1, 0.1]))\n",
    "img * hv.Points([img.closest((0.1,0.1))])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also easily take cross-sections of the Image by using the sample method or collapse a dimension using the ``reduce`` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img.sample(x=0) + img.reduce(x=np.mean)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The constructor of ``Image`` attempts to validate the input data by ensuring it is regularly sampled. In some cases, your data may be not be regularly sampled to a sufficiently high precision in which case you qill see an exception recommending the use of [``QuadMesh``](./QuadMesh.ipynb) instead. If you see this message and are sure that the ``Image`` element is appropriate, you can set the ``rtol`` value in the constructor to allow a higher deviation in sample spacing than the default of ``10e-6``. Alternatively, you can set this globally using ``hv.config.image_rtol`` as described in the [Installing and Configuring](../../../user_guide/Installing_and_Configuring.ipynb) user guide.\n",
    "\n",
    "One additional way to create Image objects is via the separate [ImaGen](https://github.com/pyviz-topics/imagen) library, which creates parameterized streams of images for experiments, simulations, or machine-learning applications.\n",
    "\n",
    "For full documentation and the available style and plot options, use ``hv.help(hv.Image).``"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}