aerialgeometry
Vision-only camera-geometry prediction from a single aerial image.
aerialgeometry is a command-line tool and a small Python library that takes
one RGB image captured by an aerial platform and predicts the camera
geometry:
| Output | Meaning | Values |
|---|---|---|
height |
drone altitude above ground | meters |
distance |
horizontal distance to the imaged subject | meters |
angle |
viewing angle | 30°, 60° or 90° |
It is the self-contained, pip-installable version of the research script
infer.py behind
Rectifying Geometry-Induced Similarity Distortions for Real-World Aerial–Ground Person Re-Identification — Kailash A. Hambarde, Hugo Proença. arXiv:2601.21405.
About
Aerial–ground person re-identification (AG-ReID) must match people across drone and ground cameras with extreme differences in altitude, distance and viewing angle. The GeoReID framework conditions its matching on explicit camera geometry. When a dataset does not provide that metadata, GeoReID obtains it with a vision-only multi-task geometry prediction network (Fig. 3, Sec. III-B of the paper) — and that is exactly what this package ships.
A shared ResNet-50 encoder extracts visual features, followed by two task-specific heads: a regression head for altitude and horizontal distance, and a classification head for the viewing angle. This package contains only the geometry predictor; the full GeoReID framework lives in the GeoReID repository.
Model card
| Task | Vision-only camera-geometry estimation (no external sensors) |
| Input | Single RGB image |
| Outputs | altitude, horizontal distance, viewing angle |
| Backbone | ResNet-50 (ImageNet-pretrained) |
| Heads | 2-output regression + 3-class classification |
| Preprocessing | resize 256×256 → center-crop 224×224 → ImageNet normalization |
| Framework | PyTorch / torchvision |
| Held-out metrics (stored in the released checkpoint) | height MAE 3.39 m · distance MAE 3.86 m · angle accuracy 92.3% |
| Benchmarks | AG-ReIDv1, AG-ReIDv2, CARGO, DetReIDX |
Units are meters because that is how the underlying benchmarks annotate geometry. The angle classifier is restricted to the three viewing angles used in the datasets: 30°, 60° and 90°.
Installation
Requires Python 3.9 or later.
python3 -m pip install aerialgeometry
torch and torchvision are installed as dependencies. Inference runs on
CPU; if a CUDA-capable GPU and a matching PyTorch build are available, it is
used automatically.
To install the latest revision straight from git:
python3 -m pip install 'git+https://github.com/kailashhambarde/GeoReID'
Model weights
The trained checkpoint (~100 MB) is not bundled with the package. The predictor looks for weights in this order:
- the
--model-pathCLI argument /model_path=Python argument, - the
AERIALGEOMETRY_MODELenvironment variable, - cached weights at
~/.cache/aerialgeometry/best.pth, - an automatic download from the
AERIALGEOMETRY_MODEL_URLenvironment variable (e.g. a GitHub release asset or a Hugging Face file).
The simplest setup for end users is to host the checkpoint somewhere public and export the URL once:
export AERIALGEOMETRY_MODEL_URL="https://github.com/<you>/GeoReID/releases/download/v1.0/best.pth"
aerialgeometry photos/
# downloads ~/.cache/aerialgeometry/best.pth on first run, then predicts
To prepare a slim checkpoint from your training run (drop the optimizer and scheduler state, keep only what inference needs):
import torch
ckpt = torch.load("runs/drone_predictor_gpu1/best.pth", map_location="cpu", weights_only=False)
torch.save(
{
"model_state": ckpt["model_state"],
"normalization_stats": ckpt["normalization_stats"],
},
"best.pth",
)
Quick start
# every image in a folder (recursively) -> predictions.txt
aerialgeometry photos/
# a single image -> one row on stdout
aerialgeometry photo.jpg
from aerialgeometry import Predictor
predictor = Predictor() # cached / auto-downloaded weights
pred = predictor.predict("photo.jpg")
print(pred.height, pred.distance, pred.angle) # e.g. 88.41 117.02 60.0
Command line
usage: aerialgeometry [-h] [-o OUTPUT] [--model-path MODEL_PATH]
[--device DEVICE] [--batch-size BATCH_SIZE]
[--version]
input
Estimate drone height, distance and viewing angle from aerial images
(arXiv:2601.21405).
positional arguments:
input Folder of images (scanned recursively) or a single
image file.
optional arguments:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
Output CSV file. For a folder input the default is
<input>/predictions.txt; for a single image the
default is stdout.
--model-path MODEL_PATH
Path to the trained checkpoint. Defaults to cached
weights; see README for AERIALGEOMETRY_MODEL /
AERIALGEOMETRY_MODEL_URL.
--device DEVICE Torch device, e.g. 'cpu' or 'cuda:0' (default: auto).
--batch-size BATCH_SIZE
Number of images to process per batch (default: 8).
--version Print version number and exit.
Examples:
aerialgeometry photos/ -o out/predictions.csv
aerialgeometry photos/ --model-path best.pth --device cpu
aerialgeometry photos/ --batch-size 32 --device cuda:0 # large jobs on GPU
The output is CSV with columns image_path,height,distance,angle (identical
to the original infer.py predictions.txt format, so existing pipelines
keep working):
image_path,height,distance,angle
photos/0401_05_04_2024_09_39_90_120_60_...jpg,88.4123,117.0234,60.0
Python API
from aerialgeometry import Predictor
# Uses cached / auto-downloaded weights; pass model_path=... for a checkpoint.
predictor = Predictor(device="cuda:0") # device is optional, auto-detected
# Single image (file path or PIL image)
pred = predictor.predict("photo.jpg")
print(pred.height) # 88.41 (meters)
print(pred.distance) # 117.02 (meters)
print(pred.angle) # 60.0 (30 / 60 / 90)
print(pred.angle_probabilities) # [0.01 0.98 0.01] over [30, 60, 90]
# Batch a list of images directly (paths and/or PIL images, order preserved)
preds = predictor.predict_batch(["a.jpg", "b.jpg", some_pil_image])
for pred in preds:
print(pred.height, pred.distance, pred.angle)
# Scan a folder (processed in batches of 8 by default; adjust for big jobs)
for path, pred in predictor.predict_folder("photos/", batch_size=64):
print(path, pred.height, pred.distance, pred.angle)
The model is also importable for embedding into larger systems:
from aerialgeometry import MultiTaskModel
model = MultiTaskModel() # ResNet-50 + regression/classification heads
How it works
- Each image is resized to 256×256 and center-cropped to 224×224, then normalized with ImageNet statistics (the same pipeline used in training).
- The ResNet-50 backbone produces a shared feature vector.
- The regression head predicts altitude and horizontal distance, denormalized with the mean/std statistics stored in the checkpoint.
- The classification head predicts the viewing angle among {30, 60, 90}°.
The network was trained on aerial imagery where the filenames carry the
ground-truth geometry
(PID_DD_MM_YYYY_HH_MM_altitude_distance_angle_...), so it requires no
external sensors at inference time.
Numerical note. On GPUs PyTorch may use TF32 arithmetic by default, so GPU predictions can differ from CPU predictions by a few centimeters — negligible relative to the model's error, and the angle class is unaffected.
Results
The full GeoReID framework is evaluated on four aerial–ground person ReID benchmarks — AG-ReIDv1, AG-ReIDv2, CARGO and DetReIDX — where it improves cross-view matching, especially in high-altitude and large viewing-angle regimes. Complete tables and ablations are in the paper.
Publishing to PyPI
From the project root:
python3 -m pip install build twine
python3 -m build # builds sdist + wheel into dist/
python3 -m twine upload dist/* # enter your PyPI credentials
Then users can pip install aerialgeometry. Remember to host the checkpoint
and set AERIALGEOMETRY_MODEL_URL (or document --model-path).
Citation
If you use this tool in your research, please cite:
@article{hambarde2026rectifying,
title={Rectifying Geometry-Induced Similarity Distortions for Real-World Aerial-Ground Person Re-Identification},
author={Hambarde, Kailash A and Proen{\c{c}}a, Hugo},
journal={arXiv preprint arXiv:2601.21405},
year={2026}
}
Acknowledgements
This work was supported by national funds through FCT – Fundação para a Ciência e a Tecnologia, I.P., and, when applicable, co-funded by EU funds under project UID/50008/2025 – Instituto de Telecomunicações.
License
MIT. See LICENSE.
Metadata
Release files for aerialgeometry 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aerialgeometry-0.1.0.tar.gz | 15.9 kB | With provenance | Details for aerialgeometry-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aerialgeometry-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for aerialgeometry-0.1.0-py3-none-any.whl |
Total release size: 29.9 kB
Release files / aerialgeometry-0.1.0.tar.gz
| Download URL | aerialgeometry-0.1.0.tar.gz |
|---|---|
| Size | 15.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
caa4c8e42f62a6a2fc1efc3c2dbd93152a2b5cb9fbf59bbe0970c249b9b3eb9c
|
|
BLAKE2b-256 checksum How to use checksums |
63077094da621bf8fef43bf00c979219dc60ed07f18853ae8aa978cbfe4651f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2026.
Transparency logRelease files / aerialgeometry-0.1.0-py3-none-any.whl
| Download URL | aerialgeometry-0.1.0-py3-none-any.whl |
|---|---|
| Size | 14.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dbe72209c272a76498bef61b28b306f539acfca2871f51658d7bd0db64b65b01
|
|
BLAKE2b-256 checksum How to use checksums |
ae1b59df7eb6ff2e07a021651de6f0f311887fb7778089a5078e25b814dff9da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2026.
Transparency logSecurity for aerialgeometry 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for aerialgeometry-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.