tilekit 0.1.0__tar.gz

tilekit-0.1.0/.idea/.gitignore

@@ -0,0 +1,8 @@
+# 默认忽略的文件
+/shelf/
+/workspace.xml
+# 基于编辑器的 HTTP 客户端请求
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

tilekit-0.1.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

tilekit-0.1.0/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="uv (tilekit)" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="py13" project-jdk-type="Python SDK" />
+</project>

tilekit-0.1.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/tilekit.iml" filepath="$PROJECT_DIR$/.idea/tilekit.iml" />
+    </modules>
+  </component>
+</project>

tilekit-0.1.0/.idea/tilekit.iml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="uv (tilekit)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

tilekit-0.1.0/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

tilekit-0.1.0/.idea/workspace.xml

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="7ecbaad1-0830-4879-b1c9-a862886743c8" name="更改" comment="">
+      <change afterPath="$PROJECT_DIR$/.idea/.gitignore" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/inspectionProfiles/profiles_settings.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/misc.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/modules.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/tilekit.iml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/.idea/vcs.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="FileTemplateManagerImpl">
+    <option name="RECENT_TEMPLATES">
+      <list>
+        <option value="Python Script" />
+      </list>
+    </option>
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="ProjectColorInfo">{
+  &quot;associatedIndex&quot;: 8
+}</component>
+  <component name="ProjectId" id="368YvrMt0ewdwPXScps4FAd05Jq" />
+  <component name="ProjectLevelVcsManager">
+    <ConfirmationsSetting value="1" id="Add" />
+  </component>
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent">{
+  &quot;keyToString&quot;: {
+    &quot;ModuleVcsDetector.initialDetectionPerformed&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.git.unshallow&quot;: &quot;true&quot;,
+    &quot;git-widget-placeholder&quot;: &quot;main&quot;,
+    &quot;last_opened_file_path&quot;: &quot;F:/zpz/Projects3/tilekit/src/tilekit&quot;,
+    &quot;node.js.detected.package.eslint&quot;: &quot;true&quot;,
+    &quot;node.js.detected.package.tslint&quot;: &quot;true&quot;,
+    &quot;node.js.selected.package.eslint&quot;: &quot;(autodetect)&quot;,
+    &quot;node.js.selected.package.tslint&quot;: &quot;(autodetect)&quot;,
+    &quot;nodejs_package_manager_path&quot;: &quot;npm&quot;,
+    &quot;settings.editor.selected.configurable&quot;: &quot;com.jetbrains.python.configuration.PyActiveSdkModuleConfigurable&quot;,
+    &quot;vue.rearranger.settings.migration&quot;: &quot;true&quot;
+  }
+}</component>
+  <component name="RecentsManager">
+    <key name="CopyFile.RECENT_KEYS">
+      <recent name="F:\zpz\Projects3\tilekit\src\tilekit" />
+      <recent name="F:\zpz\Projects3\tilekit\tilekit" />
+    </key>
+    <key name="MoveFile.RECENT_KEYS">
+      <recent name="F:\zpz\Projects3\tilekit\test" />
+    </key>
+  </component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-js-predefined-d6986cc7102b-b26f3e71634d-JavaScript-PY-251.26094.141" />
+        <option value="bundled-python-sdk-9f8e2b94138c-36ea0e71a18c-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-251.26094.141" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="默认任务">
+      <changelist id="7ecbaad1-0830-4879-b1c9-a862886743c8" name="更改" comment="" />
+      <created>1764389899006</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1764389899006</updated>
+      <workItem from="1764389900136" duration="637000" />
+      <workItem from="1764390545007" duration="171000" />
+      <workItem from="1764390726886" duration="1651000" />
+      <workItem from="1764392460821" duration="643000" />
+      <workItem from="1764393268748" duration="2106000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

tilekit-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: tilekit
+Version: 0.1.0
+Summary: tilekit
+Author: ZPZ
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: mercantile>=1.2.1
+Requires-Dist: numpy>=2.3.5
+Requires-Dist: pillow>=12.0.0
+Requires-Dist: rasterio>=1.4.3
+Requires-Dist: requests>=2.32.5
+Requires-Dist: tqdm>=4.67.1
+Description-Content-Type: text/markdown
+
+# tilekit
+
+A lightweight toolkit for downloading **JL1 (Jilin-1)** XYZ/TMS tiles and saving them as **georeferenced GeoTIFFs**.
+
+`tilekit` wraps the low-level HTTP requests, TMS/XYZ conversion, logging, and raster writing into a simple, high-level API based on `mercantile`, `rasterio`, and `Pillow`.
+
+---
+
+## Features
+
+- 🗺 **Bounding box download**  
+  Construct tile lists from a lon/lat bounding box and zoom level.
+
+- 📐 **Shapefile-based download**  
+  Use a polygon boundary (shapefile, EPSG:4326) to determine the tile coverage.
+
+- 🔁 **XYZ → TMS conversion**  
+  Handles the JL1 API’s TMS-style Y coordinate internally, while filenames remain in standard XYZ.
+
+- ⏸ **Resume support / precheck**  
+  Skips tiles that already exist on disk (`z/x/y.tif`) to avoid duplicate downloads.
+
+- 🧍 **Human-like throttling**  
+  Randomized delays between requests to mimic human behavior and reduce the risk of rate limiting.
+
+- 🧾 **Structured logging**  
+  Logs progress and errors both to console and to `download.log` in the output folder.
+
+---
+
+## Installation
+
+Once published on PyPI:
+
+```bash
+pip install tilekit
+```
+
+
+
+## Getting Started
+
+### 1. Download tiles by lon/lat bounding box
+
+```
+from tilekit.downloader import TileDownloader
+
+min_lon = 114.98
+max_lon = 117.20
+min_lat = 38.69
+max_lat = 41.18
+zoom = 18
+
+# JL1 API keys (replace with your own)
+mk = "your_mk_token_here"
+tk = "your_tk_token_here"
+
+downloader = TileDownloader.from_lon_lat(
+    min_lat=min_lat,
+    max_lat=max_lat,
+    min_lon=min_lon,
+    max_lon=max_lon,
+    zoom=zoom,
+    mk=mk,
+    tk=tk,
+)
+
+print("Total tiles to download:", len(downloader.tile_list))
+
+downloader.download_tiles(
+    output_folder=r"F:\xxx\JL1Tiles",
+    verbose_debug=False,
+)
+```
+
+This will:
+
+- Compute all tiles covering the bounding box at zoom level 18
+- Convert XYZ Y to JL1’s TMS convention internally
+- Download each tile and save it as `z/x/y.tif` with proper georeferencing
+
+------
+
+### 2. Download tiles based on a shapefile boundary
+
+```
+from tilekit.downloader import TileDownloader
+
+zoom = 18
+mk = "your_mk_token_here"
+tk = "your_tk_token_here"
+
+# Shapefile should be in EPSG:4326 (lon/lat)
+shp_path = r"beijing.shp"
+
+downloader = TileDownloader.from_shp(
+    shp_path=shp_path,
+    zoom=zoom,
+    mk=mk,
+    tk=tk,
+)
+
+print("Total tiles to download:", len(downloader.tile_list))
+
+downloader.download_tiles(
+    output_folder=r"F:\xxx\JL1Tiles",
+    verbose_debug=False,
+)
+```
+
+`from_shp` will:
+
+- Read the shapefile using `geopandas`
+- Reproject to EPSG:4326 if necessary
+- Use the overall bounding box (`total_bounds`) to determine the tile range
+
+> Note: `geopandas` is only required if you use `from_shp`.
+>  You can install it via `pip install geopandas`.
+
+------
+
+## API Overview
+
+### `TileDownloader`
+
+```
+@dataclass
+class TileDownloader:
+    tile_list: Sequence[mercantile.Tile]
+    mk: str = "..."
+    tk: str = "..."
+    zoom: Optional[int] = None
+
+    def download_tiles(
+        self,
+        output_folder: Union[str, Path],
+        tile_list: Optional[Sequence[Tile]] = None,
+        verbose_debug: bool = False,
+    ) -> None:
+        ...
+```
+
+**Key methods:**
+
+- `TileDownloader.from_lon_lat(min_lat, max_lat, min_lon, max_lon, zoom, mk, tk)`
+   Build a downloader from a bounding box.
+- `TileDownloader.from_shp(shp_path, zoom, mk, tk)`
+   Build a downloader from a shapefile boundary.
+- `TileDownloader.from_XYZs(tiles, mk, tk)`
+   Build a downloader from an existing list of `mercantile.Tile` objects (all at the same zoom level).
+- `TileDownloader.download_tiles(output_folder, tile_list=None, verbose_debug=False)`
+   Download all tiles and save as GeoTIFF files (`z/x/y.tif`), skipping files that already exist.
+
+------
+
+## Output Format
+
+Each downloaded tile is saved as a **multi-band GeoTIFF**:
+
+- Filename: `output_folder/z/x/y.tif`
+- Coordinate reference system: `EPSG:4326`
+- Transform: computed from the tile’s geographic bounds via `rasterio.transform.from_bounds`
+- Compression: LZW (`Compression.lzw`)
+- Bands: derived from the source image (e.g., RGB → 3 bands)
+
+------
+
+## Requirements
+
+Core dependencies (installed automatically when you install `tilekit`):
+
+- `mercantile`
+- `rasterio`
+- `numpy`
+- `requests`
+- `Pillow`
+- `tqdm`
+
+Optional (for shapefile-based workflows):
+
+- `geopandas`
+
+------
+
+## Notes
+
+- You must provide valid **JL1 API keys** (`mk`, `tk`) to access the tile service.
+   The examples in this README use placeholder values; please replace them with your own.
+- The downloader includes:
+  - A precheck step that skips already downloaded tiles
+  - Randomized delays between requests via `human_delay` to reduce the risk of being rate-limited
+
+------
+
+## License
+
+`tilekit` is released under the **Apache 2.0** License.

tilekit-0.1.0/README.md

@@ -0,0 +1,197 @@
+# tilekit
+
+A lightweight toolkit for downloading **JL1 (Jilin-1)** XYZ/TMS tiles and saving them as **georeferenced GeoTIFFs**.
+
+`tilekit` wraps the low-level HTTP requests, TMS/XYZ conversion, logging, and raster writing into a simple, high-level API based on `mercantile`, `rasterio`, and `Pillow`.
+
+---
+
+## Features
+
+- 🗺 **Bounding box download**  
+  Construct tile lists from a lon/lat bounding box and zoom level.
+
+- 📐 **Shapefile-based download**  
+  Use a polygon boundary (shapefile, EPSG:4326) to determine the tile coverage.
+
+- 🔁 **XYZ → TMS conversion**  
+  Handles the JL1 API’s TMS-style Y coordinate internally, while filenames remain in standard XYZ.
+
+- ⏸ **Resume support / precheck**  
+  Skips tiles that already exist on disk (`z/x/y.tif`) to avoid duplicate downloads.
+
+- 🧍 **Human-like throttling**  
+  Randomized delays between requests to mimic human behavior and reduce the risk of rate limiting.
+
+- 🧾 **Structured logging**  
+  Logs progress and errors both to console and to `download.log` in the output folder.
+
+---
+
+## Installation
+
+Once published on PyPI:
+
+```bash
+pip install tilekit
+```
+
+
+
+## Getting Started
+
+### 1. Download tiles by lon/lat bounding box
+
+```
+from tilekit.downloader import TileDownloader
+
+min_lon = 114.98
+max_lon = 117.20
+min_lat = 38.69
+max_lat = 41.18
+zoom = 18
+
+# JL1 API keys (replace with your own)
+mk = "your_mk_token_here"
+tk = "your_tk_token_here"
+
+downloader = TileDownloader.from_lon_lat(
+    min_lat=min_lat,
+    max_lat=max_lat,
+    min_lon=min_lon,
+    max_lon=max_lon,
+    zoom=zoom,
+    mk=mk,
+    tk=tk,
+)
+
+print("Total tiles to download:", len(downloader.tile_list))
+
+downloader.download_tiles(
+    output_folder=r"F:\xxx\JL1Tiles",
+    verbose_debug=False,
+)
+```
+
+This will:
+
+- Compute all tiles covering the bounding box at zoom level 18
+- Convert XYZ Y to JL1’s TMS convention internally
+- Download each tile and save it as `z/x/y.tif` with proper georeferencing
+
+------
+
+### 2. Download tiles based on a shapefile boundary
+
+```
+from tilekit.downloader import TileDownloader
+
+zoom = 18
+mk = "your_mk_token_here"
+tk = "your_tk_token_here"
+
+# Shapefile should be in EPSG:4326 (lon/lat)
+shp_path = r"beijing.shp"
+
+downloader = TileDownloader.from_shp(
+    shp_path=shp_path,
+    zoom=zoom,
+    mk=mk,
+    tk=tk,
+)
+
+print("Total tiles to download:", len(downloader.tile_list))
+
+downloader.download_tiles(
+    output_folder=r"F:\xxx\JL1Tiles",
+    verbose_debug=False,
+)
+```
+
+`from_shp` will:
+
+- Read the shapefile using `geopandas`
+- Reproject to EPSG:4326 if necessary
+- Use the overall bounding box (`total_bounds`) to determine the tile range
+
+> Note: `geopandas` is only required if you use `from_shp`.
+>  You can install it via `pip install geopandas`.
+
+------
+
+## API Overview
+
+### `TileDownloader`
+
+```
+@dataclass
+class TileDownloader:
+    tile_list: Sequence[mercantile.Tile]
+    mk: str = "..."
+    tk: str = "..."
+    zoom: Optional[int] = None
+
+    def download_tiles(
+        self,
+        output_folder: Union[str, Path],
+        tile_list: Optional[Sequence[Tile]] = None,
+        verbose_debug: bool = False,
+    ) -> None:
+        ...
+```
+
+**Key methods:**
+
+- `TileDownloader.from_lon_lat(min_lat, max_lat, min_lon, max_lon, zoom, mk, tk)`
+   Build a downloader from a bounding box.
+- `TileDownloader.from_shp(shp_path, zoom, mk, tk)`
+   Build a downloader from a shapefile boundary.
+- `TileDownloader.from_XYZs(tiles, mk, tk)`
+   Build a downloader from an existing list of `mercantile.Tile` objects (all at the same zoom level).
+- `TileDownloader.download_tiles(output_folder, tile_list=None, verbose_debug=False)`
+   Download all tiles and save as GeoTIFF files (`z/x/y.tif`), skipping files that already exist.
+
+------
+
+## Output Format
+
+Each downloaded tile is saved as a **multi-band GeoTIFF**:
+
+- Filename: `output_folder/z/x/y.tif`
+- Coordinate reference system: `EPSG:4326`
+- Transform: computed from the tile’s geographic bounds via `rasterio.transform.from_bounds`
+- Compression: LZW (`Compression.lzw`)
+- Bands: derived from the source image (e.g., RGB → 3 bands)
+
+------
+
+## Requirements
+
+Core dependencies (installed automatically when you install `tilekit`):
+
+- `mercantile`
+- `rasterio`
+- `numpy`
+- `requests`
+- `Pillow`
+- `tqdm`
+
+Optional (for shapefile-based workflows):
+
+- `geopandas`
+
+------
+
+## Notes
+
+- You must provide valid **JL1 API keys** (`mk`, `tk`) to access the tile service.
+   The examples in this README use placeholder values; please replace them with your own.
+- The downloader includes:
+  - A precheck step that skips already downloaded tiles
+  - Randomized delays between requests via `human_delay` to reduce the risk of being rate-limited
+
+------
+
+## License
+
+`tilekit` is released under the **Apache 2.0** License.

tilekit-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "tilekit"
+version = "0.1.0"
+description = "tilekit"
+license = { text = "Apache-2.0" }
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.11"
+authors = [
+    { name = "ZPZ" }
+]
+dependencies = [
+    "mercantile>=1.2.1",
+    "numpy>=2.3.5",
+    "pillow>=12.0.0",
+    "rasterio>=1.4.3",
+    "requests>=2.32.5",
+    "tqdm>=4.67.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# [tool.uv]
+# package-dir = "src"
+
+# [tool.hatch.build.targets.wheel]
+# packages = ["src/foo"]

tilekit-0.1.0/src/tilekit/__init__.py

@@ -0,0 +1 @@
+from .downloader import TileDownloader