voxcity.downloader.gsi
======================

.. py:module:: voxcity.downloader.gsi

.. autoapi-nested-parse::

   Module for downloading bare-earth DEM (Digital Terrain Model) tiles from the
   Geospatial Information Authority of Japan (GSI / 国土地理院) and converting them
   into a VoxCity-compatible georeferenced GeoTIFF.

   GSI publishes elevation tiles on the standard XYZ Web-Mercator tile grid at
   ``https://cyberjapandata.gsi.go.jp/xyz/{type}/{z}/{x}/{y}.txt``. Each tile is a
   256x256 grid of elevation values (meters) as CSV text, with ``e`` marking
   no-data. Resolutions, finest first: dem5a (5 m laser, z15), dem5b (5 m photo,
   z15), dem10b (10 m nationwide, z14).

   The mosaic is written natively in EPSG:3857 (no resampling); the downstream
   ``create_dem_grid_from_geotiff_polygon`` reprojects from the file's own CRS.

   .. rubric:: Example

   >>> verts = [(140.09, 36.21), (140.12, 36.21), (140.12, 36.24), (140.09, 36.24)]
   >>> save_gsi_dem_as_geotiff(verts, "dem.tif")



Functions
---------

.. autoapisummary::

   voxcity.downloader.gsi.save_gsi_dem_as_geotiff


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

.. py:function:: save_gsi_dem_as_geotiff(rectangle_vertices, filepath, dem_type=None, nodata=GSI_NODATA, sleep=0.4, timeout_s=10, include_dem10b_fallback=True)

   Download GSI bare-earth DEM for an ROI and save an EPSG:3857 GeoTIFF.

   :param rectangle_vertices: list of (lon, lat) tuples defining the ROI.
   :param filepath: output GeoTIFF path.
   :param dem_type: None (default) to build a seamless mosaic by overlaying the
                    finest products available per pixel (see below), or one of
                    'dem5a' / 'dem5b' / 'dem10b' to force a single product with
                    no merging.
   :param nodata: no-data fill value.
   :param sleep: seconds between requests (politeness; set 0 in tests).
   :param timeout_s: per-request timeout.
   :param include_dem10b_fallback: when auto-merging, backfill pixels covered by
                                   neither 5 m product with dem10b (10 m). Set False to leave
                                   such pixels as no-data.

   :returns: The written filepath.

   .. note::

      With ``dem_type=None`` the ROI is composed at z15 from dem5a, with
      dem5b filling any dem5a no-data pixels, and (optionally) dem10b filling
      whatever remains. This produces a seamless terrain even when the ROI
      straddles a dem5a coverage boundary, instead of leaving no-data holes.
      dem5b is fetched only for tiles where dem5a is incomplete, and dem10b
      only when 5 m no-data pixels remain, so fully dem5a-covered ROIs incur
      no extra requests. dem10b (z14) is half the resolution of the 5 m
      products; because both grids share the global mercator origin and
      differ by an exact power of two, its pixels are mapped without
      resampling artifacts.

   :raises ValueError: if rectangle_vertices is empty, dem_type is invalid, or
       no tiles cover the area.