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 case apply to you, please read on


Step 1: clone the G4X-helpers repository

$ git clone git@github.com:Singular-Genomics/G4X-helpers.git

navigate to the repo directory: 

$ cd G4X-helpers

Note

all following 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 advanced configuration to properly 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 images.

learn how to install and verify OpenJPEG for use with Glymur


Create a Conda environment

Install miniconda, conda, or mamba. (instructions)

create the environment:

$ conda create -n g4x-helpers_env python=3.10

# if this is your first time using conda ...
# $ conda init

activate the environment:

$ conda activate g4x-helpers_env

Install the package:

$ pip install .

Install into your current python environment via pip

$ 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, you can confirm that Glymur recognizes OpenJPEG via:

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

Success

The output shows a correct version string 

2.4.1

An OpenJPEG version above 2.2.0 is detected. You can now proceed to use G4X-helpers

Warning

# output
0.0.0

Glymur does not detect OpenJPEG and reports 0.0.0 or other error.
In this case we strongly suggest performing the G4X-helpers installation and the following steps to enable OpenJPEG in a Conda environment.
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

Inside your Conda environment:

conda install -c conda-forge openjpeg

This has been tested on MacOS with Homebrew:

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


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, you can call the following commands from any terminal and help statements should be printed:

  • resegment --help
  • update_bin --help
  • new_bin --help
  • tar_viewer --help

Tip

you can see the output of such a --help statement in the CLI usage section.

⸻