Installation

Requirements

Crappy was successfully installed and tested on Linux (Ubuntu 18.04 and higher), Windows (8 and higher) and MacOS (Sierra and higher). It was also successfully installed on Raspberry Pi 3B+ and 4B. As a Python module, Crappy can probably be installed on other systems able to run Python, but that was not tested.

Note

We develop Crappy on recent OS versions, and no particular effort is made to ensure compatibility with older OS versions.

Crappy requires Python 3.6 or later, as well as the following module :

  • numpy (1.21.0 or higher)

The following modules are not mandatory but will provide additional functionalities (this list is not exhaustive) :

  • matplotlib (1.5.3 or higher, for plotting graphs and displaying images)

  • opencv (3.0 or higher, to perform image acquisition and processing)

  • pyserial (To interface with serial sensors and actuators)

  • Tk (For the configuration interface of cameras)

  • scikit-image (0.11 or higher)

  • Simple-ITK (for faster image recording)

  • PyCUDA (for GPU accelerated features)

Note

Knowing which modules are needed for a given setup is easy. Just write the script and start it, if a module is missing Crappy will simply tell you !

1. Check your Python version

Before installing Crappy, first check that you have a compatible version of Python installed. You can get the current version of Python by running python --version in a console. The version should then be displayed, e.g. Python 3.9.7.

Note

On Windows, Python is not natively installed and might not be present at all ! In this case, the given command will display an error message.

If the current version of Python is not compatible with Crappy (requires Python >=3.6), or if Python is not installed, you will first need to install a compatible version of Python. The precise installation steps for each OS are beyond the scope of this documentation.

Note

On Linux and MacOS, you will likely need to install the new version of Python alongside the original version. Never uninstall the original version, or your system will break !

2. Deploy a virtual environment (optional)

It is recommended to install Crappy in a virtual environment, to avoid conflicts with other Python packages installed at the user or system level. This step is however not mandatory,and it is possible to install and run Crappy at the user level.

To create an virtual environment called venv_crappy, run the following command at the location of your choice.

python -m venv venv_crappy

This should create a new folder called venv_crappy at the location of your console, containing an independent install of Python.

3. Install Crappy

Once you have a compatible version of Python installed, and after optionally setting up a virtual environment, you’re ready to install Crappy. A single line of code is necessary to install Crappy :

python -m pip install crappy

Following th same pattern, you can also install any additional module that you would need to use along with Crappy. For example :

python -m pip install matplotlib

Note

You can install at once most of the modules necessary for a specific use of Crappy by using the so-called extras. To do so, simply run :

python -m pip install crappy[<extra>]

The available extras are SBC, image, hardware and main. They contain respectively modules for interfacing with single board computers, for recording and displaying images and videos, for interfacing with hardware over serial or USB, and main contains the three most used modules in Crappy after the mandatory Numpy.

4. Check your install

Once you have installed Crappy, you can run a few checks to make sure it works fine on your system. First, try to simply import it :

python -c "import crappy;print(crappy.__version__)"

This command should return without an error and print the installed version of Crappy. If that is not the case, please refer to the Troubleshooting page of the documentation.

If you can successfully import Crappy, you can then try to run a few examples to confirm that Crappy operates as expected. The examples folder of the GitHub repository contains a wide collection of readily-runnable examples. To execute a test script called example.py, run the following lines in a console :

python example.py

If you’re successful with all these steps, congratulations ! You just installed Crappy on your machine ! We wish you success in your work.