How to Run Agisoft Metashape in Headless Mode with Python Scripting
News

How to Run Agisoft Metashape in Headless Mode with Python Scripting

Posted on by admin

Agisoft Metashape isn’t just a graphical interface for 3D model creation—it’s also a powerful automation engine. With Python scripting, users can run Metashape in headless mode (i.e., without a GUI), ideal for server-based processing, batch workflows, and integration into cloud pipelines. In this article, we explore how to use Metashape’s Python API in headless mode, complete with examples and tips.

What Is Headless Mode in Agisoft Metashape?

Headless mode refers to running Metashape via command line or Python scripts, without launching the graphical user interface. This is especially useful for automated workflows on remote servers or cloud instances (e.g., AWS EC2, Google Cloud, Azure).

Why Use Headless Scripting?

  • Automate repetitive workflows (e.g. importing photos, aligning, exporting)
  • Run multiple jobs in batch mode overnight
  • Process data in the cloud without needing a GUI
  • Integrate photogrammetry into enterprise pipelines

Requirements

  • Agisoft Metashape Professional installed (1.8 or newer)
  • Valid license (node-locked or floating)
  • Python 3.x (comes bundled with Metashape)
  • Access to the CLI (Command Prompt, Terminal, SSH)

Running a Python Script Headlessly

Metashape provides a command line tool that can be used to run Python scripts:

metashape.sh -r script.py

On Windows, use:

metashape.exe -r C:\path\to\script.py

You can also pass arguments to the script:

metashape.exe -r script.py --project_folder "C:\data\site1"

Sample Headless Script

The following is a simple Python script that loads images, aligns them, and builds a sparse point cloud.

import Metashape
import sys
import os

path = sys.argv[1] if len(sys.argv) > 1 else "project"
images_path = os.path.join(path, "images")
output_path = os.path.join(path, "output.psx")

doc = Metashape.Document()
chunk = doc.addChunk()
chunk.addPhotos([os.path.join(images_path, f) for f in os.listdir(images_path) if f.endswith(".jpg")])
chunk.matchPhotos(accuracy=Metashape.HighAccuracy, preselection=Metashape.GenericPreselection)
chunk.alignCameras()
doc.save(output_path)

Typical Workflow Steps in Python

  • Import photos
  • Align cameras
  • Optimize alignment
  • Build dense cloud
  • Build DEM
  • Build orthomosaic or mesh
  • Export results

Where to Find the Python API Reference

The official Python API is documented here: https://agisoft.freshdesk.com. It includes descriptions of all classes, methods, and parameters for advanced automation.

Example: Full Automation Script

# Example: Full pipeline (simplified)
import Metashape

doc = Metashape.Document()
chunk = doc.addChunk()
chunk.addPhotos(["/data/images/img1.jpg", "/data/images/img2.jpg"])
chunk.matchPhotos(accuracy=Metashape.HighAccuracy)
chunk.alignCameras()
chunk.buildDepthMaps(quality=Metashape.MediumQuality)
chunk.buildDenseCloud()
chunk.buildModel()
chunk.buildUV()
chunk.buildTexture()
doc.save("/data/project_complete.psx")

Advanced Options

  • Exporting orthomosaics as GeoTIFFs
  • Importing GCPs from CSV
  • Batch processing multiple folders
  • Cloud-based deployment (Docker, EC2, remote sync)

Tips for Headless Execution

  • Use sys.argv to pass project or image paths dynamically
  • Always include error handling in scripts for unattended runs
  • Log progress to a file (via logging or print() redirected to log)
  • Check licensing availability when using floating licenses
  • Use doc.save() periodically to avoid data loss

Conclusion

Agisoft Metashape’s Python API and headless capabilities unlock a whole new level of flexibility for professionals and researchers. From automated drone image pipelines to cloud-based 3D model generation, the possibilities are endless. With a little scripting, you can turn Metashape into a powerful, silent engine running behind the scenes—faster, repeatable, and hands-free.