# map_tile_downloader

**Repository Path**: echohye/map_tile_downloader

## Basic Information

- **Project Name**: map_tile_downloader
- **Description**: 一个使用 Python 和 Tkinter 构建的图形界面应用程序，用于从在线服务或本地目录下载地图瓦片 (XYZ/ZYX 格式)，支持并发下载、全球/区域范围选择、多种存储格式和离线预览。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-27
- **Last Updated**: 2025-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 地图瓦片下载器 (Map Tile Downloader)

一个使用 Python 和 Tkinter 构建的图形界面应用程序，用于从在线服务或本地目录下载地图瓦片 (XYZ/ZYX 格式)，支持并发下载、全球/区域范围选择、多种存储格式和离线预览。

<div style="text-align: center;">
    <img src="images/example.png" width="50%" alt="地图瓦片下载器示例">
</div>

## 功能特性

*   **图形用户界面 (GUI)**: 基于 Tkinter，操作直观方便。
*   **多种瓦片源**:
    *   支持在线瓦片服务 URL (如 ArcGIS, OSM)。
    *   支持从本地目录复制瓦片。
*   **灵活的下载范围**:
    *   指定经纬度范围下载区域瓦片。
    *   设置“全球下载级别”作为基础，下载低级别全球瓦片，高级别则下载指定区域瓦片。
*   **可配置参数**:
    *   下载层级范围 (最小/最大级别)。
    *   瓦片存储格式 (PNG, JPG)。
    *   本地存储路径格式 (ZXY, ZYX)。
    *   并发线程数 (1-8，默认5)。
    *   裁切超出范围的瓦片。
*   **智能处理**:
    *   下载前检查保存目录，非空时提示用户确认。
    *   自动创建不存在的目录结构。
    *   下载/复制过程中显示详细日志和每级瓦片统计。
*   **离线预览**: 下载完成后，可一键生成 HTML 文件，使用 Leaflet.js 在浏览器中离线查看下载的瓦片。
*   **现代化包管理**: 使用 `uv` 进行项目初始化和依赖管理。

## 快速开始

### 先决条件

*   **Python 3.8 或更高版本**
*   **`uv` 包管理器**: 请先安装 [uv](https://github.com/astral-sh/uv)。

### 安装

1.  **克隆或下载此仓库**:

    ```bash
    git clone <repository-url>
    # 或者下载 ZIP 包并解压
    cd map_tile_downloader
    ```

2.  **安装依赖**:

    `uv` 会根据 `pyproject.toml` 文件自动解析和安装依赖。

    ```bash
    # 在项目根目录下
    uv sync
    ```

### 运行

使用 `uv` 运行项目：

```bash
# 在项目根目录下
uv run python main.py
```

程序启动后，默认保存路径为项目目录下的 `data` 文件夹。

### 打包为可执行文件 (Windows .exe)

您可以使用 `PyInstaller` 将项目打包成独立的 `.exe` 文件。

1.  **安装 PyInstaller** (如果尚未安装):

    ```bash
    uv add pyinstaller
    ```
2.  **打包**:

    ```bash
    # 在项目根目录下执行
    # --onefile: 打包成单个 exe
    # --windowed: 隐藏控制台窗口 (GUI 应用)
    # --name: 指定 exe 文件名
    # --add-data: 添加图标等数据文件 (Windows 使用分号分隔)
    uv run "src/build_version.py";uv run pyinstaller -F -w -i 'src/logo/logo.ico' --add-data="src/logo/logo.ico;logo" --name "MapTileDownloader" main.py
    ```
3.  **运行**:

    打包完成后，可在 `dist` 目录下找到 `MapTileDownloader.exe` 文件并运行。

## 使用说明

1.  **配置参数**:
    *   **瓦片源**: 输入在线服务 URL 模板 (如 `https://example.com/{z}/{y}/{x}.png`) 或本地路径模板 (如 `C:\tiles\{z}\{y}\{x}.png`)。
    *   **检测源**: 点击此按钮判断源是网络 URL 还是本地路径，以决定是下载还是复制。
    *   **保存路径**: 选择瓦片保存的本地目录。默认为项目下的 `data` 文件夹。
    *   **下载级别**: 设置要下载的最小和最大缩放级别。
    *   **全球下载级别**: (可选) 勾选并设置级别 N，程序会先下载 1-N 级的全球瓦片，然后下载 N-max_level 的指定区域瓦片。
    *   **下载范围**: 输入需要下载区域的左上角和右下角经纬度坐标，支持裁切超出范围的瓦片。
    *   **存储选项**: 选择图片保存格式 (PNG/JPG) 和本地路径格式 (ZXY/ZYX)。
    *   **性能设置**: 调整并发下载线程数 (1-8)。
2.  **开始下载**: 点击“开始下载”按钮启动任务。日志窗口会显示进度和结果。
3.  **预览**: 下载完成后，点击“预览”按钮生成 `preview.html` 并在浏览器中打开，以查看下载的瓦片。

## 项目结构

```
map_tile_downloader/
├── pyproject.toml        # 项目配置和依赖 (uv)
├── README.md             # 本说明文件
├── app_icon.png          # 应用图标 (用于 GUI 和打包)
├── main.py               # 程序入口点
├── src/
│   ├── __init__.py
│   ├── __main__.py
│   ├── gui.py            # Tkinter 图形界面
│   ├── downloader.py     # 核心下载/复制逻辑
│   ├── utils.py          # 辅助函数 (坐标转换等)
│   └── build_version.py  # 版本信息文件生成
└── dist/                 # (打包后生成) PyInstaller 输出目录
```

## 依赖

*   `requests`: 用于网络请求。
*   `Pillow`: 用于图像处理 (格式转换)。
*   `tkinter`: Python 内置 GUI 库。
*   `pathlib`: Python 内置，用于现代路径操作。
*   `concurrent.futures`: Python 内置，用于线程池并发。
*   `webbrowser`: Python 内置，用于打开预览网页。
*   `urllib.parse`: Python 内置，用于 URL 编码。
*   `logging`: Python 内置，用于日志记录。
*   `typing`: Python 内置，用于类型提示。
*   `shutil`: Python 内置，用于文件复制。
*   `io`: Python 内置，用于处理字节流。
*   `math`: Python 内置，用于数学计算。

(开发/打包时)
*   `pyinstaller`: 用于将 Python 应用打包成独立可执行文件。