全部文章内容请转公众号【时空智能计算】及交流群867520770，原创不易，求关注支持，更多开源GIS相关知识技能分享，免费提供学习问答交流。
一、函数概述
ST_PixelAsPolygons主要实现栅格转转矢量数据，核心特点是能将栅格的每个像素转换为对应的地理多边形（像素的空间边界），并返回该像素的列坐标（x）、行坐标（y）和像素值（val），是栅格数据矢量化、像素级空间分析的基础工具，可对比【ST_DumpAsPolygons】函数。
二、参数解析
1. 函数语法
setof record ST_PixelAsPolygons(
raster rast, — 输入栅格对象
integer band = 1, — 待转换的波段号，默认1（从1开始索引）
boolean exclude_nodata_value = TRUE — 是否排除NODATA值的像素，默认TRUE
);
2. 返回值结构
函数返回记录集合（setof record），每条记录对应栅格的一个像素，包含 4 个字段：
| geom | geometry | 该像素的地理边界多边形（与栅格的空间参考、像素大小完全匹配） |
| val | double precision | 该像素的数值（NODATA 值会返回 NULL，若exclude_nodata_value=TRUE则不返回该像素） |
| x | integer | 像素的列坐标（1 基索引，从左到右计数） |
| y | integer | 像素的行坐标（1 基索引，从上到下计数） |
三、核心特性
1. 逐像素返回，无合并
-
这是该函数最核心的特点：栅格有多少个有效像素，就返回多少个多边形，每个多边形严格对应一个像素的空间范围。
-
区别于ST_DumpAsPolygons：后者会将连续且值相同的像素合并为一个多边形，而ST_PixelAsPolygons始终逐像素返回，适合需要像素级精细分析的场景。
2. NODATA 值的灵活处理
- exclude_nodata_value = TRUE（默认）：仅返回非 NODATA 值的像素，NODATA 像素直接过滤，不生成记录；
- exclude_nodata_value = FALSE：返回所有像素（包括 NODATA），此时 NODATA 像素的val字段为 NULL，geom字段仍为像素多边形。
3. 像素多边形的地理坐标规则
像素多边形的边界由栅格的元数据（原点、像素大小、旋转参数）决定：
- 栅格原点（通常为左上角）是第一个像素（x=1,y=1）的角点；
- 像素大小（ST_PixelWidth/ST_PixelHeight）决定多边形的宽和高；
- 若栅格有旋转参数，多边形也会同步旋转，始终匹配像素的实际地理范围。
四、与 ST_DumpAsPolygons 区别
| 返回粒度 | 逐像素，1 像素 = 1 多边形 | 合并同值连续像素，多像素 = 1 多边形 |
| 适用场景 | 像素级精细分析（如单像素值查询、像素边界提取） | 区域级分析（如相同值的连片区域识别、栅格分区） |
| 返回字段 | geom, val, x, y | geom, val |
| 效率 | 数据量大（像素数 = 记录数），效率较低 | 数据量小（合并后记录数少），效率较高 |
五、典型应用
1. 像素级空间查询
查询指定地理坐标对应的栅格像素值、列行坐标：
— 查找点(0.002, 0)所在的像素信息
SELECT (gv).x, (gv).y, (gv).val
FROM (SELECT ST_PixelAsPolygons(rast) gv FROM raster_table) foo
WHERE ST_Intersects((gv).geom, ST_SetSRID(ST_MakePoint(0.002, 0), 4269));
2. 栅格像素的矢量导出
将栅格转换为矢量多边形要素，导出为 Shapefile/GeoJSON 等格式，用于 GIS 软件分析：
— 将栅格转换为矢量表
CREATE TABLE raster_as_polygons AS
SELECT
(gv).geom,
(gv).val AS pixel_value,
(gv).x AS pixel_col,
(gv).y AS pixel_row
FROM (SELECT ST_PixelAsPolygons(rast, 1, FALSE) gv FROM raster_table) foo;
— 添加空间索引，提升查询效率
CREATE INDEX idx_raster_polygons_geom ON raster_as_polygons USING GIST (geom);
3. 像素值的空间统计
统计指定区域内的像素值分布（如高程栅格的海拔统计、遥感影像的 NDVI 值统计）：
— 统计研究区内像素值的最大值、最小值、平均值
WITH study_area AS (
SELECT ST_SetSRID(ST_MakePolygon(ST_MakeLine(ARRAY[
ST_MakePoint(0, 0), ST_MakePoint(0.004, 0), ST_MakePoint(0.004, –0.002), ST_MakePoint(0, –0.002), ST_MakePoint(0, 0)
])), 4269) AS geom
),
pixel_polygons AS (
SELECT (gv).val
FROM (SELECT ST_PixelAsPolygons(rast) gv FROM raster_table) foo
JOIN study_area sa ON ST_Intersects((gv).geom, sa.geom)
)
SELECT
MAX(val) AS max_val,
MIN(val) AS min_val,
AVG(val) AS avg_val
FROM pixel_polygons;
六、注意事项
索引规则：像素的 x（列）、y（行）均为 1 基索引，栅格左上角第一个像素是 (x=1,y=1)，避免与 0 基索引混淆；
性能优化：
- 对大栅格，先通过ST_Crop裁剪研究区，再调用该函数，减少返回的像素数量；
- 为结果表创建空间索引（如上述示例），提升后续空间查询效率；
NODATA 值匹配：exclude_nodata_value过滤的是栅格波段的官方 NODATA 值（如波段设置的 NODATA=0），而非 NULL，若需过滤 NULL 值，需额外加WHERE val IS NOT NULL；
多波段处理：默认处理波段 1，若需处理多波段，需为每个波段单独调用函数，或通过UNION ALL合并结果；
空间参考一致性：返回的多边形与输入栅格的空间参考（SRID）完全一致，无需额外转换。
七、总结
ST_PixelAsPolygons是栅格像素级矢量化的核心工具，核心要点可归纳为 3 点：
该函数是栅格数据与矢量数据联动分析的桥梁，常用于像素值查询、栅格矢量化导出、像素级空间统计等场景，是 PostGIS 栅格处理的高频函数。
