msfootprint 0.1.31

msfootprint: A Python package for extracting Microsoft's global building footprints based on user-defined boundaries

This tool allows users to retrieve microsoft global building footprint data based on a specified boundary (such as a shapefile or GeoJSON). The footprints are then saved as Geopackage file to a specified output directory.

The computational engine of msfootprint leverages PySpark and split large areas into smaller tiles for parallel processing. Each tile is processed concurrently, significantly reducing execution time. PySpark's distributed architecture ensures efficient data handling and fault tolerance, enabling fast and reliable downloading of large geospatial datasets.

Features

• Supports multiple boundary input file formats: .shp, .gpkg, .kml, .geojson.
• Allows users to specify a boundary and retrieve building footprint data for a specific country or region or small study area.
• Faster downloading, feasible for large scale data download.
• Compatible with Google Earth Engine (GEE)/ required GEE authentications.

Usage

It needs a GEE account to access the data.

To install the required dependencies, run the following:

pip install msfootprint

W Once installed, import it in notebook or any python compiler.

import msfootprint as msf

Initialize all the variables

#Import all necessary things
import pathlib as Path
boundary_shp = Path('./shapefile_directory')
out_dir = Path('./output_directory')

#Import the 3 letter country ISO code of your study area, Eg. For Nepal, NPL, for United States of America it will be 'USA'
countryISO = 'USA'

For US, it is automated, so no need to give statename but for other countries having multiple tables need to follow aforementioned step

Now, run the main script

msf.BuildingFootprintwithISO(countryISO, boundary_shp, out_dir)

It will save the building footprint as geojson format in designated location.

Sometimes if above code doesnot works and has a error on accessing data, it needs earth-engine projectID to access the building footprint data If so,

#mention the ee projectID
geeprojectID = 'your-earth-engine-existing-projrct-id'

#run the code
msf.BuildingFootprintwithISO(countryISO, boundary_shp, out_dir, geeprojectID)

‼️ If Java RUN time error or something related to JAVA pops up!, it might be because of outdated JAVA in your system. For detailed configuration notes, see: JAVA setup.

Developers Usage

# Clone the repository
git clone https://github.com/supathdhitalGEO/msfootprint.git

cd msfootprint

uv venv   #Creating a virtual environment

#In Mac, Activate the environment
source .venv/bin/activate

#install development and testing dependencies
uv pip install -e .

uv pip install -e ".[dev]"

#and run the test
pytest tests/test_function.py

Cite this Work

If you use msfootprint in your work, please cite it as follows:

Dhital, S. (2025). msfootprint: A Python package for extracting Microsoft's global building footprints based on user-defined boundaries. Zenodo. https://doi.org/10.5281/zenodo.14595247

in BibTex,

@software{dhital2025msfootprint,
  author       = {S. Dhital},
  title        = {msfootprint: A Python package for extracting Microsoft's global building footprints based on user-defined boundaries},
  year         = {2025},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.14595247},
  url          = {https://doi.org/10.5281/zenodo.14595247}
}

For Any Information

Feel free to reach out to me: Supath Dhital
Email: sdhital@crimson.ua.edu