API Reference

This page details the public API and the internal helper functions of the pysift module. Because PythonSIFT is designed for educational transparency, understanding these internal functions is just as valuable as understanding the main entry point.

Primary API

computeKeypointsAndDescriptors(image, sigma=1.6, num_intervals=3, assumed_blur=0.5, image_border_width=5)

The core entry point that orchestrates the entire SIFT pipeline. It sequentially calls all internal generation and localization functions.

Parameters:

  • image (numpy.ndarray): The input grayscale image. Must be a 2D array. It will be internally cast to float32 for precision.
  • sigma (float, default 1.6): The standard deviation of the initial Gaussian blur.
  • num_intervals (int, default 3): The number of distinct scales per octave.
  • assumed_blur (float, default 0.5): The assumed inherent blur of the source image.
  • image_border_width (int, default 5): The width (in pixels) of the image border to ignore when searching for extrema.

Returns:

  • keypoints (list[cv2.KeyPoint]): A list of localized, filtered, and scaled OpenCV KeyPoint objects.
  • descriptors (numpy.ndarray): A 2D array of shape (N, 128) and type float32 containing the descriptor vectors.

Internal Pipeline Stages

The following functions are called sequentially by computeKeypointsAndDescriptors. They are documented here for researchers who wish to override or inspect specific mathematical steps of the algorithm.

1. Scale-Space Pyramid Generation

  • generateBaseImage(image, sigma, assumed_blur) Pre-processes the image. It upsamples the input image by a factor of 2 via linear interpolation (INTER_LINEAR). This mathematical trick dramatically increases the number of stable, high-frequency keypoints found. It then applies the initial base blur, subtracting the assumed_blur using Pythagorean subtraction (sqrt(max((sigma ** 2) - ((2 * assumed_blur) ** 2), 0.01))).

  • computeNumberOfOctaves(image_shape) Determines how many times the image can be downsampled by half before becoming too small. Uses the standard formula: int(round(log(min(image_shape)) / log(2) - 1)).

  • generateGaussianKernels(sigma, num_intervals) Calculates the exact sequential blur scales needed. Instead of blurring the original image repeatedly, SIFT blurs the previously blurred image for efficiency. This function calculates those delta sigmas.

  • generateGaussianImages(image, num_octaves, gaussian_kernels) Applies cv2.GaussianBlur iteratively to build the multidimensional scale-space pyramid.

  • generateDoGImages(gaussian_images) Creates the Difference-of-Gaussians pyramid. It loops through adjacent images in the same octave and uses cv2.subtract to find the approximate Laplacian of Gaussian. This is where edge and corner responses peak.

2. Extrema Detection & Localization

  • findScaleSpaceExtrema(gaussian_images, dog_images, num_intervals, sigma, image_border_width, contrast_threshold=0.04) Scans every pixel in the DoG pyramid against its 26 neighbors (8 in the current scale, 9 in the scale above, 9 in the scale below) to find local minima/maxima.

  • isPixelAnExtremum(first_subimage, second_subimage, third_subimage, threshold) A fast boolean check to see if the center pixel of a 3x3x3 sub-tensor is strictly strictly greater or lesser than all surrounding values.

  • localizeExtremumViaQuadraticFit(i, j, image_index, octave_index, ...) The most mathematically dense function in the library. It uses a 3D Taylor series expansion to interpolate the true, sub-pixel location of the extremum. It computes the 3D Gradient (using computeGradientAtCenterPixel) and the 3D Hessian matrix (computeHessianAtCenterPixel), solving the linear system using numpy.linalg.lstsq. It rejects points with low contrast or points located on straight edges (by evaluating the ratio of the Hessian's eigenvalues: (trace**2) / det).

3. Orientation & Filtering

  • computeKeypointsWithOrientations(keypoint, octave_index, gaussian_image, ...) Computes a 36-bin histogram of local gradient directions around the keypoint. It uses quadratic interpolation to find the precise sub-bin peak of the histogram. If a secondary peak exists that is at least 80% (peak_ratio=0.8) of the maximum, a duplicate keypoint is generated at the same location but with this new angle.

  • removeDuplicateKeypoints(keypoints) Uses a custom sorting key (cmp_to_key(compareKeypoints)) to remove redundant features that may have been generated during localization.

  • convertKeypointsToInputImageSize(keypoints) Because generateBaseImage doubled the image size, all computed keypoint coordinates (pt) and sizes (size) must be divided by 2 to map correctly back to the user's original input image.

4. Descriptor Extraction

  • generateDescriptors(keypoints, gaussian_images, window_width=4, num_bins=8, ...) Constructs the final 128-dimensional vectors. It iterates over a 16x16 window, computes gradients, rotates the window coordinates to match the keypoint's dominant angle, and uses complex Inverse Trilinear Interpolation to distribute the gradient magnitudes smoothly across the 4x4 spatial bins and 8 orientation bins. Finally, it normalizes the vector, thresholds elements greater than 0.2 (to counter camera saturation/glare), and normalizes again.