doc/01-Starting-PyImageJ.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook is part of the PyImageJ [Tutorial Series](./notebooks.rst), and assumes familiarity with the ImageJ API. Dedicated tutorials for ImageJ can be found [here](https://imagej.net/tutorials/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1 Starting ImageJ from Python\n",
    "\n",
    "The [pyimagej](https://pypi.org/project/pyimagej/) module enables access to the entire ImageJ API from Python in a natural way.\n",
    "\n",
    "Let's initialize an ImageJ gateway including Fiji plugins, at a reproducible version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ImageJ version: 2.5.0/1.53r\n"
     ]
    }
   ],
   "source": [
    "import imagej\n",
    "\n",
    "# initialize ImageJ\n",
    "ij = imagej.init('sc.fiji:fiji:2.5.0')\n",
    "print(f\"ImageJ version: {ij.getVersion()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1.1 Ways to initialize\n",
    "\n",
    "| Requirement                                            | Code<sup>1</sup>                                                  | Reproducible?<sup>2</sup> |\n",
    "|:-------------------------------------------------------|:------------------------------------------------------------------|:-------------------------:|\n",
    "| Newest available version of ImageJ2 w/ ImageJ support  | `ij = imagej.init()`                                              | NO                        |\n",
    "| Specific version of ImageJ2 w/ ImageJ support          | `ij = imagej.init('2.5.0')`                                       | YES                       |\n",
    "| Interactive (newest version)*                          | `ij = imagej.init(mode='interactive')`                            | NO                        |\n",
    "| Interactive (specific version)*                        | `ij = imagej.init('net.imagej:imagej:2.5.0', mode='interactive')` | YES                       |\n",
    "| Without support for original ImageJ (newest versions)  | `ij = imagej.init('net.imagej:imagej', add_legacy=False`          | NO                        |\n",
    "| With Fiji plugins (newest version)                     | `ij = imagej.init('sc.fiji:fiji')`                                | NO                        |\n",
    "| With Fiji plugins (specific version)                   | `ij = imagej.init('sc.fiji:fiji:2.5.0')`                          | YES                       |\n",
    "| From a local installation                              | `ij = imagej.init('/Applications/Fiji.app')`                      | DEPENDS                   |\n",
    "\n",
    "*: _`mode='interactive'` is unavailalbe on macOS. Instead use `mode='gui'`. When set to `gui` mode the Python interpeter is blocked and no longer interactive. Check out the [initialization](Initialization.md) documentation for more information._\n",
    "\n",
    "<sup>1</sup> pyimagej uses [`jgo`](https://github.com/scijava/jgo) internally to call up ImageJ, so all of these initializations are tied to the usage of `jgo`. You can read up on the [usage of `jgo`](https://github.com/scijava/jgo#usage) to find out more about this initialization.\n",
    "\n",
    "<sup>2</sup> ___Reproducible___ means code is stable, executing the same today, tomorrow, and in years to come. While it is convenient and elegant to depend on the newest version of a program, behavior may change when new versions are released—for the better if bugs are fixed; for the worse if bugs are introduced—and people executing your notebook at a later time may encounter broken cells, unexpected results, or other more subtle behavioral differences. You can help avoid this pitfall by pinning to a specific version of the software. The British Ecological Society published [Guide to Better Science: Reproducible Code](https://www.britishecologicalsociety.org/wp-content/uploads/2018/12/BES-Reproducible-Code.pdf) diving into the relevant challenges in more detail, including an [R](https://www.r-project.org/)-centric illustration of best practices. A web search for `reproducible python` also yields several detailed articles."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1.2 The ImageJ2 gateway\n",
    "\n",
    "The ImageJ2 gateway is the object interface that lets you use ImageJ-related\n",
    "features (see [Initialization.md](Initialization.md)).  This gateway contains\n",
    "all of the regular ImageJ2 Java functions. PyImageJ also adds a module of\n",
    "convenience functions under `ij.py`. For example, converting a numpy array to\n",
    "an ImageJ2 dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(3, 4, 5)\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "\n",
    "array = np.random.rand(5, 4, 3)\n",
    "dataset = ij.py.to_java(array)\n",
    "\n",
    "print(dataset.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1.3 Increasing the memory available to Java\n",
    "\n",
    "Java's virtual machine (the JVM) has a \"max heap\" value limiting how much\n",
    "memory it can use. You can increase it:\n",
    "\n",
    "```python\n",
    "import imagej\n",
    "import scyjava\n",
    "scyjava.config.add_options('-Xmx6g')\n",
    "ij = imagej.init()\n",
    "```\n",
    "\n",
    "Replace `6g` with the amount of memory Java should have. You can also pass\n",
    "[other JVM arguments](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html).\n",
    "\n",
    "Without having specified the max heap value explicitly, here is how much memory this notebook's JVM has available:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'ImageJ2 2.5.0/1.53r; Java 11.0.15-internal [amd64]; 305MB of 16016MB'"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ij.getApp().getInfo(True)"
   ]
  }
 ],
 "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.10.6"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": true,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "307px"
   },
   "toc_section_display": true,
   "toc_window_display": true
  },
  "vscode": {
   "interpreter": {
    "hash": "fd4de699765e9fab70e2644720b91b55c1a435ebb41ccdac66a2b7a412168f61"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}