wesamoyo-geotools 1.2.0
Professional geospatial engine for surveying, civil engineering, and high-precision UTM transformations with Combined Scale Factor (CSF)
Requires Python: >=3.8
Keywords: surveying, geospatial, GIS, COGO, UTM, Houndtid Labs Uganda, civil engineering, CSF, Uganda, East Africa, coordinate conversion, traverse adjustment, wesamoyo

markdown
# 🌍 Wesamoyo GeoTools

**High-Precision Geospatial Engine for Surveyors, Civil Engineers & GIS Professionals**

Developed by **Houndtid Labs Uganda** — engineered for East African surveying conditions and global precision standards.

---

## 🎯 Why Wesamoyo?

Unlike standard converters, Wesamoyo GeoTools accounts for **Earth curvature**, **elevation distortion**, and **local UTM zones** (35N/36N split). Your data is ready for **real-world construction** and **legal land surveying** — not just mapping.

---

## 🚀 Professional Engineering Features

### 1. High-Precision Coordinate Transformation
| Feature | Description |
|--------|-------------|
| **Geographic ↔ UTM** | Convert between WGS84 Lat/Long and UTM Easting/Northing |
| **3D Awareness** | Full support for Ellipsoidal Height (Elevation) |
| **Automatic Zone Detection** | Identifies UTM Zones automatically — including Uganda's 35N/36N split |
| **Southern Hemisphere Logic** | Correctly handles 10,000,000m False Northing for projects in Mbarara, Masaka, Kampala |

---

### 2. Engineering Scale Factor Suite — Critical for Construction
**Don't just move points — correct them.**

| Factor | Purpose |
|--------|---------|
| **Grid Scale Factor (k)** | Corrects UTM projection distortion |
| **Elevation Factor (EF)** | Accounts for height above ellipsoid (Sea Level) |
| **Combined Scale Factor (CSF)** | 🟡 **The Golden Number** — converts Map Distance to Ground Distance |

> ✅ Used by surveyors to ensure tape-measured distances match engineering designs.

---

### 3. Professional Survey IO — Multi-Format Export
Take **one CSV** and generate deliverables for **every department**:

| Format | Use Case |
|--------|----------|
| **AutoCAD (DXF)** | 3D DXF files — points appear at true elevation in Civil 3D/AutoCAD |
| **Web/Mobile (GeoJSON)** | 3D GeoJSON for Google Maps, Leaflet, mobile apps |
| **Clean Survey CSV** | Sanitized output with Easting, Northing, Zone, CSF metadata |

---

## 📦 Installation

```bash
pip install wesamoyo-geotools
🎯 Quick Start Examples
📁 Bulk Process a Survey CSV
Process thousands of site points in seconds.

python
from wesamoyo_geotools.io import SurveyIO
from wesamoyo_geotools.coordinates import CoordinateConverter

# Automatically detects 'lat', 'lon', 'alt' or 'lng' headers
SurveyIO.process_csv(
    "field_data.csv", 
    "final_report.csv", 
    CoordinateConverter.latlong_to_utm
)
📐 Engineering Math Test (3D)
Verify the Combined Scale Factor for a high-altitude project.

python
from wesamoyo_geotools.coordinates import CoordinateConverter

conv = CoordinateConverter()

# Lat: 1.0°, Lon: 34.0°, Alt: 2000m (Elevation)
res = conv.latlong_to_utm(1.0, 34.0, 2000.0)

print(f"Easting: {res.easting:.3f}")
print(f"Northing: {res.northing:.3f}")
print(f"Combined Scale Factor: {res.combined_scale_factor:.8f}")
🏗️ Export for AutoCAD
python
from wesamoyo_geotools.io import SurveyIO

points = [
    (611263.8, 110547.1, 2000.0),
    (611300.5, 110600.2, 2005.0)
]

SurveyIO.export_to_dxf(points, "site_plan.dxf")
📊 Industry Use Cases
Industry	Application
🛣️ Road & Bridge Construction	Use CSF to ensure ground-measured distances match engineering design
📋 Cadastral Surveying	Process land parcel boundaries with high-precision WGS84 math
⛰️ Topographic Mapping	Generate 3D DXF points for contouring in AutoCAD
🏢 Real Estate Tech	Convert GPS coordinates for web-based property portals via GeoJSON
🛠 Advanced Capabilities
🧠 Smart Header Detection — No need to format your CSV perfectly. Engine finds latitude, lat, y, longitude, lon, lng, alt, elevation automatically.

🛡️ Robust Error Handling — Skips messy data rows without crashing batch processes.

📦 3D Geometry — All exports maintain Z (Elevation) values for full BIM/CAD integration.

🏢 About Houndtid Labs Uganda
Houndtid Labs Uganda specializes in geospatial engineering solutions for the East African construction and surveying industry. We build tools that work accurately at the equator and beyond.

Contact: houndtidai@gmail.com
Website: https://houndtid.com

📄 Terms of Use
Proprietary Software — All rights reserved.

This software is the property of Houndtid Labs Uganda. It is provided for use under license and may not be copied, modified, distributed, or reverse-engineered without explicit written permission.

For licensing inquiries: houndtidai@gmail.com