用途
portolan-thumbnails 用于从 Portolan 集合生成高质量缩略图。它通过 chiitiler（基于 MapLibre GL Native）在服务端渲染集合实际的 styles/default.json 样式，从而生成与浏览器门户一致的主图级图像，效果远优于默认基于 matplotlib 的缩略图。
主要能力
- 读取集合的 styles/default.json（即门户实际使用的样式）。
- 重写数据源，通过 pmtiles:// 协议指向本地 PMTiles 文件。
- 可选在原始图层下方叠加底图。
- 通过 chiitiler 进行服务端渲染。
- 保留原始样式（颜色、透明度、描边不变）。
- 支持输出 PNG、JPG、WebP 格式。
- 原始 styles/default.json 不会被修改，仅创建临时 .render-style.json 并在渲染后删除。
使用方式
前置要求
- Node.js 18+ 和 npm
- Git（用于克隆 chiitiler）
- 包含 .pmtiles 和 styles/default.json 的集合
批量渲染
在目录目录（catalog directory）中运行脚本，为所有包含 PMTiles 和样式的集合渲染缩略图。脚本包含配置项：CATALOG_DIR（目录根路径）、OUTPUT_FORMAT（png | jpg | webp）、SIZE（最长边像素）、QUALITY（JPEG/WebP 质量，PNG 忽略）、USE_BASEMAP（是否叠加底图）、BASEMAP_URL（底图地址）。
脚本会先安装 chiitiler（若未安装），在端口 13579 启动服务，然后遍历集合目录，提取 collection.json 中的 bbox，构建渲染样式并调用 chiitiler 的 /clip 接口输出缩略图。
单集合渲染
可针对单个集合渲染，步骤包括启动服务、读取 bbox、构建样式、调用接口输出。
底图选项
默认使用 Carto Light。可替换为 Carto Dark、Carto Voyager、OpenStreetMap、Stadia Smooth、Stadia Dark。设置 USE_BASEMAP=false 可使用纯白背景（文件更小，无外部请求）。
输出格式
- png：无损，支持透明，文件较大
- jpg：文件较小，无透明，适合照片
- webp：压缩最佳，现代浏览器支持
生成后同步
缩略图生成后，可通过 portolan push s3://bucket/catalog 同步到远程，versions.json 会自动更新新的缩略图校验和。
适用场景
适用于需要精致缩略图的集合，例如主图（hero images）、精选集合（featured collections）。该功能为可选启用，默认的 portolan check --fix 缩略图仍作为基线。
限制
- 需要 Node.js 18+、npm 和 Git。
- 需要集合包含 .pmtiles 和 styles/default.json。
- 渲染速度受 bbox 大小和缩放级别影响，过大或过高时可减小 SIZE。
- 底图加载依赖对瓦片服务器的网络访问。
- 若 PMTiles 在 bbox 范围内无数据，可能生成空图或黑图。
- 集合 bbox 高度或宽度接近零时，图像会很细或很小，这属于正常情况。
- 批量渲染时需设置 CHIITILER_PROCESSES=0 以启用多进程模式，防止内存崩溃。
故障排查
- npm install 失败：确认 Node.js 18+（node --version）。
- 服务无法启动：检查端口（lsof -i :13579）。
- 批量中途崩溃：确保设置 CHIITILER_PROCESSES=0。
- 空图/黑图：确认 PMTiles 在 bbox 范围内有数据。
- 图像过细/过小：集合 bbox 高度/宽度接近零，属正常。
- 底图未加载：检查对瓦片服务器的网络访问。
- 渲染过慢：bbox 过大或缩放过高，减小 SIZE。