Skip to content

Installation Guide

This guide provides step-by-step instructions for installing Space-map on your system.

Prerequisites

Before installing Space-map, ensure you have:

  • Python 3.7 or higher - Check with python --version
  • pip - Python package installer
  • Git - For cloning the repository
  • 8GB+ RAM - Recommended for processing large datasets
  • Optional: NVIDIA GPU - For GPU-accelerated LDDMM

Installation Methods

This is the recommended installation method as it gives you access to the latest code and examples.

Step 1: Clone the Repository

git clone https://github.com/a12910/space-map.git
cd space-map

Step 2: Create Virtual Environment

Using a virtual environment is highly recommended to avoid dependency conflicts.

On Linux/macOS: 

python -m venv venv
source venv/bin/activate

On Windows: 

python -m venv venv
venv\Scripts\activate

You should see (venv) prefix in your terminal prompt.

Step 3: Install Dependencies

pip install --upgrade pip
pip install -r requirement.txt

This will install all required packages including PyTorch, OpenCV, Kornia, and others.

Step 4: Install Space-map

For Development (Recommended): 

pip install -e .

This installs Space-map in "editable" mode, allowing you to modify the code and see changes immediately.

For Regular Use: 

pip install .

Step 5: Verify Installation

python -c "import space_map; print(f'Space-map version: {space_map.__version__}')"

If you see the version number (e.g., "Space-map version: 0.1.0"), installation was successful!

Method 2: Direct GitHub Installation

For quick installation without cloning:

# Create and activate virtual environment first
python -m venv venv
source venv/bin/activate  # On Linux/Mac
# venv\Scripts\activate   # On Windows

# Install directly from GitHub
pip install git+https://github.com/a12910/space-map.git

GPU Support (Optional)

For GPU-accelerated LDDMM registration, you need CUDA-enabled PyTorch.

Check GPU Availability

import torch
print(f"CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"GPU device: {torch.cuda.get_device_name(0)}")

Install CUDA-enabled PyTorch

If you have an NVIDIA GPU, install the appropriate PyTorch version:

For CUDA 11.8: 

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

For CUDA 12.1: 

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

For CPU-only: 

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

Visit PyTorch Get Started for the latest installation commands.

Platform-Specific Notes

Linux

Most dependencies should install smoothly. If you encounter issues, install build tools:

sudo apt-get update
sudo apt-get install python3-dev build-essential

macOS

Install Xcode command line tools if needed:

xcode-select --install

For Apple Silicon (M1/M2/M3), PyTorch will use MPS acceleration automatically.

Windows

  • Install Visual C++ Build Tools for some dependencies
  • Use PowerShell or Command Prompt (not Git Bash) for virtual environment activation

Troubleshooting

Common Issues

Problem: "ModuleNotFoundError: No module named 'space_map'"

Solution: Make sure you're in the virtual environment and installed the package: 

which python  # Should show venv/bin/python
pip install -e .

Problem: OpenCV import errors

Solution: Try the headless version: 

pip uninstall opencv-python
pip install opencv-python-headless

Problem: PyTorch CUDA not working

Solution: Reinstall PyTorch with correct CUDA version: 

pip uninstall torch torchvision
# Then install with appropriate CUDA version (see GPU Support section)

Problem: Out of memory during installation

Solution: Install packages one at a time: 

pip install numpy pandas
pip install torch
pip install opencv-python
pip install -r requirement.txt

Verifying Your Installation

Run this complete test:

import space_map
import torch
import cv2
import pandas as pd
import numpy as np

print(f"Space-map version: {space_map.__version__}")
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"OpenCV version: {cv2.__version__}")
print("✓ All core dependencies loaded successfully!")

Updating Space-map

If you installed in development mode (pip install -e .), update with:

cd space-map
git pull origin master
pip install -r requirement.txt  # Update dependencies if needed

Uninstallation

To remove Space-map:

pip uninstall space-map

To remove the virtual environment:

deactivate  # Exit virtual environment
rm -rf venv  # Delete virtual environment directory

Dependencies Overview

Space-map requires the following packages:

Core Scientific

  • numpy - Numerical computing
  • pandas - Data manipulation
  • scipy - Scientific algorithms
  • scikit-learn - Machine learning utilities

Computer Vision

  • opencv-python - Image processing
  • scikit-image - Image algorithms
  • tifffile - TIFF image I/O
  • nibabel - Medical imaging formats

Deep Learning

  • torch - PyTorch deep learning framework
  • kornia - Differentiable computer vision

Visualization

  • matplotlib - Plotting
  • seaborn - Statistical visualization

Performance

  • numba - JIT compilation for speed
  • tqdm - Progress bars

Registration

  • pycpd - Coherent Point Drift algorithm

See requirement.txt for the complete list with version requirements.

Next Steps

After successful installation:

  1. Quick Start Guide - Learn the basic workflow
  2. Example Notebooks - Try interactive tutorials
  3. GitHub Repository - Explore the source code

Getting Help

If you encounter issues not covered here:

  • Check GitHub Issues for similar problems
  • Create a new issue with:
  • Your error message
  • Python version (python --version)
  • Operating system
  • Installation method used
  • Join GitHub Discussions for community support

Installation complete? Continue to the Quick Start Guide to begin using Space-map!