Installation#

From PyPI#

pip install polartools

From conda-forge#

If you already manage your scientific Python stack with conda or mamba:

mamba install -c conda-forge polartools

From source#

For development, clone and install in editable mode with the dev extras:

git clone https://github.com/APS-4ID-POLAR/polartools
cd polartools
pip install -e .[dev,docs]

Or with conda for the heavier native dependencies (Qt, HDF5 plugins):

git clone https://github.com/APS-4ID-POLAR/polartools
cd polartools
mamba env create -f environment.yml
mamba activate polartools-dev

The conda route is the recommended one on a beamline workstation: the environment file installs pyqt6 (and with it qt6-main, which carries the X11 libraries Qt needs) from conda-forge rather than leaving Qt to a PyPI wheel. Note that conda-forge’s pyqt package is still PyQt5 — the viewers are PyQt6, so ask for pyqt6 if you build an environment by hand.

Qt system libraries on Linux#

The graphical tools need PyQt6, which comes in as a normal dependency either way. What a pip install cannot provide is the handful of X11 libraries Qt loads at runtime. If a viewer exits immediately with

qt.qpa.plugin: Could not load the Qt platform plugin "xcb"

the system libraries are missing. On Debian/Ubuntu:

sudo apt-get install libxcb-cursor0 libegl1 libgl1

On RHEL/Rocky:

sudo dnf install xcb-util-cursor libglvnd-egl libglvnd-glx

libxcb-cursor0 is the one most often absent: Qt 6.5 and newer refuse to start the xcb platform plugin without it. A conda install of pyqt6 brings its own copy (xcb-util-cursor) and so sidesteps this entirely.

Over SSH, pass -X or -Y and check that $DISPLAY is set. With no display at all, set QT_QPA_PLATFORM=offscreen — enough to import and test the GUI modules, but nothing will be drawn.

Verifying#

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

Should print a version string like 0.6.0 (or 0.6.0.postN+gHASH for a development checkout).

To check that the graphical side works too:

python -c "from PyQt6.QtCore import QT_VERSION_STR; print(QT_VERSION_STR)"
scan-viewer .

Console scripts#

Installing the package puts three applications on your PATH:

Command	Opens	Documented in
`scan-viewer [directory]`	The scan browser, and the spectrum and image viewers behind its buttons	Scan viewers
`flyscan-dichro-gui [options]`	The post-scan flyscan dichroism viewer	Flyscan dichroism
`xmcd-gui`	Interactive XMCD normalization and dichroism	XMCD GUI

Optional: enable pre-commit hooks#

If you’ll be contributing, install the pre-commit hooks so ruff runs on every commit:

pre-commit install