PyDeck支持3D图层吗?参数设置在哪里?

wowwwai GIS研习社 · 工具流程与项目排障

很多做 Python 可视化和 WebGIS 原型的同学会问：PyDeck支持3D图层吗?参数设置在哪里? 答案是支持，但它不是通过一个单独的“开启 3D”按钮完成，而是由图层类型、字段映射、视角参数和渲染参数共同决定。

引言：PyDeck支持3D图层吗

PyDeck 是 deck.gl 的 Python 封装，常用于在 Jupyter Notebook、Streamlit 或 HTML 页面中制作交互式地图。它可以显示二维点、线、面，也可以显示柱状图、三维建筑、三维路径、点云等 3D 图层。

对 GIS 用户来说，最常见的 PyDeck 3D 场景包括：

• 把面数据拉伸成 3D 柱状图，例如人口、房价、POI 密度。
• 显示三维建筑轮廓，例如基于建筑高度字段做城市建模。
• 显示飞线、轨迹和路径，例如物流、航线、车辆轨迹。
• 显示点云或大规模散点，例如 LiDAR 抽样点、城市事件点。

所以，问题的关键不是“PyDeck 能不能做 3D”，而是你选择的图层是否支持 3D 参数，以及这些参数应该写在 Layer、ViewState 还是 Deck 配置里。

背景：为什么设置了 PyDeck 图层却看不到 3D 效果

很多初学者在 PyDeck 中写了地图图层，但结果仍然像普通二维地图。常见原因有四类：

• 图层不支持拉伸或高度：例如普通 ScatterplotLayer 主要显示点符号，不会自动变成三维建筑。
• 没有设置 3D 参数：PolygonLayer 需要设置 extruded=True，并用 get_elevation 指定高度来源。
• 视角仍是俯视：如果 pitch 为 0，即使图层有高度，也很难看出 3D 效果。
• 字段或坐标格式错误：高度字段为空、经纬度字段顺序错误、几何坐标不是 WGS84，都可能导致显示异常。

PyDeck 的 3D 图层参数设置主要分布在三个位置：Layer 图层参数、ViewState 视角参数、Deck 全局输出参数。理解这三层配置，是排查问题的第一步。

原理：PyDeck 3D图层参数设置在哪里

PyDeck 的核心对象通常由三部分组成：

• pydeck.Layer：决定画什么，例如点、线、面、柱状图、路径、三维建筑。
• pydeck.ViewState：决定从哪里看地图，例如中心点、缩放级别、倾斜角和旋转角。
• pydeck.Deck：决定如何组合图层、底图、提示框和输出。

如果要做 PyDeck 3D 图层，最重要的参数通常在 Layer 中。例如 PolygonLayer 的 extruded、get_elevation、elevation_scale，ColumnLayer 的 get_elevation、radius，ArcLayer 的 get_source_position、get_target_position 等。

但图层有了高度还不够。要明显看到立体效果，还需要在 ViewState 中设置 pitch，通常可设为 40 到 60。bearing 用于旋转地图方向，能增强三维观察效果。

步骤：用 PyDeck 做一个可见的 3D 柱状图层

下面用一个最小示例说明 PyDeck 3D图层参数设置在哪里。这个例子使用 ColumnLayer，根据点位和数值字段生成 3D 柱状图，适合展示 POI 数量、网格统计值、人口密度等空间统计结果。

步骤一：准备数据字段

PyDeck 的数据通常可以来自 Pandas DataFrame。3D 柱状图至少需要经度、纬度和高度值字段。

import pandas as pd
import pydeck as pdk

data = pd.DataFrame({
    "name": ["A区", "B区", "C区"],
    "lon": [116.38, 116.40, 116.42],
    "lat": [39.90, 39.91, 39.89],
    "value": [120, 260, 180]
})

这里的 lon 和 lat 是 WGS84 经纬度坐标，value 用来控制柱体高度。

步骤二：在 Layer 中设置 3D 图层参数

ColumnLayer 是 PyDeck 中很适合做 3D 柱状图的图层。关键参数如下：

• get_position：指定每个柱子的经纬度位置。
• get_elevation：指定柱体高度字段。
• elevation_scale：放大或缩小高度效果。
• radius：柱子半径，单位通常按米理解。
• get_fill_color：设置柱体颜色。
• pickable：允许鼠标悬停识别要素。

layer = pdk.Layer(
    "ColumnLayer",
    data,
    get_position="[lon, lat]",
    get_elevation="value",
    elevation_scale=20,
    radius=300,
    get_fill_color="[255, 140, 0, 180]",
    pickable=True,
    auto_highlight=True
)

如果你问“PyDeck 3D图层参数设置在哪里”，对于这个例子，答案就是主要写在 pdk.Layer() 里。高度、颜色、半径和交互能力都属于图层参数。

步骤三：在 ViewState 中设置倾斜视角

如果不设置 pitch，地图默认接近俯视，柱子看起来可能不明显。因此需要设置一个倾斜视角。

view_state = pdk.ViewState(
    longitude=116.40,
    latitude=39.90,
    zoom=11,
    pitch=50,
    bearing=20
)

pitch=50 表示地图向三维视角倾斜。bearing=20 表示地图方向旋转 20 度，有助于观察柱体侧面。

步骤四：组合 Deck 并输出

最后把图层和视角放入 pdk.Deck() 中。

deck = pdk.Deck(
    layers=[layer],
    initial_view_state=view_state,
    tooltip={"text": "{name}n数值：{value}"},
    map_style="light"
)

deck.to_html("pydeck_3d_column.html")

运行后会生成一个 HTML 文件。打开后应该能看到倾斜视角下的三维柱状图，并且鼠标悬停时会显示名称和数值。

步骤：用 PolygonLayer 拉伸面数据为 3D 建筑

如果你的数据是建筑面、行政区面或网格面，常用的是 PolygonLayer。它的关键在于 extruded=True 和 get_elevation。

import pydeck as pdk
import pandas as pd

buildings = pd.DataFrame({
    "name": ["building_1"],
    "height": [80],
    "polygon": [[
        [116.397, 39.908],
        [116.398, 39.908],
        [116.398, 39.909],
        [116.397, 39.909],
        [116.397, 39.908]
    ]]
})

polygon_layer = pdk.Layer(
    "PolygonLayer",
    buildings,
    get_polygon="polygon",
    get_elevation="height",
    elevation_scale=1,
    extruded=True,
    get_fill_color="[80, 160, 255, 180]",
    get_line_color="[255, 255, 255]",
    pickable=True,
    auto_highlight=True
)

view_state = pdk.ViewState(
    longitude=116.3975,
    latitude=39.9085,
    zoom=16,
    pitch=55,
    bearing=30
)

deck = pdk.Deck(
    layers=[polygon_layer],
    initial_view_state=view_state,
    tooltip={"text": "{name}n高度：{height} m"},
    map_style="light"
)

deck.to_html("pydeck_3d_building.html")

这里的 extruded=True 是让面要素被拉伸成立体体块的关键参数。如果没有这个参数，即使设置了 get_elevation，也可能仍然显示为二维面。

常见坑：PyDeck 3D图层不显示或看起来不立体

1. 只设置了高度字段，没有设置 extruded

在 PolygonLayer 中，get_elevation 只是指定高度来源，extruded=True 才是启用面拉伸的关键。

pdk.Layer(
    "PolygonLayer",
    data,
    get_polygon="polygon",
    get_elevation="height",
    extruded=True
)

2. pitch 太小，看不出 3D

如果 pitch=0，地图是俯视状态。建议先用 pitch=45 或 pitch=55 测试。

3. 高度值太小，需要 elevation_scale

有些字段数值只有 1、2、3，直接作为高度时几乎看不出来。可以用 elevation_scale 放大视觉效果。

get_elevation="value",
elevation_scale=100

注意，elevation_scale 是视觉放大，不应替代真实数据单位说明。正式制图时要在图例或说明中注明。

4. 经纬度顺序写反

PyDeck 和 deck.gl 通常使用 [longitude, latitude]，也就是经度在前、纬度在后。很多 GIS 数据处理库中也会这样表示坐标，但手工写数据时很容易写反。

get_position="[lon, lat]"

如果点跑到海里、国外或地图空白区域，优先检查经纬度顺序和坐标系。

5. 数据不是 WGS84 经纬度

PyDeck 常用于 Web 地图场景，输入坐标通常应为 WGS84 经纬度。如果你的数据来自投影坐标系，例如 CGCS2000 高斯投影、UTM 或地方坐标，需要先转换为经纬度。

如果数据来自 GeoPandas，可以检查并转换坐标系：

gdf = gdf.to_crs(epsg=4326)

6. 字段名写错或字段为空

get_elevation="height" 要求数据中确实存在 height 字段。如果字段名大小写不一致、存在空值或字符串格式不规范，都会影响 3D 显示。

方法比较：不同 PyDeck 3D 图层怎么选

如果你只是想把统计值立起来，优先选 ColumnLayer。如果你有建筑轮廓或行政区面，优先选 PolygonLayer。如果你想表达两个地点之间的空间联系，可以考虑 ArcLayer。

检查清单：排查 PyDeck 3D 图层参数问题

当 PyDeck 3D 图层没有达到预期效果时，可以按下面顺序检查：

• 图层类型是否支持当前 3D 表达方式。
• Layer 中是否设置了高度相关参数，例如 get_elevation。
• 面图层是否设置了 extruded=True。
• ViewState 中是否设置了 pitch。
• 高度字段是否存在、是否为数值、是否有空值。
• 经纬度顺序是否为 [lon, lat]。
• 坐标系是否为 WGS84 经纬度。
• elevation_scale 是否过小或过大。
• 浏览器是否支持 WebGL，显卡加速是否正常。
• 数据量是否过大，是否需要抽稀、聚合或切片。

一个实用判断方法：先用 3 条测试数据做最小示例。如果最小示例能显示 3D，再替换为真实数据。这样可以快速区分是代码参数问题，还是数据质量问题。

FAQ：PyDeck支持3D图层吗常见问题

PyDeck支持3D图层吗？

支持。PyDeck 可以使用 deck.gl 的多种图层能力，常见 3D 图层包括 ColumnLayer、PolygonLayer、ArcLayer、PathLayer 和 PointCloudLayer。不同图层的 3D 参数不同，需要按图层类型设置。

PyDeck 3D图层参数设置在哪里？

主要在 pdk.Layer() 中设置，例如 get_elevation、extruded、elevation_scale、radius。视角相关参数在 pdk.ViewState() 中设置，例如 pitch、bearing、zoom。

为什么设置了 get_elevation 还是没有 3D 效果？

如果使用的是 PolygonLayer，除了 get_elevation，还要设置 extruded=True。另外还要检查 pitch 是否大于 0，高度字段是否有效，elevation_scale 是否太小。

PyDeck 的 3D 高度单位是什么？

通常可以按米来理解，但实际显示效果还会受到图层类型、坐标系统、缩放级别和 elevation_scale 影响。做专题图时建议明确说明高度字段含义和缩放比例。

PyDeck 可以直接读取 Shapefile 做 3D 吗？

PyDeck 本身更常接收 Pandas DataFrame 或 JSON 风格数据。Shapefile 通常先用 GeoPandas 读取，再转换坐标系和几何字段，最后整理成 PyDeck 可用的坐标数组或 GeoJSON 数据。

PyDeck 3D 图层适合生产级 WebGIS 吗？

PyDeck 很适合数据分析、原型验证、Notebook 展示和轻量 Web 可视化。如果是大规模生产级 WebGIS，通常还要考虑瓦片化、服务端切片、前端框架集成、权限控制和性能优化。

结论：PyDeck 3D效果由图层参数和视角参数共同决定

回到标题问题，PyDeck支持3D图层吗?参数设置在哪里? PyDeck 支持 3D 图层，但参数不是集中在一个地方。图层是否三维，主要由 Layer 中的图层类型和高度参数决定；三维效果是否明显，则由 ViewState 中的 pitch、bearing 和 zoom 决定。

实际使用时，建议先用 ColumnLayer 或 PolygonLayer 做最小示例，确认 get_elevation、extruded、elevation_scale 和 pitch 生效后，再接入真实 GIS 数据。这样最容易定位 PyDeck 3D图层参数设置问题，也能避免把坐标系、字段质量和渲染参数混在一起排查。