HIPP (Historical Image Pre-Processing) is a python library to pre-process scanned historical (film based) aerial and satellite images in preparation for Structure from Motion surface reconstruction and photogrammetric analysis.
Examples of images that are currently supported or planned to be supported include:
- aerial images with fiducial (or pseudo fiducial) markers, such as from:
- the aerial photo single frame dataset of USGS Earth Explorer (EE)
- the North American Glacier Photography (NAGAP) database from https://arcticdata.io/
- declassified US reconnaissance satellite images, in particular:
- KH-9 Hexagon panoramic camera images, i.e. Declass 3 dataset from EE
- KH-9 Hexagon mapping camera images, i.e. Declass 2 dataset from EE (to be included)
- KH-4/4A/4B Corona images, i.e. Declass 1 dataset from EE (to be included)
- Download of imagery is supported through our sister package usgsxplore.
-
Detection of fiducial markers
- Built-in application to generate fiducial marker templates
- Detection of fiducial marker coordinates using OpenCV template matching
- Sub-pixel accuracy for fiducial detection
- Supports detection of 4 midside and/or 4 corner fiducials
- Filtering of low-confidence matches
- Estimates the principal point based on valid fiducials
- Quality Control Outputs:
- Cropped windows around detected fiducials for visual inspection
- Distribution plots of principal point deviations and individual fiducial coordinates
- Matching score distributions
- RMSE of fiducial coordinates before and after affine transformation
-
Detection of fiducial marker proxies (pseudo-fiducial) (feature in development)
-
Image Restitution
- Computes the appropriate geometric transformation between detected and calibrated fiducial positions:
- 1 point → Translation
- 2 points → Similarity transformation
- 3+ points → Affine transformation
- Crops the image around the estimated principal point to a standard size
- Applies CLAHE (Contrast Limited Adaptive Histogram Equalization) to enhance features in the image
- Computes the full affine transformation matrix (including crop transformation)
- Computes the appropriate geometric transformation between detected and calibrated fiducial positions:
See this notebook for example.
Supports missions 1201–1219. Input is either a .tgz archive from USGS Earth Explorer or a list of pre-extracted scan strip .tif files.
-
Image Joining
- Joins scan strips into a single composite image
- ORB keypoint matching + RANSAC Euclidean alignment between consecutive strips
- Block-wise compositing via rasterio
WarpedVRTfor memory-efficient handling of large scans
-
Image Restitution
- Detects fiducial markers (disk-shaped for missions ≤ 1213, wagon-wheel for missions ≥ 1214) via template matching and DBSCAN clustering
- Builds a Thin Plate Spline (TPS) warp from matched fiducial positions to their known physical layout
- Fallback strategy chain for images with missing or low-confidence fiducials:
CollimationStrategy— refines edges via collimation line peaks (missions 1206+)PolyStrategy— RANSAC polynomial fit of top/bottom film edgesFlatStrategy— flat-edge approximation for older missions without collimation lines
-
Quality Control
- Quickview JPEGs of the joined mosaic and the final restituted image
- Per-image figures showing detected fiducials, edge fits, and warp quality
- Per-image log file; failures preserve intermediate files for inspection and retry
-
CLI
# Single image hipp-kh9pc preproc -i scan.tgz -o /out/ hipp-kh9pc preproc -i t1.tif t2.tif t3.tif -o /out/ # Batch (parallel) hipp-kh9pc batch-preproc -i /data/scans/ -o /out/ -j 4
See this notebook for a full preprocessing example.
See this notebook for a detailed walkthrough of the restitution strategies.
pip install hipphipp is distributed under the terms of the Apache-2.0 license.
The data you create with hipp depend on the input datasets you use.