Installation

The app

The easiest way to install PyJAMAS is using the app for MacOS-Intel, MacOS-Silicon and Windows 11, which can be downloaded here. HOWEVER, if you want to take advantage of machine learning models and GPU capabilities on MacOS or Windows machines, you should use the pypi installation as described below.

Known problems:

  1. Corrupt application / unidentified developer

In MacOS, depending on the security settings, running the app for the first time can cause an error message indicating that the application is broken or from an unidentified developer. Check this site for ways to allow PyJAMAS to run. Alternatively, open a Terminal and type:

$ xattr -cr /Applications/pyjamas.app

substituting “/Applications/pyjamas.app” with the path where PyJAMAS was installed. The same trick can be applied to the dmg file before installation:

$ xattr -cr pyjamas.dmg

Using pypi

Follow the steps below to install PyJAMAS from the pypi repository.

APPLE-INTEL

  1. Install Python 3.10.

  2. Download and install PyJAMAS by opening a terminal and typing:

    $ python -m pip install pyjamas-rfglab

APPLE-SILICON

  1. Install Python 3.10.

  2. Download and install PyJAMAS:

    $ python -m pip install pyjamas-rfglab

  3. PyJAMAS supports the use of the GPU on the Silicon chips. You just need to install tensorflow-metal:

    $ python -m pip install tensorflow-metal

Known problems:

  1. PyJAMAS uses PyQt6 to create a cross-platform user interface, but PyQt6 does not play well with MacOS Catalina or earlier MacOS versions. If you are using an old MacOS and cannot upgrade, you can still use the last version of PyJAMAS written with PyQt5:

    $ python -m pip install pyjamas-rfglab==2023.8.0

WINDOWS

  1. Install Python 3.10.

  2. Download and install PyJAMAS by opening a terminal and typing:

    $ python -m pip install pyjamas-rfglab

  3. PyJAMAS supports the use of CUDA-enabled GPUs in Windows. Please, check here (https://tensorflow.org/install/gpu) for instructions on how to configure your system. Briefly:

    1. Download and install the NVIDIA GPU drivers (https://www.nvidia.com/drivers).

    2. Download and install the CUDA Toolkit (https://developer.nvidia.com/cuda-toolkit-archive).

    3. Download and install the cuDNN SDK (https://developer.nvidia.com/cudnn and https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html).

Known problems:

  1. CUDA and cuDNN are picky with the version of each other that they talk to. If PyJAMAS displays an error that cusolver64_10.dll is not found:

    1. Go to the folder C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\V11.2\bin (replacing V11.2 by whichever version you installed).

    2. Create a copy of the file cusolver64_11.dll.

    3. Rename the copy as cusolver64_10.dll.

  2. Import skimage can cause the following error: “ImportError: DLL load failed while importing _rolling_ball_cy: The specified module could not be found.”. To fix the error:

    1. The error is caused because the system is missing the Microsoft C and C++ runtime libraries. These libraries are required by many applications built by using Microsoft C and C++ tools.

    2. Download and install the Microsoft C and C++ runtime libraries by running vcredist_x64.exe (https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170).

LINUX

  1. Install Python 3.10.

  2. Download and install PyJAMAS by opening a terminal and typing:

    $ python -m pip install pyjamas-rfglab

Known problems:

  1. In Linux systems, you will need permissions to install PyJAMAS globally. To restrict the PyJAMAS installation to the current user, install it with:

    $ python –m pip install --user --no-cache-dir -U pyjamas-rfglab

RUNNING PyJAMAS

  1. To run PyJAMAS, open a terminal and type:

    $ pyjamas

  2. The code for PyJAMAS can be found in the PyJAMAS folder under the Python site packages (e.g. /usr/local/lib/python3.10/site-packages in MacOS). The location of the source code is important to extend PyJAMAS using plugins. Alternatively, you can download the PyJAMAS source code from: https://bitbucket.org/rfg_lab/pyjamas/src/master/.

  3. PyJAMAS can be run from the source code by opening a terminal, navigating to the folder that contains the code, and typing:

    $ python -m pyjamas.pjscore

Known problems:

  1. The analysis of image batches in PyJAMAS can generate interactive Jupyter notebooks. Interactivity in Jupyter notebooks relies on ipywidgets, a package installed with PyJAMAS. Please, check the ipywidgets documentation if you have issues with interactivity in notebooks (e.g. there are no interactive features). Most often the following steps are sufficient to fix any issues:

    1. Download and install the Nodejs JavaScript runtime.

    2. Open a new terminal and execute the following command for JupyterLab:

    $ jupyter labextension install @jupyter-widgets/jupyterlab-manager

    or this one for Jupyter Notebook:

    $ jupyter nbextension enable --py widgetsnbextension

    1. Reopen your Jupyter server.

Using virtual environments

Virtual environments allow isolation of Python packages, preventing interference and incompatibilities between different package dependencies and versions thereof.

PyJAMAS can be used inside a virtual environment. We strongly recommend the use of conda environments.

conda

Download and install anaconda, miniconda or mamba. In a terminal or an anaconda power shell, create a virtual environment with:

$ conda create -n envpyjamas python=3.10

substituting 3.10 with the version of the Python interpreter that you would like to use, and envpyjamas with the name of the virtual environment. If you use mamba, use mamba instead of conda.

anaconda stores virtual environments within the folder that contains the anaconda distribution. You can find the location of your virtual environment with:

$ conda info --envs

Next, activate the environment with:

$ conda activate envpyjamas

Now you may proceed with the download and installation of PyJAMAS as above, using python as the name of the Python interpreter.

You can deactivate the virtual environment at any time with:

$ conda deactivate