Metadata-Version: 2.1
Name: wind-turbine-academic-zt
Version: 1.1.1
Summary: Streamlined academic tool for wind turbine height estimation using 2D ground shadow models and ephemeris.
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 🌪️ Academic Wind Turbine Height Estimator (ZT)

A streamlined, industrial-grade Python tool for robust wind turbine height inversion from optical remote sensing imagery. 

Unlike traditional methods that struggle with relief displacement (satellite side-looking distortion), this tool strictly utilizes a **Pure Ground Shadow Model (Base-to-Shadow Tip)** extracted via deep learning. By operating entirely on the 2D ground plane, the system naturally immunizes itself against 3D satellite viewing geometric distortions.

## 🌟 Core Architectural Breakthroughs

* **Zero Distortion Inversion**: Relies purely on ground-projected shadow distances, eliminating the need for complex satellite elevation/azimuth compensation.
* **Triple-Track Data Injection**: Adaptive input routing handling standard metadata, manual overrides, or entirely missing metadata.
* **Astronomical Ephemeris Fallback**: Includes a built-in orbital mechanics engine. Provide the spatial coordinates and time, and the system mathematically resolves the solar geometry—no metadata required.

## 🛠️ Environment Initialization

```bash
pip install --upgrade wind-turbine-academic-zt
```

*(Note: Ensure PyTorch and Ultralytics YOLOv8 are properly configured in your environment before execution).*

## 🚀 Execution Protocols (Triple-Track Architecture)

The system operates via a unified CLI entry point. You must provide the target image (`--tiff`) and its Ground Sample Distance (`--gsd`).

Choose **ONE** of the three operational tracks based on your available data:

### Track 1: Automated XML Parsing (Standard)
Automatically extracts solar geometry from standard satellite metadata (e.g., GF-2). Includes anomaly interception for known telemetry issues (e.g., Zenith/Elevation confusion).
```bash
python main.py --tiff data/demo.tif --gsd 0.8 --xml data/demo.xml
```

### Track 2: Manual Angle Injection
Bypass metadata extraction entirely and inject a known solar elevation angle directly.
```bash
python main.py --tiff data/demo.tif --gsd 0.8 --sun_ele 63.18
```

### Track 3: Astronomical Ephemeris Mode (Metadata-Free)
If metadata is lost or corrupted (e.g., drone imagery, historical archives), provide the geospatial and temporal coordinates. The built-in ephemeris engine will resolve the solar angle mathematically.
```bash
python main.py --tiff data/demo.tif --gsd 0.8 --ephemeris --lat 38.25 --lon 107.10 --time "2026-05-25 04:00:00"
```

## 📊 Output Artifacts

Upon successful execution, verified artifacts are generated in the `output/` directory:
* `final_heights.csv`: Contains extracted Pixel Distances, Ground Shadow Lengths, and Calculated Physical Heights (m).
