geo-intel-offline 1.0.1__py3-none-any.whl

geo_intel_offline/pip.py

@@ -0,0 +1,150 @@
+"""
+Point-in-Polygon (PIP) algorithm using Ray Casting.
+
+Ray Casting Algorithm:
+- Cast a ray from the point to infinity (we use East, +X direction)
+- Count intersections with polygon edges
+- Odd intersections = inside, even = outside
+
+Design Decisions:
+1. Ray Casting chosen over Winding Number for:
+   - Simpler implementation
+   - Better performance
+   - Deterministic results
+
+2. Handle polygon rings (exterior + holes):
+   - Exterior ring: inside = true
+   - Interior rings (holes): inside = false
+
+3. Edge cases handled:
+   - Points on vertices
+   - Points on edges
+   - Horizontal rays (collinear with edges)
+"""
+
+from typing import List, Tuple
+
+
+def point_in_polygon(
+    point: Tuple[float, float],
+    polygon: List[Tuple[float, float]]
+) -> bool:
+    """
+    Check if a point is inside a polygon using ray casting.
+    
+    Args:
+        point: (lat, lon) tuple
+        polygon: List of (lat, lon) tuples forming polygon ring
+    
+    Returns:
+        True if point is inside polygon, False otherwise
+    """
+    if not polygon or len(polygon) < 3:
+        return False
+    
+    lat, lon = point
+    inside = False
+    
+    # Ray casting: check intersections with horizontal ray going East
+    j = len(polygon) - 1
+    for i in range(len(polygon)):
+        lat_i, lon_i = polygon[i]
+        lat_j, lon_j = polygon[j]
+        
+        # Check if ray crosses edge
+        if ((lat_i > lat) != (lat_j > lat)):
+            # Calculate intersection point
+            if lon_j != lon_i:
+                # Avoid division by zero (horizontal edges)
+                intersect_lon = (lat - lat_i) * (lon_j - lon_i) / (lat_j - lat_i) + lon_i
+            else:
+                intersect_lon = lon_i
+            
+            # Count intersection if ray crosses to the right
+            if lon < intersect_lon:
+                inside = not inside
+        
+        j = i
+    
+    return inside
+
+
+def point_in_polygon_with_holes(
+    point: Tuple[float, float],
+    exterior: List[Tuple[float, float]],
+    holes: List[List[Tuple[float, float]]] = None
+) -> bool:
+    """
+    Check if point is in polygon with holes (interior rings).
+    
+    Design Decision: Exterior ring defines inclusion, holes define exclusion.
+    This handles countries with lakes, islands with lakes, etc.
+    
+    Args:
+        point: (lat, lon) tuple
+        exterior: Exterior polygon ring
+        holes: List of interior rings (holes)
+    
+    Returns:
+        True if point is inside exterior but not in any hole
+    """
+    if not point_in_polygon(point, exterior):
+        return False
+    
+    # Check if point is in any hole (exclude from result)
+    if holes:
+        for hole in holes:
+            if point_in_polygon(point, hole):
+                return False
+    
+    return True
+
+
+def distance_to_polygon_edge(
+    point: Tuple[float, float],
+    polygon: List[Tuple[float, float]]
+) -> float:
+    """
+    Calculate minimum distance from point to polygon edge.
+    
+    Used for confidence scoring: closer to edge = lower confidence.
+    
+    Args:
+        point: (lat, lon) tuple
+        polygon: Polygon ring
+    
+    Returns:
+        Distance in degrees (approximate, for confidence scoring)
+    """
+    if not polygon:
+        return float('inf')
+    
+    min_dist = float('inf')
+    lat, lon = point
+    
+    j = len(polygon) - 1
+    for i in range(len(polygon)):
+        lat_i, lon_i = polygon[i]
+        lat_j, lon_j = polygon[j]
+        
+        # Distance to line segment
+        # Use point-to-line-segment distance formula
+        dx = lon_j - lon_i
+        dy = lat_j - lat_i
+        
+        if dx == 0 and dy == 0:
+            # Degenerate segment (point)
+            dist = ((lat - lat_i) ** 2 + (lon - lon_i) ** 2) ** 0.5
+        else:
+            # Project point onto line segment
+            t = max(0, min(1, ((lat - lat_i) * dy + (lon - lon_i) * dx) / (dx * dx + dy * dy)))
+            
+            proj_lat = lat_i + t * dy
+            proj_lon = lon_i + t * dx
+            
+            dist = ((lat - proj_lat) ** 2 + (lon - proj_lon) ** 2) ** 0.5
+        
+        min_dist = min(min_dist, dist)
+        j = i
+    
+    return min_dist

geo_intel_offline/polygon_utils.py

@@ -0,0 +1,104 @@
+"""
+Shared polygon processing utilities.
+Consolidates duplicate code from data builders.
+"""
+
+from typing import List, Tuple, Dict
+
+
+def calculate_bounding_box(polygon: List[Tuple[float, float]]) -> Tuple[float, float, float, float]:
+    """Calculate bounding box for a polygon."""
+    if not polygon:
+        return 0.0, 0.0, 0.0, 0.0
+    
+    lats = [p[0] for p in polygon]
+    lons = [p[1] for p in polygon]
+    return min(lats), max(lats), min(lons), max(lons)
+
+
+def calculate_adaptive_step_size(lat_range: float, lon_range: float) -> float:
+    """
+    Calculate adaptive step size for geohash sampling based on polygon size.
+    
+    Geohash precision 6 covers ~1.2km x 0.6km cells. We need step size small enough
+    to ensure we sample multiple points within each geohash cell for reliable coverage.
+    
+    Returns:
+        Step size in degrees
+    """
+    max_range = max(lat_range, lon_range)
+    min_range = min(lat_range, lon_range)
+    
+    # For very small polygons, use very fine sampling to ensure geohash coverage
+    # Geohash precision 6 = ~0.01° latitude, ~0.02° longitude
+    if max_range < 0.001:
+        return 0.001  # ~111m - very fine for tiny islands
+    elif max_range < 0.01:
+        return 0.002  # ~222m - fine sampling for small islands
+    elif max_range < 0.05:
+        return 0.005  # ~555m - good for small countries
+    elif max_range < 0.1:
+        return 0.008  # ~888m - ensure multiple samples per geohash
+    elif max_range < 0.5:
+        return 0.015  # ~1.6km - medium countries
+    elif max_range < 2.0:
+        return 0.025  # ~2.7km - large countries
+    else:
+        return 0.05  # ~5.5km - very large countries
+
+
+def calculate_safe_iteration_limits(
+    min_lat: float,
+    max_lat: float,
+    min_lon: float,
+    max_lon: float,
+    step: float
+) -> Tuple[int, int, int, float]:
+    """
+    Calculate safe iteration limits to prevent infinite loops.
+    
+    These limits are only used as a safety net for truly infinite loops,
+    not to reduce coverage. Returns very generous limits.
+    
+    Returns:
+        Tuple of (max_lat_iterations, max_lon_iterations, max_total_iterations, adjusted_step)
+    """
+    lat_range = max_lat - min_lat
+    lon_range = max_lon - min_lon
+    
+    max_lat_iter = int(lat_range / step) + 10 if step > 0 else 10000  # +10 buffer
+    max_lon_iter = int(lon_range / step) + 10 if step > 0 else 10000  # +10 buffer
+    max_total = max_lat_iter * max_lon_iter
+    
+    # Use original step (don't adjust - preserve full coverage)
+    adjusted_step = step
+    
+    # Only apply a truly massive safety cap (10 million iterations) to prevent infinite loops
+    # This should never be hit in normal operation
+    if max_total > 10000000:
+        max_total = 10000000
+    
+    return max_lat_iter, max_lon_iter, max_total, adjusted_step
+
+
+def get_polygon_centroid(polygon: List[Tuple[float, float]]) -> Tuple[float, float]:
+    """Calculate polygon centroid."""
+    if not polygon:
+        return 0.0, 0.0
+    
+    lats = [p[0] for p in polygon]
+    lons = [p[1] for p in polygon]
+    return sum(lats) / len(lats), sum(lons) / len(lons)
+
+
+def convert_geojson_coords_to_latlon(coords_list: List) -> List[Tuple[float, float]]:
+    """
+    Convert GeoJSON coordinates [lon, lat] to internal format [(lat, lon), ...].
+    
+    Args:
+        coords_list: GeoJSON coordinate list (each element is [lon, lat])
+    
+    Returns:
+        List of (lat, lon) tuples
+    """
+    return [(p[1], p[0]) for p in coords_list]

geo_intel_offline/resolver.py

@@ -0,0 +1,306 @@
+"""
+Resolver orchestration - coordinates the resolution pipeline.
+
+Resolution Pipeline:
+1. Encode lat/lon to geohash
+2. Query geohash index for candidate countries
+3. For each candidate:
+   a. Load polygon
+   b. Test point-in-polygon
+   c. If match, calculate confidence
+4. Return best match or handle ambiguity
+
+Edge Cases Handled:
+- Points in oceans (no country match)
+- Border points (multiple candidates)
+- Geohash boundary cases (check neighbors)
+- Countries with holes (islands, lakes)
+"""
+
+from typing import List, Tuple, Optional, Dict
+from .geohash import encode, get_neighbors
+from .pip import point_in_polygon_with_holes
+from .confidence import calculate_confidence
+from .data_loader import get_loader
+from .modular_data_loader import ModularDataLoader
+
+
+class ResolutionResult:
+    """Result of a geo-intelligence resolution."""
+    
+    def __init__(
+        self,
+        country_id: Optional[int] = None,
+        country_name: Optional[str] = None,
+        iso2: Optional[str] = None,
+        iso3: Optional[str] = None,
+        continent: Optional[str] = None,
+        timezone: Optional[str] = None,
+        confidence: float = 0.0
+    ):
+        self.country_id = country_id
+        self.country_name = country_name
+        self.iso2 = iso2
+        self.iso3 = iso3
+        self.continent = continent
+        self.timezone = timezone
+        self.confidence = confidence
+    
+    def to_dict(self) -> Dict:
+        """Convert to dictionary."""
+        return {
+            "country": self.country_name,
+            "iso2": self.iso2,
+            "iso3": self.iso3,
+            "continent": self.continent,
+            "timezone": self.timezone,
+            "confidence": self.confidence
+        }
+    
+    def is_valid(self) -> bool:
+        """Check if result is valid (has country)."""
+        return self.country_id is not None
+
+
+def resolve(
+    lat: float,
+    lon: float,
+    data_dir: Optional[str] = None,
+    countries: Optional[List[str]] = None,
+    continents: Optional[List[str]] = None,
+    exclude_countries: Optional[List[str]] = None,
+    loader: Optional[ModularDataLoader] = None
+) -> ResolutionResult:
+    """
+    Resolve latitude/longitude to geo-intelligence.
+    
+    Main resolution function that orchestrates the entire pipeline.
+    
+    Args:
+        lat: Latitude (-90 to 90)
+        lon: Longitude (-180 to 180)
+        data_dir: Optional custom data directory
+        countries: Optional list of ISO2 codes to load (modular format)
+        continents: Optional list of continent names to load (modular format)
+        exclude_countries: Optional list of ISO2 codes to exclude (modular format)
+        loader: Optional pre-configured loader instance
+    
+    Returns:
+        ResolutionResult with country information and confidence
+    """
+    if loader is None:
+        # Use modular loader if filters specified, otherwise use default
+        if countries or continents or exclude_countries:
+            loader = ModularDataLoader(
+                data_dir=data_dir,
+                countries=countries,
+                continents=continents,
+                exclude_countries=exclude_countries
+            )
+        else:
+            loader = get_loader(data_dir)
+    point = (lat, lon)
+    
+    # Step 1: Encode to geohash
+    geohash = encode(lat, lon)
+    
+    # Step 2: Get candidate countries
+    candidates = loader.get_candidate_countries(geohash)
+    
+    # Step 3: If no candidates from primary geohash, try neighbors
+    # This handles edge cases where point is on geohash boundaries
+    if not candidates:
+        neighbors = get_neighbors(geohash)
+        for neighbor_hash in neighbors:
+            neighbor_candidates = loader.get_candidate_countries(neighbor_hash)
+            candidates.extend(neighbor_candidates)
+        candidates = list(set(candidates))  # Deduplicate
+    
+    # Step 3b: If still no candidates, try extended neighbors (9x9 grid around point)
+    # This improves accuracy for small countries/islands that may have sparse geohash coverage
+    if not candidates:
+        # Get all neighbors of neighbors (extended search)
+        extended_neighbors = set()
+        for neighbor_hash in neighbors:
+            extended_neighbors.add(neighbor_hash)
+            for extended_neighbor in get_neighbors(neighbor_hash):
+                extended_neighbors.add(extended_neighbor)
+        
+        for extended_hash in extended_neighbors:
+            if extended_hash != geohash:  # Skip primary (already checked)
+                extended_candidates = loader.get_candidate_countries(extended_hash)
+                candidates.extend(extended_candidates)
+        candidates = list(set(candidates))  # Deduplicate
+    
+    # Step 3c: Final fallback - if still no candidates, try checking all loaded countries
+    # This catches edge cases where geohash indexing missed coverage for small countries
+    if not candidates:
+        # Try to get all country IDs from the loader
+        try:
+            # For monolithic loader, we can iterate through metadata
+            if hasattr(loader, 'metadata') and loader.metadata:
+                candidates = list(loader.metadata.keys())
+            # For modular loader, check if we can get all loaded countries
+            elif hasattr(loader, '_loaded_countries'):
+                candidates = list(loader._loaded_countries.keys())
+        except:
+            pass  # Fallback failed, continue with empty candidates
+    
+    if not candidates:
+        # No country found (likely ocean or unsupported area)
+        return ResolutionResult()
+    
+    # Step 4: Test point-in-polygon for each candidate
+    matches = []
+    
+    for country_id in candidates:
+        polygon_data = loader.get_polygon(country_id)
+        if not polygon_data:
+            continue
+        
+        # Handle MultiPolygon - check all exteriors
+        is_multi = polygon_data.get('multi', False)
+        exteriors_data = polygon_data.get('exteriors', [])
+        
+        if is_multi and exteriors_data:
+            # MultiPolygon: check all exteriors
+            for exterior in exteriors_data:
+                exterior_tuples = [(p[0], p[1]) for p in exterior]
+                holes = polygon_data.get('holes', [])
+                holes_tuples = [[(p[0], p[1]) for p in hole] for hole in holes] if holes else None
+                
+                # Test point-in-polygon for this exterior
+                if point_in_polygon_with_holes(point, exterior_tuples, holes_tuples):
+                    metadata = loader.get_metadata(country_id)
+                    if metadata:
+                        # Calculate confidence
+                        confidence = calculate_confidence(
+                            point,
+                            exterior_tuples,
+                            holes_tuples,
+                            candidate_count=len(candidates)
+                        )
+                        
+                        matches.append({
+                            'country_id': country_id,
+                            'metadata': metadata,
+                            'confidence': confidence,
+                            'polygon': (exterior_tuples, holes_tuples)
+                        })
+                        break  # Found match, no need to check other exteriors
+        else:
+            # Single polygon
+            exterior = polygon_data.get('exterior', [])
+            holes = polygon_data.get('holes', [])
+            
+            # Convert coordinate lists to tuples
+            exterior_tuples = [(p[0], p[1]) for p in exterior]
+            holes_tuples = [[(p[0], p[1]) for p in hole] for hole in holes] if holes else None
+            
+            # Test point-in-polygon
+            if point_in_polygon_with_holes(point, exterior_tuples, holes_tuples):
+                metadata = loader.get_metadata(country_id)
+                if metadata:
+                    # Calculate confidence
+                    confidence = calculate_confidence(
+                        point,
+                        exterior_tuples,
+                        holes_tuples,
+                        candidate_count=len(candidates)
+                    )
+                    
+                    matches.append({
+                        'country_id': country_id,
+                        'metadata': metadata,
+                        'confidence': confidence,
+                        'polygon': (exterior_tuples, holes_tuples)
+                    })
+    
+    # Step 5: If no matches from geohash candidates, try broader search
+    # This handles cases where geohash index doesn't have complete coverage
+    if not matches:
+        # Fallback: Check all countries (expensive, but ensures accuracy)
+        # This is a last resort when geohash indexing missed the country
+        metadata_dict = loader.metadata
+        polygons_dict = loader.polygons
+        
+        for country_id, meta in metadata_dict.items():
+            # Skip if already checked as candidate
+            if country_id in candidates:
+                continue
+            
+            polygon_data = polygons_dict.get(country_id)
+            if not polygon_data:
+                continue
+            
+            # Handle MultiPolygon
+            is_multi = polygon_data.get('multi', False)
+            exteriors_data = polygon_data.get('exteriors', [])
+            
+            if is_multi and exteriors_data:
+                for exterior in exteriors_data:
+                    exterior_tuples = [(p[0], p[1]) for p in exterior]
+                    holes = polygon_data.get('holes', [])
+                    holes_tuples = [[(p[0], p[1]) for p in hole] for hole in holes] if holes else None
+                    
+                    if point_in_polygon_with_holes(point, exterior_tuples, holes_tuples):
+                        confidence = calculate_confidence(
+                            point,
+                            exterior_tuples,
+                            holes_tuples,
+                            candidate_count=1  # Single match in fallback
+                        )
+                        
+                        matches.append({
+                            'country_id': country_id,
+                            'metadata': meta,
+                            'confidence': confidence * 0.95,  # Slightly lower confidence for fallback match
+                            'polygon': (exterior_tuples, holes_tuples)
+                        })
+                        break
+            else:
+                exterior = polygon_data.get('exterior', [])
+                holes = polygon_data.get('holes', [])
+                
+                if not exterior:
+                    continue
+                
+                exterior_tuples = [(p[0], p[1]) for p in exterior]
+                holes_tuples = [[(p[0], p[1]) for p in hole] for hole in holes] if holes else None
+                
+                if point_in_polygon_with_holes(point, exterior_tuples, holes_tuples):
+                    confidence = calculate_confidence(
+                        point,
+                        exterior_tuples,
+                        holes_tuples,
+                        candidate_count=1
+                    )
+                    
+                    matches.append({
+                        'country_id': country_id,
+                        'metadata': meta,
+                        'confidence': confidence * 0.95,
+                        'polygon': (exterior_tuples, holes_tuples)
+                    })
+    
+    # Step 6: Return best match (highest confidence)
+    if not matches:
+        # No valid PIP matches found - return None
+        return ResolutionResult()
+    
+    # Sort by confidence (descending)
+    matches.sort(key=lambda x: x['confidence'], reverse=True)
+    best_match = matches[0]
+    
+    metadata = best_match['metadata']
+    return ResolutionResult(
+        country_id=best_match['country_id'],
+        country_name=metadata['name'],
+        iso2=metadata.get('iso2'),
+        iso3=metadata.get('iso3'),
+        continent=metadata.get('continent'),
+        timezone=metadata.get('timezone'),
+        confidence=best_match['confidence']
+    )
+
+

geo_intel_offline-1.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Geo Intelligence Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.