cuCIM/hipCIM 

hipCIM

hipCIM is a HIP port of the cuCIM library under the RAPIDS ecosystem. This library is an extensible toolkit designed to provide GPU accelerated I/O, computer vision & image processing primitives for N-Dimensional images with a focus on biomedical imaging.

Resources

• hipCIM API reference

Install hipCIM on ROCm 10.0.0 via AMD PyPI

Note: The prebuilt amd-hipcim wheels are built against the manylinux_2_28 standard (glibc 2.28) and repaired with auditwheel, so they are portable across any glibc ≥ 2.28 Linux distribution (for example Ubuntu 20.04+, Debian 10+, RHEL/AlmaLinux/Rocky 8+, and SUSE), not just Ubuntu 24.04. The Ubuntu 24.04 steps below are one convenient, tested setup; any distribution providing Python 3.12 and glibc ≥ 2.28 works.

• [Optional step] ROCm 10.0.0 is installed from the pip index below, so a plain Ubuntu 24.04 container can be used

   docker run --cap-add=SYS_PTRACE --ipc=host --privileged=true   \
        --shm-size=128GB --network=host --device=/dev/kfd     \
        --device=/dev/dri --group-add video -it               \
        -v $HOME:$HOME  --name ${LOGNAME}_rocm                \
    ubuntu:24.04
  

• Install required (non-ROCm) system dependencies

   apt-get update && \
       apt-get install -y lsb-release gnupg curl ca-certificates && \
       curl -fsSL https://apt.kitware.com/keys/kitware-archive-latest.asc \
           | gpg --dearmor -o /usr/share/keyrings/kitware-archive-keyring.gpg && \
       echo "deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ $(lsb_release -cs) main" \
           > /etc/apt/sources.list.d/kitware.list && \
       apt-get update && \
       apt-get install -y git wget gcc g++ make ninja-build git-lfs \
                     yasm libopenslide-dev libwebp-dev libzstd-dev \
                     python3 python3-venv python3-dev libpython3-dev cmake
  

• Create a python3 virtual environment and install the ROCm 10.0.0 SDK from the public pip index. The device-gfx* extras carry the GPU code objects; install one per architecture in use (device-gfx942 for MI300X / MI325X, device-gfx950 for MI350X / MI355X).

   python3 -m venv hipcim_dev
   source hipcim_dev/bin/activate
   pip install --upgrade pip
   pip install "rocm[libraries,devel,device-gfx942,device-gfx950]" --index-url https://stable.repo.amd.com/rocm/whl-next/
   # ensure that a wheel exists for the target architecture
   pip list | grep rocm-sdk-device
  

• Setup environment variables

  export ROCM_HOME=$(rocm-sdk path --root)
  

• Install hipcim. There are two options:

  Option 1 — ROCm already available (installed at the system level or via the ROCm SDK venv step above). Installs CuPy (amd-cupy) as a hipCIM dependency:

  pip install amd-hipcim --extra-index-url=https://pypi.amd.com/rocm-10.0.0/simple/
  

  Option 2 — ROCm not installed. The [rocm] extra pulls in ROCm and CuPy, so provide both public indexes (you can skip the ROCm SDK install step above):

  pip install "amd-hipcim[rocm]" \
    --extra-index-url=https://pypi.amd.com/rocm-10.0.0/simple/ \
    --extra-index-url=https://stable.repo.amd.com/rocm/whl-next/
  

• Verify installation

  pip show -v amd-hipcim
  

• Expected output

  Version details: (26, 6, 1, 'dev50', 'g03857c672')
  Name: amd-hipcim
  Version: 26.6.0
  Summary: hipCIM - an extensible toolkit designed to provide GPU accelerated I/O, computer vision & image processing primitives for N-Dimensional images with a focus on biomedical imaging.
  Home-page: https://rocm.docs.amd.com/projects/hipCIM/en/latest/
  Author: AMD Corporation
  Author-email: 
  License: Apache 2.0
  Location: /tmp/hipcim-venv/lib/python3.12/site-packages
  Requires: amd-cupy, click, lazy-loader, numpy, scikit-image, scipy
  Required-by: 
  Metadata-Version: 2.4
  Installer: pip
  Classifiers:
    Development Status :: 5 - Production/Stable
    Intended Audience :: Developers
    Intended Audience :: Education
    Intended Audience :: Science/Research
    Intended Audience :: Healthcare Industry
    Topic :: Scientific/Engineering
    Operating System :: POSIX :: Linux
    Environment :: Console
    Environment :: GPU :: AMD Instinct :: MI300
    License :: OSI Approved :: Apache Software License
    Programming Language :: C++
    Programming Language :: Python
    Programming Language :: Python :: 3
  Entry-points:
    [console_scripts]
    cucim = cucim.clara.cli:main
  Project-URLs:
    Homepage, https://rocm.docs.amd.com/projects/hipCIM/en/latest/
    Documentation, https://rocm.docs.amd.com/projects/hipCIM/en/latest/
    Source, https://github.com/AMD-Ecosystem/hipCIM
    Tracker, https://github.com/AMD-Ecosystem/hipCIM/issues
  

• Create a sample image (scikit-image is installed as a hipCIM dependency and the image it ships is bundled, so nothing is downloaded)

  mkdir -p sample_image
  python3 -c "from skimage import data, io; io.imsave('sample_image/sample.tif', data.astronaut())"
  

• Run a sample program

  from cucim import CuImage
  img = CuImage("sample_image/sample.tif")
  resolutions = img.resolutions
  level_dimensions = resolutions["level_dimensions"]
  level_count = resolutions["level_count"]
  print(resolutions)
  print(level_count)
  print(level_dimensions)
  region = img.read_region([0,0], level_dimensions[level_count - 1], level_count - 1, device="cuda")
  print(region.device)

• Output

  {'level_count': 1, 'level_dimensions': ((512, 512),), 'level_downsamples': (1.0,), 'level_tile_sizes': ((0, 0),)}
  1
  ((512, 512),)
  [Warning] Loading image('sample_image/sample.tif') with a slow-path. The pixel format of the loaded image would be RGBA (4 channels) instead of RGB!
  cuda
  

Build hipCIM on ROCm 10.0.0 from source

Please use the below steps to build the hipCIM library on a ROCm based MI300X/MI325X/MI350X/MI355X system from source.

• [Optional step] ROCm 10.0.0 is installed from the pip index below, so a plain Ubuntu 24.04 container can be used

   docker run --cap-add=SYS_PTRACE --ipc=host --privileged=true   \
        --shm-size=128GB --network=host --device=/dev/kfd     \
        --device=/dev/dri --group-add video -it               \
        -v $HOME:$HOME  --name ${LOGNAME}_rocm                \
    ubuntu:24.04
  

• Install required (non-ROCm) system dependencies

   apt-get update && \
       apt-get install -y lsb-release gnupg curl ca-certificates && \
       curl -fsSL https://apt.kitware.com/keys/kitware-archive-latest.asc \
           | gpg --dearmor -o /usr/share/keyrings/kitware-archive-keyring.gpg && \
       echo "deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ $(lsb_release -cs) main" \
           > /etc/apt/sources.list.d/kitware.list && \
       apt-get update && \
       apt-get install -y git wget gcc g++ make ninja-build git-lfs \
                     yasm libopenslide-dev libwebp-dev libzstd-dev \
                     python3 python3-venv python3-dev libpython3-dev cmake
  

• Checkout the latest version of hipCIM from git

  git clone git@github.com:AMD-Ecosystem/hipCIM.git
  cd hipCIM
  

• Create a python3 virtual environment, install the ROCm 10.0.0 SDK and python dependencies. AMDGPU_TARGETS lists the architectures to build for. The release targets gfx942 (MI300X / MI325X) and gfx950 (MI350X / MI355X), and both need their own device-gfx* extras, which carry the GPU code objects.

   python3 -m venv hipcim_dev
   source hipcim_dev/bin/activate
   pip install --upgrade pip
   pip install "rocm[libraries,devel,device-gfx942,device-gfx950]" --index-url https://stable.repo.amd.com/rocm/whl-next/
   pip install -r ./requirements.txt
   # ensure that a wheel exists for the target architecture
   pip list | grep rocm-sdk-device
  

  To build for a single GPU, align AMDGPU_TARGETS with the device extra. For example, for a gfx950 target, use AMDGPU_TARGETS=gfx950 with rocm[libraries,devel,device-gfx950]. Setting AMDGPU_TARGETS without using its corresponding device wheel will result in binaries that won't run.

  If a device wheel is added or removed later, run rocm-sdk init to relink it.

• Setup environment variables

  export ROCM_HOME=$(rocm-sdk path --root)
  export AMDGPU_TARGETS="gfx942;gfx950"
  

  With a system-level ROCm installation (/opt/rocm) instead of the pip SDK, point ROCM_PATH at the ROCm root rather than using rocm-sdk:

  export ROCM_PATH=$(dirname $(dirname $(readlink -f $(command -v hipcc))))   # e.g. /opt/rocm-7.2.3
  

  Set this whenever the ROCm root is not detected: hipcc is usually reached through /usr/bin/hipcc, and the build then derives /usr as the ROCm root and fails with CMake Error at CMakeLists.txt:39 (find_package) (HIP package not found).

• Build the cpp base libraries

  ./run_amd build_local cpp release

• Build the python3 bindings

  ./run_amd build_local hipcim release

• Install the hipCIM python3 package (CuPy resolves from the public AMD index)

  pip install amd-cupy --extra-index-url https://pypi.amd.com/rocm-10.0.0/simple/
  python3 -m pip install python/cucim --extra-index-url https://pypi.amd.com/rocm-10.0.0/simple/

• [First time only] Generate test data files

  # Generate test TIFF images required for C++ tests
  ./test_data/gen_images.sh

• Run all cpp unit tests

  ./run_amd test cpp release

• Run all python3 unit tests

  ./run_amd test_python

Troubleshooting rocJPEG and VA-API

GPU decode of SVS/TIFF whole slide images goes through rocJPEG, which decodes on the VCN engine via VA-API. If read_region(..., device="cuda") fails with InitVAAPI(drm_node) returned ROCJPEG_STATUS_NOT_INITIALIZED, libva could not load its backend driver. Point it at the driver ROCm ships:

export LIBVA_DRIVERS_PATH="$(rocm-sdk path --root)/lib/rocm_sysdeps/lib"   # pip SDK
export LIBVA_DRIVERS_PATH="/opt/rocm/core-10.0/lib/rocm_sysdeps/lib"       # apt / ROCm image

This variable is needed because libva dlopens <driver>_drv_video.so from a directory fixed when libva was built (/usr/lib/x86_64-linux-gnu/dri), which LD_LIBRARY_PATH does not affect. The only compatible driver is ROCm's own radeonsi_drv_video.so: ROCm vendors libva 1.22 and requires __vaDriverInit_1_22, while Ubuntu 24.04's Mesa driver exports __vaDriverInit_1_20. LD_LIBRARY_PATH and LIBVA_DRIVER_NAME are not needed — and LIBVA_DRIVER_NAME=amdgpu breaks the lookup, because ROCm ships no amdgpu_drv_video.so.

If that alone doesn't resolve it:

• /dev/dri isn't passed to the container (--device=/dev/dri), or the container user isn't in the render group that owns /dev/dri/renderD* (--group-add "$(getent group render | cut -d: -f3)"; video only covers the card* nodes).
• rocJPEG always decodes on device 0, that is /dev/dri/renderD128, regardless of HIP_VISIBLE_DEVICES, so a legacy or integrated GPU enumerating first fails initialization.
• The host exposes no VCN JPEG engine, which is common on SR-IOV guests. No variable helps there.

Code Coverage

hipCIM supports comprehensive code coverage for both C++ and Python components. For detailed information about generating and understanding code coverage reports, please refer to scripts/README.md.

Quick commands:

• C++ Coverage: ./run_amd cpp_coverage
• Python Coverage: Automatically generated with ./run_amd test_python

Contributing Guide

Contributions to hipCIM are more than welcome! Please review the CONTRIBUTING.md file for information on how to contribute code and issues to the project.

Acknowledgments

Without awesome third-party open source software, this project wouldn't exist.

Please find LICENSE-3rdparty.md to see which third-party open source software is used in this project.

License

Apache-2.0 License (see LICENSE file).

Copyright (c) 2020-2026, NVIDIA CORPORATION. Modifications Copyright (C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.