RasterLite2：把 SQLite 栅格覆盖、元数据和地图配置拆开讲清楚

ℹ️ 读者定位

适合你，如果： 你已经会基础 SQLite / SQL，正在做离线 GIS、桌面工具或单文件空间数据交付，想知道 RasterLite2 如何在 SQLite / SpatiaLite 体系中存储、管理和渲染栅格。

开始前需要： 了解 SQLite 表、函数、BLOB 和扩展加载；本文的 SQL 主要用于理解接口和验证对象是否存在。

读完可以完成： 说清 SQLite、SpatiaLite 和 RasterLite2 的分工，理解 Coverage、Section、Tile 的关系，按任务找到栅格导入、元数据、样式和地图配置函数，并知道哪些结果还需要现场验证。

暂时不适合： 需要完整安装手册、生产性能基准或针对某个发行版的部署脚本的场景；本文不会把未经现场运行的命令写成已验证结果。

很多人把 SpatiaLite 简单理解成"SQLite 加空间能力"。这个理解对点、线、面很有效，但遇到栅格时，容易把 SpatiaLite、RasterLite2 和 PostGIS Raster 混成一个东西。

更准确的说法是：RasterLite2 是面向 SQLite 数据库的栅格存储、覆盖管理和地图输出能力，通常通过 SpatiaLite 的集成接口使用。 它并不只是维护几张元数据表，而是把栅格组织成 Coverage、Section 和 Tile，并把瓦片像元以压缩 BLOB 的形式存进 SQLite；元数据、样式和地图配置是围绕这套栅格数据组织起来的附加能力。

这篇内容分为以下几个部分：

1. 先把 RasterLite2 放回 SQLite / SpatiaLite 体系里。
2. 解释 Coverage、Section、Tile 和金字塔如何落到表中。
3. 区分元数据初始化、Coverage 创建和外部栅格导入。
4. 再看 SRID、范围、关键词、Raster Style 和 Map Configuration。
5. 给出验证骨架，并明确哪些内容不能靠函数名证明。
6. 最后判断什么场景适合继续评估 RasterLite2。

一、先把 RasterLite2 放回体系里

1.1 它不是"只有元数据的栅格目录"

SQLite 提供数据库文件、事务和表；SpatiaLite 提供 Geometry BLOB、空间元数据、空间 SQL、空间索引以及 SLD/SE 样式等空间能力；RasterLite2 则提供栅格 Coverage 的创建、瓦片化存储、读取、导入导出、压缩、金字塔和地图输出等能力。

可以先记住这张分工图：

SQLite 数据库文件
  ├─ SpatiaLite 基础能力
  │   ├─ geometry_columns / spatial_ref_sys 等空间元数据
  │   ├─ Geometry BLOB、空间 SQL、空间索引
  │   └─ SLD/SE Styled Layers 及其 Raster Style 接口
  │
  └─ RasterLite2 栅格能力
      ├─ raster_coverages：Coverage 目录
      ├─ <coverage>_sections：输入影像分区
      ├─ <coverage>_tiles：瓦片索引与空间范围
      ├─ <coverage>_tile_data：压缩后的像元 BLOB
      ├─ levels / section_levels：金字塔相关表
      └─ RL2_*：创建、导入、读取、导出和地图输出函数

RasterLite2 在 SQLite / SpatiaLite 中的层次关系

这里的"集成"不能理解成任何 mod_spatialite 都自动带有完整 RasterLite2。函数是否可用，取决于目标构建是否包含相应的 RasterLite2、SpatiaLite 和 XML 支持；官方 GDAL 文档也把 RasterLite2 驱动列为同时依赖 libsqlite3、librasterlite2 和 libspatialite 的统一 SQLite / SpatiaLite / RasterLite2 驱动。

1.2 和 PostGIS Raster 不要直接画等号

RasterLite2 和 PostGIS Raster 都能处理栅格，但对象模型和运行环境不同。RasterLite2 的核心对象是 SQLite 文件中的 Coverage、Section、Tile 和相关金字塔；PostGIS Raster 则属于 PostgreSQL / PostGIS 的 Raster 类型和函数体系。

因此，选型时不要只问"RasterLite2 是不是更小的 PostGIS Raster"，而要问：

• 数据是不是需要跟着应用走，最好就是一个 SQLite 文件？
• 是否主要面向离线、单机或低写入并发？
• 需要的是瓦片化栅格存储和地图输出，还是完整的服务端栅格分析生态？

二、RasterLite2 真正存储的是什么

2.1 Coverage 是最上层容器

一个 Raster Coverage 定义一组共同的栅格约束，例如像元类型、Sample Type、波段配置、压缩方式、瓦片尺寸、SRID 和像元分辨率。Coverage 还拥有自己的总体范围。

raster_coverages 是 Coverage 目录和配置表，作用类似于矢量数据中的 geometry_columns：它记录 Coverage 的关键配置，但不是装下所有像元的那张表。

2.2 Section 是输入影像或覆盖片段

一个 Coverage 可以由多个 Section 组成。Section 通常对应导入 Coverage 的一幅外部影像，但不同 Section 不要求完全相邻，也可以存在空白区域或相互重叠；重叠时，RasterLite2 按 Section 的规则处理覆盖关系。

Section 的元数据通常落在 <coverage_name>_sections 表中，包括 Section 的空间范围，以及根据策略选择保存的输入路径、MD5 和影像摘要等信息。

2.3 Tile 才是像元数据的基本存储单元

Section 会被切分成许多 Tile。Tile 的空间范围和索引信息保存在 <coverage_name>_tiles 表，实际编码后的像元 BLOB 保存在 <coverage_name>_tile_data 表。把重的像元 BLOB 单独放表里，是为了减少内部 SQL 查询处理索引和元数据时的负担。

因此，下面这句话必须分清：

CreateRasterCoveragesTable() 只创建 Coverage 目录表；它不会创建某个具体 Coverage，也不会把 GeoTIFF 自动写进 SQLite。

2.4 金字塔不是元数据表的同义词

RasterLite2 支持物理和虚拟金字塔，也支持按 Section 建立金字塔或建立覆盖整体的 Monolithic Pyramid。金字塔可能带来额外存储，也可能通过虚拟层级减少存储，但具体行为取决于 Coverage 类型、策略和目标版本。

这也是原文需要补上的边界：Coverage 元数据、Tile 存储和金字塔是三个不同层次，不能把 raster_coverages 表当成 RasterLite2 的全部内容。

三、从数据库初始化到真实栅格数据

3.1 初始化、升级和创建 Coverage 是三件事

初始化基础元数据

对于新建数据库，InitSpatialMetaDataFull() 是 SpatiaLite 提供的完整初始化入口之一；官方说明它会依次处理基础空间元数据、Raster Coverage 表、Vector Coverage 表和样式表。

如果只需要补建 RasterLite2 的目录表，可以使用：

SELECT CreateRasterCoveragesTable();
SELECT ReCreateRasterCoveragesTriggers();

这两步只是准备 Raster Coverage 的管理结构，不能代替 Coverage 创建和栅格导入。

升级旧数据库

CreateMissingRasterlite2Columns() 的准确定位是：为旧版 SpatiaLite 数据库补齐 RasterLite2 v2 及后续版本所需的缺失元数据列。官方特别说明，它主要面向 SpatiaLite 5.0.0 / 5.0.1 等旧数据库的安全升级；它不是每次新建数据库都必须执行的 RasterLite2 初始化步骤。

创建一个具体 Coverage

真正创建 Coverage 的入口是 RL2_CreateRasterCoverage()。它会根据 Coverage 名称、Sample Type、Pixel Type、波段数、压缩方式、瓦片尺寸、SRID、像元分辨率和策略等参数创建一套具体的 Coverage 表结构。

接口形态可以这样理解：

-- 示意：参数必须按实际数据、目标版本和空间参考系填写。
SELECT RL2_CreateRasterCoverage(
    'dem',       -- coverageName
    'UINT16',    -- sampleType
    'DATAGRID',  -- pixelType
    1,           -- numBands
    'DEFLATE',   -- compressionType
    100,         -- quality
    512, 512,    -- tileWidth, tileHeight
    4326,        -- SRID
    0.0001,      -- horizontal pixel resolution
    0.0001       -- vertical pixel resolution
);

该函数返回 1 表示成功、0 表示失败，-1 表示参数无效。上面只是接口示意，不代表当前电脑已经创建成功；Coverage 的 SRID、像元类型、分辨率、压缩方式和 NoData 值都要与实际数据一致。

3.2 外部影像导入才会产生 Section 和 Tile

创建空 Coverage 后，还需要把外部数据导入。常见入口是：

-- 示意：GeoTIFF 可以从自身读取空间参考；普通 TIFF、JPEG、ASCII Grid
-- 往往还需要显式提供 forceSRID 或 WorldFile。
SELECT RL2_LoadRaster(
    'dem',
    'D:/data/dem.tif',
    0,       -- withWorldFile
    NULL,    -- forceSRID，按数据情况填写
    1        -- pyramidize
);

RL2_LoadRaster() 的作用是向已有 Coverage 创建并填充一个 Section；函数会把影像切成 Tile，按 Coverage 的规则编码并写入数据库。官方函数参考还说明，这类从外部文件读取数据的函数涉及文件系统访问，在某些构建中只有设置 SPATIALITE_SECURITY=relaxed 后才可用。

如果只是调用 CreateRasterCoveragesTable()，数据库里最多只有目录基础设施，不能据此声称"栅格已导入"。

3.3 一段更可靠的检查骨架

下面这段 SQL 只检查函数和基础对象，不冒充完成了导入：

SELECT spatialite_version();
SELECT HasLibXML2();
 
SELECT CreateRasterCoveragesTable();
SELECT ReCreateRasterCoveragesTriggers();
 
SELECT name
FROM sqlite_master
WHERE type = 'table'
  AND name = 'raster_coverages';
 
-- 如果已经创建具体 Coverage，再检查其派生表是否出现：
-- SELECT name
-- FROM sqlite_master
-- WHERE type = 'table'
--   AND name LIKE 'dem%';

spatialite_version() 只能说明 SpatiaLite 版本；HasLibXML2() 只能说明 XML 支持是否存在。是否真正注册了 RasterLite2 的 RL2_* 函数、是否能创建 Coverage、是否能导入影像，仍要看目标连接中的实际返回值和错误。

☑️ 实际运行结果待补充

请在目标 SQLite CLI、Java Connection 或 C# Connection 中补充真实输出，至少展示扩展加载、HasLibXML2()、一个 RL2_* 函数的返回值，以及 raster_coverages 和具体 Coverage 派生表是否存在。建议文件名：截图资源/02-rasterlite2-metadata-check.png。

四、Coverage 元数据、样式和地图配置

4.1 SRID、范围和关键词是 Coverage 的附加目录信息

Raster Coverage 创建时已经包含主 SRID和像元分辨率；下面这些 SE_ 接口主要维护 Coverage 的附加元数据：

信息	代表函数	准确作用
备用 SRID	SE_RegisterRasterCoverageSrid() / SE_UnregisterRasterCoverageSrid()	为已有 Coverage 登记或删除备用 SRID；不会自动重投影像元
覆盖范围	SE_UpdateRasterCoverageExtent()	根据 Coverage 内容更新范围，并处理已定义的备用 SRID
关键词	SE_RegisterRasterCoverageKeyword() / SE_UnregisterRasterCoverageKeyword()	为已有 Coverage 添加或移除目录关键词

这些接口都要求目标 Coverage 已经存在。它们不能替代 RL2_CreateRasterCoverage()，也不能替代 RL2_LoadRaster()。

4.2 Raster Style 是渲染规则，不是像元数据

样式是一条独立链路：

CreateStylingTables()
        ↓
SE_RegisterRasterStyle(valid SLD/SE XML BLOB)
        ↓
SE_RegisterRasterStyledLayer(coverage_name, style_id / style_name)
        ↓
RL2_GetMapImageFromRaster(..., style_name, ...)
        ↓
返回地图图像 BLOB

CreateStylingTables() 会创建 SLD/SE Styled Layers 相关表，并且会隐式确保 Raster Coverage 目录表存在；SE_RegisterRasterStyle() 注册的是合法 Raster 类型 SLD/SE XML；SE_RegisterRasterStyledLayer() 把样式关联到已有 Raster Layer。

但"样式注册成功"不等于"客户端已经渲染成功"。要验证渲染，还需要真实 Coverage、有效的样式 XML、空间范围、输出尺寸，并调用地图输出函数或使用实际客户端读取结果。

4.3 RL2 Map Configuration 是可注册的多图层配置

RL2 Map Configuration 不是单个 Coverage 的像元存储表，而是可登记的 XML 配置对象，适合描述多图层地图及其样式组合：

任务	函数
注册	RL2_RegisterMapConfiguration(config BLOB)
删除	RL2_UnregisterMapConfiguration(config_id) 或按名称删除
更新	RL2_ReloadMapConfiguration(config_id / config_name, config BLOB)
统计数量	RL2_NumMapConfigurations()
枚举名称、标题、摘要	RL2_MapConfigurationNameN()、RL2_MapConfigurationTitleN()、RL2_MapConfigurationAbstractN()
根据配置输出地图	RL2_GetImageFromMapConfiguration(...)

配置 BLOB 必须是合法的 RL2 Map Configuration XML。只有注册配置还不代表已经输出地图；要验证业务结果，还需要调用 RL2_GetImageFromMapConfiguration() 并检查返回的图像 BLOB。

五、从"函数存在"到"业务可用"还差几步

5.1 把验证拆成四层

1. 连接层 ：确认 SQLite 连接加载了目标扩展，记录 spatialite_version()，并检查 HasLibXML2() 等编译能力。
2. 元数据层 ：检查 raster_coverages、触发器和样式表是否存在。
3. 栅格层 ：用 RL2_CreateRasterCoverage() 创建具体 Coverage，再用 RL2_LoadRaster() 导入真实影像；检查 Section、Tile 和 Tile BLOB 表是否出现、记录是否增长。
4. 地图层：注册 Raster Style 或 Map Configuration，调用地图输出函数，检查返回图像或客户端显示结果。

前两层只能证明基础设施存在；第三层才接近"栅格已经进入数据库"；第四层才是在验证"地图真的能输出"。

5.2 本文没有验证哪些内容

当前本地素材没有提供目标环境中的 RasterLite2 DLL、真实栅格文件、导入日志、像元查询结果或地图输出截图。因此本文不下这些结论：

• 某个 GeoTIFF 已经成功写入 SQLite。
• 某个 Coverage 已经可以在 QGIS 或其他客户端中显示。
• 某种压缩、金字塔或重采样配置已经在当前环境生效。
• RasterLite2 在某种数据规模下比 PostGIS Raster 更快。
• 某个函数在所有 SpatiaLite / RasterLite2 构建中都可用。

⚠️ 不要把目录表、函数返回值和概念图混成同一类证据

raster_coverages 存在，只能说明 Coverage 目录基础设施存在；RL2_CreateRasterCoverage() 成功，才说明具体 Coverage 结构创建成功；RL2_LoadRaster() 成功并产生 Section / Tile 数据，才说明外部栅格已经进入数据库；地图输出函数返回有效图像，才说明渲染链路至少跑通一次。

六、怎么判断它适不适合你的项目

场景	判断	原因
离线地图包、桌面 GIS、单机专题数据	值得评估	SQLite 单文件便于复制、交付和随应用部署；RasterLite2 还提供瓦片、压缩和金字塔能力
SpatiaLite 矢量 + RasterLite2 栅格统一放在一个文件	值得评估	同一 SQLite 文件可以同时管理矢量空间对象和 Raster Coverage
多人共享、持续写入、权限和服务化	谨慎	SQLite 的并发与权限模型仍然是文件数据库模型，不是 PostgreSQL 服务端模型
需要完整 Raster 分析、服务治理和成熟团队生态	对比 PostGIS Raster	两者的数据库模型、函数体系和服务化能力不同，不能只按"是否支持栅格"判断

一个更准确的结论是：RasterLite2 不只是把栅格元数据放进 SQLite，而是把栅格按 Coverage、Section、Tile 组织并存储在 SQLite 中，再提供压缩、金字塔、导入导出、样式和地图配置能力。 raster_coverages、Raster Style 和 RL2 Map Configuration 都很重要，但它们只是完整 RasterLite2 工作流中的不同层次。

参考资料

• RasterLite2 基本概念：Coverage、Section、Tile
• RasterLite2 SQL 函数参考
• SpatiaLite 5.1.0 SQL 函数参考
• GDAL RasterLite2 驱动说明
• SpatiaLite 官方项目页
• SpatiaLite Cookbook：Metadata
• SQLite RTree 官方文档
• PostGIS Raster