Metadata-Version: 2.4
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.
Author: AMD Corporation
License: Apache 2.0
Project-URL: Homepage, https://rocm.docs.amd.com/projects/hipCIM/en/latest/
Project-URL: Documentation, https://rocm.docs.amd.com/projects/hipCIM/en/latest/
Project-URL: Source, https://github.com/AMD-Ecosystem/hipCIM
Project-URL: Tracker, https://github.com/AMD-Ecosystem/hipCIM/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Environment :: GPU :: AMD Instinct :: MI300
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-3rdparty.md
Requires-Dist: click
Requires-Dist: lazy-loader>=0.4
Requires-Dist: numpy<3.0,>=1.23.4
Requires-Dist: scikit-image<0.27.0,>=0.23.2
Requires-Dist: scipy<1.17,>=1.11.2
Requires-Dist: amd-cupy!=14.1.0,>=14.0.1
Provides-Extra: test
Requires-Dist: imagecodecs>=2021.6.8; platform_machine == "x86_64" and extra == "test"
Requires-Dist: matplotlib>=3.7; extra == "test"
Requires-Dist: numpydoc>=1.7; extra == "test"
Requires-Dist: opencv-python-headless>=4.6; extra == "test"
Requires-Dist: openslide-python>=1.3.0; platform_machine == "x86_64" and extra == "test"
Requires-Dist: pooch>=1.6.0; extra == "test"
Requires-Dist: psutil>=5.8.0; extra == "test"
Requires-Dist: pytest-cov>=2.12.1; extra == "test"
Requires-Dist: pytest-lazy-fixtures>=1.0.0; extra == "test"
Requires-Dist: pytest-rerunfailures>=14.0; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pytest<9.0.0a0,>=7.0.0; extra == "test"
Requires-Dist: pywavelets>=1.6; extra == "test"
Requires-Dist: tifffile>=2022.8.12; extra == "test"
Provides-Extra: developer
Requires-Dist: black; extra == "developer"
Requires-Dist: isort; extra == "developer"
Requires-Dist: pre-commit; extra == "developer"
Requires-Dist: ruff; extra == "developer"
Provides-Extra: docs
Requires-Dist: ipython; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: numpydoc>=1.7; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: recommonmark; extra == "docs"
Requires-Dist: sphinx<8.2.0,>=8.0.0; extra == "docs"
Provides-Extra: rocm
Requires-Dist: rocm[devel,device-gfx942,device-gfx950,libraries]==10.0.*; extra == "rocm"
Dynamic: license-file
Dynamic: provides-extra

# <div align="left">&nbsp;cuCIM/hipCIM&nbsp;</div>

## hipCIM 
hipCIM is a [HIP](https://github.com/ROCm/hip) port of the [cuCIM](https://github.com/rapidsai/cucim) library under the [RAPIDS](https://github.com/rapidsai) 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](https://rocm.docs.amd.com/projects/hipCIM/en/latest/reference/hipcim/index.html#hipcim-reference)

### Install hipCIM on ROCm 10.0 via AMD PyPI

> **Note:** The prebuilt `amd-hipcim` wheels are built against the [`manylinux_2_28`](https://github.com/pypa/manylinux) 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 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++ 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 SDK from the public pip index
	```
	python3 -m venv hipcim_dev
	source hipcim_dev/bin/activate
	pip install --upgrade pip
	pip install "rocm[libraries,devel]" --index-url https://stable.repo.amd.com/rocm/whl-next/
  ```

- Setup environment variables
  ```
  export ROCM_HOME=$(rocm-sdk path --root)
  #For MI300X / MI325X (gfx942)
  export AMDGPU_TARGETS=gfx942
  #For MI350X / MI355X (gfx950)
  export AMDGPU_TARGETS=gfx950
	```
- 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
  ```


 - Run a sample program
   ```python3
    from cucim import CuImage
    img = CuImage("sample_image/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)
   ```

 - 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
   ```


### Build hipCIM on ROCm 10.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 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++ 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 SDK and python dependencies
	```
	python3 -m venv hipcim_dev
	source hipcim_dev/bin/activate
	pip install --upgrade pip
	pip install "rocm[libraries,devel]" --index-url https://stable.repo.amd.com/rocm/whl-next/
	pip install -r ./requirements.txt
	```

- Setup environment variables
  ```
  export ROCM_HOME=$(rocm-sdk path --root)
  #For MI300X / MI325X (gfx942)
  export AMDGPU_TARGETS=gfx942
  #For MI350X / MI355X (gfx950)
  export AMDGPU_TARGETS=gfx950
  ```

- Build the cpp base libraries

  ```bash
  ./run_amd build_local cpp release
  ```

- Build the python3 bindings

  ```bash
  ./run_amd build_local hipcim release
  ```

- Install the hipCIM python3 package (CuPy resolves from the public AMD index)
  ```bash
  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
  ```bash
  # Generate test TIFF images required for C++ tests
  ./test_data/gen_images.sh
  ```

- Run all cpp unit tests
  ```bash
  ./run_amd test cpp release
  ```

- Run all python3 unit tests
  ```bash
  ./run_amd test_python
  ```


### 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](scripts/README.md#code-coverage).

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](https://github.com/AMD-Ecosystem/hipCIM/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](LICENSE-3rdparty.md) to see which third-party open source software
is used in this project.

## License

Apache-2.0 License (see [LICENSE](LICENSE) file).

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