Plotly 3D 坐标轴完全指南：使用 plotly.py 的 scene 精确控制 3D 图表轴

Plotly 3D 坐标轴完全指南使用 plotly.py 的 scene 精确控制 3D 图表轴【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py本指南以 plotly.py 官方文档 doc/python/3d-axes.md 为骨架结合仓库源码深入讲解 3D 图的layout.scene坐标轴体系。3D 图表如Mesh3d、Surface、Scatter3d都通过layout.scene下的xaxis、yaxis、zaxis三个子属性完成范围、标题、刻度、配色与悬停 spike 的精细定制。读完本文你将掌握手动设置轴范围、单边 autorange5.17 新增、固定比例轴aspectmode、刻度格式化、背景网格配色及关闭工具提示指引线等全部实战技巧。一、3D 坐标轴的载体layout.scene与 2D 图表使用layout.xaxis、layout.yaxis不同Plotly 中所有 3D 图go.Scatter3d、go.Surface、go.Mesh3d、go.Volume、go.Cone等共享一个名为scene的布局容器。该容器位于layout.scene内部通过xaxis、yaxis、zaxis三个属性分别控制三个坐标轴的范围、标题、刻度、颜色、网格与 spike 行为。从源码生成的图对象定义可以确认这一点。在 plotly/graph_objs/layout/_scene.py 中Scene类的_valid_props包含xaxis、yaxis、zaxis、aspectmode、aspectratio、bgcolor、camera、domain、dragmode、hovermode、annotations、uirevision等属性其中xaxis/yaxis/zaxis分别是plotly.graph_objs.layout.scene.XAxis / YAxis / ZAxis类型的实例见 plotly/graph_objs/layout/_scene.py。这三个轴对象的属性集几乎完全一致例如 plotly/graph_objs/layout/scene/_xaxis.py 中XAxis的_valid_props就涵盖了range、autorange、nticks、tick0、ticktext、tickvals、tickfont、ticks、ticksuffix、tickwidth、showbackground、backgroundcolor、gridcolor、zerolinecolor、showspikes、title等完整能力。在实际代码中既可以用嵌套 dict 写法scene dict(xaxisdict(...))也可以使用更 Pythonic 的属性链写法fig.update_layout( scenedict( xaxisdict(range[-100, 100], nticks4), yaxisdict(range[-50, 100], nticks4), zaxisdict(range[-100, 100], nticks4), ) ) # 等价写法下划线链式 fig.update_layout(scene_xaxis_range[-100, 100], scene_xaxis_nticks4)plotly.py的update_layout支持用下划线把嵌套层级拼成扁平参数名如scene_xaxis_range这在批量修改多个轴时非常方便。二、手动设置轴范围Range3D 图的每个轴默认根据数据自动计算范围autorange。要手动控制只需在对应轴的 dict 中设置range为一个[下限, 上限]二元列表import plotly.graph_objects as go import numpy as np np.random.seed(1) N 70 fig go.Figure(data[go.Mesh3d(x(70*np.random.randn(N)), y(55*np.random.randn(N)), z(40*np.random.randn(N)), opacity0.5, colorrgba(244,22,100,0.6) )]) fig.update_layout( scene dict( xaxis dict(nticks4, range[-100,100],), yaxis dict(nticks4, range[-50,100],), zaxis dict(nticks4, range[-100,100],),), width700, margindict(r20, l10, b10, t10)) fig.show()关键点设置range后该轴的autorange会被自动置为False源码中 XAxis.autorange 的文档明确指出当range同时给出上下界时autorange自动为 False。三轴可分别设置不同范围例如上面把yaxis的上限收窄到 100、xaxis/zaxis保持[-100, 100]从而改变立方体空间的视觉比例。搭配nticks4可限制每个轴上的刻度数量上限nticks仅在tickmodeauto时生效实际刻度数会自动选取小于等于该值的整数见 plotly/graph_objs/layout/scene/_xaxis.py。width700与margin用于控制画布尺寸与留白适合在文档或 Notebook 中呈现 3D 场景。三、只设置单边边界5.17 新增从 plotly.py 5.17 开始range的任意一端都可以设为None此时该端自动回退到 autorange另一端保持手动指定。这样既能精确卡住某一侧例如数据下边界贴地又能让另一侧随数据自适应。import plotly.graph_objects as go import numpy as np np.random.seed(1) N 70 fig go.Figure(data[go.Mesh3d(x(70*np.random.randn(N)), y(55*np.random.randn(N)), z(40*np.random.randn(N)), opacity0.5, colorrgba(244,22,100,0.6) )]) fig.update_layout( scene dict( xaxis dict(nticks4, range[-100,100],), yaxis dict(nticks4, range[None, 100],), zaxis dict(nticks4, range[-100, None],),), width700, margindict(r20, l10, b10, t10)) fig.show()上例中yaxis的range[None, 100]下限交给 autorange上限锁死在 100zaxis的range[-100, None]下限锁死在 -100上限交给 autorangexaxis仍为完整的[-100, 100]。源码层面对这一行为的支撑体现在两处XAxis.range 的文档明确写道Leaving either or both elementsnullimpacts the defaultautorange将任一端置为 null 会影响默认 autorange 行为XAxis.autorange 支持min/max枚举值可以只在最小端或最大端应用 autorange语义与range[None, x]/range[x, None]一致两种写法可以互相印证。四、固定比例轴aspectmode 与 aspectratio默认情况下3D 场景会按数据范围自动适配盒子比例但这往往导致图形在某一维度被拉长或压扁。plotly.py通过scene的aspectmode属性提供四种比例模式其官方语义见 plotly/graph_objs/layout/_scene.py如下取值含义auto默认值。按data方式绘制但当某一个轴超过另外两轴的 4 倍大小时退化为cube以避免过度拉伸cube三个轴画成等长立方体忽略各轴范围差异data轴的绘制长度与其数据范围成比例manual轴的绘制长度与aspectratio指定的比例一致一旦设置了aspectratio就默认采用此模式aspectratio是scene下的一个独立子对象plotly.graph_objs.layout.scene.Aspectratio用x、y、z三个数字描述各轴的相对长度。下面的例子用make_subplots创建 2×2 的 3D 子图并为四个 scene 分别演示四种模式import plotly.graph_objects as go from plotly.subplots import make_subplots import numpy as np N 50 fig make_subplots(rows2, cols2, specs[[{is_3d: True}, {is_3d: True}], [{is_3d: True}, {is_3d: True}]], print_gridFalse) for i in [1,2]: for j in [1,2]: fig.add_trace( go.Mesh3d( x(60*np.random.randn(N)), y(25*np.random.randn(N)), z(40*np.random.randn(N)), opacity0.5, ), rowi, colj) fig.update_layout(width700, margindict(r10, l10, b10, t10)) # 左上角子图固定为立方体 fig.update_layout(scene_aspectmodecube) # 右上角子图手动指定比例让 z 轴显得比另外两轴大一倍 fig.update_layout(scene2_aspectmodemanual, scene2_aspectratiodict(x1, y1, z2)) # 左下角子图按各轴数据范围成比例绘制 fig.update_layout(scene3_aspectmodedata) # 右下角子图自动默认即 data 与 cube 的智能折中 fig.update_layout(scene4_aspectmodeauto) fig.show()要点解析多 3D 子图时scene 按序号命名第一个是scene之后是scene2、scene3、scene4对应make_subplots的 2×2 网格。update_layout中的scene2_aspectmode、scene2_aspectratio就是访问第二个 scene 的下划线链式写法。创建 3D 子图必须在specs中把对应格子标记为{is_3d: True}这是make_subplots将普通 2D 网格升级为 3D scene 的关键参见 plotly/subplots.py 中的网格规格处理。scene3_aspectmodedata适用于数据本身在三轴上量纲差异明显的场景如经纬度海拔scene_aspectmodecube适合需要各向同性的几何展示。五、设置坐标轴标题3D 轴的标题通过各轴的title.text设置。与 2D 轴不同3D 轴标题必须写成titledict(text...)的嵌套结构title本身是layout.scene.xaxis.title子对象完整写法如下import plotly.graph_objects as go import numpy as np # Define random surface N 50 fig go.Figure() fig.add_trace(go.Mesh3d(x(60*np.random.randn(N)), y(25*np.random.randn(N)), z(40*np.random.randn(N)), opacity0.5, coloryellow )) fig.add_trace(go.Mesh3d(x(70*np.random.randn(N)), y(55*np.random.randn(N)), z(30*np.random.randn(N)), opacity0.5, colorpink )) fig.update_layout(scene dict( xaxisdict( titledict( textX AXIS TITLE ) ), yaxisdict( titledict( textY AXIS TITLE ) ), zaxisdict( titledict( textZ AXIS TITLE ) ), ), width700, margindict(r20, b10, l10, t10)) fig.show()补充说明同一 scene 中允许多个 trace 共存上面叠加了两个半透明Mesh3d轴标题由layout.scene统一控制与 trace 数量无关。title子对象还支持font属性字号、颜色、字族可以在需要突出轴名时进一步定制上面的例子仅用到了最核心的text字段。若不想显示某轴标签可以把该轴的showaxeslabels设为False该布尔属性同样定义在 plotly/graph_objs/layout/scene/_xaxis.py 的_valid_props中。六、刻度格式化Ticks Formatting3D 轴继承了 2D 轴几乎所有刻度控制能力包括自定义刻度文本ticktexttickvals、最大刻度数nticks、刻度字体tickfont、刻度前后缀ticksuffix/tickprefix、刻度方向ticks、首刻度位置tick0与刻度线宽tickwidth。import plotly.graph_objects as go import numpy as np # Define random surface N 50 fig go.Figure(data[go.Mesh3d(x(60*np.random.randn(N)), y(25*np.random.randn(N)), z(40*np.random.randn(N)), opacity0.5, colorrgba(100,22,200,0.5) )]) # Different types of customized ticks fig.update_layout(scene dict( xaxis dict( ticktext [TICKS,MESH,PLOTLY,PYTHON], tickvals [0,50,75,-50]), yaxis dict( nticks5, tickfontdict( colorgreen, size12, familyOld Standard TT, serif,), ticksuffix#), zaxis dict( nticks4, ticksoutside, tick00, tickwidth4),), width700, margindict(r10, l10, b10, t10) ) fig.show()各属性行为对照源码说明属性作用源码依据ticktext/tickvals把指定位置tickvals显示为自定义文本ticktext二者等长配对使用可实现完全自定义刻度标签plotly/graph_objs/layout/scene/_xaxis.pynticks自动模式下刻度数的上限实际值 ≤ 该值plotly/graph_objs/layout/scene/_xaxis.pytickfont刻度文字的字族、字号、颜色_valid_props中的tickfontticksuffix在每个刻度后追加字符如#、%、°plotly/graph_objs/layout/scene/_xaxis.pyticks刻度线相对轴的位置outside/inside/_valid_props中的tickstick0第一个刻度出现的位置配合dtick使用plotly/graph_objs/layout/scene/_xaxis.pytickwidth刻度线的宽度像素plotly/graph_objs/layout/scene/_xaxis.py七、背景与网格颜色Background and Grid Color3D 场景中每个轴都对应一面墙axis wall。通过各轴的backgroundcolor可以分别给三面墙涂色配合gridcolor网格线颜色与zerolinecolor零线颜色即可定制出独特的三维空间配色。注意墙色要可见必须把该轴的showbackground设为True。import plotly.graph_objects as go import numpy as np N 50 fig go.Figure(data[go.Mesh3d(x(30*np.random.randn(N)), y(25*np.random.randn(N)), z(30*np.random.randn(N)), opacity0.5,)]) # xaxis.backgroundcolor is used to set background color fig.update_layout(scene dict( xaxis dict( backgroundcolorrgb(200, 200, 230), gridcolorwhite, showbackgroundTrue, zerolinecolorwhite,), yaxis dict( backgroundcolorrgb(230, 200,230), gridcolorwhite, showbackgroundTrue, zerolinecolorwhite), zaxis dict( backgroundcolorrgb(230, 230,200), gridcolorwhite, showbackgroundTrue, zerolinecolorwhite,),), width700, margindict( r10, l10, b10, t10) ) fig.show()实现细节三个轴各自独立着色x轴墙为偏蓝的rgb(200, 200, 230)y轴墙为偏紫的rgb(230, 200, 230)z轴墙为偏黄的rgb(230, 230, 200)网格线与零线统一为白色形成清晰的三维纸盒效果。backgroundcolor在 XAxis.backgroundcolor 中被定义为标准的颜色属性支持 hex、rgb/rgba、hsl、hwb、lab/lch/oklab/oklch 以及 CSS 命名色等全部 CSS 颜色格式。若想整体隐藏所有墙可以把各轴的showbackground设为False整个 scene 的背景色则由layout.scene.bgcolor控制见 plotly/graph_objs/layout/_scene.py。八、禁用工具提示 spikeDisabling Tooltip Spikes默认情况下把鼠标悬停在 3D 数据点上时Plotly 会从悬停点向三个轴的墙面上各画一条指引线spike帮助读取坐标。可以通过各轴的showspikes参数关闭这一行为例如只保留向x-y平面的投影即z轴的 spike同时关闭x、y轴的 spikeimport plotly.graph_objects as go import numpy as np N 50 fig go.Figure(data[go.Mesh3d(x(30*np.random.randn(N)), y(25*np.random.randn(N)), z(30*np.random.randn(N)), opacity0.5,)]) fig.update_layout(scenedict(xaxis_showspikesFalse, yaxis_showspikesFalse)) fig.show()源码语义showspikes的文档plotly/graph_objs/layout/scene/_xaxis.py指出它Sets whether or not spikes starting from data points to this axis wall are shown on hover——即控制从数据点向该轴墙面投射 spike 的开关。因此把xaxis_showspikes与yaxis_showspikes设为False只保留zaxis的 spike悬停时就只会看到数据点在x-y平面上的投影线这正是原文档注释中projection of the tooltip on the x-y plane的含义若想彻底关闭所有指引线把三个轴的showspikes全部设为False即可相关的配套属性还有spikecolor、spikethickness、spikesides可用于进一步定制 spike 的外观同见 plotly/graph_objs/layout/scene/_xaxis.py 的_valid_props。九、进阶场景级属性速查除三个轴之外layout.scene还提供了若干场景级控制项属性全集见 plotly/graph_objs/layout/_scene.pybgcolor整个 3D 场景的背景色camera相机视角包含eye、up、center等用于程序化设置观察角度对应 plotly/graph_objs/layout/scene/_camera.pyaspectmode/aspectratio第四节已详述控制场景盒子比例domainscene 在画布中的占位区域x、y的[0,1]区间dragmode拖拽交互模式枚举值为orbit、turntable、zoom、pan或False见 plotly/graph_objs/layout/_scene.pyhovermode悬停模式枚举值为closest或Falseuirevision控制用户对相机的操作旋转/缩放在fig.update后是否保持默认继承layout.uirevisionannotations3D 场景内的注解对象列表。十、结语把 3D 轴调教成你想要的形态通过layout.scene的xaxis/yaxis/zaxisplotly.py 为 3D 图表提供了与 2D 同样丰富、甚至更精细的坐标轴控制能力从最基础的range手动定界、5.17 引入的单边None自动边界到aspectmode的四种盒子比例策略、ticktext/tickvals的自由刻度标签、三面墙的独立配色再到showspikes对悬停指引线的开关每一类需求都有对应的属性与源码级的明确语义。读者可以基于本仓库的 plotly/graph_objs/layout/_scene.py 与 plotly/graph_objs/layout/scene/_xaxis.py 继续探索其余属性或参考仓库中的 3D 相关教程文档如 doc/python/3d-scatter-plots.md、doc/python/3d-surface-plots.md、doc/python/3d-mesh.md组合出完整的 3D 可视化方案。【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考