landlensdb: Geospatial Image Handling and Management

Streamlined geospatial image handling and database management

Overview

landlensdb helps you manage geolocated images and integrate them with other spatial data sources. The library supports:

• Image downloading and storage
• EXIF/geotag extraction
• Road-network alignment
• PostgreSQL integration
• Image anonymization (blur faces and license plates)

This workflow is designed for geo-data scientists, map enthusiasts, and anyone needing to process large sets of georeferenced images.

Features

• GeoImageFrame Management: Download, map, and convert geolocated images into a GeoDataFrame-like structure.
• Mapillary API Integration: Fetch and analyze images with geospatial metadata.
• EXIF Data Processing: Extract geolocation, timestamps, and orientation from image metadata.
• Database Operations: Store image records in PostgreSQL; retrieve them by location or time.
• Road Network Alignment: Snap image captures to road networks for precise route mapping.
• Image Anonymization: Automatically blur faces and license plates in street-level imagery using YOLOv8.

Installation

Install the latest release from PyPI:

pip install landlensdb

Dependencies

[!IMPORTANT] You MUST have both GDAL and PostgreSQL with PostGIS installed to use landlensdb.

• See GDAL Docs for instructions on installing GDAL.
• See PostGIS for installing PostGIS on top of PostgreSQL.

Minimum Requirements:

• GDAL ≥ 3.5 (ensure command-line tools work, e.g., gdalinfo --version)
• PostgreSQL ≥ 14
• PostGIS ≥ 3.5 (the extension must be installed in your PostgreSQL database)
• Python ≥ 3.10

Quick Start

Below is a minimal example creating a GeoImageFrame:

from landlensdb.geoclasses import GeoImageFrame
from shapely.geometry import Point

# Create a simple GeoImageFrame from scratch
geo_frame = GeoImageFrame(
	{
		"image_url": ["https://example.com/image1.jpg"],
		"name": ["SampleImage"],
		"geometry": [Point(-120.5, 35.2)]
	}
)

print(geo_frame.head())

Image Anonymization

Blur faces and license plates in street-level images:

from landlensdb.handlers.image import Local

# Load images with anonymization enabled
# Model downloads automatically on first use
images = Local.load_images(
    "/path/to/images",
    anonymize=True,
    overwrite=True  # Overwrite original images
)

# Or save to a new directory
images = Local.load_images(
    "/path/to/images",
    anonymize=True,
    anonymize_output_dir="/path/to/output"
)

The default model is based on dashcam_anonymizer. Custom models compatible with Ultralytics (YOLOv5/v8/v9/v10/v11, ONNX, TensorRT) can be specified via model_path.

For additional usage examples, see our documentation.

Documentation

Full documentation (including tutorials and advanced usage) is available in this repository's docs/ folder. You can build the docs locally by installing the optional [docs] extras:

pip install -e '.[docs]'
mkdocs serve

Then open http://127.0.0.1:8000/ in your browser.

Developer Guides

Local Development 1. Clone this repository. 2. Install in editable mode with dev extras: pip install --upgrade pip pip install -e .[dev] 3. Make changes as needed and contribute via Pull Requests.

Testing

We use pytest for testing. Tests requires the following test database. Create if does not exist:

createdb landlens_test && psql landlens_test -c "create extension postgis"

Then, we can run the tests:

pytest tests

You can also run specific test files or functions, for example:

pytest tests/test_geoimageframe.py

Code Formatting & Pre-commit

landlensdb uses Black for formatting. Once you’ve installed [dev] extras:

pre-commit install
pre-commit run --all-files

This enforces linting and formatting on each commit.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to open issues, submit pull requests, and follow our code of conduct.

License

This project is licensed under the MIT License. See LICENSE.md for details.