Merge pull request #133 from rohangirishrao/installation-instructions

Add installation instructions

Author: ehrenfeu

README.md

@@ -10,28 +10,81 @@
 [![DOI](https://zenodo.org/badge/156891364.svg)][doi]
 
 This package contains a diverse collection of Python functions dealing with
-paths, I/O (file handles, ...), strings etc. and tons of [Fiji][fiji] /
-[ImageJ2][imagej] convenience wrappers to simplify scripting and reduce
-cross-script redundanciees.
+paths, I/O (file handles, ...), strings etc. and tons of [Fiji] / [ImageJ2]
+convenience wrappers to simplify scripting and reduce cross-script redundancies.
 
 Initially this has been a multi-purpose package where a substantial part had
-been useful in **CPython** as well. However, since the latest Jython
-release is still based on Python 2.7 (see the [Jython 3 roadmap][jython3] for
-more info), *imcflibs* is now basically limited to the **Fiji / ImageJ2
-ecosystem**.
+been useful in **CPython** as well. However, since the latest Jython release is
+still based on Python 2.7 (see the [Jython 3 roadmap][jython3] for more info),
+*imcflibs* is now basically limited to the **Fiji / ImageJ2 ecosystem**.
 
 Releases are made through Maven and published to the [SciJava Maven
 repository][sj_maven]. The easiest way to use the lib is by adding the **`IMCF
 Uni Basel`** [update site][imcf_updsite] to your ImageJ installation.
 
 The [`pip install`able package][pypi] is probably only useful for two cases:
 running `pytest` (where applicable) and rendering [HTML-based API docs][apidocs]
-using [`pdoc`][pdoc]. Let us know in case you're having another use case 🎪 for
-it.
+using [pdoc]. Let us know in case you're having another use case 🎪 for it.
 
 Developed and provided by the [Imaging Core Facility (IMCF)][imcf] of the
 Biozentrum, University of Basel, Switzerland.
 
+## Installation Instructions
+
+Two ways of installing the `imcflibs` package are described here, the "*easy*"
+one through the *Fiji Update Sites* and the "*manual*" method using packages
+explicitly downloaded from [SciJava Maven][sj_maven].
+
+### 🧿 Default: Installation via Update Sites
+
+After a fresh install of [Fiji], navigate to *Help* -> *Update* and in the
+resulting window, press *Manage Update Sites*. Here, search for and tick the
+following necessary update sites for this package.
+
+- ImageJ
+- Fiji
+- 3D ImageJ-Suite
+- clij2
+- IJPB-plugins
+- IMCF Uni Basel
+- StarDist
+- CALM
+- TrackMate-Cellpose
+- TrackMate-Helper
+- TrackMate-StarDist
+- TrackMate-Weka
+- TrackMate-MorpholibJ
+
+The **`IMCF Uni Basel`** update-site will always provide the latest compatible
+combination of *official*`.jar` file to use this package.
+
+### 🏗 Alternative: SciJava Maven Package 👷
+
+💡 **IMPORTANT:** 💡 same as for the *default* installation previously
+described, you will need to enable **all Update Sites listed above** in your
+Fiji as well when using the method described here!
+
+The most up-to-date `.jar` (or any other published version, including
+pre-releases) for this package can be always found on the [Scijava Maven
+repository][sj_maven]. Navigate to the `python-imcflibs` folder, pick the
+desired version (can also be a pre-release) and download the contained `.jar`
+file, e.g. `python-imcflibs-2.0.0.jar`.
+
+Then simply that file in the `jars` folder of your Fiji installation, e.g
+`D:\Development\Fiji.app\jars\` or `/opt/Fiji.app/jars/`, possibly removing
+other versions of the same package from that folder - then (re-)start Fiji.
+
+If you'd prefer to use the cutting-edge version from GitHub, look into the
+[development instructions](DEVELOPMENT.md) for details.
+
+### Installation Testing
+
+To check the package's correct installation in Fiji, search for *Script
+Interpreter* in the Search bar, and type `:lang python`, followed by e.g.
+`import imcflibs.imagej.misc`. If no errors are shown, the installation was
+successful. Alternatively, you can scroll in the sidebar of the Interpreter to
+search for imcflibs.
+
 ## Example usage
 
 ### Shading correction / projection
@@ -50,17 +103,17 @@ correct_and_project(raw_image, out_path, model, "Maximum", ".ics")
 
 ### Split TIFFs by channels and slices
 
-* See the [Split_TIFFs_By_Channels_And_Slices.py][script_split] script.
+- See the [Split_TIFFs_By_Channels_And_Slices.py][script_split] script.
 
 ### Use status and progress bar updates
 
-* See the [FluoView_OIF_OIB_OIR_Simple_Stitcher.py][script_fvstitch] script.
+- See the [FluoView_OIF_OIB_OIR_Simple_Stitcher.py][script_fvstitch] script.
 
 [imcf]: https://www.biozentrum.unibas.ch/imcf
-[imagej]: https://imagej.net
+[imagej2]: https://imagej.net
 [fiji]: https://fiji.sc
 [jython3]: https://www.jython.org/jython-3-roadmap
-[sj_maven]: https://maven.scijava.org/#nexus-search;gav~ch.unibas.biozentrum.imcf~~~~
+[sj_maven]: https://maven.scijava.org/service/rest/repository/browse/releases/ch/unibas/biozentrum/imcf/
 [imcf_updsite]: https://imagej.net/list-of-update-sites/
 [script_split]: https://github.com/imcf/imcf-fiji-scripts/blob/master/src/main/resources/scripts/Plugins/IMCF_Utilities/Convert/Split_TIFFs_By_Channels_And_Slices.py
 [script_fvstitch]: https://github.com/imcf/imcf-fiji-scripts/blob/master/src/main/resources/scripts/Plugins/IMCF_Utilities/Stitching_Registration/FluoView_OIF_OIB_OIR_Simple_Stitcher.py