03_numpy_interaction.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c0e52ae3",
   "metadata": {},
   "source": [
    "# Combining *PyDIP* and *NumPy*\n",
    "The following are some examples of using the *DIPlib* Python binding, *PyDIP*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "e5f54035",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "DIPlib -- a quantitative image analysis library\n",
      "Version 3.5.1 (Sep  5 2024)\n",
      "For more information see https://diplib.org\n"
     ]
    }
   ],
   "source": [
    "import diplib as dip\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "63d65b23",
   "metadata": {},
   "source": [
    "## Converting between images and arrays\n",
    "Casting a *NumPy* array to a *PyDIP* image does not incur a data copy. The array and the image will share data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "04108053",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.0\n"
     ]
    }
   ],
   "source": [
    "arr = np.zeros((3, 4))\n",
    "img = dip.Image(arr)\n",
    "img[0, 0] = 1\n",
    "print(arr[0, 0])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "07e22edb",
   "metadata": {},
   "source": [
    "For the reverse operation, the same is true when using `np.asarray()`, or `np.array(..., copy=False)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "880497fb",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[10]\n"
     ]
    }
   ],
   "source": [
    "img = dip.Image((5, 6), 1, \"UINT8\")\n",
    "arr = np.asarray(img)\n",
    "arr[2, 3] = 10\n",
    "print(img[3, 2])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b187d7e6",
   "metadata": {},
   "source": [
    "As you've noticed above, we reversed the indexing. *PyDIP*'s first dimension is horizontal (x), the second is vertical (y), etc. In *NumPy* the last dimensin is horizontal, the second to last vertical, etc.\n",
    "\n",
    "This can be confusing when combining *PyDIP* functionality with other image processing packages such as *scikit-image*. For this situation, it is possible to reconfigure *PyDIP* to reverse its dimensions, to match *NumPy*'s (we won't call this function right now)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "301c76e0",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function ReverseDimensions in module diplib.PyDIP_bin:\n",
      "\n",
      "ReverseDimensions(...) method of builtins.PyCapsule instance\n",
      "    ReverseDimensions() -> None\n",
      "\n",
      "    By default, DIPlib uses the (x,y,z) index order. This order is reversed from\n",
      "    how NumPy (and, by extension, packages such as scikit-image, matplotlib and\n",
      "    imageio) index. Calling `ReverseDimensions()` causes DIPlib, for the remainder\n",
      "    of the session, to also follow the (z,y,x) index order, giving dimensions the\n",
      "    same order as Python users might be used to. Use this function at the top of\n",
      "    your program, right after importing the `diplib` package. There is no way to\n",
      "    revert to the default order. Please don't try to mix dimension ordering within\n",
      "    your program.\n",
      "\n",
      "    See dip.AreDimensionsReversed().\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(dip.ReverseDimensions)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "118fb4aa",
   "metadata": {},
   "source": [
    "When converting a tensor image (e.g. a color image) to an array, the tensor dimension will be the last array dimension."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "14fda101",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(60, 50, 3)\n"
     ]
    }
   ],
   "source": [
    "img = dip.Image((50, 60), 3, \"UINT8\")\n",
    "arr = np.asarray(img)\n",
    "print(arr.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40fed6c4",
   "metadata": {},
   "source": [
    "When converting an array to an image, there is no indication of whether there is a tensor dimension, and which one it is. So, *PyDIP* uses a simple heuristic to guess if the array represents a tensor (or color) image:\n",
    " - if the array has more than two dimensions, and\n",
    " - the first or the last dimension has 4 or fewer elements,\n",
    "then that dimension is the tensor dimension. Thus, only the first or last dimension is ever considered. We chose 4 as a threshold to catch both RGB and RGBA images."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "d2aacc79",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<Tensor image (3x1 column vector, 3 elements), UINT8, sizes {50, 60}>\n"
     ]
    }
   ],
   "source": [
    "a = dip.Image(arr)\n",
    "print(a.__repr__())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "61d77d7e",
   "metadata": {},
   "source": [
    "Note that the image is not marked as being a color image. One has to manually add this informaiton if it is relevant:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "8a430cb1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<Color image (3x1 column vector, 3 elements, sRGB), UINT8, sizes {50, 60}>\n"
     ]
    }
   ],
   "source": [
    "a = dip.Image(arr)\n",
    "a.SetColorSpace('sRGB')\n",
    "print(a.__repr__())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "760eb516",
   "metadata": {},
   "source": [
    "## Calling *NumPy* functions with an image\n",
    "When calling a *NumPy* with a `dip.Image` object as input, the output of the *NumPy* function will be a *NumPy* array, just as if the function had been called with an array as input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "3b833167",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'numpy.ndarray'>\n",
      "(9000,)\n",
      "uint8\n"
     ]
    }
   ],
   "source": [
    "a = np.ravel(img)\n",
    "print(type(a))\n",
    "print(a.shape)\n",
    "print(a.dtype)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e969d35f",
   "metadata": {},
   "source": [
    "## Calling PyDIP functions with an array\n",
    "When calling a *PyDIP* function with a `np.array` object as input, the output will be a `dip.Image` object, just as if the function had been called with an array as input. In fact, the array is cast to an image exactly as described earlier."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "4bd76921",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<Tensor image (3x1 column vector, 3 elements), SFLOAT, sizes {50, 60}>\n"
     ]
    }
   ],
   "source": [
    "a = dip.Gauss(arr)\n",
    "print(a.__repr__())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d4f24f1",
   "metadata": {},
   "source": [
    "The `out` keyword argument to *PyDIP* functions is easier to use with a `dip.Image` object than with a `np.array` object. When passing in an image object, the image can be reforged (meaning its data segment can be reallocated, changing the size, number of tensor elements, and/or data type). The same is not true for an input of a different type, which will be converted to a protected `dip.Image` object (see [the documentation on the protect flag](https://diplib.org/diplib-docs/dip-Image.html#protect)). This means that it must have the right sizes to receive the output of the function. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "6ebbb775",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[31mParameterError exception: Image is protected\n"
     ]
    }
   ],
   "source": [
    "a = np.zeros(10)\n",
    "try:\n",
    "    dip.Gauss(img, out=a)\n",
    "except Exception as e:\n",
    "    print(f\"\\033[31m{type(e).__name__} exception:\", str(e).split('\\n')[0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "39298fef",
   "metadata": {},
   "outputs": [],
   "source": [
    "a = np.zeros((60, 50, 3))\n",
    "dip.Gauss(img, out=a)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "007e3598",
   "metadata": {},
   "source": [
    "Note how the filter is computed in the output type, 64-bit float in this case.\n",
    "\n",
    "This is most useful to work in-place, where the feature is easy to use:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "47b643eb",
   "metadata": {},
   "outputs": [],
   "source": [
    "dip.Gauss(arr, out=arr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ed74d4e3",
   "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.12.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}