NXT GIS

NXT GIS is a Python FastAPI backend for advanced geospatial analysis, focused on infrastructure planning (e.g., electrical grid design). It provides APIs to analyze building footprints, suggest optimal utility pole placements, and compute efficient distribution lines using spatial algorithms and a PostGIS database.

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

---

Table of Contents

• Features
• API Endpoints
• Example Usage
• Geospatial Algorithms
• Database Requirements
• Environment Variables
• Google Earth Engine Setup
• Development
• Deployment
• Contributing
• Architecture
• License

---

Features

• Building Analysis: Query and filter buildings within a geographic area.
• Pole Placement: Suggests optimal utility pole locations to cover a set of points.
• Distribution Lines: Computes minimum spanning tree (MST) for efficient connection of poles.
• GeoJSON Support: All geospatial data is handled in standard GeoJSON format.
• PostGIS Integration: Leverages spatial queries for high performance.

---

API Endpoints

Endpoint	Method	Description
/buildings	POST	Returns buildings within a specified polygon, filtered by area.
/poles-by-coverage	POST	Suggests pole locations to cover a set of points using spatial algorithms.
/distribution-lines-by-poles	POST	Computes optimal distribution lines (MST) between poles.

Request/Response Examples

/buildings (POST)

Request Body:

{
  "outline": { "type": "Polygon", "coordinates": [[[...]]] },
  "min_building_area": 30,
  "source": "bing-maps-stored" // or "earth-engine-open-buildings" or "osm"
}

Response:

{
  "type": "FeatureCollection",
  "features": [ ... ]
}

/poles-by-coverage (POST)

Request Body:

{
  "points": { "type": "FeatureCollection", "features": [ ... ] },
  "radius_in_meters": 50,
  "algo": "KDTREE" // or "GREEDY"
}

Response: GeoJSON FeatureCollection of pole points.

/distribution-lines-by-poles (POST)

Request Body:

{
  "poles": { "type": "FeatureCollection", "features": [ ... ] }
}

Response: GeoJSON FeatureCollection of LineString features.

---

Geospatial Algorithms

• K-Center & Greedy Coverage: Used for optimal pole placement to cover all points within a given radius.
• Minimum Spanning Tree (MST): Used to compute the most efficient way to connect all poles with distribution lines.
• Spatial Filtering: Uses PostGIS to filter and analyze building geometries.

---

Database Requirements

• PostgreSQL with PostGIS extension enabled.
• Required tables: at minimum, a buildings table with a geometry column.
• Example setup:

  CREATE EXTENSION postgis;
  CREATE TABLE buildings (
    id SERIAL PRIMARY KEY,
    geom geometry(Polygon, 4326)
    -- other attributes...
  );

---

Environment Variables

Copy .env.example to .env and fill in the values:

Variable	Required	Default	Description
GEODATA_DB_HOST	Yes	—	PostgreSQL host
GEODATA_DB_PORT	Yes	—	PostgreSQL port (typically 5432)
GEODATA_DB_NAME	Yes	—	Database name
GEODATA_DB_USERNAME	Yes	—	Database user
GEODATA_DB_PASSWORD	Yes	—	Database password
CORS_ALLOWED_ORIGINS	No	http://localhost:4200,http://localhost:4300	Comma-separated list of allowed CORS origins
CORS_ALLOWED_ORIGIN_REGEX	No	—	Optional regex for allowed CORS origins (e.g. for deploy preview URLs)
EARTH_ENGINE_PROJECT_ID	Yes	—	GCP project ID of your Earth Engine service account
EARTH_ENGINE_CLIENT_EMAIL	Yes	—	Service account email (e.g. name@project.iam.gserviceaccount.com)
EARTH_ENGINE_CLIENT_ID	Yes	—	Numeric client ID of the service account
EARTH_ENGINE_CLIENT_X509_CERT_URL	Yes	—	Certificate URL for the service account key
EARTH_ENGINE_PRIVATE_KEY	Yes	—	PEM private key (newlines escaped as \n)
EARTH_ENGINE_PRIVATE_KEY_ID	Yes	—	ID of the private key

---

Google Earth Engine Setup

The /buildings endpoint can fetch building footprints from Google Earth Engine (Open Buildings). To use this source you need a GCP service account authorized for Earth Engine.

1. Create a Google Cloud project

Go to the Google Cloud Console and create a new project (or use an existing one).

2. Enable the Earth Engine API

In your project, navigate to APIs & Services → Library and enable the Google Earth Engine API.

3. Register the project with Earth Engine

Visit earthengine.google.com and register your Cloud project. This is a one-time step required before the API can be used.

4. Create a service account

In IAM & Admin → Service Accounts, create a new service account. Grant it the Earth Engine Resource Viewer role (or Editor if write access is needed).

5. Generate a key

Select the service account, go to Keys → Add Key → Create new key, choose JSON, and download the file.

6. Map the JSON fields to env vars

The downloaded JSON contains all the values you need:

Env var	JSON field
EARTH_ENGINE_PROJECT_ID	project_id
EARTH_ENGINE_CLIENT_EMAIL	client_email
EARTH_ENGINE_CLIENT_ID	client_id
EARTH_ENGINE_CLIENT_X509_CERT_URL	client_x509_cert_url
EARTH_ENGINE_PRIVATE_KEY	private_key (escape newlines as \n)
EARTH_ENGINE_PRIVATE_KEY_ID	private_key_id

---

Development

1. Install Python 3.13+

We recommend using Homebrew to install Python on macOS:

brew install python

Set your PATH to use the Homebrew-installed Python (not the system Python):

export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH

Check your Python version:

python3 --version

2. Create a Virtual Environment (one-time)

Create a virtual environment in your project directory (do this only once):

python3 -m venv .venv

3. Activate the Virtual Environment (every new terminal session)

Activate the virtual environment before working on the project (do this every time you open a new terminal):

source .venv/bin/activate

To deactivate the virtual environment:

deactivate

4. Upgrade pip (recommended)

python3 -m pip install --upgrade pip

5. Install Dependencies

Install all required packages from requirements.txt:

pip install -r requirements.txt

If you add or update packages, regenerate the requirements file:

pip freeze > requirements.txt

6. Run the Server Locally

Start the FastAPI server with Uvicorn:

uvicorn src.app:app --reload

---

Deployment

For production, use Gunicorn with Uvicorn workers (as defined in the Procfile). The recommended number of workers is (2 x number_of_cores) + 1. Note that on many cloud providers, a "vCPU" maps to a single hyper-thread rather than a full physical core — so 1 vCPU on a basic plan is effectively only a single thread. Check your provider's documentation to understand how many physical threads you actually have before sizing workers.

• Gunicorn worker rule of thumb
• On threads and vCPUs
• Example: DigitalOcean vCPU explanation

---

Contributing

See CONTRIBUTING.md for guidelines on how to set up your environment, open issues, and submit pull requests.

---

Architecture

flowchart TD
    Client["Client (Web/App)"]
    API["NXT GIS FastAPI Server"]
    DB["PostGIS Database (Bing Maps Stored)"]
    GEE["Google Earth Engine API (Open Buildings)"]
    OSM["OpenStreetMap Overpass API"]

    Client <--> API
    API <--> DB
    API <--> GEE
    API <--> OSM

Loading

The NXT GIS FastAPI server fetches the buildings layer from three possible sources, depending on the request:

• PostGIS Database (Bing Maps Stored): For stored building footprints.
• Google Earth Engine API (Open Buildings): For up-to-date building outlines from satellite data.
• OpenStreetMap Overpass API: For community-sourced building data.

The client specifies the desired source in the /buildings API request.

---

License

NXT GIS is licensed under the Mozilla Public License 2.0. See LICENSE for the full text.

SPDX-License-Identifier: MPL-2.0

Third-party dependency licenses

NXT GIS links against psycopg2-binary for PostgreSQL/PostGIS access. That package is distributed under the GNU Lesser General Public License with additional exceptions that relax linking restrictions for applications using the library (as described in the psycopg license). Review that license if you redistribute or bundle dependencies. Other libraries pulled in via requirements.txt carry their own terms; use a tool such as pip-licenses for an inventory.