voxcity 0.5.14__py3-none-any.whl → 0.5.16__py3-none-any.whl

voxcity/downloader/gee.py

@@ -4,6 +4,19 @@ Module for interacting with Google Earth Engine API and downloading geospatial d
 This module provides functionality to initialize Earth Engine, create regions of interest,
 download various types of satellite imagery and terrain data, and save them as GeoTIFF files.
 It supports multiple data sources including DEMs, land cover maps, and building footprints.
+
+The module offers the following main functionalities:
+1. Earth Engine initialization and region of interest (ROI) management
+2. Digital Elevation Model (DEM) data access from multiple sources
+3. Land cover data retrieval from ESA WorldCover, Dynamic World, and ESRI
+4. Building footprint and height data extraction
+5. GeoTIFF export with customizable parameters
+
+Dependencies:
+    - ee: Google Earth Engine Python API
+    - geemap: Python package for interactive mapping with Earth Engine
+
+Note: Most functions require Earth Engine authentication to be set up beforehand.
 """
 
 # Earth Engine and geospatial imports
@@ -14,17 +27,29 @@ import geemap
 # from ..geo.utils import convert_format_lat_lon
 
 def initialize_earth_engine():
-    """Initialize the Earth Engine API."""
+    """Initialize the Earth Engine API.
+    
+    This function must be called before using any other Earth Engine functionality.
+    It assumes that Earth Engine authentication has been set up properly.
+    
+    Raises:
+        ee.EEException: If authentication fails or Earth Engine is unavailable
+    """
     ee.Initialize()
 
 def get_roi(input_coords):
     """Create an Earth Engine region of interest polygon from coordinates.
     
     Args:
-        input_coords: List of coordinate pairs defining the polygon vertices in (lon, lat) format
+        input_coords: List of coordinate pairs defining the polygon vertices in (lon, lat) format.
+                     The coordinates should form a valid polygon (non-self-intersecting).
         
     Returns:
-        ee.Geometry.Polygon: Earth Engine polygon geometry
+        ee.Geometry.Polygon: Earth Engine polygon geometry representing the ROI
+        
+    Note:
+        The function automatically closes the polygon by connecting the last vertex
+        to the first vertex if they are not the same.
     """
     coords = input_coords.copy()
     coords.append(input_coords[0])
@@ -34,10 +59,14 @@ def get_center_point(roi):
     """Get the centroid coordinates of a region of interest.
     
     Args:
-        roi: Earth Engine geometry
+        roi: Earth Engine geometry object representing the region of interest
         
     Returns:
-        tuple: (longitude, latitude) of centroid
+        tuple: (longitude, latitude) coordinates of the centroid
+        
+    Note:
+        The centroid is calculated using Earth Engine's geometric centroid algorithm,
+        which may not always fall within the geometry for complex shapes.
     """
     center_point = roi.centroid()
     center_coords = center_point.coordinates().getInfo()
@@ -47,11 +76,15 @@ def get_ee_image_collection(collection_name, roi):
     """Get the first image from an Earth Engine ImageCollection filtered by region.
     
     Args:
-        collection_name: Name of the Earth Engine ImageCollection
+        collection_name: Name of the Earth Engine ImageCollection (e.g., 'LANDSAT/LC08/C02/T1_TOA')
         roi: Earth Engine geometry to filter by
         
     Returns:
-        ee.Image: First image from collection clipped to ROI
+        ee.Image: First image from collection clipped to ROI, with any masked pixels unmasked
+        
+    Note:
+        The function sorts images by time (earliest first) and unmasks any masked pixels
+        in the final image. This is useful for ensuring complete coverage of the ROI.
     """
     # Filter collection by bounds and get first image
     collection = ee.ImageCollection(collection_name).filterBounds(roi)
@@ -61,11 +94,15 @@ def get_ee_image(collection_name, roi):
     """Get an Earth Engine Image clipped to a region.
     
     Args:
-        collection_name: Name of the Earth Engine Image
+        collection_name: Name of the Earth Engine Image asset
         roi: Earth Engine geometry to clip to
         
     Returns:
         ee.Image: Image clipped to ROI
+        
+    Note:
+        Unlike get_ee_image_collection(), this function works with single image assets
+        rather than image collections. It's useful for static datasets like DEMs.
     """
     collection = ee.Image(collection_name)
     return collection.clip(roi)
@@ -73,13 +110,22 @@ def get_ee_image(collection_name, roi):
 def save_geotiff(image, filename, resolution=1, scale=None, region=None, crs=None):
     """Save an Earth Engine image as a GeoTIFF file.
     
+    This function provides flexible options for exporting Earth Engine images to GeoTIFF format.
+    It handles different export scenarios based on the provided parameters.
+    
     Args:
         image: Earth Engine image to save
-        filename: Output filename
-        resolution: Output resolution in degrees (default: 1)
-        scale: Output scale in meters
-        region: Region to export
-        crs: Coordinate reference system
+        filename: Output filename for the GeoTIFF
+        resolution: Output resolution in degrees (default: 1), used when scale is not provided
+        scale: Output scale in meters (overrides resolution if provided)
+        region: Region to export (required if scale is provided)
+        crs: Coordinate reference system (e.g., 'EPSG:4326')
+    
+    Note:
+        - If scale and region are provided, uses ee_export_image()
+        - Otherwise, uses ee_to_geotiff() with resolution parameter
+        - The function automatically converts output to Cloud Optimized GeoTIFF (COG)
+          format when using ee_to_geotiff()
     """
     # Handle different export scenarios based on provided parameters
     if scale and region:
@@ -96,13 +142,30 @@ def save_geotiff(image, filename, resolution=1, scale=None, region=None, crs=Non
 def get_dem_image(roi_buffered, source):
     """Get a digital elevation model (DEM) image for a region.
     
+    This function provides access to various global and regional Digital Elevation Model (DEM)
+    datasets through Earth Engine. Each source has different coverage areas and resolutions.
+    
     Args:
-        roi_buffered: Earth Engine geometry with buffer
-        source: DEM source ('NASA', 'COPERNICUS', 'DeltaDTM', 'FABDEM', 'England 1m DTM',
-               'DEM France 5m', 'DEM France 1m', 'AUSTRALIA 5M DEM', 'USGS 3DEP 1m')
+        roi_buffered: Earth Engine geometry with buffer - should be larger than the actual
+                     area of interest to ensure smooth interpolation at edges
+        source: DEM source, one of:
+               - 'NASA': SRTM 30m global DEM
+               - 'COPERNICUS': Copernicus 30m global DEM
+               - 'DeltaDTM': Deltares global DTM
+               - 'FABDEM': Forest And Buildings removed MERIT DEM
+               - 'England 1m DTM': UK Environment Agency 1m terrain model
+               - 'DEM France 5m': IGN RGE ALTI 5m France coverage
+               - 'DEM France 1m': IGN RGE ALTI 1m France coverage
+               - 'AUSTRALIA 5M DEM': Geoscience Australia 5m DEM
+               - 'USGS 3DEP 1m': USGS 3D Elevation Program 1m DEM
                
     Returns:
         ee.Image: DEM image clipped to region
+        
+    Note:
+        Some sources may have limited coverage or require special access permissions.
+        The function will raise an error if the selected source is not available for
+        the specified region.
     """
     # Handle different DEM sources
     if source == 'NASA':
@@ -154,9 +217,30 @@ def get_dem_image(roi_buffered, source):
 def save_geotiff_esa_land_cover(roi, geotiff_path):
     """Save ESA WorldCover land cover data as a colored GeoTIFF.
     
+    Downloads and exports the ESA WorldCover 10m resolution global land cover map.
+    The output is a colored GeoTIFF where each land cover class is represented by
+    a unique color as defined in the color_map.
+    
     Args:
         roi: Earth Engine geometry defining region of interest
         geotiff_path: Output path for GeoTIFF file
+        
+    Land cover classes and their corresponding colors:
+        - Trees (10): Dark green
+        - Shrubland (20): Orange
+        - Grassland (30): Yellow
+        - Cropland (40): Purple
+        - Built-up (50): Red
+        - Barren/sparse vegetation (60): Gray
+        - Snow and ice (70): White
+        - Open water (80): Blue
+        - Herbaceous wetland (90): Teal
+        - Mangroves (95): Light green
+        - Moss and lichen (100): Beige
+        
+    Note:
+        The output GeoTIFF is exported at 10m resolution, which is the native
+        resolution of the ESA WorldCover dataset.
     """
     # Initialize Earth Engine
     ee.Initialize()
@@ -197,10 +281,30 @@ def save_geotiff_esa_land_cover(roi, geotiff_path):
 def save_geotiff_dynamic_world_v1(roi, geotiff_path, date=None):
     """Save Dynamic World land cover data as a colored GeoTIFF.
     
+    Downloads and exports Google's Dynamic World near real-time land cover classification.
+    The data is available globally at 10m resolution from 2015 onwards, updated every 2-5 days.
+    
     Args:
         roi: Earth Engine geometry defining region of interest
         geotiff_path: Output path for GeoTIFF file
-        date: Optional date string to get data for specific time
+        date: Optional date string (YYYY-MM-DD) to get data for specific time.
+              If None, uses the most recent available image.
+    
+    Land cover classes and their colors:
+        - water: Blue (#419bdf)
+        - trees: Dark green (#397d49)
+        - grass: Light green (#88b053)
+        - flooded_vegetation: Purple (#7a87c6)
+        - crops: Orange (#e49635)
+        - shrub_and_scrub: Tan (#dfc35a)
+        - built: Red (#c4281b)
+        - bare: Gray (#a59b8f)
+        - snow_and_ice: Light purple (#b39fe1)
+        
+    Note:
+        If a specific date is provided but no image is available, the function
+        will use the closest available date and print a message indicating the
+        actual date used.
     """
     # Initialize Earth Engine
     ee.Initialize()
@@ -287,10 +391,29 @@ def save_geotiff_dynamic_world_v1(roi, geotiff_path, date=None):
 def save_geotiff_esri_landcover(roi, geotiff_path, year=None):
     """Save ESRI Land Cover data as a colored GeoTIFF.
     
+    Downloads and exports ESRI's 10m resolution global land cover classification.
+    This dataset is updated annually and provides consistent global coverage.
+    
     Args:
         roi: Earth Engine geometry defining region of interest
         geotiff_path: Output path for GeoTIFF file
-        year: Optional year to get data for specific time
+        year: Optional year (YYYY) to get data for specific time.
+              If None, uses the most recent available year.
+    
+    Land cover classes and colors:
+        - Water (#1A5BAB): Water bodies
+        - Trees (#358221): Tree cover
+        - Flooded Vegetation (#87D19E): Vegetation in water-logged areas
+        - Crops (#FFDB5C): Agricultural areas
+        - Built Area (#ED022A): Urban and built-up areas
+        - Bare Ground (#EDE9E4): Exposed soil and rock
+        - Snow/Ice (#F2FAFF): Permanent snow and ice
+        - Clouds (#C8C8C8): Cloud cover
+        - Rangeland (#C6AD8D): Natural vegetation
+        
+    Note:
+        The function will print the year of the data actually used, which may
+        differ from the requested year if data is not available for that time.
     """
     # Initialize Earth Engine
     ee.Initialize()
@@ -371,9 +494,18 @@ def save_geotiff_esri_landcover(roi, geotiff_path, year=None):
 def save_geotiff_open_buildings_temporal(aoi, geotiff_path):
     """Save Open Buildings temporal data as a GeoTIFF.
     
+    Downloads and exports building height data from Google's Open Buildings dataset.
+    This dataset provides building footprints and heights derived from satellite imagery.
+    
     Args:
         aoi: Earth Engine geometry defining area of interest
         geotiff_path: Output path for GeoTIFF file
+        
+    Note:
+        - The output GeoTIFF contains building heights in meters
+        - The dataset is updated periodically and may not cover all regions
+        - Resolution is fixed at 4 meters per pixel
+        - Areas without buildings will have no-data values
     """
     # Initialize Earth Engine
     ee.Initialize()
@@ -402,14 +534,24 @@ def save_geotiff_open_buildings_temporal(aoi, geotiff_path):
 def save_geotiff_dsm_minus_dtm(roi, geotiff_path, meshsize, source):
     """Get the height difference between DSM and DTM from terrain data.
     
+    Calculates the difference between Digital Surface Model (DSM) and Digital Terrain
+    Model (DTM) to estimate heights of buildings, vegetation, and other above-ground
+    features.
+    
     Args:
         roi: Earth Engine geometry defining area of interest
         geotiff_path: Output path for GeoTIFF file
-        meshsize: Size of each grid cell in meters
-        source: Source of terrain data ('England' or 'Netherlands')
+        meshsize: Size of each grid cell in meters - determines output resolution
+        source: Source of terrain data, one of:
+               - 'England 1m DSM - DTM': UK Environment Agency 1m resolution
+               - 'Netherlands 0.5m DSM - DTM': AHN4 0.5m resolution
         
-    Returns:
-        ee.Image: Image representing DSM minus DTM (building/vegetation heights)
+    Note:
+        - A 100m buffer is automatically added around the ROI to ensure smooth
+          interpolation at edges
+        - The output represents height above ground level in meters
+        - Negative values may indicate data artifacts or actual below-ground features
+        - The function requires both DSM and DTM data to be available for the region
     """
     # Initialize Earth Engine
     ee.Initialize()

voxcity/downloader/mbfp.py

@@ -4,6 +4,16 @@ Module for downloading and processing Microsoft Building Footprints data.
 This module provides functionality to download building footprint data from Microsoft's
 open dataset, which contains building polygons extracted from satellite imagery using
 AI. It handles downloading quadkey-based data files and converting them to GeoJSON format.
+
+The data is organized using quadkeys, which are hierarchical spatial indexing strings
+that identify tiles on the map at different zoom levels. Each quadkey corresponds to
+a specific geographic area and zoom level.
+
+Key Features:
+- Downloads building footprint data from Microsoft's global buildings dataset
+- Handles quadkey-based spatial queries
+- Converts compressed data files to GeoJSON format
+- Supports rectangular region queries using vertex coordinates
 """
 
 import pandas as pd
@@ -15,11 +25,22 @@ from ..geoprocessor.polygon import load_gdf_from_multiple_gz, swap_coordinates
 def get_geojson_links(output_dir):
     """Download and load the dataset links CSV file containing building footprint URLs.
     
+    This function downloads a master CSV file from Microsoft's server that contains
+    links to all available building footprint datasets. The CSV includes metadata
+    such as location names, quadkeys, URLs, and file sizes for each dataset tile.
+    
     Args:
-        output_dir: Directory to save the downloaded CSV file
+        output_dir (str): Directory path where the CSV file will be saved
         
     Returns:
-        pandas.DataFrame: DataFrame containing dataset links and quadkey information
+        pandas.DataFrame: DataFrame containing dataset links with columns:
+            - Location: String identifier for the geographic region
+            - QuadKey: String representing the tile's quadkey
+            - Url: Direct download link for the GeoJSON data
+            - Size: File size information
+    
+    Note:
+        The CSV file is cached locally in the output directory for future use.
     """
     # URL for the master CSV file containing links to all building footprint data
     url = "https://minedbuildings.z5.web.core.windows.net/global-buildings/dataset-links.csv"
@@ -43,13 +64,23 @@ def get_geojson_links(output_dir):
 def find_row_for_location(df, lon, lat):
     """Find the dataset row containing building data for a given lon/lat coordinate.
     
+    This function searches through the dataset links DataFrame to find the appropriate
+    tile containing the specified geographic coordinates. It converts the input
+    coordinates to tile coordinates at the same zoom level as each quadkey and
+    checks for a match.
+    
     Args:
-        df: DataFrame containing dataset links
-        lon: Longitude coordinate to search for
-        lat: Latitude coordinate to search for
+        df (pandas.DataFrame): DataFrame containing dataset links from get_geojson_links()
+        lon (float): Longitude coordinate to search for (-180 to 180)
+        lat (float): Latitude coordinate to search for (-90 to 90)
         
     Returns:
-        pandas.Series: Matching row from DataFrame, or None if no match found
+        pandas.Series: Matching row from DataFrame containing the quadkey and download URL,
+                      or None if no matching tile is found
+    
+    Note:
+        The function handles invalid quadkeys gracefully by skipping them and
+        continues searching through all available tiles.
     """
     for index, row in df.iterrows():
         quadkey = str(row['QuadKey'])
@@ -71,12 +102,27 @@ def find_row_for_location(df, lon, lat):
 def get_mbfp_gdf(output_dir, rectangle_vertices):
     """Download and process building footprint data for a rectangular region.
     
+    This function takes a list of coordinates defining a rectangular region and:
+    1. Downloads the necessary building footprint data files covering the region
+    2. Loads and combines the GeoJSON data from all relevant files
+    3. Processes the data to ensure consistent coordinate ordering
+    4. Assigns unique sequential IDs to each building
+    
     Args:
-        output_dir: Directory to save downloaded files
-        rectangle_vertices: List of (lon, lat) tuples defining the rectangle corners
+        output_dir (str): Directory path where downloaded files will be saved
+        rectangle_vertices (list): List of (lon, lat) tuples defining the rectangle corners.
+                                 The coordinates should define a bounding box of the
+                                 area of interest.
         
     Returns:
-        dict: GeoJSON data containing building footprints
+        geopandas.GeoDataFrame: GeoDataFrame containing building footprints with columns:
+            - geometry: Building polygon geometries
+            - id: Sequential unique identifier for each building
+            
+    Note:
+        - Files are downloaded only if not already present in the output directory
+        - Coordinates in the input vertices should be in (longitude, latitude) order
+        - The function handles cases where some vertices might not have available data
     """
     print("Downloading geojson files")
     df_links = get_geojson_links(output_dir)

voxcity/downloader/oemj.py

@@ -5,6 +5,17 @@ This module provides functionality to download, compose, crop and save satellite
 from OpenEarthMap Japan as georeferenced GeoTIFF files. It handles coordinate conversions between
 latitude/longitude and tile coordinates, downloads tiles within a polygon region, and saves the
 final image with proper geospatial metadata.
+
+Key Features:
+    - Convert between geographic (lat/lon) and tile coordinates
+    - Download satellite imagery tiles for a specified region
+    - Compose multiple tiles into a single image
+    - Crop images to a specified polygon boundary
+    - Save results as georeferenced GeoTIFF files
+
+Example Usage:
+    polygon = [(139.7, 35.6), (139.8, 35.6), (139.8, 35.7), (139.7, 35.7)]  # Tokyo area
+    save_oemj_as_geotiff(polygon, "tokyo_satellite.tiff", zoom=16)
 """
 
 import requests
@@ -16,15 +27,22 @@ from osgeo import gdal, osr
 import pyproj
 
 def deg2num(lon_deg, lat_deg, zoom):
-    """Convert longitude/latitude coordinates to tile coordinates.
+    """Convert longitude/latitude coordinates to tile coordinates using Web Mercator projection.
+    
+    The function converts geographic coordinates to tile coordinates using the standard
+    Web Mercator tiling scheme (XYZ). The resulting coordinates can be used to identify
+    and download specific map tiles.
     
     Args:
-        lon_deg (float): Longitude in degrees
-        lat_deg (float): Latitude in degrees
-        zoom (int): Zoom level
+        lon_deg (float): Longitude in degrees (-180 to 180)
+        lat_deg (float): Latitude in degrees (-90 to 90)
+        zoom (int): Zoom level (0-20, where 0 is most zoomed out)
         
     Returns:
-        tuple: (x, y) tile coordinates
+        tuple: (x, y) tile coordinates as floats
+        
+    Example:
+        >>> x, y = deg2num(139.7, 35.6, 16)  # Tokyo coordinates
     """
     lat_rad = math.radians(lat_deg)
     n = 2.0 ** zoom
@@ -33,15 +51,21 @@ def deg2num(lon_deg, lat_deg, zoom):
     return (xtile, ytile)
 
 def num2deg(xtile, ytile, zoom):
-    """Convert tile coordinates to longitude/latitude coordinates.
+    """Convert tile coordinates back to longitude/latitude coordinates.
+    
+    This is the inverse operation of deg2num(). It converts tile coordinates
+    back to geographic coordinates using the Web Mercator projection.
     
     Args:
         xtile (float): X tile coordinate
         ytile (float): Y tile coordinate
-        zoom (int): Zoom level
+        zoom (int): Zoom level (0-20)
         
     Returns:
         tuple: (longitude, latitude) in degrees
+        
+    Example:
+        >>> lon, lat = num2deg(29326, 13249, 15)  # Sample tile coordinates
     """
     n = 2.0 ** zoom
     lon_deg = xtile / n * 360.0 - 180.0
@@ -52,12 +76,24 @@ def num2deg(xtile, ytile, zoom):
 def download_tiles(polygon, zoom):
     """Download satellite imagery tiles covering a polygon region.
     
+    Downloads all tiles that intersect with the given polygon at the specified zoom level
+    from the OpenEarthMap Japan server. The function calculates the minimum bounding box
+    that contains the polygon and downloads all tiles within that box.
+    
     Args:
-        polygon (list): List of (lon, lat) coordinates defining the region
-        zoom (int): Zoom level for tile detail
+        polygon (list): List of (lon, lat) tuples defining the region vertices in clockwise
+                       or counterclockwise order
+        zoom (int): Zoom level for tile detail (recommended range: 14-18)
         
     Returns:
-        tuple: (tiles dict mapping (x,y) to Image objects, bounds tuple)
+        tuple: (
+            tiles: dict mapping (x,y) tile coordinates to PIL Image objects,
+            bounds: tuple of (min_x, min_y, max_x, max_y) tile coordinates
+        )
+        
+    Note:
+        Higher zoom levels provide more detail but require downloading more tiles.
+        The function will print progress messages during download.
     """
     print(f"Downloading tiles")
 
@@ -85,14 +121,23 @@ def download_tiles(polygon, zoom):
     return tiles, (min(min_x, max_x), min(min_y, max_y), max(min_x, max_x), max(min_y, max_y))
 
 def compose_image(tiles, bounds):
-    """Compose downloaded tiles into a single image.
+    """Compose downloaded tiles into a single continuous image.
+    
+    Takes individual map tiles and combines them into a single large image based on
+    their relative positions. The tiles are placed according to their x,y coordinates
+    within the bounds.
     
     Args:
         tiles (dict): Mapping of (x,y) coordinates to tile Image objects
-        bounds (tuple): (min_x, min_y, max_x, max_y) tile bounds
+        bounds (tuple): (min_x, min_y, max_x, max_y) tile coordinate bounds
         
     Returns:
-        Image: Composed PIL Image
+        Image: Composed PIL Image with dimensions (width x height) where:
+              width = (max_x - min_x + 1) * 256
+              height = (max_y - min_y + 1) * 256
+              
+    Note:
+        Each tile is assumed to be 256x256 pixels, which is standard for web maps.
     """
     min_x, min_y, max_x, max_y = bounds
     width = abs(max_x - min_x + 1) * 256
@@ -104,16 +149,26 @@ def compose_image(tiles, bounds):
     return result
 
 def crop_image(image, polygon, bounds, zoom):
-    """Crop composed image to polygon boundary.
+    """Crop composed image to the exact polygon boundary.
+    
+    Creates a mask from the polygon coordinates and uses it to crop the image,
+    removing areas outside the polygon of interest. The polygon coordinates are
+    converted from geographic coordinates to pixel coordinates in the image space.
     
     Args:
         image (Image): PIL Image to crop
-        polygon (list): List of (lon, lat) coordinates
+        polygon (list): List of (lon, lat) coordinates defining the boundary
         bounds (tuple): (min_x, min_y, max_x, max_y) tile bounds
-        zoom (int): Zoom level
+        zoom (int): Zoom level used for coordinate conversion
         
     Returns:
-        tuple: (cropped Image, bounding box)
+        tuple: (
+            cropped Image: PIL Image cropped to polygon boundary,
+            bbox: tuple of (left, upper, right, lower) pixel coordinates of bounding box
+        )
+        
+    Raises:
+        ValueError: If the polygon does not intersect with the downloaded tiles
     """
     min_x, min_y, max_x, max_y = bounds
     img_width, img_height = image.size
@@ -139,15 +194,23 @@ def crop_image(image, polygon, bounds, zoom):
     return cropped.crop(bbox), bbox
 
 def save_as_geotiff(image, polygon, zoom, bbox, bounds, output_path):
-    """Save cropped image as georeferenced GeoTIFF.
+    """Save cropped image as a georeferenced GeoTIFF file.
+    
+    Converts the image to a GeoTIFF format with proper spatial reference information
+    using the Web Mercator projection (EPSG:3857). The function handles coordinate
+    transformation and sets up the necessary geospatial metadata.
     
     Args:
         image (Image): PIL Image to save
         polygon (list): List of (lon, lat) coordinates
-        zoom (int): Zoom level
-        bbox (tuple): Bounding box of cropped image
+        zoom (int): Zoom level used for coordinate calculations
+        bbox (tuple): Bounding box of cropped image in pixels (left, upper, right, lower)
         bounds (tuple): (min_x, min_y, max_x, max_y) tile bounds
-        output_path (str): Path to save GeoTIFF
+        output_path (str): Path where the GeoTIFF will be saved
+        
+    Note:
+        The output GeoTIFF will have 3 bands (RGB) and use the Web Mercator
+        projection (EPSG:3857) for compatibility with most GIS software.
     """
     min_x, min_y, max_x, max_y = bounds
     
@@ -187,12 +250,35 @@ def save_as_geotiff(image, polygon, zoom, bbox, bounds, output_path):
     dataset = None
 
 def save_oemj_as_geotiff(polygon, filepath, zoom=16):
-    """Download and save OpenEarthMap Japan imagery as GeoTIFF.
+    """Download and save OpenEarthMap Japan imagery as a georeferenced GeoTIFF file.
+    
+    This is the main function that orchestrates the entire process of downloading,
+    processing, and saving satellite imagery for a specified region.
     
     Args:
-        polygon (list): List of (lon, lat) coordinates defining region
-        filepath (str): Output path for GeoTIFF
+        polygon (list): List of (lon, lat) coordinates defining the region to download.
+                       Must be in clockwise or counterclockwise order.
+        filepath (str): Output path for the GeoTIFF file
         zoom (int, optional): Zoom level for detail. Defaults to 16.
+                            - 14: ~9.5m/pixel
+                            - 15: ~4.8m/pixel
+                            - 16: ~2.4m/pixel
+                            - 17: ~1.2m/pixel
+                            - 18: ~0.6m/pixel
+    
+    Example:
+        >>> polygon = [
+                (139.7, 35.6),  # Bottom-left
+                (139.8, 35.6),  # Bottom-right
+                (139.8, 35.7),  # Top-right
+                (139.7, 35.7)   # Top-left
+            ]
+        >>> save_oemj_as_geotiff(polygon, "tokyo_area.tiff", zoom=16)
+    
+    Note:
+        - Higher zoom levels provide better resolution but require more storage
+        - The polygon should be relatively small to avoid memory issues
+        - The output GeoTIFF will be in Web Mercator projection (EPSG:3857)
     """
     try:
         tiles, bounds = download_tiles(polygon, zoom)