GEOWATCH On Windows¶

Windows usage is far less tested than Linux. If possible use Linux, but we will try to support windows. This document outlines high level steps to get geowatch running on windows. We will use miniconda3 for Python. Other options will works.

Steps I used on windows 10:

Installer Miniconda¶

Download Miniconda3 Windows 64-bit installer (with Python 3.10 as the default).

Run the installer (using default settings).

Install Bash¶

We will also need msys or git-bash

Download the git-bash 64-bit standalone installer <https://git-scm.com/download/win> and install it with default settings.

Environment Setup¶

From the start menu, run the Anaconda Prompt (miniconda).

BEFORE installing geowatch we will need to use conda to get some dependencies that don’t have windows binaries hosted on pypi.

It is recommened to be in a virtual enviornment

conda create -n geowatch python=3.10 -y
conda activate geowatch

conda install gdal jq scikit-learn ffmpeg curl -c conda-forge -y

# If you don't have a GPU
conda install pytorch torchvision cpuonly -c pytorch -y

# If you have a NVIDIA GPU (untested)
conda install pytorch torchvision pytorch-cuda=11.8 -c pytorch nvidia -y

Now that these initial requirements have been satisfied we will use pip to install the rest of the requirements:

pip install geowatch[headless]

Optional: Installing From Source¶

If you want to use the source code directly, open an anaconda prompt and run:

# Or the path to wherever you installed the git bash executable
"C:\Program Files\Git\bin\bash.exe"

source $USERPROFILE/miniconda3/etc/profile.d/conda.sh
conda activate geowatch

git clone https://gitlab.kitware.com/computer-vision/geowatch
cd geowatch
pip install -e .[headless]

Running The Tutorial¶

Unfortunately I’ve been unable to figure out how to get the bash kernel for Jupyter notebooks to work on Windows. To run the tutorial you will need to run the bash commands directly in msys or git-bash.

From the start menu, open an anaconda prompt. In this shell we need to start bash and then activate our conda virtualenv:

"C:\Program Files\Git\bin\bash.exe"

source $USERPROFILE/miniconda3/etc/profile.d/conda.sh
conda activate geowatch

The bash tutorial lives here, and can be downloaded and run via:

curl -LJO https://gitlab.kitware.com/computer-vision/geowatch/-/raw/main/tutorial/tutorial1_rgb_network.sh

# Show the tutorial (it's readable)
cat tutorial1_rgb_network.sh

# The tutorial is self-executing.
source tutorial1_rgb_network.sh

OR if you cloned the source repo:

cd geowatch
./tutorial/tutorial1_rgb_network.sh

Or you can run the tutorial commands one at a time by copy / pasting commands from the script into your terminal.

WSL2 Instructions¶

Ensure you have WSL2 enabled:

In the start menu search for “Turn Windows Features On or Off”. A Windows Features dialog will pop up. Scroll down to “Windows Subsystem for Linux” and ensure it is checked. Press OK, and restart your computer when prompted.

After rebooting type “powershell” in the start menu. Right click the powershell icon and click run as administrator.

wsl --install -d Ubuntu

You might be prompted to visit a web page for more information. You will need to do this to download and install a WSL2 Linux kernel update package.

You might get an error:

“Error: 0x80370102 The virtual machine could not be started because a required feature is not installed.”

Which means you need to enable virtualization in your BIOS, AND ensure that “Virtual Machine Platform” windows feature is enabled.

https://support.microsoft.com/en-us/windows/enable-virtualization-on-windows-11-pcs-c5578302-6e43-4b4b-a449-8ced115f58e1

If this works you will be prompted to enter a new username/password.

Running on WSL2¶

If you have a working WSL2 prompt, install conda:

# Download the conda install script into a temporary directory
mkdir -p ~/tmp
cd ~/tmp

# To update to a newer version see:
# https://docs.conda.io/en/latest/miniconda_hashes.html for updating
CONDA_INSTALL_SCRIPT=Miniconda3-py310_23.3.1-0-Linux-x86_64.sh
curl https://repo.anaconda.com/miniconda/$CONDA_INSTALL_SCRIPT > $CONDA_INSTALL_SCRIPT

# For security, it is important to verify the hash
CONDA_EXPECTED_SHA256=aef279d6baea7f67940f16aad17ebe5f6aac97487c7c03466ff01f4819e5a651
echo "${CONDA_EXPECTED_SHA256}  ${CONDA_INSTALL_SCRIPT}" > conda_expected_hash.sha256
if ! sha256sum --status -c conda_expected_hash.sha256; then
    echo "Downloaded file does not match hash! DO NOT CONTINUE!"
else
    echo "Hash verified, continue with install"
    chmod +x $CONDA_INSTALL_SCRIPT
    # Install miniconda to user local directory
    _CONDA_ROOT=$HOME/.local/conda
    sh $CONDA_INSTALL_SCRIPT -b -p $_CONDA_ROOT
    # Activate the basic conda environment
    source $_CONDA_ROOT/etc/profile.d/conda.sh
    # Update the base
    conda update --name base conda --yes
fi

Create an activate the virtual env

conda create -n geowatch python=3.10 -y
conda activate geowatch

Install geowatch and GDAL:

pip install geowatch[headless,development,optional]

pip install --prefer-binary GDAL>=3.4.1 --find-links https://girder.github.io/large_image_wheels

You will also want to install ffmpeg:

sudo apt update -y
sudo apt install ffmpeg -y

It also may be necessary to install the following packages:

sudo apt install libxcb-icccm4, libxcb-image0, libxcb-keysyms1, libxcb-render-util0, libxcb-xkb1, libxkbcommon-x11-0 -y

You can download the shell version of the tutorial:

curl -LJO https://gitlab.kitware.com/computer-vision/geowatch/-/raw/main/tutorial/tutorial1_rgb_network.sh

# Can be run directly
source tutorial1_rgb_network.sh

Or the Jupyter version of the tutorial:

curl -LJO https://gitlab.kitware.com/computer-vision/geowatch/-/raw/main/tutorial/tutorial1_rgb_network.ipynb

# ensure you have jupyter with bash_kernel installed
pip install jupyter bash_kernel
python -m bash_kernel.install

# Start the notebook
jupyter notebook tutorial1_rgb_network.ipynb

For Jupyter on WSL you will need to start a browser on your host machine. Use the URL with the authentication token the jupyter notebook command printed out (you should be able to ctrl+click it)