Environment Setup

This guide will help you set up your development environment for the Autostitch project. Follow the instructions for your operating system.

I tested the instructions for my environment, but many of you use other platforms. I’ve generated install instructions with Claude Opus for a variety of operating systems. I edited them (and they look good to me!) but I wasn’t able to test every one of these. Please submit a bug report if you find a problem!

Quick Reference

All platforms need:

• Python 3.10+ (3.11 or 3.12 recommended)
• tkinter – usually bundled with Python
• Required packages: numpy, opencv-python, pillow

The instructions below are trying to get you set up with these requirements.

Linux / WSL

If you’re using Linux or Windows Subsystem for Linux (WSL), setup is straightforward.

1. Install Python

Most Linux distributions come with Python. Check your version:

python3 --version

If you need to install or upgrade Python:

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip python3-tk

# Fedora
sudo dnf install python3 python3-pip python3-tkinter

2. Install Required Packages

pip install numpy opencv-python pillow

3. Verify Installation

python3 -c "import cv2; import numpy; import tkinter; print('Setup complete!')"

WSL-Specific Notes

If you’re using WSL and the GUI doesn’t display:

1. WSL2 with WSLg (Windows 11): GUI apps should work automatically.

2. WSL2 without WSLg: You need an X server on Windows:

   • Install VcXsrv or X410

   • Launch the X server with “Disable access control” checked

   • In WSL, add to your ~/.bashrc:

     export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

macOS

1. Install Python

macOS comes with Python, but it may be outdated. We recommend installing a recent version of Python via Homebrew:

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python python-tk

Alternatively, download and install Python from python.org.

2. Install Required Packages

pip3 install numpy opencv-python pillow

3. Verify Installation

python3 -c "import cv2; import numpy; import tkinter; print('Setup complete!')"

Troubleshooting

“No module named tkinter”: Reinstall Python with Tk support:

brew reinstall python-tk

Windows

These instructions are for using Anaconda on Windows. It bundles Python with common scientific packages and avoids many configuration headaches. You don’t have to use Anaconda for this course, but for non-CSSE majors this is the easist way to get set up with Python.

Step 1: Install Anaconda

1. Go to anaconda.com/download
2. Download the Windows installer (it’s a large file, ~500MB)
3. Run the installer
4. Accept the license agreement
5. Choose “Just Me” when asked who to install for
6. Use the default installation location
7. On the “Advanced Options” screen, leave the default settings and click Install
8. Wait for installation to complete (this takes a few minutes)

Step 2: Open Anaconda Prompt

Important: On Windows, always use Anaconda Prompt instead of the regular Command Prompt when you are working with Python.

1. Click the Start menu
2. Type “Anaconda Prompt”
3. Click on “Anaconda Prompt” (it should have a green icon)

You’ll see a window that looks like Command Prompt but says (base) at the beginning of the line. This means Anaconda is active.

Step 3: Install Required Packages

In Anaconda Prompt, type the following command and press Enter:

conda install numpy pillow opencv

When asked “Proceed ([y]/n)?”, type y and press Enter. Wait for the installation to finish.

Step 4: Verify Everything Works

In Anaconda Prompt, type:

python -c "import cv2; import numpy; import tkinter; print('Setup complete!')"

If you see “Setup complete!”, you’re ready to go.

Step 5: Running the Project

1. Open Anaconda Prompt (not regular Command Prompt)

2. Navigate to your project folder. For example, if your project is in Documents\p2-autostitch:

   cd Documents\p2-autostitch

3. Run the GUI:

   python gui.py

Common Windows Issues

“python” or “conda” is not recognized

You’re probably using regular Command Prompt instead of Anaconda Prompt. Close the window and open Anaconda Prompt from the Start menu.

The GUI window doesn’t appear or crashes

Make sure you’re not running Python from within OneDrive or a network drive. Copy the project to a local folder like C:\Projects\.

conda install is slow or fails

Try using conda-forge:

conda install -c conda-forge numpy pillow opencv