pyarchinit-photogrammetry

Open-source photogrammetry engine for archaeology and heritage BIM, integrated with PyArchInit.

From photos to georeferenced point clouds, meshes, DEMs and orthophotos, with the tools an excavation needs: coded targets, ground control, sections, pottery profiles, contour lines, cut/fill volumes, point-cloud classification, Segment Anything 2.1, IFC export, and direct publishing into a PyArchInit database. Everything is scriptable in Python and runs on CPU, Apple Silicon included.

Status: alpha (0.3). Python library, command line and desktop application (on the same API, with a built-in Python console). Italian version: README.it.md.

Desktop application (no Python needed)

Download the build for your system from the Releases page:

Open the disk image and drag the app to Applications (macOS), or unzip and run PyArchInit Photogrammetry.exe (Windows). The application starts on a page with Nuovo progetto, Apri progetto and Progetto demo: the demo creates a synthetic trench and a bowl on a turntable and processes them in a few minutes. If PyArchInit 5 is installed (~/pyarchinit_5), the interface connects to its database at start and the demo database is written inside pyarchinit_DB_folder so that QGIS can open it too; PostgreSQL/PostGIS servers are reachable from PyArchInit > Connetti. The builds are unsigned: on macOS right-click > Open the first time (or xattr -dr com.apple.quarantine "/Applications/PyArchInit Photogrammetry.app"), on Windows choose More info > Run anyway. Details in docs/packaging.md.

Installation with pip

Use a dedicated virtual environment (not the Anaconda base environment, see Troubleshooting). With uv:

uv venv --seed --python 3.12 ~/venvs/ppg && source ~/venvs/ppg/bin/activate
uv pip install "pyarchinit-photogrammetry[all]"      # engine, mesh (Open3D), IFC, PostGIS, desktop GUI

With the standard tools:

python3 -m venv ~/venvs/ppg && source ~/venvs/ppg/bin/activate   # Windows: ~\venvs\ppg\Scripts\activate
pip install -U pip && pip install "pyarchinit-photogrammetry[all]"

Optional: pip install "pyarchinit-photogrammetry[sam]" adds Segment Anything 2.1 (PyTorch). A global ppg/ppg-gui without activating anything: uv tool install "pyarchinit-photogrammetry[all]" (or pipx install).

From source:

git clone https://github.com/enzococca/pyarchinit-photogrammetry
cd pyarchinit-photogrammetry
uv venv --seed --python 3.12 .venv && source .venv/bin/activate
uv pip install -e ".[all,dev]"
pytest -q

Python 3.10-3.12. Writing geometries into a PyArchInit SQLite database needs mod_spatialite (found automatically in QGIS, MacPorts, Homebrew and Linux locations, or set SPATIALITE_LIBRARY_PATH). On headless Linux servers Open3D needs the EGL/GL libraries: sudo apt-get install libegl1 libgl1 libgomp1.

Start

ppg doctor                        # checks the environment and says what to fix
ppg demo ~/ppg_demo --process     # synthetic trench + 8 targets, bowl on a turntable, pottery meshes, PyArchInit DB
ppg-gui ~/ppg_demo/scavo.ppg      # open the processed trench in the interface
ppg-gui ~/ppg_demo/ceramica/ceramica.ppg   # the bowl (local metric frame from the turntable targets)
ppg-gui                           # start page: new, open, demo, recent projects

ppg-gui is the same as ppg gui and python -m pyarchinit_photogrammetry.gui. The interface writes a log in ~/Library/Logs/pyarchinit-photogrammetry (macOS), %LOCALAPPDATA%\pyarchinit-photogrammetry\logs (Windows) or ~/.local/state/pyarchinit-photogrammetry/logs (Linux); Aiuto > Apri cartella dei log opens it.

Troubleshooting

• ppg-gui does nothing, or crashes on start. Run ppg doctor. A frequent cause is an old copy of the package installed in another Python (for example Anaconda's base) that comes first on PATH: activate the right environment (which ppg-gui must point inside it) or uninstall the other copy (/opt/anaconda3/bin/python -m pip uninstall pyarchinit-photogrammetry).
• Anaconda base environment: its SciPy wheels may not load on recent macOS (ImportError ... __thread_bss ... zero-fill section) and its PROJ data is picked up by rasterio. Use a dedicated virtual environment; PROJ_LIB/PROJ_DATA/GDAL_DATA exported by Anaconda or QGIS are redirected to the data bundled with rasterio.
• The mesh step says "Poisson reconstruction failed... height field instead". Poisson reconstruction runs in a separate process because PoissonRecon (Open3D) can crash on some clouds; the pipeline retries and then builds a 2.5D surface. Open3D 0.20.0 crashes systematically on macOS and is excluded (open3d!=0.20.0); 0.19 works.
• Native dialogs crashing on macOS 26/27 (NSInternalInconsistencyException ... targetSizeInPoints): the interface uses Qt's own message boxes, no action needed.
• The 3D view hangs on macOS: pyvistaqt older than 0.13 hangs on start; pip install -U pyvistaqt.

Screenshots

Top right: the orthomosaic/DEM view with the US polygons loaded from PyArchInit, contour lines and a section trace as layers, the Sezioni pane with the drawing, and the PyArchInit pane. Middle right: the IFC export opened with IfcOpenShell, one element per unit. Bottom: the bowl of the turntable demo reconstructed from 32 synthetic photos and its profile drawing (rim 16.0 cm measured against 16.0 cm true).

Working with QGIS, Metashape, WebODM and Photo3D

• QGIS, live: QGIS > Apri in QGIS opens orthophoto, DEM and every drawn layer in a QGIS project; drawings and attribute edits appear in QGIS within a second.
• Metashape: File > Importa > Progetto Metashape reads a .psx directly (calibrated cameras, markers, tie points, model, exported DEM/orthophoto) and continues here (dense cloud, sections, PyArchInit, IFC) without aligning again.
• WebODM/ODM: the task folder or all.zip becomes a project with orthophoto, DEM, point cloud and mesh.
• Photo3D: ppg photo3d-job is a ready Photo3D engine; sessions can also be imported.

Details in docs/integrations.md. In the packaged application, SAM 2.1 is installed on first use (PyTorch in a separate environment, see the same page).

Desktop interface

ppg-gui opens the desktop application (Italian UI): start page with recent projects; a toolbar with the workflow (photos, markers, alignment, references, dense cloud, model, texture, DEM, orthophoto, Elabora tutto); workspace with chunks, cameras, markers and products; 3D view (VTK, with a software fallback renderer); orthomosaic and DEM view with drawing tools (stratigraphic units, section traces, measurements, spot heights, SAM 2.1 prompts); photo view with manual marker placement; reference pane with GCP and check point errors; Python console bound to the project (doc, chunk); background processing with progress, cancel and a status-bar indicator; a drawing toolbar and a Layer pane (show/hide, zoom, attributes on click) for units, sections, contour lines and spot heights; a Sezioni pane with the drawings; a log pane with level filter, search, copy and save; error windows with a hint, the traceback and a Copia button; light and dark themes; Aiuto > Diagnostica ambiente (the same checks as ppg doctor); a PyArchInit menu to connect, publish orthophotos, DEMs and models, and write unit polygons and spot heights. See docs/gui.md.

Quick start (Python)

import pyarchinit_photogrammetry as ppg

doc = ppg.Document()
chunk = doc.add_chunk("Saggio 1")
chunk.add_photos(["foto/"])
chunk.detect_markers("aruco_4x4_50")          # coded targets, decoded automatically
chunk.match_photos(quality="high")
chunk.align_cameras()
chunk.import_reference("gcp.csv", crs="EPSG:3004")
report = chunk.update_transform()             # GCP georeferencing + accuracy report
print(report["control_rmse"])

chunk.build_depth_maps(quality="medium")
chunk.build_point_cloud()
chunk.build_model()                           # Poisson; surface="height_field" for terrain
chunk.build_texture()
chunk.build_dem()                             # GeoTIFF in the chunk CRS
chunk.build_orthomosaic()                     # GeoTIFF RGBA, true-ortho with occlusion test
chunk.generate_report("report.html")
doc.save("scavo.ppg")

The same workflow from the command line:

ppg markers sheet targets.pdf --codes 0-23 --size-mm 40      # print the targets
ppg process scavo.ppg foto/ --gcp gcp.csv --crs EPSG:3004   # whole pipeline + report
ppg export scavo.ppg --ortho ortho.tif --dem dem.tif --model model.obj --cloud cloud.las

Scripts can work on an open project, as in the GUI: ppg run myscript.py --project scavo.ppg, then ppg.app.document inside the script (in the GUI: Strumenti > Esegui script Python).

What it does

PyArchInit integration

from pyarchinit_photogrammetry.pyarchinit import PyArchInit

pa = PyArchInit.connect()          # the database configured in PyArchInit
pa.publish_orthomosaic(chunk, sito="Lagoi", nome_doc="Ortofoto saggio 1",
                       link_us=[("1", "101"), ("1", "102")])
pa.publish_dem(chunk, sito="Lagoi", nome_doc="DEM saggio 1")
pa.publish_model(chunk, sito="Lagoi", nome_doc="Modello saggio 1")
units = pa.us_polygons("Lagoi")    # US polygons as shapely geometries

Conventions follow PyArchInit 5 (branch Stratigraph_00001): media_table, media_thumb_table ({id}_{name}_thumb.png 150 px, {id}_{name}.png 2008x1417), media_to_entity_table (US/us_table, REPERTO, CERAMICA, ...), documentazione_table (Fotopiano, DEM, Modello tridimensionale, source Fotogrammetria), footprints in pyarchinit_documentazione, polygons in pyunitastratigrafiche, heights in pyarchinit_quote, sections in pyarchinit_sezioni, volumes in computo_metrico_table. entity_uuid is filled when the column exists. Rasters are copied next to the thumbnail folder (<media>/fotogrammetria/<site>/). See docs/pyarchinit.md.

Pottery from a turntable

ppg markers turntable mat.pdf --n 12 --diameter-mm 180     # also writes mat.csv

Photograph the vessel or sherd on the mat, process with --gcp mat.csv (local frame, mm accuracy), then:

ppg pottery model.obj --out profilo.svg --scale 1 --title "US 101 n. 34"

The axis is estimated from the surface normals (works on sherds); with the turntable you can impose it with --axis 0,0,0,0,0,1.

Accuracy check

The test suite renders a synthetic trench (4 x 3 m, a wall stub, 8 targets at known EPSG:3004 coordinates, 28 photos with lens distortion) and checks the products metrically: all photos aligned, control RMSE < 2 mm, independent check points < 3 mm, DEM median error < 3 mm, orthophoto target positions < 5 mm.

Architecture

pyarchinit_photogrammetry/
  core/        Document, Chunk, Camera, Sensor, Marker, ScaleBar, PointCloud, CRS
  engine/      sfm (pycolmap), dense, meshing, isolate (crash-proof workers), texturing, dem, ortho
  markers/     coded targets, GCP import/export, georeferencing
  archaeo/     sections, pottery, terrain (contours, volumes), stratigraphy (units)
  bim/         IFC export
  ai/          classification, SAM 2.1
  pyarchinit/  config.cfg, database, media, high-level bridge
  io/          EXIF, exports, report
  gui/         desktop interface (PySide6, pyvista, qtawesome icons, themes, log, start page)
  doctor.py    environment diagnosis (`ppg doctor`)
  demo.py      demo data set
  cli.py       `ppg` command
packaging/     PyInstaller spec and build script for the desktop application

Projects are a JSON file (name.ppg) plus a folder (name.ppg.files/) with the data of each chunk; photo paths inside the project folder are stored relative, so projects can be moved.

License

GNU GPL v2 or later, like PyArchInit. Third-party engines keep their licences (COLMAP BSD, OpenMVS AGPL when used as an external program, SAM 2.1 Apache 2.0).

Author: Enzo Cocca