Installation

plMapcalc Python edition is a single script — plmapcalc.py — with no build step. Installation means: get Python, install three packages, download the script.

Requirements

• Python 3.9 or newer
• numpy ≥ 1.24
• rasterio ≥ 1.3 — requires GDAL shared libraries (installed automatically via pip wheel)
• numba ≥ 0.61 (strongly recommended) — requires LLVM; pip wheel includes it on most platforms
• numba-cuda ≥ 0.29 (optional, GPU only) — CUDA target for numba; requires a dedicated venv, see GPU setup below

Step-by-step: Linux / macOS

python3 --version

python3 -m venv ~/.venv/mapcalc
source ~/.venv/mapcalc/bin/activate

pip install numpy rasterio numba

pip install -r requirements.txt

wget https://plmapcalc.netzel.pl/plmapcalc.py

python3 plmapcalc.py --help

Step-by-step: Windows

pip install numpy rasterio numba

python plmapcalc.py --help

Without numba

If numba cannot be installed, plMapcalc still works but uses a pure-Python fallback loop. Expect processing times 50–200× slower than the JIT path. The tool prints a warning at startup:

[WARN] numba not installed – processing will be slower.

GPU acceleration (optional)

Passing --gpu routes the pixel kernel to a CUDA-capable GPU via numba-cuda. Each GPU thread processes one pixel; thousands of pixels run simultaneously. This is most effective for large rasters with compute-intensive expressions.

Hardware requirements

Python packages

GPU mode requires a dedicated virtual environment with the following pip packages. These must not be mixed with torch (which pins cuda-bindings<13 — incompatible with numba-cuda≥0.25).

Install — step by step

1. Create a dedicated venv and activate it
   shell

   python3 -m venv ~/.venv/plmc_gpu
   source ~/.venv/plmc_gpu/bin/activate

2. Install plmapcalc core dependencies
   shell

   pip install numpy rasterio numba

3. Install numba-cuda and CUDA libraries
   shell

   pip install numba-cuda
   pip install nvidia-cuda-runtime-cu12 \
               nvidia-cuda-nvcc-cu12 \
               nvidia-cuda-nvrtc-cu12 \
               nvidia-nvjitlink-cu12

   For Blackwell GPUs (RTX 50xx) ensure the CUDA 12.8 versions are installed:

   shell

   pip install "nvidia-cuda-runtime-cu12>=12.8" \
               "nvidia-cuda-nvcc-cu12>=12.8" \
               "nvidia-cuda-nvrtc-cu12>=12.8" \
               "nvidia-nvjitlink-cu12>=12.8"

4. Create missing .so symlinks

   pip installs versioned libraries (e.g. libnvvm.so.4.0.0) but not the unversioned symlink (libnvvm.so) that the pathfinder requires. Run once after installation:

   shell

   find $VIRTUAL_ENV -path "*/nvidia/*" -name "lib*.so.*" | while read f; do
       link="${f%.so.*}.so"
       [ ! -e "$link" ] && ln -sf "$f" "$link" && echo "linked: $link"
   done

   Or use the provided patch_activate_cuda.sh helper which performs this step automatically alongside patching LD_LIBRARY_PATH.

5. Patch the venv activate script (LD_LIBRARY_PATH)

   CUDA shared libraries installed via pip are not on the default library path. The helper script patches the venv activate to add them automatically:

   shell

   bash patch_activate_cuda.sh   # run with venv active
   source $VIRTUAL_ENV/bin/activate

6. Verify
   shell

   python -c "from numba import cuda; cuda.detect()"

   Expected output lists your GPU(s) with compute capability and marks them as [SUPPORTED].

Usage

python plmapcalc.py --gpu -i band4.tif -i band3.tif \
    -o ndvi.tif:float32:-9999 \
    -e 'x = IN[0]+IN[1]; OUT[0] = -9999 if x==0 else (IN[0]-IN[1])/x'

Blackwell (RTX 50xx) note

Blackwell GPUs (Compute Capability 12.0, sm_120) are supported via PTX JIT compilation. The first run compiles PTX to native sm_120 code, which takes approximately 30 seconds. Subsequent runs use the cached binary and are fast. Native Blackwell kernels require CUDA 12.8 or newer and driver ≥ 570.