Installation

Although Pyctools has been written for Linux computers, the cross-platform nature of Python means it can also be installed on Windows and (probably) MacOS computers. (I’ve tested Windows installation on a virtual machine, but don’t have a MacOS machine to test it with.)

Pyctools requires Python 3 and its package manager pip. These are probably already installed on Linux computers, but may need to be installed on Windows and MacOS. Python installers can be downloaded from https://www.python.org/downloads/.

I strongly recommend using a Python virtual environment to install Pyctools. This isolates your Pyctools setup from other Python software on your computer, preventing possible clashes over required versions of some dependencies.

After creating a virtual environment for Pyctools, activate it and update its copy of pip:

$ python3 -m venv --system-site-packages pyctools
$ source pyctools/bin/activate
(pyctools) $ python -m pip install -U pip
Collecting pip
  Using cached pip-21.3.1-py3-none-any.whl (1.7 MB)
Installing collected packages: pip
  Attempting uninstall: pip
    Found existing installation: pip 20.0.2
    Uninstalling pip-20.0.2:
      Successfully uninstalled pip-20.0.2
Successfully installed pip-21.3.1

Note the use of --system-site-packages when creating the virtual environment. This allows access to system wide Python packages, preventing unnecessary duplication in the virtual environment.

Now you can install Pyctools:

(pyctools) $ pip install pyctools-core
Collecting pyctools-core
  Downloading pyctools_core-0.7.0.tar.gz (396 kB)
     |████████████████████████████████| 396 kB 916 kB/s
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
Requirement already satisfied: numpy<2 in /usr/lib64/python3.6/site-packages (from pyctools-core) (1.17.3)
Collecting exiv2>=0.11
  Using cached exiv2-0.17.1-cp36-cp36m-manylinux_2_28_x86_64.whl (15.1 MB)
Requirement already satisfied: pillow in /usr/lib64/python3.6/site-packages (from pyctools-core) (8.4.0)
Requirement already satisfied: docutils in /usr/lib/python3.6/site-packages (from pyctools-core) (0.14)
Building wheels for collected packages: pyctools-core
  Building wheel for pyctools-core (pyproject.toml) ... done
  Created wheel for pyctools-core: filename=pyctools.core-0.7.0-cp36-cp36m-linux_x86_64.whl size=621929 sha256=ed40977bab66c9ae1655f6a0766660542b8b2871a858c569fd5fe1dd25853a43
  Stored in directory: /home/jim/.cache/pip/wheels/2e/ed/d4/233ab864b806a264d7573d0f37ceeb6ac1adf08413c790dc97
Successfully built pyctools-core
Installing collected packages: exiv2, pyctools-core
Successfully installed exiv2-0.17.1 pyctools-core-0.7.0

Note that the pyctools-core package is compiled during installation. This is because it contains some components that aren’t pure Python. Compiling these components from “C” enables them to run much faster.

On Windows you may get an error message like “Microsoft Visual C++ 14.0 or greater is required.” Fortunately MicroSoft provide a free compiler which you can download from https://visualstudio.microsoft.com/visual-cpp-build-tools/. Select the “Desktop development with C++” option in the Visual Studio Installer.

After you have successfully installed Pyctools you can test it by running the pyctools-editor GUI. If you get a “ModuleNotFoundError: No module named ‘PyQt5’” error then you need to install one of PyQt5, PyQt6, PySide2, or PySide6, e.g. pip install pyqt6. (Note that pip package names are case insensitive.)

Pyctools has several optional dependencies that provide extra features as detailed below.

Dependencies

On Linux these dependencies can usually be installed with the distribution’s package manager application. Most are also available from the Python Package Index (PyPI). These will often be newer versions. The pip command should be used to install packages from PyPI. Do not run pip as root (e.g. with sudo) as this may corrupt your operating system. If you are not using a virtual environment then use pip install --user to install in your local user directory.

NumPy

If NumPy is already installed, the command python3 -c 'import numpy' should run without error.

NumPy should be installable with a Linux system’s package manager. Be sure to get the “development headers” version (probably has -dev or -devel in the name) to allow Cython extensions that use NumPy to be compiled. Alternatively it can be installed with pip:

pip3 install --user -U numpy

(The -U option will upgrade any existing installation.)

python-exiv2

Use pip to install python-exiv2:

pip3 install --user -U exiv2

OpenCV

OpenCV is an optional dependency. If it is not installed then some Pyctools components will not be usable.

If OpenCV is already installed the python3 -c 'import cv2' command will run without error.

OpenCV should be installable with a Linux system’s package manager. You need to install the Python bindings as well as the core library.

FFmpeg

FFmpeg is used to read and write video files. If you are only interested in still image processing then it is not required.

The ffmpeg -h command will show if FFmpeg is already installed.

FFmpeg should be installable with a Linux system’s package manager. Installing it on Windows is not so easy.

rawkit

The pyctools.components.io.rawimagefilereader component uses rawkit to read raw image files such as the CR2 format produced by Canon cameras. If you need to process raw images you can install rawkit using pip:

pip3 install --user rawkit

rawpy

The pyctools.components.io.rawimagefilereader2 component uses rawpy to read raw image files such as the CR2 format produced by Canon cameras. If you need to process raw images you can install rawpy using pip:

pip3 install --user rawpy

PyQt or PySide

The Pyctools visual editor uses the Qt graphics system via a Python package. Pyctools can use any one of PyQt5, PyQt6, PySide2, or PySide6.

At least one of these should be installable with your system’s package manager.

PyOpenGL

PyOpenGL is an optional dependency. If it is not installed then the pyctools.components.qt.qtdisplay component will not be usable.

If PyOpenGL is already installed the python3 -c 'import OpenGL' command will run without error.

PyOpenGL should be installable with a Linux system’s package manager. It may be called python-opengl or similar.

pillow

The easiest way to install pillow is with pip:

pip3 install --user pillow

Pyctools core

Although Pyctools can be installed from PyPI, it may be better to clone the GitHub repo. Cloning the repo makes it easy to keep up to date with a git pull command.

Clone the repo and install Pyctools as follows:

git clone https://github.com/jim-easterbrook/pyctools.git
cd pyctools
pip3 install --user .

You can easily install most of the dependencies at the same time with pip3 install --user .[all].

Documentation

Pyctools documentation is available online but it’s sometimes useful to have a local copy. A local copy may be more up to date and should include documentation of all your installed components, not just the core Pyctools ones. The documentation is built using a package called Sphinx, available from PyPI:

pip3 install --user Sphinx

Having installed Sphinx you can use utils/build_docs.py to build the documentation:

cd pyctools
python3 utils/build_docs.py

The documentation can be read with any web browser. The start page is doc/html/index.html.

Pyctools extras

It is hoped that there will be an increasing number of extra Pyctools packages to expand the range of components available. So far I’ve written a PAL coder / decoder simulation package and a package of extra components that probably aren’t general enough to include in the core distribution. These packages also demonstrate how Pyctools can be extended. They are installed in the usual way:

git clone https://github.com/jim-easterbrook/pyctools-pal.git
cd pyctools-pal
pip3 install --user .

git clone https://github.com/jim-easterbrook/pyctools-jim.git
cd pyctools-jim
pip3 install --user .

Comments or questions? Please email jim@jim-easterbrook.me.uk.