SakuGIS：A Verifiable Image Geolocation Workbench

中文版，English version(current)

SakuGIS is a macOS desktop GIS for image geolocation. Rather than treating the coordinates produced by a multimodal model as a conclusion, it returns the model's place hypotheses to OpenStreetMap, Nominatim, Overpass, and an optional local PostGIS backend for name resolution and spatial verification, then presents every candidate and its evidence chain as expandable, comparable QGIS layers.

Developed by the UrbanComp team and released under GNU GPL-2.0-or-later.

Download

The current build is SakuGIS 0.4.0 (Apple Silicon test build).

• Release version

Requirements

Item	Requirement
Processor	Apple Silicon (M1 or later); Intel Macs are not supported
System	macOS 13 or later
QGIS	No separate installation; an independent QGIS runtime is bundled
Model service	Your own Qwen API key on an OpenAI-compatible endpoint
Web search	Brave Search API key, optional

The package is large because it ships a complete QGIS runtime, so no separate Python, PyQt, or PyQGIS setup is needed.

This test build is ad-hoc signed and not Apple-notarized. On first launch, right-click SakuGIS in Finder and choose Open.

Why verifiability

A multimodal model can return coordinates for a photograph directly, but two problems follow. The coordinates may not correspond to any real geographic entity, and highly similar places, such as replica buildings or landscapes of the same type, cannot be told apart from the model output alone.

SakuGIS separates generation from verification. The model only extracts evidence and proposes candidates. Whether a candidate holds is decided by real OSM place records and spatial relationship checks.

Geographically diverse hypotheses are kept as expandable QGIS layers rather than collapsed into a single answer.

Three-stage pipeline

1. Evidence extraction. Visual and contextual cues are extracted from each photo. In multi-photo queries, each image is sent in its own vision request and the evidence is merged locally, avoiding multi-image context failures.
2. Hypothesis and place resolution. Candidates are proposed and resolved to real OSM records through Nominatim or a local PostGIS name index. When an alias cannot be matched safely, coordinate-based reverse lookup attaches a real OSM identity without moving the queried point.
3. Verification and reranking. Candidates are rescored using Nominatim reverse geocoding, Overpass spatial constraints, and optional PostGIS ST_Covers, ST_DWithin, and ST_Distance checks. Timeouts and unavailable data are recorded as unknown rather than as mismatches.

The verification panel lists reverse geocoding results, spatial checks, component scores, coverage, and data sources.

Case examples

All results below come from the packaged Apple Silicon application, with the full three-stage pipeline, OSM verification, candidate comparison, and place information retrieval.

Eiffel Tower, Paris. Separated from the Las Vegas replica, with a composite score of 88.8 and a GIS score of 78.0.

Sydney Opera House. Ranked first, with the Copenhagen and Oslo hypotheses suppressed; the details panel loaded five descriptions and eight source-linked photographs.

Palace Museum, Beijing. Ranked above the Taipei and Shenyang alternatives, with a composite score of 83.9 and 100% GIS coverage.

The Place Explorer opens only when a candidate has both a named GIS identity and valid online material.

The regression run of 28 July 2026 covered five scenes: the Shanghai waterfront (two photos), Mount Fuji with a pagoda (three photos), the Erg Chebbi dunes, the Jökulsárlón glacier lagoon, and Sugarloaf Mountain in Rio de Janeiro. All 5/5 core runs and 5/5 web-enrichment runs passed; 17 of 17 candidates resolved to real place records across 18 model requests with no retries.

Features

Map and data

• QGIS-powered canvas with pan, zoom, full extent, and project save and load
• OpenStreetMap basemap and replaceable XYZ imagery layers
• GeoJSON, GeoPackage, Shapefile, KML, GeoTIFF, and other common formats
• Layer visibility, ordering, renaming, opacity, and candidate navigation

Analysis workflow

• A Case workspace that jointly analyzes up to six photos taken at the same location, while retaining single-photo and text-only queries
• Expandable candidate layers with a click-to-compare panel covering composite, evidence-review, cross-photo, GIS, and coverage signals
• A Place Explorer combining local GIS evidence, web descriptions, and photos, either floating or docked
• Bilingual Markdown query reports with evidence, checks, sources, and uncertainty notes

Interface and configuration

• Chinese and English runtime interface with persistent light and dark modes
• Each launch opens on one of 24 major world cities selected at random
• About SakuGIS checks GitHub Releases for updates
• A single Settings window for endpoint, key, model, temperature, timeouts, prompt budget, candidate limit, and the PostGIS connection

Getting started

1. Download and open the DMG, then drag SakuGIS into Applications.
2. On first launch, right-click the application and choose Open, then confirm.
3. Open Settings → Settings… and enter the Qwen endpoint and API key on the API Services page. The default endpoint is Alibaba Cloud's public OpenAI-compatible service. Starting an analysis opens Settings automatically when the key is missing, and saved changes apply without a restart.
4. Drop in one or more photos, or enter a text description, and start the analysis.
5. For web descriptions and photos, configure a Brave Search API key. Without it, geolocation and candidate scoring still run.

Keys and the PostGIS connection string are stored only in the current user's macOS Keychain, never in configuration files. No keys are included in the repository.

For batch or production workflows, connect a local PostGIS database built from OSM data. See the repository documentation.

Data sources and usage policy

By default SakuGIS uses the public OpenStreetMap Nominatim and Overpass services. These are volunteer-maintained and governed by explicit usage policies:

• Single interactive queries fall within normal use. Do not point batch, automated, or high-frequency workloads at the public endpoints.
• For work at scale, deploy a local OSM/PostGIS backend or self-hosted Nominatim and Overpass instances.
• Map and place data come from OpenStreetMap contributors under the ODbL.

Place photographs come from Brave image search. They are reference material only, do not indicate the actual capture location, and remain subject to the original publisher's rights. Results and thumbnails use a short-lived in-memory cache and are not written to disk.

The satellite layer in the current prototype uses a replaceable custom XYZ definition. The legacy Google tile endpoint it references is not a supported endpoint in the current Google Maps Tile API documentation. Deployers are responsible for confirming availability and usage rights and should substitute an officially supported provider in production.

Responsible use

SakuGIS is intended for geographic research, spatial verification in urban and disaster settings, and assisted interpretation when image location metadata is missing.

Do not use it to locate private photographs, track specific individuals, or for any purpose that infringes on privacy or personal safety. Do not submit private imagery containing identifiable personal information.

Candidate scores are ranking signals. They are not calibrated probabilities and should not be the sole basis for high-stakes decisions. Conclusions should be checked against the evidence, checks, and sources given in the report.

SakuGIS is research software. Version 0.4.0 is a test build, and interfaces and behaviour may change in later releases.

Known limitations

• Apple Silicon and macOS 13 or later only; no Windows or Linux build
• About 1.7 GB, because an independent QGIS runtime is bundled
• Not Apple-notarized, so first launch requires manual confirmation
• Requires a user-supplied model service key; API costs are borne by the user
• When public OSM services are used, results depend on network conditions and service rate limits

License and citation

SakuGIS is released under GNU GPL-2.0-or-later. QGIS and the bundled runtime components retain their respective licenses; redistribution obligations are listed in THIRD_PARTY_NOTICES.md.

If SakuGIS is used in research, it can be cited as:

@software{sakugis2026,
  title  = {SakuGIS: A Verifiable Image Geolocation Workbench with
            Multi-Agent Reasoning and OSM/PostGIS Verification},
  author = {UrbanComp Lab},
  year   = {2026},
  url    = {https://github.com/whuyao/SakuGIS},
  note   = {Version 0.4.0}
}

Documentation and feedback

• Architecture
• Geolocation agents
• PostGIS backend
• Report format
• Packaging
• Security policy

Please send issues and feature suggestions to GitHub Issues.