cesiumjs-anywidget 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

cesiumjs_anywidget/__init__.py

@@ -1,6 +1,27 @@
 """CesiumJS Anywidget - A Jupyter widget for CesiumJS 3D globe visualization."""
 
 from .widget import CesiumWidget
+from .geoid import (
+    get_geoid_undulation,
+    msl_to_wgs84,
+    wgs84_to_msl,
+    clear_geoid_cache,
+    set_geoid_data_url,
+)
+from .logger import get_logger, set_log_level
+from .exif_utils import extract_all_metadata, extract_gps_data, extract_datetime
 
-__version__ = "0.1.0"
-__all__ = ["CesiumWidget"]
+__version__ = "0.6.0"
+__all__ = [
+    "CesiumWidget",
+    "get_geoid_undulation",
+    "msl_to_wgs84",
+    "wgs84_to_msl",
+    "clear_geoid_cache",
+    "set_geoid_data_url",
+    "get_logger",
+    "set_log_level",
+    "extract_all_metadata",
+    "extract_gps_data",
+    "extract_datetime",
+]

cesiumjs_anywidget/exif_utils.py

@@ -0,0 +1,281 @@
+"""EXIF data extraction utilities for photo geolocation."""
+
+import exifread
+from datetime import datetime
+from typing import Optional, Dict, Any, Tuple
+from pathlib import Path
+from .logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _convert_to_degrees(value) -> float:
+    """Convert GPS coordinates to degrees.
+    
+    Parameters
+    ----------
+    value : exifread.utils.Ratio list
+        GPS coordinate in degrees, minutes, seconds format
+        
+    Returns
+    -------
+    float
+        Coordinate in decimal degrees
+    """
+    d = float(value.values[0].num) / float(value.values[0].den)
+    m = float(value.values[1].num) / float(value.values[1].den)
+    s = float(value.values[2].num) / float(value.values[2].den)
+
+    # Normalize malformed DMS values from some writers
+    # Some encoders store seconds as total arc-seconds * 60 (e.g., 1425 instead of 23.75)
+    if s >= 60 and m < 60:
+        s = s / 60.0
+
+    if s >= 60:
+        carry = int(s // 60)
+        s = s - (carry * 60)
+        m += carry
+
+    if m >= 60:
+        carry = int(m // 60)
+        m = m - (carry * 60)
+        d += carry
+
+    return d + (m / 60.0) + (s / 3600.0)
+
+
+def extract_gps_data(image_path: str) -> Optional[Dict[str, float]]:
+    """Extract GPS coordinates from image EXIF data.
+    
+    Parameters
+    ----------
+    image_path : str
+        Path to the image file
+        
+    Returns
+    -------
+    dict or None
+        Dictionary containing 'latitude', 'longitude', and optionally 'altitude'
+        Returns None if GPS data is not available
+        
+    Examples
+    --------
+    >>> gps_data = extract_gps_data('photo.jpg')
+    >>> if gps_data:
+    ...     print(f"Location: {gps_data['latitude']}, {gps_data['longitude']}")
+    """
+    try:
+        with open(image_path, 'rb') as f:
+            tags = exifread.process_file(f, details=False)
+        
+        # Check if GPS data exists
+        if 'GPS GPSLatitude' not in tags or 'GPS GPSLongitude' not in tags:
+            logger.warning(f"No GPS data found in {image_path}")
+            return None
+        
+        # Extract latitude
+        lat = _convert_to_degrees(tags['GPS GPSLatitude'])
+        if tags.get('GPS GPSLatitudeRef', 'N').values[0] == 'S':
+            lat = -lat
+        
+        # Extract longitude
+        lon = _convert_to_degrees(tags['GPS GPSLongitude'])
+        if tags.get('GPS GPSLongitudeRef', 'E').values[0] == 'W':
+            lon = -lon
+        
+        result = {
+            'latitude': lat,
+            'longitude': lon,
+        }
+        
+        # Extract altitude if available
+        if 'GPS GPSAltitude' in tags:
+            alt_tag = tags['GPS GPSAltitude']
+            altitude = float(alt_tag.values[0].num) / float(alt_tag.values[0].den)
+            
+            # Check altitude reference (0 = above sea level, 1 = below sea level)
+            if 'GPS GPSAltitudeRef' in tags:
+                alt_ref = tags['GPS GPSAltitudeRef'].values[0]
+                if alt_ref == 1:
+                    altitude = -altitude
+            
+            result['altitude'] = altitude
+        
+        logger.info(f"Extracted GPS data from {image_path}: {result}")
+        return result
+        
+    except Exception as e:
+        logger.error(f"Error extracting GPS data from {image_path}: {e}")
+        return None
+
+
+def extract_datetime(image_path: str) -> Optional[datetime]:
+    """Extract capture datetime from image EXIF data.
+    
+    Parameters
+    ----------
+    image_path : str
+        Path to the image file
+        
+    Returns
+    -------
+    datetime or None
+        Image capture datetime, or None if not available
+        
+    Examples
+    --------
+    >>> dt = extract_datetime('photo.jpg')
+    >>> if dt:
+    ...     print(f"Captured on: {dt.strftime('%Y-%m-%d %H:%M:%S')}")
+    """
+    try:
+        with open(image_path, 'rb') as f:
+            tags = exifread.process_file(f, details=False)
+        
+        # Try different datetime tags
+        for tag_name in ['EXIF DateTimeOriginal', 'EXIF DateTime', 'Image DateTime']:
+            if tag_name in tags:
+                dt_str = str(tags[tag_name])
+                # Parse datetime (format: "YYYY:MM:DD HH:MM:SS")
+                dt = datetime.strptime(dt_str, '%Y:%m:%d %H:%M:%S')
+                logger.info(f"Extracted datetime from {image_path}: {dt}")
+                return dt
+        
+        logger.warning(f"No datetime found in {image_path}")
+        return None
+        
+    except Exception as e:
+        logger.error(f"Error extracting datetime from {image_path}: {e}")
+        return None
+
+
+def extract_camera_info(image_path: str) -> Dict[str, Any]:
+    """Extract camera information from image EXIF data.
+    
+    Parameters
+    ----------
+    image_path : str
+        Path to the image file
+        
+    Returns
+    -------
+    dict
+        Dictionary containing camera make, model, focal length, sensor size, etc.
+        
+    Examples
+    --------
+    >>> info = extract_camera_info('photo.jpg')
+    >>> print(f"Camera: {info.get('make')} {info.get('model')}")
+    """
+    result = {}
+    
+    try:
+        with open(image_path, 'rb') as f:
+            tags = exifread.process_file(f, details=False)
+        
+        # Camera make and model
+        if 'Image Make' in tags:
+            result['make'] = str(tags['Image Make'])
+        if 'Image Model' in tags:
+            result['model'] = str(tags['Image Model'])
+        
+        # Focal length
+        if 'EXIF FocalLength' in tags:
+            focal_tag = tags['EXIF FocalLength']
+            focal_length = float(focal_tag.values[0].num) / float(focal_tag.values[0].den)
+            result['focal_length_mm'] = focal_length
+        
+        # Focal length in 35mm equivalent
+        if 'EXIF FocalLengthIn35mmFilm' in tags:
+            result['focal_length_35mm'] = int(tags['EXIF FocalLengthIn35mmFilm'].values[0])
+        
+        # Image dimensions
+        if 'EXIF ExifImageWidth' in tags:
+            result['image_width'] = int(tags['EXIF ExifImageWidth'].values[0])
+        if 'EXIF ExifImageLength' in tags:
+            result['image_height'] = int(tags['EXIF ExifImageLength'].values[0])
+        
+        # Orientation
+        if 'Image Orientation' in tags:
+            result['orientation'] = str(tags['Image Orientation'])
+        
+        logger.info(f"Extracted camera info from {image_path}: {result}")
+        return result
+        
+    except Exception as e:
+        logger.error(f"Error extracting camera info from {image_path}: {e}")
+        return result
+
+
+def get_image_dimensions(image_path: str) -> Optional[Tuple[int, int]]:
+    """Get image dimensions (width, height) from file.
+    
+    Parameters
+    ----------
+    image_path : str
+        Path to the image file
+        
+    Returns
+    -------
+    tuple or None
+        (width, height) in pixels, or None if unable to read
+    """
+    try:
+        from PIL import Image
+        with Image.open(image_path) as img:
+            return img.size
+    except Exception as e:
+        logger.error(f"Error reading image dimensions from {image_path}: {e}")
+        return None
+
+
+def extract_all_metadata(image_path: str) -> Dict[str, Any]:
+    """Extract all relevant metadata from an image.
+    
+    Combines GPS, datetime, camera info, and image dimensions into one dictionary.
+    
+    Parameters
+    ----------
+    image_path : str
+        Path to the image file
+        
+    Returns
+    -------
+    dict
+        Dictionary containing all extracted metadata
+        
+    Examples
+    --------
+    >>> metadata = extract_all_metadata('photo.jpg')
+    >>> print(metadata)
+    {'latitude': 48.8566, 'longitude': 2.3522, 'altitude': 100,
+     'datetime': datetime(2024, 1, 15, 14, 30, 0),
+     'make': 'Canon', 'model': 'EOS R5', ...}
+    """
+    metadata = {
+        'file_path': str(Path(image_path).absolute()),
+        'file_name': Path(image_path).name,
+    }
+    
+    # GPS data
+    gps_data = extract_gps_data(image_path)
+    if gps_data:
+        metadata.update(gps_data)
+    
+    # Datetime
+    dt = extract_datetime(image_path)
+    if dt:
+        metadata['datetime'] = dt
+        metadata['datetime_str'] = dt.isoformat()
+    
+    # Camera info
+    camera_info = extract_camera_info(image_path)
+    metadata.update(camera_info)
+    
+    # Image dimensions
+    dims = get_image_dimensions(image_path)
+    if dims:
+        metadata['width'] = dims[0]
+        metadata['height'] = dims[1]
+    
+    return metadata

cesiumjs_anywidget/geoid.py

@@ -0,0 +1,299 @@
+"""Geoid conversion utilities for MSL to WGS84 altitude conversion.
+
+This module provides functions to convert between Mean Sea Level (MSL) altitudes
+and WGS84 ellipsoid heights using the EGM96 geoid model.
+
+The EGM96 15-minute grid data is automatically downloaded from the internet on
+first use and cached locally. You can customize the data source URL if needed.
+"""
+
+import os
+import tarfile
+import urllib.request
+import zipfile
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+from .logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# Default URL for EGM96 15-minute grid data
+# This is the official NGA download link
+DEFAULT_EGM96_URL = "https://earth-info.nga.mil/php/download.php?file=egm-96interpolation"
+
+# User-configurable URL (can be changed before first use)
+_EGM96_DATA_URL: Optional[str] = None
+
+# Cached geoid model
+_geoid_model = None
+
+# Cache directory for downloaded geoid files
+_CACHE_DIR = Path.home() / ".cache" / "cesiumjs_anywidget" / "geoid"
+
+
+def set_geoid_data_url(url: str) -> None:
+    """Set a custom URL for downloading EGM96 geoid data.
+    
+    This must be called before the first use of geoid functions.
+    
+    Parameters
+    ----------
+    url : str
+        URL to download EGM96 grid data (tar.bz2 or direct grid file)
+        
+    Examples
+    --------
+    >>> from cesiumjs_anywidget.geoid import set_geoid_data_url
+    >>> set_geoid_data_url("https://example.com/egm96-15.tar.bz2")
+    """
+    global _EGM96_DATA_URL, _geoid_model
+    _EGM96_DATA_URL = url
+    # Clear cached model to force reload with new URL
+    _geoid_model = None
+    get_geoid_undulation.cache_clear()
+
+
+def _download_egm96_grid(url: str, cache_dir: Path) -> Path:
+    """Download and extract the EGM96 grid file from an archive (zip or tar.bz2).
+    
+    Parameters
+    ----------
+    url : str
+        URL to download the archive from
+    cache_dir : Path
+        Directory to store the extracted grid file
+        
+    Returns
+    -------
+    Path
+        Path to the extracted .GRD file
+        
+    Raises
+    ------
+    FileNotFoundError
+        If no .GRD file found in archive
+    Exception
+        If download or extraction fails
+    """
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Expected output file (WW15MGH.GRD is the standard EGM96 15-minute grid)
+    grd_file = cache_dir / "WW15MGH.GRD"
+    
+    if grd_file.exists():
+        return grd_file
+    
+    # Download the archive
+    archive_path = cache_dir / "egm96-data.archive"
+    
+    if not archive_path.exists():
+        logger.info("Downloading EGM96 grid data from %s...", url)
+        urllib.request.urlretrieve(url, archive_path)
+        logger.info("Download complete: %s", archive_path)
+    
+    # Detect archive type and extract
+    logger.info("Extracting %s...", archive_path)
+    
+    try:
+        # Try ZIP first
+        with zipfile.ZipFile(archive_path, 'r') as zip_ref:
+            # Find the .GRD file in the archive
+            grd_members = [name for name in zip_ref.namelist() 
+                          if name.endswith('.GRD') or name.endswith('.grd')]
+            
+            if not grd_members:
+                raise FileNotFoundError(f"No .GRD file found in ZIP archive {archive_path}")
+            
+            # Extract the first .GRD file found
+            member_name = grd_members[0]
+            zip_ref.extract(member_name, cache_dir)
+            
+            # Rename to standard name if needed
+            extracted_path = cache_dir / member_name
+            if extracted_path.name != grd_file.name:
+                extracted_path.rename(grd_file)
+                
+    except zipfile.BadZipFile:
+        # Try tar.bz2
+        with tarfile.open(archive_path, "r:bz2") as tar:
+            # Find the .GRD file in the archive
+            grd_members = [m for m in tar.getmembers() 
+                          if m.name.endswith('.GRD') or m.name.endswith('.grd')]
+            
+            if not grd_members:
+                raise FileNotFoundError(f"No .GRD file found in tar.bz2 archive {archive_path}")
+            
+            # Extract the first .GRD file found
+            member = grd_members[0]
+            tar.extract(member, cache_dir)
+            
+            # Rename to standard name if needed
+            extracted_path = cache_dir / member.name
+            if extracted_path.name != grd_file.name:
+                extracted_path.rename(grd_file)
+    
+    logger.info("Extraction complete: %s", grd_file)
+    
+    # Clean up archive if extraction successful
+    if archive_path.exists() and grd_file.exists():
+        archive_path.unlink()
+    
+    return grd_file
+
+
+def _get_geoid_model():
+    """Get or create the cached EGM96 geoid model.
+    
+    The model is loaded from GeoidEGM96 using a .GRD grid file.
+    The grid file is automatically downloaded on first use and cached locally.
+    
+    Returns
+    -------
+    GeoidEGM96
+        The cached geoid model instance
+    """
+    global _geoid_model
+    
+    if _geoid_model is None:
+        from pygeodesy.geoids import GeoidEGM96
+        from pygeodesy.datums import Datums
+        
+        # Use custom URL if set, otherwise use default
+        url = _EGM96_DATA_URL if _EGM96_DATA_URL else DEFAULT_EGM96_URL
+        
+        # Download and extract the grid file if needed
+        grd_file = _download_egm96_grid(url, _CACHE_DIR)
+        
+        # Create the GeoidEGM96 model with the grid file path
+        _geoid_model = GeoidEGM96(str(grd_file), datum=Datums.WGS84)
+    
+    return _geoid_model
+
+
+@lru_cache(maxsize=1000)
+def get_geoid_undulation(latitude: float, longitude: float) -> float:
+    """Calculate the geoid undulation at a given location using EGM96.
+    
+    The geoid undulation (also called geoid height or geoid separation) is the
+    height of the geoid above the WGS84 reference ellipsoid. This value is
+    needed to convert between GPS/MSL altitudes and WGS84 ellipsoid heights.
+    
+    On first use, the EGM96 15-minute grid data will be automatically downloaded
+    and cached locally. Subsequent calls will use the cached data.
+    
+    Parameters
+    ----------
+    latitude : float
+        Latitude in degrees (-90 to 90)
+    longitude : float
+        Longitude in degrees (-180 to 180 or 0 to 360)
+        
+    Returns
+    -------
+    float
+        Geoid undulation in meters. Positive values indicate the geoid is
+        above the WGS84 ellipsoid at this location.
+        
+    Examples
+    --------
+    >>> # France (46°N, 4°E) - geoid is about 47m above ellipsoid
+    >>> undulation = get_geoid_undulation(46.0, 4.0)
+    >>> 45 < undulation < 50
+    True
+    
+    Notes
+    -----
+    The EGM96 model provides approximately ±0.5 to ±1 meter accuracy globally.
+    The grid data is downloaded automatically from GeographicLib on first use.
+    """
+    geoid = _get_geoid_model()
+    
+    # GeoidEGM96.height() accepts lat, lon directly
+    return geoid.height(latitude, longitude)
+
+
+
+def msl_to_wgs84(altitude_msl: float, latitude: float, longitude: float) -> float:
+    """Convert Mean Sea Level (MSL) altitude to WGS84 ellipsoid height.
+    
+    GPS receivers typically report altitude above MSL (geoid), but CZML and
+    Cesium use WGS84 ellipsoid heights. This function performs the conversion:
+    
+        WGS84_height = altitude_msl + geoid_undulation
+    
+    Parameters
+    ----------
+    altitude_msl : float
+        Altitude above Mean Sea Level in meters
+    latitude : float
+        Latitude in degrees (-90 to 90)
+    longitude : float
+        Longitude in degrees (-180 to 180 or 0 to 360)
+        
+    Returns
+    -------
+    float
+        Height above WGS84 ellipsoid in meters
+        
+    Examples
+    --------
+    >>> # Sea level in France would be ~47m above WGS84 ellipsoid
+    >>> wgs84_height = msl_to_wgs84(0, 46.0, 4.0)
+    >>> 45 < wgs84_height < 50
+    True
+    
+    >>> # Mountain at 1000m MSL
+    >>> wgs84_height = msl_to_wgs84(1000, 46.0, 4.0)
+    >>> 1045 < wgs84_height < 1050
+    True
+    """
+    geoid_undulation = get_geoid_undulation(latitude, longitude)
+    return altitude_msl + geoid_undulation
+
+
+def wgs84_to_msl(altitude_wgs84: float, latitude: float, longitude: float) -> float:
+    """Convert WGS84 ellipsoid height to Mean Sea Level (MSL) altitude.
+    
+    This is the inverse of msl_to_wgs84. Useful when you have WGS84 heights
+    (e.g., from Cesium) and need to display MSL altitudes to users.
+    
+        altitude_msl = WGS84_height - geoid_undulation
+    
+    Parameters
+    ----------
+    altitude_wgs84 : float
+        Height above WGS84 ellipsoid in meters
+    latitude : float
+        Latitude in degrees (-90 to 90)
+    longitude : float
+        Longitude in degrees (-180 to 180 or 0 to 360)
+        
+    Returns
+    -------
+    float
+        Altitude above Mean Sea Level in meters
+        
+    Examples
+    --------
+    >>> # WGS84 height of ~47m in France is approximately sea level
+    >>> msl_alt = wgs84_to_msl(47, 46.0, 4.0)
+    >>> -3 < msl_alt < 3
+    True
+    """
+    geoid_undulation = get_geoid_undulation(latitude, longitude)
+    return altitude_wgs84 - geoid_undulation
+
+
+def clear_geoid_cache() -> None:
+    """Clear the cached geoid model and undulation values.
+    
+    This function clears both the geoid model cache and the LRU cache
+    used by get_geoid_undulation. Useful for testing or to force reloading
+    the geoid data.
+    """
+    global _geoid_model
+    _geoid_model = None
+    get_geoid_undulation.cache_clear()