The Problem
Urban planners and GIS analysts need a way to turn raw spatial data—point clouds, OpenStreetMap (OSM) layers, and multi‑view imagery—into textual representations that large language models (LLMs) can reason over. Existing pipelines are fragmented, requiring separate tools for annotation, graph construction, and prompt engineering.
What This Does
SpatialLLM implements a three‑stage pipeline that converts heterogeneous city‑scale data into a structured “scene graph” (JSON) that can be fed directly to an LLM.
OSM ingestion – process/osmprocess.py reads shapefiles (--shppath) and outputs a JSON dump of building, road, and parcel attributes. Automatic point‑cloud annotation – process/autoannotate.py aligns a raw point cloud (.ply/.txt) with the OSM geometry, using a control‑text file (x y z lon lat per line) to generate an enriched point cloud and a mapping file. Scene‑graph generation – process/generatescenegraph.py merges the annotated cloud, OSM mapping, and original OSM JSON into a final graph (outputjson).
The resulting JSON can be used as context for any LLM (e.g., ChatGPT, Claude) to answer spatial queries such as navigation, site selection, or hazard analysis. Example PDFs in examples/ illustrate the downstream reasoning outcomes.
How To Use It
Create a clean Python 3.8 environment conda create -n spatialllm python=3.8 conda activate spatialllm Install geospatial stack (conda) and Python deps (pip) conda install -c conda-forge geopandas geopy gdal pip install -r requirements.txt
Data preparation
Place OSM shapefiles in a folder (e.g., data/WHU/) and point‑cloud files in a working directory.
Run the pipeline
Step 1: OSM → JSON
python process/osmprocess.py \ --shppath data/WHU/ \ --output data/WHU/WHU.json
Step 2: Point‑cloud annotation
python process/autoannotate.py \ --workdir work/ \ --shpdir data/WHU/ \ --pcfile city.ply \ --controltxt control.txt \ --res 0.5
Step 3: Build scene graph
python process/generatescenegraph.py \ --pcfile work/annotatedcity.ply \ --shpdir data/WHU/ \ --osmmapfile work/osmmap.json \ --osmjsonfile data/WHU/WHU.json \ --outputjson work/scenegraph.json
Inference
The repository ships a minimal inference script:
python infer/inference.py # reads infer/config.yaml
infer/config.yaml holds model identifiers, temperature, and the path to the generated scenegraph.json. Adjust it before running.
Real‑World Use
A city‑level decision support system can call generatescenegraph.py nightly on newly acquired LiDAR scans. The produced scenegraph.json is then passed to an LLM via the inference.py wrapper, enabling natural‑language queries like “Which parcels within a 500 m radius of the new subway station have excess flood risk?” The response can be fed back into a GIS dashboard for visual verification.
import json, requests
with open("work/scenegraph.json") as f: ctx = json.load(f)
payload = {"model": "gpt-4o", "messages": [{"role":"system","content":"You are a spatial analyst."}, {"role":"user","content":f"Answer: {ctx}"}]} resp = requests.post("https://api.openai.com/v1/chat/completions", json=payload, headers={"Authorization": f"Bearer {API_KEY}"}) print(resp.json()["choices"][0]["message"]["content"])
Code Health & Issues
Medium – No test suite – repository lacks any tests/ directory or pytest configuration. Medium – No CI/CD – no .github/workflows, Makefile, or similar automation; changes are not automatically validated. Low – Unpinned dependencies – requirements.txt lists packages without version pins; reproducibility depends on the current PyPI state. Low – Minimal documentation – README covers install and pipeline steps, but function‑level docstrings are sparse; users must read source to understand arguments. Low – No lockfile – absence of pipfile.lock or conda environment file makes exact environment recreation difficult. Low – License present – LICENSE file exists, mitigating legal risk.
No obvious security secrets are stored in the repo. Error handling in the three pipeline scripts is minimal; they assume well‑formed inputs and will raise uncaught exceptions on missing files or malformed control texts.
The Bottom Line
SpatialLLM provides a concrete end‑to‑end conversion from raw urban spatial data to LLM‑ready text, with clear scripts for each stage. It is usable for research prototypes or small‑scale municipal pilots, but the lack of tests, CI, and pinned dependencies means production deployments will require additional engineering effort to harden the pipeline and ensure repeatable builds.