Tut_installation

This tutorial is written for VOP v0.6.1

Prerequisites

This tutorial is made to help getting the VOP up and running on a fresh setup. It does however make some assumptions on the hardware and software that you are using.

• I have only tested this software on PiOS Lite. So get that installed first.
• You need SSH access to your Pi that will run the VOP. Through network cable or wifi.
• Before proceeding. Connect your HDMI monitor to your Pi through HDMI1. You will probably need a microHDMI to HDMI adapter or cable.
• This software is written with the Pi Camera HQ in mind. Connect it with the ribbon cable.
• Point the camera to the HDMI-monitor.

If you need help with any steps. I can only say what works for me in my own setup. And I barely know that.

Installation

When the above is done, I am assuming you have ssh'd into your pi, it has internet access and you see the prompt alive and well in your terminal of choice.

Part 1 - Dependencies

Firstly. The Pi needs some underlying system libraries to handle video encoding, DRM/KMS display output, and OpenGL ES. You should be able to install them with the following command:

sudo apt update
sudo apt install -y git python3-pip python3-venv python3-dev ffmpeg \
libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-dev libsdl2-image-dev \
libgl1-mesa-dri libegl1 libgles2 libx11-dev rpicam-apps

Why these packages?

• git - Used to clone the VOP repository directly from Codeberg.
• python3-pip - The package installer required to fetch the Python dependencies later.
• python3-venv - Provides the module to create isolated Python environments, which is strictly enforced by modern Debian.
• ffmpeg - Handles backend video encoding, decoding, and media processing.
• libsdl2-2.0-0 - The core Simple DirectMedia Layer library. This allows Pygame to draw directly to the hardware framebuffer via KMS/DRM without an x11 or Wayland desktop.
• libsdl2-image-2.0-0 - An extension for SDL2 required to load various image formats.
• libgl-mesa-dri - Provides the Direct Rendering Infrastructure (DRI) drivers for hardware accelerated OpenGL.
• libegl1 - The EGL interface. This acts as the bridge between OpenGL ES and the underlying hardware display system.
• libgles2 - Provides the OpenGL ES 2.0 API, which is essential for Modern GL to execute the hardware -accelerated projection mapping on embedded GPUs.
• rpicam-apps - Contains the rpicam-still binary required by the engine to capture raw sensor data from the Pi Camera
• python3-dev - Provides the C header files required to compile Python packages from source
• libx11-dev - Provides the X11 Window System headers required by the glcontext compiler, even though this will be running headless.

Part 2 - Download the VOP

• Move to the folder where you want to install the VOP.

• Clone the repository from Codeberg and move into the newly created directory.

git clone https://codeberg.org/jmalmsten-com/VOP.git
cd VOP

Part 3 - Create a Virtual Environment

Modern Raspberry Pi OS strongly enforces Python Virtual Environments (venv) to prevent PIP from breaking system-level Python tools.

# Create the environment inside the VOP folder
python3 -m venv venv

# Activate it (You will need to do this every time before running the VOP)
source venv/bin/activate

Part 4 - Python dependencies

Now that the virtual environment is active, install the Python packages required by the import statements.

Crucial note: We use opencv-python-headless instead of standard opencv-python. The standard version will try to install desktop UI libraries (like Qt and X11) which will fail and bloat a Lite OS.

# Install requirements. Note the --no-binary flag for pygame.
pip install Flask moderngl numpy opencv-python-headless rawpy pyrr
pip install pygame --no-binary pygame

Why these packages?

• Flask - This runs the backend server and web UI ( vop.py)
• pygame - This handles the direct-to-screen framebuffer display via KMSDRM (engine.py).
• moderngl - This powers the hardware-accelerated dual-world projection mapping
• numpy - This handles the heavy math for colorspace conversions and 4-channel image buffers.
• opencv-python-headless Processes the image saving, flipping, and latent TIFF stacking.
• rawpy - Parses and debayers the raw .dng sensor data.
• pyrr - Handles the 3D Matrix math (Matrix44) for the virtual camera frustum and aspect ratio scaling.

Part 5 - User Permissions

Since the VOP runs on PiOS Lite without a desktop environment, pygame and moderngl must talk directly to the hardware's Direct Rendering Manager(DRM). By default, a standard user does not have permission to do so.

Add your user to the video and render groups:

sudo usermod -a -G video,render $USER

(You need to log out and in or reboot for these permissions to take effect).

Part 6 Running the Engine

get back into the VOPfolder, activate the environment, and start the engine.

cd ~/VOP
source venv/bin/activate
python3 vop.py

Part 7 Accessing the Web UI

Find your Raspberry Pi's local network IP address:

hostname -I

Open a web browser on another computer or tablet on the same network and navigate to that IP adress on port 5000:

http://<YOUR_PI_IP_ADDRESS>:5000

If all now went as it should. You should be greeted by the interface of the VOP. And you are now free to make a job for the VOP and run it.

Go back to the Tutorials page for more info on how to actually run it.