Skip to content


Source installation

This page explains how you can install G4X-helpers on your local machine. If you’re happy running the tool via Docker, you can skip these installation steps and head to the Docker setup section.

You only need a local install if you want to:

  • use the G4X-helpers CLI directly on your machine
  • use the package beyond the CLI features exposed in the Docker image
  • develop or debug the codebase
  • integrate pieces of the library into your own Python environment

If these use cases apply to you, please read on


Step 1: clone the G4X-helpers repository

git clone https://github.com/singular-genomics/g4x-helpers

navigate to the repo directory: 

cd G4X-helpers

Note

All subsequent steps assume that you are in the G4X-helpers directory. You can confirm this in your terminal via pwd. You should see a path ending in: /G4X-helpers. 

> pwd
/path/to/current/directory/.../G4X-helpers


Step 2: install the package

Note

G4X-helpers depends on Glymur and OpenJPEG >= 2.2.0 for multi-threaded image loading. On some systems, Glymur may require additional configuration to detect OpenJPEG.

Due to those limitations we strongly suggest installing OpenJPEG, and thus G4X-helpers, via conda, as it reliably provides compatible and properly linked dependencies across platforms. Other installation methods (e.g., Homebrew or manual builds) may lead to issues such as Glymur reporting version 0.0.0 or failing to load JPEG 2000 (.jp2) images.


Create a conda environment

Install miniconda, conda, or mamba (instructions).

If this is your first time using conda:

conda init

Create the environment:

conda create -n g4x-helpers_env python=3.12

Activate the environment:

conda activate g4x-helpers_env

Install the package:

pip install .

Install into your current python environment via pip

Warning

pip does not create or manage virtual environments, so installing through pip install . will require that your local Python version is compatible with the package dependencies (Python >= 3.10).

pip install .

Create a venv using uv

uv sync
activate the environment 

source .venv/bin/activate


Step 3: Verify OpenJPEG installation

After installation of G4X-helpers, confirm that Glymur recognizes OpenJPEG via:

python -c "import glymur; print(glymur.version.openjpeg_version)"

Success: Version >=2.2.0

The output shows a version string >2.2.0 

2.4.1

Failure: Version <2.2.0

0.0.0

If your OpenJPEG is installed and was detected successfully, you can now proceed to use G4X-helpers.

If Glymur does not detect a compatible OpenJPEG version, please follow the steps below. If this happens, we strongly suggest performing the G4X-helpers installation and the following steps in a conda environment.

If the above installation was done using uv and Glymur failed to detect OpenJPEG, you will likely need to do the next steps with Homebrew, since conda installations are not visible to uv virtual environments.

Hints on other systems are provided, but not supported! You can find further details in the Glymur documentation on advanced installation methods.


Step 4: Install OpenJPEG

Install openjpeg through conda

conda install -c conda-forge openjpeg

Return to Step 3 to verify that Glymur detects OpenJPEG with a version >=2.2.0.

Install OpenJPEG and pkg-config

brew install openjpeg pkg-config

Create a Glymur config directory

mkdir -p ~/.config/glymur

Add the Homebrew installed OpenJPEG path to a glymurrc file in the config

printf "[library]\nopenjp2 = /opt/homebrew/lib/libopenjp2.dylib\n" > ~/.config/glymur/glymurrc

Return to Step 3 to verify that Glymur detects OpenJPEG with a version >=2.2.0.


Step 5: Verify installation

To start using G4X-helpers, ensure that you have activated the environment in which the package was installed. If your installation of G4X-helpers was successful, the following commands should print help text:

  • g4x-helpers --help
  • g4x-helpers resegment --help
  • g4x-helpers redemux --help
  • g4x-helpers update_bin --help
  • g4x-helpers new_bin --help
  • g4x-helpers tar_viewer --help
  • g4x-helpers migrate --help

Tip

You can see the expected output of the --help statements in the CLI usage section.


⸻