Software setup

1. Why this setup matters¶

A stable software setup saves time during project work. Spatial analytics projects often combine GeoAI tools, geospatial libraries, machine learning packages, notebooks, scripts, model outputs and external data. If your environment and folder structure are unclear, small technical problems can become difficult to diagnose.

The goal of this page is to guide you through a coherent setup pathway:

1. create a clear SDS320 folder structure,

2. install Miniconda or Anaconda,

3. create the course Conda Environment,

4. connect the environment to VS Code,

5. check that the core packages work,

6. know what to check first when something breaks.

2. Organise your SDS320 folders¶

Before you download the environment file, create one clear working area for SDS320. This helps separate course exercises from your own project and makes it easier to use relative paths later.

The suggested structure has two main parts:

• course/ for course material, exercises, tests and shared examples,

• project/ for your own assessed SDS320 project and final Repository.

Within both parts, data are separated into:

• data/raw/ for original downloaded files that should not be modified,

• data/processed/ for clipped, reprojected, cleaned or merged files,

• data/training/ for tiles, labels, masks or tables prepared as Training Data.

Recommended folder structure¶

sds320/
├── README.md
├── course/
│   ├── README.md
│   ├── environment.yml
│   ├── data/
│   │   ├── README.md
│   │   ├── raw/
│   │   │   ├── swissimage/
│   │   │   ├── sentinel2/
│   │   │   ├── landsat/
│   │   │   ├── naip/
│   │   │   └── vectors/
│   │   ├── processed/
│   │   └── training/
│   ├── models/
│   ├── notebooks/
│   ├── scripts/
│   └── results/
│       ├── figures/
│       ├── maps/
│       ├── predictions/
│       └── evaluation/
└── project/
    ├── README.md
    ├── environment.yml
    ├── .gitignore
    ├── data/
    │   ├── README.md
    │   ├── raw/
    │   │   ├── raster/
    │   │   └── vectors/
    │   ├── processed/
    │   └── training/
    ├── models/
    ├── notebooks/
    ├── scripts/
    └── results/
        ├── figures/
        ├── maps/
        ├── predictions/
        └── evaluation/

The additional files are useful for reproducibility:

• README.md explains what a folder contains and how it should be used.

• environment.yml records the software environment.

• .gitignore helps prevent large data files, temporary files or private files from being committed to Git.

• data/README.md documents where data came from, how they were downloaded and whether they can be shared.

Create the folders¶

Copy the command for your platform into a terminal. Run it in the location where you want to store your SDS320 work, for example your Documents folder.

$folders = @(
  "sds320\course\data\raw\swissimage",
  "sds320\course\data\raw\sentinel2",
  "sds320\course\data\raw\landsat",
  "sds320\course\data\raw\naip",
  "sds320\course\data\raw\vectors",
  "sds320\course\data\processed",
  "sds320\course\data\training",
  "sds320\course\models",
  "sds320\course\notebooks",
  "sds320\course\scripts",
  "sds320\course\results\figures",
  "sds320\course\results\maps",
  "sds320\course\results\predictions",
  "sds320\course\results\evaluation",
  "sds320\project\data\raw\raster",
  "sds320\project\data\raw\vectors",
  "sds320\project\data\processed",
  "sds320\project\data\training",
  "sds320\project\models",
  "sds320\project\notebooks",
  "sds320\project\scripts",
  "sds320\project\results\figures",
  "sds320\project\results\maps",
  "sds320\project\results\predictions",
  "sds320\project\results\evaluation"
)

foreach ($folder in $folders) {
  New-Item -ItemType Directory -Force -Path $folder | Out-Null
}

$files = @(
  "sds320\README.md",
  "sds320\course\README.md",
  "sds320\course\environment.yml",
  "sds320\course\data\README.md",
  "sds320\project\README.md",
  "sds320\project\environment.yml",
  "sds320\project\.gitignore",
  "sds320\project\data\README.md"
)

foreach ($file in $files) {
  New-Item -ItemType File -Force -Path $file | Out-Null
}

cd path/to/sds320/course

mkdir -p sds320/course/data/raw/{swissimage,sentinel2,landsat,naip,vectors}
mkdir -p sds320/course/data/{processed,training}
mkdir -p sds320/course/{models,notebooks,scripts}
mkdir -p sds320/course/results/{figures,maps,predictions,evaluation}

mkdir -p sds320/project/data/raw/{raster,vectors}
mkdir -p sds320/project/data/{processed,training}
mkdir -p sds320/project/{models,notebooks,scripts}
mkdir -p sds320/project/results/{figures,maps,predictions,evaluation}

touch sds320/README.md
touch sds320/course/README.md
touch sds320/course/environment.yml
touch sds320/course/data/README.md
touch sds320/project/README.md
touch sds320/project/environment.yml
touch sds320/project/.gitignore
touch sds320/project/data/README.md

What to put where¶

3. Software recommendations¶

For SDS320, you should have access to:

• Python through Miniconda (or another conda-compatible setup),

• a dedicated conda environment for the course,

• VS Code or comparable code editor,

• Git,

• GitHub or GitLab for your project repository,

• the packages listed in the course environment.yml.

name: sds320
channels:
  - conda-forge
  - nodefaults
dependencies:
  - python=3.12
  - setuptools<81

  # Notebook environment
  - jupyterlab
  - notebook
  - ipykernel

  # GeoAI and ML stack
  - geoai
  - samgeo
  - pytorch
  - torchgeo
  - torchvision
  - segment-geospatial

  # Geospatial stack
  - gdal
  - proj
  - pyproj
  - rasterio
  - rioxarray
  - xarray
  - geopandas
  - shapely
  - fiona
  - pyogrio
  - folium
  - leafmap
  - localtileserver

  # General scientific Python
  - numpy
  - pandas
  - matplotlib
  - scikit-learn
  - scikit-image
  - tqdm
  - requests

  # Cloud/data access
  - boto3
  - s3fs
  - awscli

If there is a good overlap between the packages you intend to use, you can use the same environment file for your SDS320 project to create a seperate sds320-project environment later on. Otherwise, I would recommend either selecting a subset or starting from scratch.

4. Hardware and OS recommendations¶

Most SDS320 work can be done on a normal laptop, especially when working with small examples, pre-trained models or limited study areas.

For heavier model training, larger image collections or repeated inference, hardware becomes more important.

5. Setup pathway¶

Follow the steps below in order.

Create folders
→ install Miniconda or Anaconda
→ create the sds320 environment
→ activate the environment
→ connect it to VS Code
→ verify packages, GPU/CPU and maps
→ document the setup in your project

A. Install Miniconda or Anaconda¶

Conda is recommended because geospatial Python packages often depend on compiled libraries such as GDAL/OGR, PROJ and GEOS. Conda can install many of these dependencies together, which usually avoids compatibility problems.

Use Miniconda as a lightweight installation. For a more detailed setup description follow the SDS210 Conda setup.

curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -o .\miniconda.exe
start /wait "" .\miniconda.exe /S
del .\miniconda.exe

conda --version
python --version

mkdir -p ~/miniconda3
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh

source ~/miniconda3/bin/activate
conda init --all

conda --version
python --version

mkdir -p ~/miniconda3
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh

source ~/miniconda3/bin/activate
conda init --all

conda --version
python --version

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh

source ~/miniconda3/bin/activate
conda init --all

conda --version
python --version

B. Save the SDS320 environment file¶

Download the course environment.yml file and save it here here:

sds320/course/environment.yml

If your own project uses the same environment, copy the file later to:

sds320/project/environment.yml

This makes the project easier to reproduce because the software requirements are documented inside the project folder.

C. Create the SDS320 environment¶

Open a terminal in the sds320/course/ folder, where the course environment.yml file is saved.

Check that the file is there:

cd path\to\sds320\course
dir

cd path/to/sds320/course
ls

Then create the environment:

conda env create -f environment.yml

This creates an environment called sds320.

Activate it with:

conda activate sds320

Your terminal prompt should now include:

(sds320)

This means that Python commands run from this terminal use the SDS320 environment.

To deactivate the environment later, use:

conda deactivate

D. Optional: update the environment¶

If the course environment file changes later, update your environment from the folder that contains environment.yml:

conda env update -f environment.yml --prune

The --prune option removes packages that are no longer listed in the file.

E. Optional: GPU and CUDA setup¶

Some GeoAI and deep learning workflows are faster with CUDA support. CUDA is relevant only for compatible NVIDIA GPUs.

You can skip this section if:

• you do not have an NVIDIA GPU,

• you use a Mac,

• your project does not require heavy model training,

• or you plan to work with small examples and pre-trained models.

Check your pathway¶

nvidia-smi

conda activate sds320
python -c "import torch; print(torch.cuda.is_available())"

conda activate sds320
python -c "import torch; print(torch.backends.mps.is_available())"

conda activate sds320
python -c "import torch; print(torch.__version__)"

sudo apt update
sudo ubuntu-drivers install
sudo reboot

nvidia-smi

conda activate sds320
python -c "import torch; print(torch.cuda.is_available())"

sudo pacman -S nvidia nvidia-utils

nvidia-smi

F. Optional: cloud alternatives¶

If your local computer struggles with larger models, cloud notebooks can provide GPU access.

Possible options include:

• Google Colab,

• Kaggle notebooks.

In this course we will use Colab, as Kaggle has restrictions for the Leafmap interactive mapping library.

G. Install and configure VS Code¶

VS Code is useful for editing scripts, Markdown files, YAML files, README files and notebooks.

Download VS Code from: https://code.visualstudio.com

For a detailed setup description follow the SDS210 VS Code setup.

After opening your SDS320 folder in VS Code:

1. open the Command Palette (Win: Ctrl + Shift + P, Mac: Cmd + Shift + P),

2. choose the Python interpreter or notebook kernel,

3. select the sds320 environment,

H. Check Git¶

Check whether Git is installed:

git --version

You should see a version number.

If Git is not available, install it from the official Git website or through your operating-system package manager.

For a detailed Git setup description follow the instructions at SDS210

You will use Git more fully in Git basics. For now, the goal is only to confirm that the command is available.

I. Verify your setup¶

After activating the environment, run the following checks.

Check Python and the active environment¶

conda activate sds320
python --version
conda info --envs

The active environment should be marked with an asterisk.

Check important packages¶

Create a notebook called:

sds320/course/notebooks/setup_check.ipynb

Run this code cell:

import importlib
import sys

print(f"Python version: {sys.version}\n")

packages = {
    "numpy": "NumPy",
    "pandas": "Pandas",
    "geopandas": "GeoPandas",
    "rasterio": "Rasterio",
    "rioxarray": "Rioxarray",
    "xarray": "Xarray",
    "matplotlib": "Matplotlib",
    "sklearn": "scikit-learn",
    "torch": "PyTorch",
    "torchvision": "TorchVision",
    "geoai": "GeoAI",
    "leafmap": "Leafmap",
    "folium": "Folium",
}

for module_name, display_name in packages.items():
    try:
        module = importlib.import_module(module_name)
        version = getattr(module, "__version__", "installed")
        print(f"{display_name}: {version}")
    except ImportError:
        print(f"{display_name}: NOT FOUND")

If a package shows NOT FOUND, first check that the notebook is using the correct sds320 kernel.

Check PyTorch and acceleration¶

Run:

import torch

print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")

if torch.cuda.is_available():
    print(f"GPU device: {torch.cuda.get_device_name(0)}")
elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
    print("Apple MPS available")
else:
    print("Running in CPU-only mode")

A CPU-only result is acceptable for many course tasks. For larger model training, discuss whether your project scope needs to be adjusted.

Check interactive maps¶

Run this in the same notebook:

import leafmap

m = leafmap.Map(center=[47.3769, 8.5417], zoom=10)
m

If an interactive map appears, your notebook and visualisation stack are working.

6. Flags & checks¶

Use this table before reinstalling packages.

For more detail, see Troubleshooting.

7. Mini task¶

Before the first project work session, complete this checklist:

• Create the sds320/ folder structure.

• Save the official environment.yml file in sds320/course/.

• Create the sds320 conda environment.

• Activate the environment.

• Open the environment in VS Code.

• Create sds320/course/notebooks/setup_check.ipynb.

• Run the package check.

• Run the PyTorch acceleration check.

• Create a small Leafmap map.

• Check that Git works with git --version.

• Add a short note to sds320/course/README.md describing when and how you created the setup.

8. Key takeaways¶

• Create the SDS320 folder structure before installing or downloading data.

• Keep course exercises and your own project separate.

• Use data/raw/ for original files and avoid modifying them directly.

• Use the provided environment.yml as the main setup reference.

• Work inside the sds320 conda environment.

• Check the active environment before debugging packages.

• Use VS Code with the correct sds320 kernel.

• Document setup choices because they affect Reproducibility.