Installation Guide

Because of naming conflicts on the Python Package Index (PyPI) (see the warning on the Home page), PythonSIFT is deliberately not distributed via standard package managers like pip.

Instead, you must clone the repository directly and include the standalone pysift.py module in your project's source tree.

Environment Prerequisites

PythonSIFT relies on standard, widely supported scientific Python libraries. It is highly recommended to use a virtual environment (venv or conda) to manage these dependencies.

Ensure you have the following installed in your environment:

Python 3: (Last officially tested on version 3.8.5, though any modern Python 3.x version should work smoothly).
NumPy: (Last tested on 1.19.4). Required for all matrix math, array manipulations, and linear algebra operations used in SIFT.
OpenCV-Python: (Last tested on 4.3.0). Required strictly for basic image I/O, resizing interpolation, Gaussian blurring, and providing the underlying cv2.KeyPoint data structure.

Installing Dependencies

You can install the required dependencies via pip in your terminal:

# Activate your virtual environment first (recommended)
pip install numpy opencv-python

(Note: You only need opencv-python. You do not need opencv-contrib-python because PythonSIFT implements the SIFT algorithm itself, rather than relying on OpenCV's non-free modules).

Adding PythonSIFT to your Project

There are two primary ways to include PythonSIFT in your workflow:

Method 1: Direct File Copy (Recommended for simple projects)

Clone the repository to your local machine:

git clone https://github.com/rmislam/PythonSIFT.git

Copy the source file into your working directory. The entire algorithm is contained within a single file:
```
cp PythonSIFT/pysift.py /path/to/your/project/directory/
```
Import it locally in your scripts:
```
import pysift
```

Method 2: Git Submodule (Recommended for version control)

If you want to track upstream changes to PythonSIFT while keeping it isolated from your own source code, add it as a git submodule:

git submodule add https://github.com/rmislam/PythonSIFT.git external/PythonSIFT

Then, ensure your Python path can resolve it:

import sys
sys.path.append('external/PythonSIFT')
import pysift

Troubleshooting Common Setup Issues

ModuleNotFoundError: No module named 'pysift' Ensure that pysift.py is in the same directory as the script you are running, or that its directory has been added to your PYTHONPATH.
AttributeError: module 'cv2' has no attribute 'KeyPoint' Your OpenCV installation is corrupted or severely outdated. Upgrade OpenCV using pip install --upgrade opencv-python.
urlparse errors during installation You accidentally ran pip install pysift. Uninstall it immediately (pip uninstall pysift) and follow the direct-file copy instructions above.

Once setup is complete, proceed to the Quick Start to extract your first set of features.