
Bokeh 3.6.2 补丁版解析ScaleBar 定位回归修复、多瓦片渲染器恢复与 Circle/Scatter 拆分后续【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokehBokeh 3.6.22024 年 12 月发布是 Bokeh 3.6 系列的一个补丁版本主要针对 3.6.0 引入的一批回归问题regressions与文档问题进行了定点修复。本文基于 docs/bokeh/source/docs/releases/3.6.2.rst 的变更清单逐一拆解每一项修复背后的代码实体——包括ScaleBar的定位机制、瓦片渲染器tile renderer的数据结构、Circle/Scatter字形拆分后的属性变化——并结合仓库源码与示例给出可落地的验证与使用建议。读完本文你将理解 3.6.2 每个补丁的来龙去脉并能据此排查升级后遇到的同类问题。一、版本背景一次以“回归修复”为核心的补丁发布补丁版本patch release的职责是修复主版本中引入的 bug、回归和文档问题而不引入新特性。3.6.2 的发布说明docs/bokeh/source/docs/releases/3.6.2.rst明确列出了 5 项变更其中 4 项是代码修复、1 项是外部链接维护变更类型关联 PR修复ScaleBar定位回归功能回归#14154恢复添加多个瓦片渲染器的能力功能回归#14170修复文档搜索框文档/构建问题#14161修复Circle/Scatter字形拆分后的回归功能回归#14085、#14089更新赞助页面链接维护#14086值得注意的是其中三项回归ScaleBar 定位、多瓦片渲染器、Circle/Scatter 拆分都与 3.6 系列对注记annotations和字形glyphs体系的内部重构直接相关。理解这些修复本质上是理解这些重构后的新数据模型。二、ScaleBar 定位回归修复#141542.1 回归发生的位置定位属性体系ScaleBar是 Bokeh 3.5 引入的注记模型用于在图中渲染比例尺。在 3.6.x 中其定位逻辑经过重构引入了location、x_units、y_units、anchor四个相互协作的属性定位回归正发生在这套新体系中。从源码 src/bokeh/models/annotations/legends.py 可以看到ScaleBar的定位相关属性定义locationPosition类型默认top_right表示比例尺在父容器通常是笛卡尔坐标系框架 cartesian frame内的位置x_units/y_unitsPositionUnits类型默认data决定position属性中 x、y 坐标值的解释方式数据空间还是屏幕空间anchorAutoAnchor类型默认auto作为比例尺定位的原点当任一或两个维度为auto时会根据position自动确定该维度的锚点使比例尺在视觉上位置合理。3.6.2 的 #14154 修复的正是这套属性组合在某些取值下出现的定位错乱。从修复意图看用户应当保持anchorauto的默认行为以获得自动纠正除非确实需要手工锚定。2.2 定位修复相关的核心参数ScaleBar的location参数决定了比例尺出现在绘图区域的哪个方位可选值与Legend一致常见取值包括top_left、top_right、bottom_left、bottom_right等Position类型继承自bokeh.core.enums.Anchor。默认值top_right在仓库单元测试中有明确断言assert scale_bar.location top_right该断言位于 tests/unit/bokeh/models/test_annotations.py 的test_ScaleBar中同时被验证的还有range默认auto、anchor默认auto、orientation默认horizontal、bar_length默认0.2等一整套默认值。如果你在升级后遇到比例尺位置异常可以先检查是否显式设置了anchor或x_units/y_units导致与默认自动定位冲突。2.3 一个完整的 ScaleBar 使用示例仓库示例 examples/basic/annotations/scale_bar_image.py 展示了在图像上叠加比例尺的完整做法其中定位相关参数与 3.6.2 修复的属性一一对应from pathlib import Path from bokeh.io import show from bokeh.models import MetricLength, ScaleBar from bokeh.plotting import figure TOOLS pan,wheel_zoom,box_zoom,reset,save,box_select p figure( titleScale bar on an image, toolsTOOLS, active_scrollwheel_zoom, ) p.x_range.range_padding 0 p.y_range.range_padding 0 p.x_range.bounds (0, 1) p.y_range.bounds (0, 1) pollen_png Path(__file__).parent / assets / pollen.png img pollen_png.read_bytes() p.image_url(x0, y0, w1, h1, url[img], anchorbottom_left) scale_bar ScaleBar( rangep.x_range, unitmm, dimensionalMetricLength(), orientationhorizontal, locationtop_right, label{value} {unit}, label_locationabove, label_aligncenter, bar_length0.2, bar_line_width2, background_fill_alpha0.8, ) p.add_layout(scale_bar) show(p)要点解读rangep.x_range将比例尺绑定到 x 轴数据范围也可设auto自动选择与orientation匹配的默认范围unitmm指定计量单位dimensionalMetricLength()声明这是公制长度量纲locationtop_right即本补丁修复所涉及的定位属性label{value} {unit}是标签模板支持{value}当前刻度值可带格式化器如{value}{%.2f}与{unit}计量单位两个特殊变量。三、多瓦片渲染器能力恢复#141703.1 问题本质同一数据源的渲染器归属#14170 恢复的是“在一张图上添加多个瓦片渲染器”的能力。要理解这个回归需要看瓦片体系的数据模型。瓦片渲染器TileRenderer定义在 src/bokeh/models/renderers/tile_renderer.py其核心属性是tile_source一个TileSource实例以及alpha瓦片透明度 0.0–1.0默认 1.0、smoothing是否对渲染瓦片做图像平滑默认True、render_parents等待新瓦片到达期间是否绘制父级瓦片默认True。瓦片数据源体系定义在 src/bokeh/models/tiles.pyTileSource基类定义url瓦片服务地址模板如http://c.tile.openstreetmap.org/{Z}/{X}/{Y}.png、tile_size瓦片像素尺寸默认 256、min_zoom/max_zoom缩放层级范围默认 0–30、attribution数据提供方署名可含 HTML等MercatorTileSource墨卡托投影瓦片基类预置x_origin_offset/y_origin_offset默认 20037508.34与initial_resolution并新增snap_to_zoom初始范围吸附到最近的更大缩放级、wrap_around水平方向连续平移环绕默认TrueTMSTileSource瓦片原点在左下角WMTSTileSource瓦片原点在左上角是 Web 地图应用中最常用的类型Google、MapQuest、Esri、OpenStreetMap 等均采用 WMTS 规范也是TileRenderer.tile_source的默认值QUADKEYTileSource使用{Q}quadkey 参数请求瓦片BBoxTileSource使用{XMIN},{YMIN},{XMAX},{YMAX}包围盒参数请求瓦片use_latlon控制输出米制还是经纬度。3.6 系列早期版本在数据源归属逻辑上存在回归导致第二个瓦片渲染器无法正常渲染#14170 修复了这一问题。从数据模型看每个TileRenderer持有独立的tile_source实例多个渲染器共用同一数据源是被允许的因此叠加多层瓦片如底图 标签层、底图 自定义覆盖层现在可以正常工作了。3.2 多瓦片渲染器与 add_tile 的使用日常使用中通常通过figure.add_tile便捷方法添加瓦片仓库示例 examples/topics/geo/tile_source.py 展示了最简用法from bokeh.plotting import figure, show # range bounds supplied in web mercator coordinates p figure(x_range(-2000000, 2000000), y_range(1000000, 7000000), x_axis_typemercator, y_axis_typemercator) p.add_tile(CartoDB Positron, retinaTrue) show(p)add_tile内部会创建TileRenderer实例并将其加入图的渲染器列表retinaTrue对应TileSource.pixel_ratio默认为 1.0设置为 2 表示2x高清瓦片系统会据此选择缩放级别使瓦片以自然尺寸显示。在 3.6.2 中你可以在同一个figure上连续调用多次add_tile或手工构造多个TileRenderer后p.add_layout/p.renderers.extend叠加不同服务商或不同层级的瓦片图层。更完整的瓦片演示可参考 examples/topics/geo/tile_demo.py 与 examples/topics/geo/tile_xyzservices.py。四、Circle 与 Scatter 字形拆分后的回归修复#14085、#140894.1 拆分的背景在 Bokeh 3.6 中Circle与Scatter两个字形被正式拆分为独立的模型Circle专注于径向字形radius-basedScatter专注于点标记marker-based。源码 src/bokeh/models/glyphs.py 中Circle 继承自RadialGlyph, LineGlyph, FillGlyph, HatchGlyph保留线、填充、阴影属性Scatter 继承自Marker支持marker属性指定标记形状。这种拆分让语义更清晰但也必然带来一批“拆分后遗症”原本Circle上可用的某些属性、Scatter的默认行为、以及两者在figure.circle()/figure.scatter()工厂方法中的参数转发都可能出现回归。3.6.2 通过 #14085 与 #14089 两个 PR 修复了这批问题。4.2 升级与排查建议如果你的代码使用figure.circle(...)绘制散点3.6.2 后应继续正常工作若升级 3.6.0/3.6.1 时遇到圆形或散点样式异常建议直接升级到 3.6.2需要绘制多种标记形状的散点图时优先使用Scatter并显式指定marker属性如circle、square、triangle需要真正的“半径驱动”圆如按数据半径缩放、或搭配SizeBar展示径向大小时使用Circle。SizeBar与Circle的搭配是 3.6 新特性之一其renderer属性接受GlyphRendererOf(RadialGlyph)或auto——当图中只有一个径向字形渲染器时可自动匹配多个时需显式指定参见 src/bokeh/models/annotations/legends.py。五、配套修复文档搜索框与赞助页链接#14161、#14086除了代码回归3.6.2 还包含两项非功能性修复文档搜索框修复#14161修复了官方文档站内搜索框失效的问题属于文档基础设施修复不影响运行时 API赞助页链接更新#14086更新了文档中指向赞助页面的链接属于链接维护。这两项修复不影响库的行为但对文档使用者体验有直接帮助也再次印证 3.6.2 是一次以“稳”为目标的补丁发布。六、验证与升级建议6.1 用单元测试验证默认行为仓库的注解模型单元测试 tests/unit/bokeh/models/test_annotations.py 覆盖了ScaleBar的完整属性面test_ScaleBar第 255 行逐一断言默认值test_ScaleBar_dimensional第 311 行验证自定义量纲——例如用Metric(base_uniteV)定义电子伏特量纲、用CustomDimensional手工定义角度量纲°/′/″并通过is_known()校验单位合法性。这组测试可以作为升级后回归自检的参考清单。6.2 ScaleBar 的量纲模型速查ScaleBar.dimensional属性接受Dimensional子类定义于 src/bokeh/models/annotations/dimensional.py内置模型包括模型说明关键默认值MetricLength公制长度基单位m排除dm、hm刻度[1, 2, 5, 10, 15, 20, 25, 50, 75, 100, ...]ImperialLength英制长度in/ft/yd/ch/fur/mi/lea刻度[1, 3, 6, 12, 60]Metric通用公制量纲可自定义base_unit如eV支持完整 SI 词头k、M、G、m、µ、n 等Angular角度量纲°/′/″刻度[1, 3, 6, 12, 60, 120, 240, 360]CustomDimensional手工定义basis映射短单位名 → 缩放因子、TeX 名、长名需自行提供ticks注意ScaleBar.unit必须能被dimensional.is_known(unit)识别否则会触发NON_MATCHING_SCALE_BAR_UNIT校验错误见 src/bokeh/models/annotations/legends.py。6.3 升级路径总结当前处于 3.6.0 或 3.6.1、且使用ScaleBar、瓦片底图或Circle/Scatter的用户应尽快升级到 3.6.2升级后如仍遇到比例尺错位请检查location/anchor/x_units/y_units四属性的组合是否合理优先保留anchorauto多图层叠加场景地图底图 标注层在 3.6.2 中已恢复正常可用多个TileRenderer共享或独立TileSource实现。结语Bokeh 3.6.2 规模虽小却精准地补上了 3.6 主版本因内部重构而留下的三块关键短板ScaleBar的定位体系、瓦片渲染器的多实例支持、以及Circle/Scatter拆分后的属性回归。对于库的维护者它是理解 3.6 数据模型重构的“修复注脚”对于使用者它是升级路径上值得停留的稳定节点。结合 3.6.2 发布说明、ScaleBar 源码、瓦片体系源码 与仓库内示例即可对本次补丁的影响面做到心中有数。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考