voxcity.downloader.oemj
=======================

.. py:module:: voxcity.downloader.oemj

.. autoapi-nested-parse::

   Module for downloading and processing OpenEarthMap Japan (OEMJ) satellite imagery.

   This module provides functionality to download, compose, crop and save satellite imagery tiles
   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)



Functions
---------

.. autoapisummary::

   voxcity.downloader.oemj.save_oemj_as_geotiff


Module Contents
---------------

.. py:function:: save_oemj_as_geotiff(polygon, filepath, zoom=16, *, ssl_verify=True, allow_insecure_ssl=False, allow_http_fallback=False, timeout_s=30)

   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.

   :param polygon: List of (lon, lat) coordinates defining the region to download.
                   Must be in clockwise or counterclockwise order.
   :type polygon: list
   :param filepath: Output path for the GeoTIFF file
   :type filepath: str
   :param zoom: 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
   :type zoom: int, optional

   .. rubric:: 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)