gomd 2.1.0__py3-none-any.whl

gomd/spatial.py

@@ -0,0 +1,222 @@
+"""
+gomd.spatial — Geospatial Haversine Geometry, IHO Sea Basin Classification,
+Global Maritime Chokepoint Proximity, and OGC CRS84 GeoJSON / GeoDataFrame Tools
+================================================================================
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Dict, List, Sequence, Tuple
+
+EARTH_RADIUS_KM = 6371.0088
+KM_PER_NAUTICAL_MILE = 1.852
+
+# Canonical coordinates of the 10 strategic global maritime chokepoints
+GLOBAL_MARITIME_CHOKEPOINTS: List[Dict[str, Any]] = [
+    {"code": "BOSPORUS", "name": "Istanbul Strait (Bosporus)", "lat": 41.1194, "lon": 29.0753, "region": "Turkish Straits"},
+    {"code": "DARDANELLES", "name": "Canakkale Strait (Dardanelles)", "lat": 40.2000, "lon": 26.4000, "region": "Turkish Straits"},
+    {"code": "SUEZ", "name": "Suez Canal", "lat": 30.5852, "lon": 32.3426, "region": "Red Sea / Mediterranean"},
+    {"code": "BAB_EL_MANDEB", "name": "Bab el-Mandeb Strait", "lat": 12.5833, "lon": 43.3333, "region": "Red Sea / Gulf of Aden"},
+    {"code": "HORMUZ", "name": "Strait of Hormuz", "lat": 26.5667, "lon": 56.2500, "region": "Persian Gulf"},
+    {"code": "MALACCA", "name": "Strait of Malacca", "lat": 2.5000, "lon": 101.5000, "region": "Southeast Asia"},
+    {"code": "GIBRALTAR", "name": "Strait of Gibraltar", "lat": 35.9667, "lon": -5.5000, "region": "Western Mediterranean"},
+    {"code": "PANAMA", "name": "Panama Canal", "lat": 9.0800, "lon": -79.6800, "region": "Central America"},
+    {"code": "DOVER", "name": "Strait of Dover (English Channel)", "lat": 51.0167, "lon": 1.4833, "region": "North-East Atlantic"},
+    {"code": "DANISH_STRAITS", "name": "Danish Straits (Oresund / Great Belt)", "lat": 55.5500, "lon": 11.0000, "region": "Baltic Sea"},
+]
+GLOBAL_CHOKEPOINTS = GLOBAL_MARITIME_CHOKEPOINTS
+
+
+
+def haversine_distance(
+    lat1: float,
+    lon1: float,
+    lat2: float,
+    lon2: float,
+) -> Dict[str, float]:
+    """
+    Compute the exact great-circle orthodromic distance between two WGS84
+    coordinates in kilometers (`km`) and nautical miles (`nm`), plus initial bearing.
+    """
+    phi1 = math.radians(float(lat1))
+    phi2 = math.radians(float(lat2))
+    dphi = math.radians(float(lat2) - float(lat1))
+    dlam = math.radians(float(lon2) - float(lon1))
+
+    a = (
+        math.sin(dphi / 2.0) ** 2
+        + math.cos(phi1) * math.cos(phi2) * (math.sin(dlam / 2.0) ** 2)
+    )
+    c = 2.0 * math.asin(min(1.0, math.sqrt(max(a, 0.0))))
+    dist_km = EARTH_RADIUS_KM * c
+    dist_nm = dist_km / KM_PER_NAUTICAL_MILE
+
+    y = math.sin(dlam) * math.cos(phi2)
+    x = math.cos(phi1) * math.sin(phi2) - math.sin(phi1) * math.cos(phi2) * math.cos(dlam)
+    bearing = (math.degrees(math.atan2(y, x)) + 360.0) % 360.0
+
+    return {
+        "distance_km": round(dist_km, 3),
+        "distance_nm": round(dist_nm, 3),
+        "initial_bearing_deg": round(bearing, 2),
+    }
+
+
+def classify_sea_basin(lat: float, lon: float) -> Dict[str, str]:
+    """
+    Classify a geographic coordinate (lat, lon) into its canonical GOMD / IHO
+    Regional Sea Basin or Major Ocean Basin.
+    """
+    la = float(lat)
+    lo = float(lon)
+
+    if 40.3 <= la <= 41.3 and 26.5 <= lo <= 29.95:
+        return {"basin_code": "MARMARA", "basin_name": "Sea of Marmara & Turkish Straits", "ocean": "Mediterranean System"}
+    if 40.8 <= la <= 46.8 and 27.4 <= lo <= 42.0:
+        return {"basin_code": "BLACK_SEA", "basin_name": "Black Sea & Sea of Azov", "ocean": "Mediterranean System"}
+    if 35.0 <= la <= 41.0 and 22.5 <= lo <= 28.5:
+        return {"basin_code": "AEGEAN", "basin_name": "Aegean Sea", "ocean": "Mediterranean System"}
+    if 30.0 <= la <= 45.8 and 15.0 <= lo <= 36.5:
+        return {"basin_code": "MED_EAST", "basin_name": "Eastern Mediterranean & Levantine Basin", "ocean": "Mediterranean System"}
+    if 35.0 <= la <= 44.5 and -5.6 <= lo < 15.0:
+        return {"basin_code": "MED_WEST", "basin_name": "Western Mediterranean", "ocean": "Mediterranean System"}
+    if 12.5 <= la <= 30.0 and 32.0 <= lo <= 43.5:
+        return {"basin_code": "RED_SEA", "basin_name": "Red Sea", "ocean": "Indian Ocean"}
+    if 53.5 <= la <= 66.0 and 9.5 <= lo <= 30.5:
+        return {"basin_code": "BALTIC", "basin_name": "Baltic Sea (HELCOM)", "ocean": "Atlantic Ocean"}
+    if 51.0 <= la <= 62.0 and -4.0 <= lo < 9.5:
+        return {"basin_code": "NORTH_SEA", "basin_name": "Greater North Sea (OSPAR)", "ocean": "Atlantic Ocean"}
+    if la >= 66.5:
+        return {"basin_code": "ARCTIC", "basin_name": "Arctic Ocean", "ocean": "Arctic Ocean"}
+    if la <= -60.0:
+        return {"basin_code": "SOUTHERN_OCEAN", "basin_name": "Southern Ocean", "ocean": "Southern Ocean"}
+    if 20.0 <= lo <= 147.0 and la < 30.0:
+        return {"basin_code": "INDIAN_OCEAN", "basin_name": "Indian Ocean", "ocean": "Indian Ocean"}
+    if -70.0 <= lo <= 20.0:
+        return {"basin_code": "ATLANTIC", "basin_name": "Atlantic Ocean", "ocean": "Atlantic Ocean"}
+    return {"basin_code": "PACIFIC", "basin_name": "Pacific Ocean", "ocean": "Pacific Ocean"}
+
+
+def chokepoint_proximity(lat: float, lon: float) -> Dict[str, Any]:
+    """
+    Compute distances (`km` and `nm`) from `(lat, lon)` to all 10 major global
+    maritime chokepoints, sorted from nearest to farthest.
+    """
+    results: List[Dict[str, Any]] = []
+    for cp in GLOBAL_MARITIME_CHOKEPOINTS:
+        d = haversine_distance(lat, lon, cp["lat"], cp["lon"])
+        results.append(
+            {
+                "code": cp["code"],
+                "name": cp["name"],
+                "region": cp["region"],
+                "distance_km": d["distance_km"],
+                "distance_nm": d["distance_nm"],
+                "bearing_deg": d["initial_bearing_deg"],
+            }
+        )
+    results.sort(key=lambda r: r["distance_km"])
+    return {
+        "query_point": {"lat": float(lat), "lon": float(lon)},
+        "sea_basin": classify_sea_basin(lat, lon),
+        "nearest_chokepoint": results[0],
+        "chokepoints": results,
+    }
+
+
+def to_geojson(
+    records: Sequence[Dict[str, Any]],
+    lat_col: str = "latitude",
+    lon_col: str = "longitude",
+) -> Dict[str, Any]:
+    """
+    Convert a sequence of GOMD observation dicts carrying coordinate columns into an
+    OGC CRS84 (`urn:ogc:def:crs:OGC:1.3:CRS84`) GeoJSON FeatureCollection.
+    """
+    features: List[Dict[str, Any]] = []
+    for row in records:
+        if lat_col in row and lon_col in row and row[lat_col] is not None and row[lon_col] is not None:
+            try:
+                lat_v = float(row[lat_col])
+                lon_v = float(row[lon_col])
+            except (TypeError, ValueError):
+                continue
+            props = {k: v for k, v in row.items() if k not in (lat_col, lon_col)}
+            features.append(
+                {
+                    "type": "Feature",
+                    "geometry": {"type": "Point", "coordinates": [lon_v, lat_v]},
+                    "properties": props,
+                }
+            )
+    return {
+        "type": "FeatureCollection",
+        "crs": {"type": "name", "properties": {"name": "urn:ogc:def:crs:OGC:1.3:CRS84"}},
+        "features": features,
+    }
+
+
+def mavi_vatan_eez_audit(
+    mainland_coast_km: float = 1577.0,
+    opposite_coast_km: float = 19.0,
+    un_registered_area_km2: float = 462000.0,
+    provider_polygon_area_km2: float = 254026.0,
+    opposite_claimed_area_km2: float = 42000.0,
+    island_distance_from_mainland_nm: float = 1.9,
+    **kwargs: Any,
+) -> Dict[str, Any]:
+    """
+    ICJ Three-Stage Equitable Maritime Delimitation, Coastal-Length Proportionality &
+    Turkish Maritime Jurisdiction ("Mavi Vatan" — UN Letter A/74/757) Scientific Audit Model.
+
+    Evaluates third-party geodatabase polygons (e.g., VLIZ Marine Regions v12, EMODnet/DG MARE,
+    Seville Map median-line geometries) against International Court of Justice (ICJ) jurisprudence
+    (1969 North Sea Continental Shelf, 1985 Libya–Malta, 2009 Black Sea, 2012 Nicaragua–Colombia),
+    measuring coastal-length proportionality (R_L), maritime area attribution ratio (R_A),
+    ICJ Disproportionality Distortion Index (D_ICJ), island cut-off/encroachment weight,
+    and discrepancy against Türkiye's official UN-registered boundaries (~462,000 km²).
+    """
+    l_main = max(float(mainland_coast_km), 0.1)
+    l_opp = max(float(opposite_coast_km), 0.01)
+    a_un = max(float(un_registered_area_km2), 0.0)
+    a_prov = max(float(provider_polygon_area_km2), 0.0)
+    a_opp_claim = max(float(opposite_claimed_area_km2), 0.01)
+    dist_nm = max(float(island_distance_from_mainland_nm), 0.0)
+
+    coastal_length_ratio = l_main / l_opp
+    equitable_area_share_pct = (l_main / (l_main + l_opp)) * 100.0
+    provider_area_discrepancy_km2 = a_un - a_prov
+    provider_underattribution_pct = ((a_un - a_prov) / max(a_un, 1.0)) * 100.0
+
+    # ICJ island cut-off weight: small islands immediately adjacent to a mainland coast
+    # receive limited/enclaved territorial-sea effect rather than full continental shelf/EEZ
+    island_effect_weight = min(1.0, (l_opp / l_main) * math.exp(-dist_nm / 12.0))
+    disproportionality_ratio = (a_opp_claim / l_opp) / max(a_prov / l_main, 1e-6)
+    compliance_score = max(0.0, min(100.0, 100.0 - min(85.0, math.log1p(disproportionality_ratio) * 14.5)))
+
+    return {
+        "mainland_coast_km": round(l_main, 2),
+        "opposite_or_island_coast_km": round(l_opp, 2),
+        "coastal_length_proportionality_ratio": round(coastal_length_ratio, 2),
+        "coastal_length_ratio_mainland_to_island": round(coastal_length_ratio, 2),
+        "equitable_mainland_share_pct": round(equitable_area_share_pct, 2),
+        "un_registered_mavi_vatan_area_km2": round(a_un, 2),
+        "un_registered_mavi_vatan_km2": round(a_un, 2),
+        "provider_raw_polygon_area_km2": round(a_prov, 2),
+        "provider_area_discrepancy_km2": round(provider_area_discrepancy_km2, 2),
+        "provider_underattribution_pct": round(provider_underattribution_pct, 2),
+        "icj_island_effect_weight_0_1": round(island_effect_weight, 4),
+        "seville_map_disproportionality_factor": round(disproportionality_ratio, 2),
+        "equitable_delimitation_compliance_score": round(compliance_score, 2),
+        "authoritative_legal_basis": (
+            "UN Letter A/74/757 (18 March 2020); 2019 Türkiye-Libya MoU; "
+            "2011 Türkiye-TRNC Continental Shelf Delimitation Agreement; "
+            "ICJ North Sea (1969), Libya-Malta (1985), Black Sea (2009), Nicaragua-Colombia (2012)"
+        ),
+        "scientific_use_disclaimer": (
+            "External provider polygons (VLIZ Marine Regions, EMODnet/DG MARE, Seville Map, or unilateral GCA claims) "
+            "are retained strictly for scientific comparison and carry zero legal validity for the Republic of Türkiye."
+        ),
+    }
+