Welcome to ZooUI Documentation!

---

ZooUI is an implementation of a Zooming User Interface (ZUI) for Python. Media is laid out upon an infinite virtual desktop, with the user able to pan and zoom through the collection.

---

Full documentation available at asd-standard.github.io/ZooUI

---

This project is a fork of github.com/davidar/pyzui, original work from which it derives its architecture and features.

ZooUI is compatible with the following media formats:

• All images recognized by VIPS
• PDF documents
• SVG (vector graphics)

---

This project is covered under the GNU General Public License v3.0, a copy must be under COPYING.txt on project root, otherwise visit gnu.org

---

Note: This documentation covers setup, usage, technical/development documentation, testing/benchmarking documentation and contribution guidelines for ZooUI.

---

ZooUI installation instructions

This ZooUI fork was developed with debian 13 "trixie" as d.e and a miniconda for dependencies management. It has also been tested on AArch64 and Win11, always with a miniconda environment managing all dependencies.

This project is a fork, original project can be found at: https://github.com/davidar/pyzui

Pip Install

Clone the repository and install in editable mode:

git clone https://github.com/asd-standard/ZooUI.git
cd ZooUI
pip install -e .

Install the system C library that pyvips binds to:

Debian / Ubuntu:

  sudo apt install libvips42 poppler-utils

Fedora:

  sudo dnf install vips poppler-utils

macOS (Homebrew):

  brew install vips poppler

After installation, launch with:

zooui

or:

zooui-gui

Or via the module:

python -m zooui

The application creates its configuration and data directories automatically on first launch (following the XDG Base Directory specification):

• Config: ~/.config/zooui/config.json
• Backups: ~/.local/share/zooui/backups/
• Tile cache: ~/.cache/zooui/tilestore/
• SVG cache: ~/.cache/zooui/svg/
• Logs: ~/.local/state/zooui/logs/

Dependencies

ZooUI has been developed with the following python version

• python=3.12.12

All dependencies have been installed in a miniconda environment, for all 3 platforms tested the procedure has always been to install miniconda, create an environment:

conda create -n "envirnoment name" python=3.12.12

And activate such envirnoment

conda activate "environment name"

with all the core dependencies installed trough the default Anaconda channel:

conda install "package"="version number"

ZooUI depends on the following Python packages:

• pyside6=6.7.2
• pillow=12.0.0

The following non-Python packages are also required by certain features of the application, those are installed trough the Conda-Forge Anaconda channel. Especially if you run linux those packages may already be present on your system and may work, it's nevertheless highly recomended to install them in the conda environment:

conda install -c conda-forge "package"="version number"

• pyvips=3.0.0

  Poppler usually gets installed with pyvips so it's not necessary to install it's anyway an explicit codebase dependency for pdf management.

• poppler=24.12.0

pdftoppm from Poppler or Xpdf (optional if you do not intend viewing PDFs);

These are the bare minimum dependencies for the project to run, on linux DE's using Wayland as display server you can also install:

• qt6-wayland-6.7.2

  This allow the project to run natively and take advantage of hardware acceleration

Ubuntu/Debian, AArch64, specific instructions

• Install miniconda and follow the instructions in the DEPENDENCIES section

Running ZooUI

• ZooUI can be run by activating the environment as explained in the DEPENDENCIES section:

conda activate "environment name"

• Then executing 'main.py' with python interpreter:

python main.py

• It is not necessary to run this from the command-line (unless you want to view the logging), and it can be run from any directory (the script will set the working directory appropriately by itself).

Windows specific instructions

• You have to install Windows subsystem for linux, (wsl), the default linux distribution should work, nevertheless if you want to be 100% sure the ZooUI have been tested with ubuntu 24.04.

• Once you have wsl installed you need to install miniconda on it, then you can create an environment and install all the dependencies as explained in the DEPENDENCIES section.

Running ZooUI (Windows)

• You can then run ZooUI by launching your wsl environment, navigate to the root of the zooui project and run:

python main.py

Generating Documentation

• Install sphinx on the conda environment you have created for the ZooUI project.

conda activate "environment name"
conda install sphinx

• Once installed sphinx on the ZooUI project environment go to the project root and then:

./docs

and run:

make clean
make html

• this will generate all the documentation adding changes to the project docstring you might have added. You can visualize documentation by opening

./docs/build/html/index.html

with any web browser

Building documentation

• Be aware, building documentation cause certain s docs project configuration files to be wiped, if you just wish to update documentation go to GENERATING DOCUMENTATION
• Install sphinx on the conda environment you have created for the ZooUI project.

conda activate "environment name"
conda install sphinx

• Once installed sphinx on the ZooUI project environment go to "project root"/docs and run:

sphinx-quickstart

• This will guide you through a few prompts:

  • Project name: your project's name
  • Author name: your name or org
  • Project release: version
  • Separate source and build dirs: usually Yes

• This creates a structure like:

docs/
|__ build/
|__ source/
|   |__ conf.py
|   |__ index.rst
|   |__ _static/
|__ Makefile

• Then navigate to ./docs and run

sphinx-apidoc -e -o source/ ..
sphinx-apidoc -e -o source/ ../zooui

• Then open ./docs/source/conf.py and add

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
sys.path.insert(0, os.path.abspath('..'))

• insert there all the sphinx stilings and then run:

make clean
make html

• this will generate all'the documentation adding changes to the project docstring you might have added. You can visualize documentation by opening ./docs/build/html/index.html with any web browser