@saibolla/ada 0.1.2

package/skills/geomaster/references/coordinate-systems.md

@@ -0,0 +1,364 @@
+# Coordinate Reference Systems (CRS)
+
+Complete guide to coordinate systems, projections, and transformations for geospatial data.
+
+## Table of Contents
+
+1. [Fundamentals](#fundamentals)
+2. [Common CRS Codes](#common-crs-codes)
+3. [Projected vs Geographic](#projected-vs-geographic)
+4. [UTM Zones](#utm-zones)
+5. [Transformations](#transformations)
+6. [Best Practices](#best-practices)
+
+## Fundamentals
+
+### What is a CRS?
+
+A Coordinate Reference System defines how coordinates relate to positions on Earth:
+
+- **Geographic CRS**: Uses latitude/longitude (degrees)
+- **Projected CRS**: Uses Cartesian coordinates (meters, feet)
+- **Vertical CRS**: Defines height/depth (e.g., ellipsoidal heights)
+
+### Components
+
+1. **Datum**: Mathematical model of Earth's shape
+   - WGS 84 (EPSG:4326) - Global GPS
+   - NAD 83 (EPSG:4269) - North America
+   - ETRS89 (EPSG:4258) - Europe
+
+2. **Projection**: Transformation from curved to flat surface
+   - Cylindrical (Mercator)
+   - Conic (Lambert Conformal)
+   - Azimuthal (Polar Stereographic)
+
+3. **Units**: Degrees, meters, feet, etc.
+
+## Common CRS Codes
+
+### Geographic CRS (Lat/Lon)
+
+| EPSG | Name | Area | Notes |
+|------|------|------|-------|
+| 4326 | WGS 84 | Global | GPS default, use for storage |
+| 4269 | NAD83 | North America | USGS data, slightly different from WGS84 |
+| 4258 | ETRS89 | Europe | European reference frame |
+| 4612 | GDA94 | Australia | Australian datum |
+
+### Projected CRS (Meters)
+
+| EPSG | Name | Area | Distortion | Notes |
+|------|------|------|------------|-------|
+| 3857 | Web Mercator | Global (85°S-85°N) | High near poles | Web maps (Google, OSM) |
+| 32601-32660 | UTM Zone N | Global (1° bands) | <1% per zone | Metric calculations |
+| 32701-32760 | UTM Zone S | Global (1° bands) | <1% per zone | Southern hemisphere |
+| 3395 | Mercator | World | Moderate | World maps |
+| 5070 | CONUS Albers | USA (conterminous) | Low | US national mapping |
+| 2154 | Lambert-93 | France | Very low | French national projection |
+
+### Regional Projections
+
+**United States:**
+- EPSG:5070 - US National Atlas Equal Area (CONUS)
+- EPSG:6350 - US National Atlas (Alaska)
+- EPSG:102003 - USA Contiguous Albers Equal Area
+- EPSG:2227 - California Zone 3 (US Feet)
+
+**Europe:**
+- EPSG:3035 - Europe Equal Area 2001
+- EPSG:3857 - Web Mercator (web mapping)
+- EPSG:2154 - Lambert 93 (France)
+- EPSG:25832-25836 - UTM zones (ETRS89)
+
+**Other:**
+- EPSG:3112 - GDA94 / MGA zone 52 (Australia)
+- EPSG:2056 - CH1903+ / LV95 (Switzerland)
+- EPSG:4326 - WGS 84 (global default)
+
+## Projected vs Geographic
+
+### When to Use Geographic (EPSG:4326)
+
+✅ Storing data (databases, files)
+✅ Global datasets
+✅ Web APIs (GeoJSON, KML)
+✅ Latitude/longitude queries
+✅ GPS coordinates
+
+```python
+# Bad: Distance calculation in geographic CRS
+gpd.geographic_crs = "EPSG:4326"
+distance = gdf.geometry.length  # WRONG! Returns degrees, not meters
+
+# Good: Calculate distance in projected CRS
+gdf_projected = gdf.to_crs("EPSG:32633")  # UTM Zone 33N
+distance_m = gdf_projected.geometry.length  # Correct: meters
+```
+
+### When to Use Projected
+
+✅ Area/distance calculations
+✅ Buffer operations
+✅ Spatial analysis
+✅ High-resolution mapping
+✅ Engineering applications
+
+```python
+import geopandas as gpd
+
+# Project to appropriate UTM zone
+gdf = gpd.to_crs(gdf.estimate_utm_crs())
+
+# Now area and distance are accurate
+area_sqm = gdf.geometry.area
+buffer_1km = gdf.geometry.buffer(1000)  # 1000 meters
+```
+
+### Web Mercator Warning
+
+⚠️ **EPSG:3857 (Web Mercator) for visualization only**
+
+```python
+# DON'T use Web Mercator for area calculations
+gdf_web = gdf.to_crs("EPSG:3857")
+area = gdf_web.geometry.area  # WRONG! Significant distortion
+
+# DO use appropriate projection
+gdf_utm = gdf.to_crs("EPSG:32633")  # or estimate_utm_crs()
+area = gdf_utm.geometry.area  # Correct
+```
+
+## UTM Zones
+
+### Understanding UTM Zones
+
+Earth is divided into 60 zones (6° longitude each):
+- Zones 1-60: West to East
+- Each zone divided into North (326xx) and South (327xx)
+
+### Finding Your UTM Zone
+
+```python
+def get_utm_zone(longitude, latitude):
+    """Get UTM zone EPSG code from coordinates."""
+    import math
+
+    zone = math.floor((longitude + 180) / 6) + 1
+
+    if latitude >= 0:
+        epsg = 32600 + zone  # Northern hemisphere
+    else:
+        epsg = 32700 + zone  # Southern hemisphere
+
+    return f"EPSG:{epsg}"
+
+# Example
+get_utm_zone(-122.4, 37.7)  # Returns 'EPSG:32610' (Zone 10N)
+```
+
+### Auto-Detect UTM Zone with GeoPandas
+
+```python
+import geopandas as gpd
+
+# Load data
+gdf = gpd.read_file('data.geojson')
+
+# Estimate best UTM zone
+utm_crs = gdf.estimate_utm_crs()
+print(f"Best UTM CRS: {utm_crs}")
+
+# Reproject
+gdf_projected = gdf.to_crs(utm_crs)
+```
+
+### Special UTM Cases
+
+**UPS (Universal Polar Stereographic):**
+- EPSG:5041 - UPS North (Arctic)
+- EPSG:5042 - UPS South (Antarctic)
+
+**UTM Non-standard:**
+- EPSG:31466-31469 - German Gauss-Krüger zones
+- EPSG:2056 - Swiss LV95 (based on UTM principles)
+
+## Transformations
+
+### Basic Transformation
+
+```python
+from pyproj import Transformer
+
+# Create transformer
+transformer = Transformer.from_crs(
+    "EPSG:4326",  # WGS 84 (lat/lon)
+    "EPSG:32633", # UTM Zone 33N (meters)
+    always_xy=True  # Input: x=lon, y=lat (not y=lat, x=lon)
+)
+
+# Transform single point
+lon, lat = -122.4, 37.7
+x, y = transformer.transform(lon, lat)
+print(f"Easting: {x:.2f}, Northing: {y:.2f}")
+```
+
+### Batch Transformation
+
+```python
+import numpy as np
+from pyproj import Transformer
+
+# Arrays of coordinates
+lon_array = [-122.4, -122.3]
+lat_array = [37.7, 37.8]
+
+transformer = Transformer.from_crs("EPSG:4326", "EPSG:32610", always_xy=True)
+xs, ys = transformer.transform(lon_array, lat_array)
+```
+
+### Transformation with PyProj CRS
+
+```python
+from pyproj import CRS
+
+# Get CRS information
+crs = CRS.from_epsg(32633)
+
+print(f"Name: {crs.name}")
+print(f"Type: {crs.type_name}")
+print(f"Area of use: {crs.area_of_use.name}")
+print(f"Datum: {crs.datum.name}")
+print(f"Ellipsoid: {crs.ellipsoid_name}")
+```
+
+## Best Practices
+
+### 1. Always Know Your CRS
+
+```python
+import geopandas as gpd
+
+gdf = gpd.read_file('data.geojson')
+
+# Check CRS immediately
+print(f"CRS: {gdf.crs}")  # Should never be None!
+
+# If None, set it
+if gdf.crs is None:
+    gdf.set_crs("EPSG:4326", inplace=True)
+```
+
+### 2. Verify CRS Before Operations
+
+```python
+def ensure_same_crs(gdf1, gdf2):
+    """Ensure two GeoDataFrames have same CRS."""
+    if gdf1.crs != gdf2.crs:
+        gdf2 = gdf2.to_crs(gdf1.crs)
+        print(f"Reprojected gdf2 to {gdf1.crs}")
+    return gdf1, gdf2
+
+# Use before spatial operations
+zones, points = ensure_same_crs(zones_gdf, points_gdf)
+result = gpd.sjoin(points, zones, predicate='within')
+```
+
+### 3. Use Appropriate Projections
+
+```python
+# For local analysis (< 500km extent)
+gdf_local = gdf.to_crs(gdf.estimate_utm_crs())
+
+# For national/regional analysis
+gdf_us = gdf.to_crs("EPSG:5070")  # US National Atlas Equal Area
+gdf_eu = gdf.to_crs("EPSG:3035")  # Europe Equal Area
+
+# For web visualization
+gdf_web = gdf.to_crs("EPSG:3857")  # Web Mercator
+```
+
+### 4. Preserve Original CRS
+
+```python
+# Keep original as backup
+gdf_original = gdf.copy()
+original_crs = gdf.crs
+
+# Do analysis in projected CRS
+gdf_projected = gdf.to_crs(gdf.estimate_utm_crs())
+result = gdf_projected.geometry.buffer(1000)
+
+# Convert back if needed
+result = result.to_crs(original_crs)
+```
+
+## Common Pitfalls
+
+### Mistake 1: Area in Degrees
+
+```python
+# WRONG: Area in square degrees
+gdf = gpd.read_file('data.geojson')
+area = gdf.geometry.area  # Wrong!
+
+# CORRECT: Use projected CRS
+gdf_proj = gdf.to_crs(gdf.estimate_utm_crs())
+area_sqm = gdf_proj.geometry.area
+area_sqkm = area_sqm / 1_000_000
+```
+
+### Mistake 2: Buffer in Geographic CRS
+
+```python
+# WRONG: Buffer of 1000 degrees
+gdf['buffer'] = gdf.geometry.buffer(1000)
+
+# CORRECT: Project first
+gdf_proj = gdf.to_crs("EPSG:32610")
+gdf_proj['buffer_km'] = gdf_proj.geometry.buffer(1000)  # 1000 meters
+```
+
+### Mistake 3: Mixing CRS
+
+```python
+# WRONG: Spatial join without checking CRS
+result = gpd.sjoin(gdf1, gdf2, predicate='intersects')
+
+# CORRECT: Ensure same CRS
+if gdf1.crs != gdf2.crs:
+    gdf2 = gdf2.to_crs(gdf1.crs)
+result = gpd.sjoin(gdf1, gdf2, predicate='intersects')
+```
+
+## Quick Reference
+
+```python
+# Common operations
+
+# Check CRS
+gdf.crs
+rasterio.open('file.tif').crs
+
+# Reproject
+gdf.to_crs("EPSG:32633")
+
+# Auto-detect UTM
+gdf.estimate_utm_crs()
+
+# Transform single point
+from pyproj import Transformer
+tx = Transformer.from_crs("EPSG:4326", "EPSG:32610", always_xy=True)
+x, y = tx.transform(lon, lat)
+
+# Create custom CRS
+from pyproj import CRS
+custom_crs = CRS.from_proj4(
+    "+proj=utm +zone=10 +ellps=WGS84 +datum=WGS84 +units=m +no_defs"
+)
+```
+
+For more information, see:
+- [EPSG Registry](https://epsg.org/)
+- [PROJ documentation](https://proj.org/)
+- [pyproj documentation](https://pyproj4.github.io/pyproj/)

package/skills/geomaster/references/core-libraries.md

@@ -0,0 +1,273 @@
+# Core Geospatial Libraries
+
+This reference covers the fundamental Python libraries for geospatial data processing.
+
+## GDAL (Geospatial Data Abstraction Library)
+
+GDAL is the foundation for geospatial I/O in Python.
+
+```python
+from osgeo import gdal
+
+# Open a raster file
+ds = gdal.Open('raster.tif')
+band = ds.GetRasterBand(1)
+data = band.ReadAsArray()
+
+# Get geotransform
+geotransform = ds.GetGeoTransform()
+origin_x = geotransform[0]
+pixel_width = geotransform[1]
+
+# Get projection
+proj = ds.GetProjection()
+```
+
+## Rasterio
+
+Rasterio provides a cleaner interface to GDAL.
+
+```python
+import rasterio
+import numpy as np
+
+# Basic reading
+with rasterio.open('raster.tif') as src:
+    data = src.read()           # All bands
+    band1 = src.read(1)         # Single band
+    profile = src.profile       # Metadata
+
+# Windowed reading (memory efficient)
+with rasterio.open('large.tif') as src:
+    window = ((0, 100), (0, 100))
+    subset = src.read(1, window=window)
+
+# Writing
+with rasterio.open('output.tif', 'w',
+                   driver='GTiff',
+                   height=data.shape[0],
+                   width=data.shape[1],
+                   count=1,
+                   dtype=data.dtype,
+                   crs=src.crs,
+                   transform=src.transform) as dst:
+    dst.write(data, 1)
+
+# Masking
+with rasterio.open('raster.tif') as src:
+    masked_data, mask = rasterio.mask.mask(src, shapes=[polygon], crop=True)
+```
+
+## Fiona
+
+Fiona handles vector data I/O.
+
+```python
+import fiona
+
+# Read features
+with fiona.open('data.geojson') as src:
+    for feature in src:
+        geom = feature['geometry']
+        props = feature['properties']
+
+# Get schema and CRS
+with fiona.open('data.shp') as src:
+    schema = src.schema
+    crs = src.crs
+
+# Write data
+schema = {'geometry': 'Point', 'properties': {'name': 'str'}}
+with fiona.open('output.geojson', 'w', driver='GeoJSON',
+                schema=schema, crs='EPSG:4326') as dst:
+    dst.write({
+        'geometry': {'type': 'Point', 'coordinates': [0, 0]},
+        'properties': {'name': 'Origin'}
+    })
+```
+
+## Shapely
+
+Shapely provides geometric operations.
+
+```python
+from shapely.geometry import Point, LineString, Polygon
+from shapely.ops import unary_union
+
+# Create geometries
+point = Point(0, 0)
+line = LineString([(0, 0), (1, 1)])
+poly = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])
+
+# Geometric operations
+buffered = point.buffer(1)              # Buffer
+simplified = poly.simplify(0.01)        # Simplify
+centroid = poly.centroid                 # Centroid
+intersection = poly1.intersection(poly2) # Intersection
+
+# Spatial relationships
+point.within(poly)      # True if point inside polygon
+poly1.intersects(poly2) # True if geometries intersect
+poly1.contains(poly2)   # True if poly2 inside poly1
+
+# Unary union
+combined = unary_union([poly1, poly2, poly3])
+
+# Buffer with different joins
+buffer_round = point.buffer(1, quad_segs=16)
+buffer_mitre = point.buffer(1, mitre_limit=1, join_style=2)
+```
+
+## PyProj
+
+PyProj handles coordinate transformations.
+
+```python
+from pyproj import Transformer, CRS
+
+# Coordinate transformation
+transformer = Transformer.from_crs('EPSG:4326', 'EPSG:32633')
+x, y = transformer.transform(lat, lon)
+x_inv, y_inv = transformer.transform(x, y, direction='INVERSE')
+
+# Batch transformation
+lon_array = [-122.4, -122.3]
+lat_array = [37.7, 37.8]
+x_array, y_array = transformer.transform(lon_array, lat_array)
+
+# Always z/height if available
+transformer_always_z = Transformer.from_crs(
+    'EPSG:4326', 'EPSG:32633', always_z=True
+)
+
+# Get CRS info
+crs = CRS.from_epsg(4326)
+print(crs.name)  # WGS 84
+print(crs.axis_info)  # Axis info
+
+# Custom transformation
+transformer = Transformer.from_pipeline(
+    'proj=pipeline step inv proj=utm zone=32 ellps=WGS84 step proj=unitconvert xy_in=rad xy_out=deg'
+)
+```
+
+## GeoPandas
+
+GeoPandas combines pandas with geospatial capabilities.
+
+```python
+import geopandas as gpd
+
+# Reading data
+gdf = gpd.read_file('data.geojson')
+gdf = gpd.read_file('data.shp', encoding='utf-8')
+gdf = gpd.read_postgis('SELECT * FROM data', con=engine)
+
+# Writing data
+gdf.to_file('output.geojson', driver='GeoJSON')
+gdf.to_file('output.gpkg', layer='data', use_arrow=True)
+
+# CRS operations
+gdf.crs  # Get CRS
+gdf = gdf.to_crs('EPSG:32633')  # Reproject
+gdf = gdf.set_crs('EPSG:4326')  # Set CRS
+
+# Geometric operations
+gdf['area'] = gdf.geometry.area
+gdf['length'] = gdf.geometry.length
+gdf['buffer'] = gdf.geometry.buffer(100)
+gdf['centroid'] = gdf.geometry.centroid
+
+# Spatial joins
+joined = gpd.sjoin(gdf1, gdf2, how='inner', predicate='intersects')
+joined = gpd.sjoin_nearest(gdf1, gdf2, max_distance=1000)
+
+# Overlay operations
+intersection = gpd.overlay(gdf1, gdf2, how='intersection')
+union = gpd.overlay(gdf1, gdf2, how='union')
+difference = gpd.overlay(gdf1, gdf2, how='difference')
+
+# Dissolve
+dissolved = gdf.dissolve(by='region', aggfunc='sum')
+
+# Clipping
+clipped = gpd.clip(gdf, mask_gdf)
+
+# Spatial indexing (for performance)
+idx = gdf.sindex
+possible_matches = idx.intersection(polygon.bounds)
+```
+
+## Common Workflows
+
+### Batch Reprojection
+
+```python
+import geopandas as gpd
+from pathlib import Path
+
+input_dir = Path('input')
+output_dir = Path('output')
+
+for shp in input_dir.glob('*.shp'):
+    gdf = gpd.read_file(shp)
+    gdf = gdf.to_crs('EPSG:32633')
+    gdf.to_file(output_dir / shp.name)
+```
+
+### Raster to Vector Conversion
+
+```python
+import rasterio.features
+import geopandas as gpd
+from shapely.geometry import shape
+
+with rasterio.open('raster.tif') as src:
+    image = src.read(1)
+    results = (
+        {'properties': {'value': v}, 'geometry': s}
+        for s, v in rasterio.features.shapes(image, transform=src.transform)
+    )
+
+geoms = list(results)
+gdf = gpd.GeoDataFrame.from_features(geoms, crs=src.crs)
+```
+
+### Vector to Raster Conversion
+
+```python
+from rasterio.features import rasterize
+import geopandas as gpd
+
+gdf = gpd.read_file('polygons.gpkg')
+shapes = ((geom, 1) for geom in gdf.geometry)
+
+raster = rasterize(
+    shapes,
+    out_shape=(height, width),
+    transform=transform,
+    fill=0,
+    dtype=np.uint8
+)
+```
+
+### Combining Multiple Rasters
+
+```python
+import rasterio.merge
+import rasterio as rio
+
+files = ['tile1.tif', 'tile2.tif', 'tile3.tif']
+datasets = [rio.open(f) for f in files]
+
+merged, transform = rasterio.merge.merge(datasets)
+
+# Save
+profile = datasets[0].profile
+profile.update(transform=transform, height=merged.shape[1], width=merged.shape[2])
+
+with rio.open('merged.tif', 'w', **profile) as dst:
+    dst.write(merged)
+```
+
+For more detailed examples, see [code-examples.md](code-examples.md).