Quick Start

This guide provides a minimal, "Hello World" tutorial for extracting SIFT keypoints and descriptors from a single image using PythonSIFT. By the end of this guide, you will have successfully detected scale-invariant features and visualized them on an image.

1. Prepare your Workspace

Ensure you have successfully completed the steps in the Installation Guide and have pysift.py in your working directory.

SIFT operates strictly on grayscale images. You will need a sample image to process. Save any reasonably sized image (e.g., 500x500 pixels) in your directory and name it image.png.

2. The Extraction Script

Create a new Python file named hello_sift.py and paste the following code. Read through the comments to understand the pipeline.

import cv2
import pysift
import numpy as np

# 1. Load the Image
# The '0' flag tells OpenCV to load the image immediately in grayscale.
# SIFT relies on pixel intensity gradients, making color channels unnecessary.
image_path = 'image.png'
image = cv2.imread(image_path, 0)

if image is None:
    print(f"Error: Could not load image from {image_path}. Check the file path.")
    exit(1)

print("Image loaded successfully.")
print("Extracting keypoints... (Note: PythonSIFT may take a few minutes on large images)")

# 2. Compute Keypoints and Descriptors
# This is the core function. It returns OpenCV KeyPoint objects and a NumPy array.
keypoints, descriptors = pysift.computeKeypointsAndDescriptors(image)

# 3. Analyze the Output
print("\n--- Extraction Complete ---")
print(f"Found {len(keypoints)} stable keypoints.")

if descriptors is not None:
    print(f"Descriptor matrix shape: {descriptors.shape}")
    print(f"Descriptor data type: {descriptors.dtype}")
else:
    print("No descriptors found.")

# 4. Visualize the Results
# cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS ensures we draw circles showing 
# the exact scale (size) and orientation (angle) of the keypoint.
output_image = cv2.drawKeypoints(
    image, 
    keypoints, 
    None, 
    color=(0, 255, 0),
    flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS
)

output_filename = 'sift_keypoints_visualized.png'
cv2.imwrite(output_filename, output_image)
print(f"\nSaved visualization to {output_filename}. Open this file to see the features.")

3. Run and Understand the Script

Execute the script from your terminal:

python hello_sift.py

Understanding the Output Variables

When the script finishes, you will receive two variables:

  1. keypoints: A Python list containing hundreds or thousands of cv2.KeyPoint objects. Each object represents a spatial location (x, y) in the image that was identified as a stable "corner" or "blob" across multiple scales. It also contains the feature's radius (size) and dominant gradient direction (angle).
  2. descriptors: A NumPy matrix of shape (N, 128), where N is the number of keypoints. Each row is a 128-element numerical signature uniquely identifying that specific keypoint's local neighborhood. You will use these vectors later to match features between two different images.

Common Pitfalls during Quick Start

  • The script is hanging / taking too long: PythonSIFT is not optimized for speed. If you are feeding it a massive 4K resolution image, it could take 10+ minutes to process. For learning purposes, resize your image to 800x600 or smaller before processing.
  • Error: NoneType object has no attribute 'astype': This means cv2.imread() failed to find your image and returned None. Double-check your file path, spelling, and ensure the image is in the same directory as your script.

Next Steps

Now that you can extract basic features, dive into the Usage Guide to understand how to tune SIFT's parameters, or check out the Template Matching Demo to see how to actually use these descriptors to find objects in scenes.