HyperASHS: Installation¶

Requirements¶

• Linux with an NVIDIA GPU is strongly recommended. Inference can run on the CPU, but takes over an hour per subject, compared with about 3 minutes on a GPU. Training requires a GPU.
• Python 3.10 or later. We recommend installing HyperASHS in its own conda environment or Python virtual environment.
• An internet connection the first time you use a model, so that it can be downloaded from Hugging Face. This happens automatically; see Models and Atlases for the list of repositories.

Unlike ASHS Classic, HyperASHS does not need a computing cluster. Registration and image processing tools (Greedy and Convert3D) are installed automatically as Python packages.

Easy setup (most users)¶

1. Create a Python environment¶

Create a new conda environment with Python 3.10 or higher:

conda create -n hyperresashs python=3.10
conda activate hyperresashs

Alternatively, create a Python virtual environment:

cd /my/project/path
python -m venv .venv
source .venv/bin/activate

2. Install HyperASHS from PyPI¶

Install the package and all its dependencies:

pip install hyperresashs

3. Verify the installation¶

hrashs check

The command should report that HyperResASHS was successfully installed and print the software version. If you see errors or warnings related to PyTorch and CUDA, follow the instructions for installing PyTorch under Advanced setup below.

Advanced setup (developers)¶

Follow these steps to install HyperASHS from source, or to install a version of PyTorch that matches your CUDA version.

1. Create a conda environment¶

conda create -n hyperresashs python=3.10
conda activate hyperresashs

2. Clone the repository¶

Clone the repository with its submodules:

git clone --recursive https://github.com/pyushkevich/HyperResASHS.git
cd HyperResASHS

If you have already cloned it without submodules, initialize them with:

git submodule update --init --recursive

3. Install PyTorch¶

For the best performance, install the PyTorch build that matches your CUDA version. To check your CUDA version, type:

nvidia-smi | grep "CUDA Version"

The output will look like this. If you get an error, CUDA is probably not configured on your machine.

| NVIDIA-SMI 535.288.01             Driver Version: 535.288.01   CUDA Version: 12.2     |

Then enter the following command, with cu118 changed to match your CUDA version (e.g., cu121):

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 \
    --index-url https://download.pytorch.org/whl/cu118

4. Install HyperASHS¶

Install the package in editable mode, together with its remaining dependencies:

pip install -e .

5. Verify the installation¶

hrashs check

Install ITK-SNAP¶

We also recommend installing ITK-SNAP 4.6 or later, which can be used to view your images and the segmentation results. Earlier versions cannot display the HyperASHS hyper-resolution segmentations over the original MRI, because these segmentations are in a different voxel space from the image. The instructions in this documentation assume that ITK-SNAP can be run from the command line by typing itksnap.

Using classic ASHS? See the equivalent page for ASHS Classic.