Skip to main content
U.S. flag

An official website of the United States government

Agisoft Metashape/Photoscan Automated Image Alignment and Error Reduction version 2.0

December 27, 2022

This repository contains python scripts which automate image alignment and sparse point cloud error reduction in the Agisoft Metashape/Photoscan structure from motion photogrammetry software package using the Agisoft Metashape Python API.
The current version of the script (version 2.0) approximates the workflow described in U.S. Geological Survey Open-File Report 2021-1039 (Over et al., 2021). The workflow involves the application of gradual selection filters to reduce errors in sparse point clouds, and improve camera lens models and camera position estimates. The error reduction technique and sparse point cloud gradual selection filter values were developed with the goal of maintaining the accuracies of traditional photogrammetric processes with newer techniques supported by structure from motion (SfM) based software. Legacy versions of this script which implement a previous version (version 1.0) of the workflow are available in the legacy_scripts directory within this repository.
The script allows users to align imagery and apply different gradual selection filters to reduce errors in sparse point clouds. After initial image alignment, two filters (Reconstruction Uncertainty [Ru], and Projection Accuracy [Pa]) are applied sequentially to a point cloud with camera optimization performed after each filter. Although initial target filter values can be supplied by the user, the final filter values will be determined by the value required to select a pre-defined percentage of the sparse points. The default is for each filter to select 50% of the sparse points, but this percentage can be changed by the user. Once the required percentage of sparse points is selected, the points are deleted and camera optimization is performed. The third filter, Reprojection Error (Re), is applied in an iterative fashion such that only a fraction (default is 10%) of the total sparse points is selected and deleted within an iteration. Camera optimization is performed between each iteration to improve the camera lens model using the newly filtered subset of higher-quality sparse point matches. These iterations continue until a user-defined RMS Reprojection Error level is achieved (default is 0.3). Once all of the points exceeding this threshold have been deleted, the tie point accuracy is optionally adjusted to a user-defined level (default final tie point accuracy is 0.3) and camera optimization is performed a final time with the "fit additional parameters" option enabled.
Although the default filter levels and iteration behavior for each filter is set to follow the workflow described in Over et al. (2021), the user can deviate from this workflow using command line arguments or by changing the hardcoded ‘defaults’ object at the beginning of the script in lines 246-324. For instance, if the user wishes to ensure that all remaining sparse points satisfy a specific Reconstruction Uncertainty (Ru) or Projection Accuracy (Pa) level, these filters can be run iteratively to delete points until the required filter level is met (similar to the previous version of this workflow found in the legacy scripts - see the fourth example in the "Example commands, from Metashape console" section). The default workflow performed by this script, and the suggested filter levels may not be appropriate for all imagery and projects; use caution if accepting these defaults.
Guidance on how to set the filter levels and more about the default workflow can be found in Over et al. (2021).

Publication Year 2022
Title Agisoft Metashape/Photoscan Automated Image Alignment and Error Reduction version 2.0
DOI 10.5066/P9DGS5B9
Authors Joshua Logan, Phillipe A Wernette, Andrew C Ritchie
Product Type Software Release
Record Source USGS Digital Object Identifier Catalog
USGS Organization Pacific Coastal and Marine Science Center