Updates to the autogeotagging algo for cleaning + speedup (#59)

* added utils functions for autogeotagging + updated to vectorized lat-lon translation to save time

* updated the tracker docs with the cleanup sequence--need to test

* added rect standardization functions to utils

* updated both geotagging examples with the new code

* add egg info to gitignore

* more fixing of broken unit tests

* updated more unit tests

* unit tests for the new functions

* update

* tons of docstring + pep8 adjustments

* update the unit tests

* check that all of the jupyter notebooks successfully run with updated functions + update all the documentation with new functions, etc

* make the readme look less trash

* update the readme again

* update the license call

---------

Co-authored-by: Perry <kperry@nrel.gov>

Author: kperrynrel

README.md

@@ -1,49 +1,88 @@
 ![Panel Segmentation Icon](docs/_static/panel_segmentation_cropped_icon.png)
 
-This repo contains the scripts for automated metadata extraction of solar PV installations, 
-using satellite imagery coupled with computer vision techniques. In this package, the user
-can perform the following actions:
-- Automatically generate a satellite image using a set of lat-long coordinates, and a Google 
-Maps API key. To get a Google Maps API key, go to the following site and set up an account:
-https://developers.google.com/maps/documentation/maps-static/get-api-key
-- Determine the presence of a solar array in the satellite image (boolean True/False), using a 
-classification model (VGG16_classification_model.h5).
-- Perform image segmentation on the satellite image, to locate the solar array(s) in the 
-image on a pixel-by-pixel basis, using an image segmentation model (VGG16Net_ConvTranpose_complete.h5).
-- Using connected components clustering, isolate individual solar arrays in the masked image.
-- Perform azimuth estimation on each solar array cluster in the masked image.
-- Using an object detection model (Faster R-CNN Resnet 50 trained via transfer learning), detect
-and classify mounting type and configuration of solar installations in satellite imagery. This includes
-classification of fixed tilt and single-axis trackers, as well as the rooftop, 
-ground, and carport mounting configurations.
-- Detect solar panels and get its latitude, longitude, and address within a geographic bounding box through the SOL-Searcher Pipeline.
-- Detect and calculate hurricane damage on solar installations given pre-hurricane and post-hurricane satellite imagery through the Hurricane Detection Pipeline.
-- Detect and calculate hail damage on solar installations given satellite imagery through the Hail Detection pipeline.
-- Convert NOAA MESH (Maximum Estimated Size of Hail) grib2 files into kml or geojson files.
-- Estimate tilt and azimuth of a solar array by processing USGS LiDAR data for the array's location.
-- Automatically estimate the solar array's tilt and azimuth by pulling and processing USGS LiDAR data
-within a shapely polygon outlining the solar array.
-
-To install Panel-Segmentation, perform the following steps:
-
-1. You must have Git large file storage (lfs) on your computer in order to download the deep learning models in this package. Go to the following site to download Git lfs: 
-
-https://git-lfs.github.com/
-
-2. Once git lfs is installed, you can now install Panel-Segmentation on your computer. We are still working on making panel-segmentation available via PyPi, so entering the following in the command line will install the package locally on your computer:
-
-git clone https://github.com/NatLabRockies/Panel-Segmentation.git
+# Panel-Segmentation
+
+Automated metadata extraction for solar PV installations using satellite imagery and computer vision.
+
+[![Build Status](https://github.com/NREL/Panel-Segmentation/actions/workflows/pytest.yaml/badge.svg)](https://github.com/NREL/Panel-Segmentation/actions)
+[![Documentation Status](https://readthedocs.org/projects/panel-segmentation/badge/?version=latest)](https://panel-segmentation.readthedocs.io/en/latest/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Overview
+
+Panel-Segmentation provides tools to detect, locate, and characterize solar PV installations from satellite and aerial imagery. It is developed at the [National Renewable Energy Laboratory (NREL)](https://www.nrel.gov/).
+
+**Capabilities include:**
+
+- **Satellite image retrieval** — pull imagery for any lat/lon coordinate via the Google Maps Static API
+- **Solar panel detection** — locate panels and retrieve their latitude, longitude, and address within a geographic bounding box (SOL-Searcher Pipeline)
+- **Storm damage assessment** — detect and quantify hurricane or hail damage on solar installations from before/after satellite imagery
+- **NOAA MESH conversion** — convert NOAA Maximum Estimated Size of Hail (MESH) grib2 files to KML or GeoJSON
+- **Tilt and azimuth estimation** — estimate array tilt and azimuth from USGS LiDAR data
+- **Mounting configuration classification** — identify roof-mount, ground-mount, carport, and other configurations using an instance segmentation model
+- **Site autotagging** — geolocate tracker rows, fixed-tilt rows, and inverters at utility-scale ground-mount sites using a deep learning pipeline
+
+---
+
+## Installation
+
+### Prerequisites
+
+Panel-Segmentation stores deep learning model weights via [Git Large File Storage (LFS)](https://git-lfs.github.com/). Install Git LFS before cloning:
+
+```bash
+# macOS
+brew install git-lfs
+
+# Linux
+sudo apt install git-lfs
+
+# Then initialize
+git lfs install
+```
+
+### Install from source
+
+```bash
+git clone https://github.com/NREL/Panel-Segmentation.git
 cd Panel-Segmentation
 pip install .
+```
 
-3. Panel-Segmentation requires the MMCV package, which can be tricky to install for CPU-only, and needs to be installed from source. To install MMCV for source, run the following in the command line:
+### Install MMCV (required for storm damage models)
 
+All CV models depend on MMCV, which must be built from source:
+
+```bash
 pip install git+https://github.com/open-mmlab/mmcv.git@v2.1.0
+```
+
+> **Note:** MMCV installation may take several minutes.
+
+---
+
+## Documentation
+
+Full documentation — including installation guides, API reference, pipeline tutorials, and example notebooks — is available at **[panel-segmentation.readthedocs.io](https://panel-segmentation.readthedocs.io/en/latest/)**.
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request on [GitHub](https://github.com/NREL/Panel-Segmentation).
+
+---
 
-Please note that installation will likely take several minutes, but is necessary for running any of the storm-related CV models.
+## Citation
 
-3. When initiating the PanelDetection() class, be sure to point your file paths to the model paths in your local Panel-Segmentation folder!
+If you use Panel-Segmentation in your research, please cite it using the following citation:
 
+K. Perry and C. Campos, "Panel Segmentation: A Python Package for Automated Solar Array Metadata Extraction Using Satellite Imagery," in IEEE Journal of Photovoltaics, vol. 13, no. 2, pp. 208-212, March 2023, doi: 10.1109/JPHOTOV.2022.3230565.
 
+---
 
+## License
 
+Panel-Segmentation is released under the [BSD 3-Clause License](LICENSE).

docs/changelog/1.0.0.rst

@@ -16,6 +16,8 @@ Scripts
 - Added the scripts for LiDAR pipeline in the lidar folder :py:mod:`panel_segmentation.lidar`. (:pull:`45`)
 - Added unit testing for all functions in the lidar folder. (:pull:`45`)
 - Added new panel-detection instance segmentation model and deprecated old models. This standardized all model architecture to MMDetetection (remove detecto dependency). (:pull:`55`)
+- Added new utils functions for faster computation + post-processing of autogeotagging pipeline, including :py:func:`panel_segmentation.utils.getRectangleDimensions`
+  and :py:func:`panel_segmentation.utils.standardizeRectangleWidth`. Updated existing functions for polygon generation from DL masks to be vectorized. (:pull:`59`)
 
 Bug Fixes
 ~~~~~~~~~

docs/examples/automated_geotagging/automated_geotagging_fixed_tilt_site.ipynb

@@ -27,6 +27,8 @@ Helper functions and utilities.
    utils.convertPolygonToGeojson
    utils.detectAzimuth
    utils.plotEdgeAz
+   utils.getRectangleDimensions
+   utils.standardizeRectangleWidth
 
 LiDAR
 -----