Newton 中的 ViewerRTX 实时可视化：log_scalar() 标量时序图与 log_array() 数组热力图完全指南

Newton 中的 ViewerRTX 实时可视化log_scalar() 标量时序图与 log_array() 数组热力图完全指南【免费下载链接】newtonAn open-source, GPU-accelerated physics simulation engine built upon NVIDIA Warp, specifically targeting roboticists and simulation researchers.项目地址: https://gitcode.com/GitHub_Trending/newton9/newton导读本文聚焦 Newton基于 NVIDIA Warp 的 GPU 加速物理仿真引擎在 changelog 4046 中引入的一项可视化能力为ViewerRTXOVRTX 实时光线追踪查看器新增实时标量曲线图与数组热力图通过log_scalar()与log_array()两个 API 暴露并支持可配置的绘图历史长度plot history与标量平滑scalar smoothing。读完本文你将掌握如何在物理仿真循环中实时监控求解器迭代数、能量守恒、接触约束数量等诊断指标以及如何将任意数值数组渲染为带 inferno 色标的热力图并理解其底层缓冲、平滑与纹理上传的实现原理。功能概述一行 changelog 背后的完整能力changelog/4046.added.md 对这一特性只有一句话描述Add live scalar plots and array heatmaps toViewerRTXthroughlog_scalar()andlog_array(), with configurable plot history and scalar smoothing.这句话涵盖了四个关键能力点实时标量图live scalar plots将每帧产生的单个数值如能量、迭代次数绘制为随时间滚动的折线图数组热力图array heatmaps将标量、一维、二维数值数组渲染为彩色热力图网格可配置绘图历史configurable plot history通过构造参数控制每个信号保留的历史样本数标量平滑scalar smoothing对原始采样做滑动平均抑制噪声抖动。虽然 changelog 只提及ViewerRTX但该功能实际由独立的PlotLogger类实现ViewerGL与ViewerRTX两个交互式后端均复用了它见 plot_logger.py 类注释Store and draw live scalar plots and array heatmaps for GL and RTX viewers。两个 Viewer 在构造函数中共享同名的plot_history_size关键字参数从而保证 API 一致。快速上手在仿真循环中监控标量指标log_scalar()是监控仿真运行状况最直接的手段。它的完整签名定义在 viewer.py 的抽象基类中ViewerRTX在 viewer_rtx.py 中实现def log_scalar( self, name: str, value: int | float | bool | np.number, *, clear: bool False, smoothing: int 1, ):参数语义如下参数类型默认值说明namestr必填信号的唯一路径/名称每个唯一name会生成一条独立的折线显示在自动创建的 Plots 浮动窗口中valueint / float / bool / np.number必填要记录的标量值clearboolFalse若为True在记录新值前丢弃该name此前积累的全部样本smoothingint1每smoothing个原始采样取一次平均后再提交到绘图历史1表示不平滑仓库自带的 example_basic_plotting.py 给出了最典型的用法——在每帧结束后把求解器诊断数据喂给 viewerdef step(self): if self.graph: wp.capture_launch(self.graph) else: self.simulate() self.sim_time self.frame_dt self._read_status() # Raw per-frame values so the overlay matches the latest plot point and side panel. self.viewer.log_scalar(Solver Iterations (max), self.log_iterations[-1]) self.viewer.log_scalar(Kinetic Energy [J], self.log_energy_kinetic[-1]) self.viewer.log_scalar(Potential Energy [J], self.log_energy_potential[-1]) self.viewer.log_scalar(Active Constraints, self.log_nefc[-1])该示例加载一个受重力下落并与地面碰撞的 humanoid 模型逐帧读取 MuJoCo 求解器的solver_niter迭代次数、energy动能/势能与nefc激活约束行数等指标见 example_basic_plotting.py并通过四个log_scalar调用实时呈现。运行方式python -m newton.examples basic_plotting --world-count 4平滑与清空的底层行为从PlotLogger.log_scalar的实现plot_logger.py可以看到三个值得注意的细节滚动缓冲每个信号的数据存放在collections.deque(maxlenself._plot_history_size)中超出历史长度后最旧样本自动被挤出因此曲线始终展示最近plot_history_size个样本平滑的取整语义smoothing 1时原始值先进入_scalar_accumulators累积器攒满smoothing个后才把平均值sum(acc) / len(acc)提交到历史缓冲。这意味着平滑后的曲线点数会比原始采样数少约smoothing倍未凑满的残留样本不会立即入图参数校验smoothing 1会抛出ValueError(smoothing must be 1)同时PlotLogger.__init__要求plot_history_size为正整数否则分别抛出TypeError非 int或ValueError≤ 0。这些行为都被 test_viewer_plotting.py 的单元测试覆盖例如test_smoothing_and_clear验证了smoothing2时两个采样(2, 4)平均为3后才入图且clearTrue会先清空累积器再记录新值test_history_rolls_and_refreshes验证了缓冲滚动与缓存刷新逻辑。log_array()把数值数组渲染成实时热力图log_array()用于将数组数据可视化为热力图签名如下viewer.py 抽象定义viewer_rtx.py 实现def log_array(self, name: str, array: wp.array[Any] | np.ndarray | None):核心语义接受的维度标量0 维渲染为单格、一维数组渲染为单行、二维数组渲染为网格更高维度会抛出ValueError(log_array only supports scalar, 1-D, or 2-D arrays.)plot_logger.py数据来源既可以是 Warp 数组wp.array内部通过.numpy()转出也可以是 NumPy 数组统一转换为float32连续数组存储删除信号传入arrayNone会移除之前以该name记录的数据并释放对应的 OpenGL 纹理plot_logger.py。# 每帧把观测向量渲染为一行热力条 self.viewer.log_array(observations, np.arange(6).reshape(2, 3)) # 不再需要时移除 self.viewer.log_array(observations, None)热力图的渲染管线inferno 色标、NaN 与自适应下采样热力图的绘制由PlotLogger内部完成值得展开的原理点有四个plot_logger.pyinferno 色标_build_heatmap_color_lut()内联构建了 256 级 inferno 颜色查找表从深蓝紫(0.001, 0, 0.014)渐变到亮黄(0.988, 0.998, 0.645)数组值按当前最小/最大值线性归一化后查表映射为 RGBANaN 处理_colorize_heatmap先取np.isfinite掩码非有限值统一着色为深灰(51, 51, 51, 255)有限值的最小/最大值则显示在窗口底部的min/max文本中若整个数组全为非有限值则整体显示为灰色并输出min -- max --自适应下采样为避免超大数组如高分辨率接触压力场创建过大的纹理_downsample_heatmap以最小 3 像素/格_heatmap_min_cell_pixels 3.0随 DPI 缩放为基准对超出的行列做分块均值降采样降采样时同样忽略 NaN 格窗口信息栏会同时显示原始形状与显示形状例如shape 512x512 shown 256x256纹理缓存每个name对应一个 GL 纹理仅当数据形状或内容变脏_array_dirty时才重新上传 RGBA 像素glTexSubImage2D纹理过滤设为GL_NEAREST以保证热力格边缘清晰plot_logger.py。配置绘图历史ViewerRTX 的 plot_history_size 参数绘图历史的长度通过 Viewer 构造函数的关键字参数配置。ViewerRTX.__init__的完整签名viewer_rtx.py中除了常规的width、height、vsync、headless、paused、fps、up_axis、num_frames、scaling、environment、async_rendering等参数外新增了def __init__( self, width: int 1280, height: int 720, ... *, plot_history_size: int 250, ):默认值 250每个log_scalar信号默认保留最近 250 个样本仅影响标量曲线文档与实现均明确指出该参数是 Maximum number of samples kept perlog_scalarsignal for the live time-series plotsviewer_rtx.py数组热力图不受其限制构造期绑定plot_history_size在__init__中直接传给PlotLogger(plot_history_size, get_windowlambda: self._window)viewer_rtx.py因此需在创建 Viewer 时一次性指定运行中不可修改。例如创建一个只保留最近 100 个采样点的 RTX 查看器viewer newton.viewer.ViewerRTX(width1280, height720, plot_history_size100)底层实现PlotLogger 的职责划分与窗口绘制该功能的实现哲学是记录与绘制解耦PlotLogger只负责数据缓冲与纹理管理窗口绘制则交给 Viewer 的 GUI 层。记录阶段与窗口无关PlotLogger的类注释明确指出 Logging is independent of window creationOpenGL 只在绘制热力图时才被加载纹理操作会激活所属窗口的上下文plot_logger.py因此log_scalar/log_array可以在窗口尚未渲染任何帧时安全调用绘制阶段draw(ui)方法plot_logger.py在屏幕右下角自动创建一个名为 Plots 的浮动窗口窗口高度随信号数量动态计算每个标量信号约 140px、每个数组约 260px均乘 DPI 缩放并对每个标量信号使用imgui.collapsing_headerimgui.plot_lines绘制曲线末尾叠加overlay_text显示最新值格式%.4g每个数组信号则展开热力图纹理窗口位置稳定性imgui.set_next_window_pos(..., imgui.Cond_.first_use_ever)保证用户拖拽过的窗口位置在折叠/展开及imgui.ini重载后保持稳定plot_logger.py生命周期管理clear_matching(owns)支持按名称谓词批量释放信号与纹理用于图层/世界切换clear()在窗口关闭前释放全部数据与纹理plot_logger.py。另外ViewerRTX.log_scalar/log_array在转发给PlotLogger前会通过self._qualify(name)对信号名做限定避免不同场景下同名信号互相污染viewer_rtx.py、viewer_rtx.py。后端覆盖范围与测试佐证尽管 changelog 文案只提到ViewerRTX从源码看该能力在多个后端有不同程度支持ViewerGL与ViewerRTX完整支持共享PlotLogger均接受plot_history_size构造参数是本文介绍的实时图/热力图能力的主阵地ViewerRerun等后端实现了log_array接口见 viewer_rerun.py 等属于各后端各自的数组可视化通路抽象契约log_scalar与log_array是 viewer.py 中定义的抽象方法所有后端必须实现。配套的单元测试 test_viewer_plotting.py 系统性地验证了该特性的关键行为可作为学习该 API 语义的补充材料test_scalar_reaches_plot_window验证标量值能进入 Plots 窗口的plot_lines且overlay_text显示最新值test_array_creates_plot_window验证数组信号会触发 Plots 窗口创建且未真正绘制前不会加载 OpenGLtest_history_rolls_and_refreshes验证滚动缓冲与缓存曲线随新样本刷新test_smoothing_and_clear验证平滑取平均、clear清空累积器以及smoothing 1抛错此外还覆盖了log_array(None)删除、空数组、高维数组抛错、纹理复用与形状变化重建等边界情形。使用建议与注意事项综合以上源码细节给出几条实操建议监控实时指标优先用log_scalar求解器迭代数、能量、约束数这类逐帧单值非常适合如需降低曲线噪声可将smoothing设为 416注意平滑会引入滞后并减少点数需要查看空间分布时用log_array例如接触压力场、高度场、粒子密度网格等二维数据传入None可随时关闭对应热力图提前规划历史长度plot_history_size在构造 Viewer 时固定交互式调试建议保持默认 250 或按需调大它对内存占用影响很小deque 只保留标量浮点值注意维度约束log_array不支持三维及以上数组多维数据需自行展平或切片后分多个name记录参数有效性plot_history_size必须是正整数smoothing必须 ≥ 1违反会抛异常建议在调试脚本中显式传入合法值。小结log_scalar()与log_array()为ViewerRTX以及ViewerGL补齐了仿真过程中实时可视化诊断数据的能力闭环一条折线即可追踪求解器的收敛行为与能量漂移一张热力图即可呈现接触压力或状态量的空间分布而plot_history_size与smoothing两个参数让开发者对数据的时间窗口与平滑程度拥有完全控制。配合 example_basic_plotting.py 的完整示例与 test_viewer_plotting.py 的边界验证读者可以快速在自己的仿真工作流中落地这套可视化管线。【免费下载链接】newtonAn open-source, GPU-accelerated physics simulation engine built upon NVIDIA Warp, specifically targeting roboticists and simulation researchers.项目地址: https://gitcode.com/GitHub_Trending/newton9/newton创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考