Installing hipCIM#
2025-10-08
5 min read time
This topic discusses how to install hipCIM using the following options:
System requirements#
Ubuntu version: 22.04
ROCm version: 6.4.3
Python version: 3.10
AMD GPU: AMD Instinct MI300X
Also, install the following ROCm components before installing hipCIM:
Installing hipCIM using AMD PyPI#
Packaged versions of hipCIM and its dependencies are distributed via AMD PyPI. This section discusses how to install hipCIM using this package index. This installation method should be used by hipCIM users. hipCIM developers should use the Building hipCIM from source
Optional: Use ROCm Docker to get started.
docker pull rocm/dev-ubuntu-22.04-complete 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 \ rocm/dev-ubuntu-22.04:6.4.1-complete
For bare metal, skip this step.
Install system dependencies.
sudo apt update sudo apt install -y lsb-release software-properties-common libopenslide0 python3.10-venv rocjpeg sudo apt install -y rocthrust-dev hipcub hipblas \ hipblas-dev hipfft hipsparse \ hiprand rocsolver rocrand-dev git git-lfs
Create the Python virtual environment.
pip install --upgrade pip python3 -m venv hipcim source hipcim/bin/activate
Install hipCIM using pip.
pip install amd-hipcim --extra-index-url=https://pypi.amd.com/simple
Verify installation.
$pip show -v amd-hipcim Name: amd-hipcim Version: 1.0.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: /home/integration/hipCIM/dev/lib/python3.10/site-packages Requires: click, lazy-loader, numpy, scikit-image, scipy Required-by: Metadata-Version: 2.4 Installer: pip Classifiers: Development Status :: 4 - Beta 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/reference/hipcim/index.html#hipcim-reference Source, https://github.com/ROCm-LS/hipCIM/ Tracker, https://github.com/ROCm-LS/hipCIM/issues
Checkout the sample jupyter notebooks.
pip install notebook git clone --depth 1 [email protected]:ROCm-LS/hipCIM.git hipcim-notebooks && \ cd hipcim-notebooks && \ git filter-branch --prune-empty --subdirectory-filter notebooks HEAD git lfs pull
Run a sample program.
from cucim import CuImage img = CuImage("oxford.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)
Here is the output:
{'level_count': 1, 'level_dimensions': ((601, 81),), 'level_downsamples': (1.0,), 'level_tile_sizes': ((0, 0),)} 1 ((601, 81),) [Warning] Loading image('oxford.tif') with a slow-path. The pixel format of the loaded image would be RGBA (4 channels) instead of RGB! cuda
Building hipCIM from source#
To build hipCIM from source, follow the steps given in this section. This installation method should be used by hipCIM developers. hipCIM users should use the Installing hipCIM using AMD PyPI
Set up the Docker image using the ROCm Docker image from Dockerhub.
docker pull rocm/dev-ubuntu-22.04 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 \ rocm/dev-ubuntu-22.04
Install the required system dependencies.
sudo apt update sudo apt install -y software-properties-common lsb-release gnupg sudo apt-key adv --fetch-keys https://apt.kitware.com/keys/kitware-archive-latest.asc sudo add-apt-repository -y "deb https://apt.kitware.com/ubuntu/ $(lsb_release -cs) main" sudo apt update sudo apt install -y git wget gcc g++ ninja-build git \ yasm libopenslide-dev python3.10-venv cmake rocjpeg rocjpeg-dev
Download the latest version of hipCIM from the git repository.
git clone [email protected]:ROCm-LS/hipCIM.git cd hipCIM
Create and activate the development environment for building hipCIM.
python3 -m venv hipcim_dev source hipcim_dev/bin/activate pip install --upgrade pip pip install -r requirements.txt
Build and install hipCIM.
To build the hipCIM library on a ROCm-based AMD system using the development environment, follow these steps:
Build the base C++ libraries.
./run_amd build_local cpp release
Build the Python bindings.
./run_amd build_local hipcim release
Install the Python bindings.
python -m pip install python/cucim --extra-index-url https://pypi.amd.com/simple
Verify the installation.
To verify the installation, follow these steps:
Execute the tests in the base C++ libraries.
./run_amd test cpp release
Execute the Python tests.
./run_amd test_python
Support and limitations#
The hipCIM support is limited to C++ and Python interfaces.
There is no support for:
GPU direct storage (KvikIO, cuFile)
rocTX tracing
hipCIM only supports features from amd-cupy 13.0 and later.