PsychoPy Builder Progress 进度条组件实战：用 0~1 连续值实时呈现时间流逝与试验进度-北京尧图网络

科研教育【免费下载链接】psychopyFor running psychology and neuroscience experiments项目地址https://gitcode.com/gh_mirrors/ps/psychopy点击查看免费下载本篇技术指南以仓库自带的 Builder Feature Demoprogress 示例为核心完整讲解 PsychoPy Builder 中Progress进度条组件的配置方式、参数含义与底层实现原理。读完本文你将掌握如何在 Builder 界面中为实验加入可实时更新的进度条用min(t/10, 1)这类表达式追踪倒计时用trials.thisN/5追踪试验完成数量并理解它生成的 Python 代码与visual.Progress的渲染机制以及如何把同样的实验发布到在线端 PsychoJS 运行。一、Demo 想展示什么Progress 组件的核心用法progress示例的官方说明非常凝练A simple demo to showcase the new Progress Component. The value of a Progress bar can be set between 0 and 1, and the bar will show this. Setting it each repeat or each frame means you can continuously keep track of values - such as time passed or trials complete.翻译成实现语言这句话包含三个关键点取值区间固定为 [0, 1]0表示进度条为空未开始1表示进度条完全填满完成进度值是可编程的任何能算出 0~1 之间数值的表达式都可以作为进度值更新时机有两种set every frame每一帧刷新适合时间流逝这类连续变化和set every repeat每次循环重复刷新适合试验完成数这类离散变化。该 Demo 位于 psychopy/demos/builder/Feature Demos/progress/目录下有两个文件实验工程文件progressBar.psyexp用 Builder 打开即可运行和readme.md说明文档。它属于仓库 demos/builder/Feature Demos 系列定位是特性演示——即用最小化的实验结构展示某个组件的典型用法。二、progressBar 实验结构逐项拆解打开 progressBar.psyexp 可以看到这是一个极简但完整的实验Flow 中只有一个TrialHandler循环名称trials重复次数nReps5顺序random不依赖任何条件文件包裹一个名为trial的 Routine。trialRoutine 内共放置了10 个组件其布局与职责如下表组件名称显示文本 / 进度公式更新模式位置 posheight 单位Textboxtimer10labelA 10 second timer:constant(0, 0.4)Progresstimer10min(t/10, 1)set every frame(-0.5, 0.3)Textboxtimer5labelA 5 second timer:constant(0, 0.2)Progresstimer5min(t/5, 1)set every frame(-0.5, 0.1)Textboxtimer1labelA 1 second timer:constant(0, 0.0)Progresstimer1min(t, 1)set every frame(-0.5, -0.1)TextboxtrialCtrLabelTrials complete:constant(0, -0.2)ProgresstrialCtrtrials.thisN/5set every repeat(-0.5, -0.3)TextboxnextLblPress SPACE to go to the next trialconstant(0, -0.4)KeyboardnextBtn监听space键constant—这个结构刻意展示了 Progress 组件的两大类典型场景1. 计时器进度set every frame三个计时进度条都使用 routine 内置计时变量t即当前 Routine 开始后经过的秒数timer10progress min(t/10, 1)10 秒内从 0 匀速填满timer5progress min(t/5, 1)5 秒内从 0 匀速填满timer1progress min(t, 1)1 秒内从 0 匀速填满。外层包上min(..., 1)是为了钳制上限即使实验循环超出预定时长进度值也不会突破 1超过 100% 的物理含义。这正是 visual/progress.py 源码中progresssetter 会再次做min/max双重钳制的缘由详见第四节。2. 试验计数进度set every repeat第四个进度条trialCtr使用trials.thisN/5thisN是当前 TrialHandler 循环中已完成的试验编号从 0 开始除以总次数 5 即得到完成比例。每次进入新的 trialrepeat时刷新一次因此它呈现的是离散的、跨 trial 的总体进度。3. 手动推进的交互循环Keyboard 组件nextBtn只监听space键allowedKeysspaceforceEndRoutineTrueregisterOnrelease。也就是说按下空格结束当前 trial、进入下一个循环配合屏幕上的提示文字Press SPACE to go to the next trial形成被试自行控制节奏的演示流程。一个小观察trials.thisN/5在 5 个 trial 中依次为 0、0.2、0.4、0.6、0.8最后一个 trial 也不会到达 1。如果希望结束时显示 100%可以改用(trials.thisN 1)/5或在LoopTerminator前单独把进度设为 1。三、Builder 中 Progress 组件的参数详解Progress 组件在 Builder 组件库中的实现位于 psychopy/experiment/components/progress/init.py类名为ProgressComponent自 2023.2.0 版本起加入见 CHANGELOG.txt 中的条目Progress bar component: A visual component to show progress along an axis其 Builder 提示语为Present a progress bar, with values ranging from 0 to 1在组件面板的Stimuli分类下同时支持 PsychoPy 与 PsychoJS 两个目标。1. Basicprogress 参数参数类型默认值说明progresscode0.0进度值范围 0未开始到 1完成它支持三种更新模式源码中allowedUpdates[constant, set every repeat, set every frame]constant进度固定不变适合静态展示set every repeat每次循环重复开始时更新适合已完成多少 trial这类按次更新的量set every frame每个渲染帧都更新适合随时间连续变化的量倒计时、动画进度等。在 psychopy/experiment/components/init.py 中progress被登记为默认值0.0、类型code的初始化参数。2. Appearance外观参数ProgressComponent 对颜色参数做了专门的语义化命名见组件源码中self.params[color].label _translate(Bar color)等三处重命名参数Builder 中显示名默认值含义colorBar colorwhite已填充部分的颜色进度条前景fillColorBack colorNone未填充部分的颜色背景槽borderColorBorder colorwhite进度条外轮廓线的颜色lineWidthLine width4轮廓线宽始终以像素计不随 units 变化opacityOpacity1.0整体不透明度0 完全透明1 完全不透明在 demo 中可以看到这套参数的实际配色三个计时器分别使用 grey / darkgrey / lightgrey 作为 bar 与 border 颜色、黑色作为背景槽fillColorblack而试验计数条trialCtr则用 dodgerblue 配白色背景槽——通过颜色即可直观区分时间进度与试验进度两组信息。3. Layout布局参数参数默认值说明pos(0, 0)进度条中心锚点位置size(0.5, 0.5)进度条整体尺寸(w, h)anchorcenter-left锚点位置见下方 9 个可选值unitsheight尺寸/位置单位demo 中统一使用height以窗口高度为 1 的相对单位ori0旋转角度anchor的 9 个候选值源码中allowedValscenter、top-center、bottom-center、center-left、center-right、top-left、top-right、bottom-left、bottom-right。anchor 同时决定填充起点——例如 anchor 为center-left时水平进度条从左向右填充这也是 demo 全部使用center-left的原因配合pos的负 x 值让进度条贴左、文字居中形成整齐的清单式布局。四、生成的代码与 visual.Progress 源码实现1. Builder 生成的初始化代码ProgressComponent.writeInitCode输出的 Python 代码模板如下与 demo 中timer10的 psyexp 参数对应timer10 visual.Progress( win, nametimer10, progressmin(t/10, 1), pos(-0.5, 0.3), size(1, 0.1), anchorcenter-left, unitsheight, barColorgrey, backColorblack, borderColorgrey, colorSpacergb, lineWidth4, opacity1, ori0, depth-2 )由于progress被设置为set every frameBuilder 还会在每一帧生成对应的更新调用timer10.setProgress(min(t/10, 1), logFalse)每帧更新默认不写日志见 psychopy/experiment/components/_base.py 中set every frame时追加logFalse的逻辑trialCtr则因set every repeat在每个循环重复处更新trialCtr.setProgress(trials.thisN/5)。2. 双矩形结构背景前景visual.Progress定义于 psychopy/visual/progress.py继承自shape.ShapeStim。其核心结构是两个叠加的矩形源码注释A basic progress bar, consisting of two rectangles: A background and a foreground. The foreground rectangle fill the background as progress approaches 1backboard背景矩形整个ShapeStim本体填充色为backColor、轮廓色为borderColorbar前景矩形一个独立的ShapeStim填充色为barColor、无轮廓尺寸随progress动态缩放。两者的位置、尺寸、锚点、单位、透明度在初始化时被绑定同步pos/size/anchor/units/opacity的 setter 都会把值同步给self.bar。绘制时progress.py 的 draw 方法先画背景再画前景 bar从而形成槽填充的视觉效果。3. progress 的钳制与填充算法attributeSetter def progress(self, value): # Sanitize value value float(value) value max(value, 0) value min(value, 1) # Store value self.__dict__[progress] value # Multiply size by progress to get bar size i 0 if self.direction vertical: i 1 sz self.size.copy() sz[i] * value self.bar.size sz节选自 progress.py其算法非常直观先把输入转成 float并用max(value, 0)与min(value, 1)双向钳制到 [0,1]然后取size的某一维水平取宽度、垂直取高度乘上progress作为前景 bar 的新尺寸。因此进度条填充比例的几何计算完全等价于bar 尺寸整体尺寸 × 进度值。4. direction填充方向及其别名direction决定填充沿哪一维进行支持大量别名progress.py 中的 _directionAliases 与_sanitizeDirection方法规范化结果可接受的输入horizontalhorizontal、horiz、x、0、False、0、Falseverticalvertical、vert、y、1、True、1、True非法值会被静默视为 horizontal。注意direction 必须与 anchor 配合使用才能控制填充方向——例如directionhorizontalanchorcenter-left时从左向右填anchorcenter-right时则从右向左填垂直方向同理文档字符串中明确写道Use in combination with anchor to control which direction the bar fills up from。切换 direction 时源码会先把进度临时置 1让两维都等于整体尺寸再恢复原值以保证重排后的几何正确性progress.py。5. complete 便捷属性complete是progress的派生属性progress.pyprogress 1时为True将其赋True会把进度置满赋False时若当前已满则清零。在 Builder 或代码组件中可以直接用timer10.complete判断计时是否结束作为分支或停止条件的依据。6. 颜色别名为了兼容 Builder 与 Coder 两套命名习惯barColor/foreColor、backColor/fillColor、borderColor/lineColor互为别名任何一组赋值都会同步到同一底层属性progress.py 初始化与属性代理。Builder 生成的代码使用barColor/backColor/borderColor而纯脚本用户可用foreColor/fillColor/lineColor。五、把 Demo 扩展到你自己的实验掌握了参数与原理后Progress 组件可以应用到任何可归一化到 [0,1] 的连续量上。以下是从 demo 公式延伸出的常用模式场景进度表达式示例更新模式倒计时N 秒min(t/N, 1)set every frame当前 trial 编号trials.thisN/nRepsset every repeat包含当前 trial 的完成度(trials.thisN 1)/nRepsset every repeat正确率nCorrect/nTotalset every repeat与响应时间挂钩min(rt/threshold, 1)set every frame音量/亮度强度任意 0~1 的刺激参数set every frame代码层使用示例Coder 模式from psychopy import visual, core win visual.Window([800, 600]) bar visual.Progress( win, namepb, progress0, directionhorizontal, pos(0, 0.2), size(0.6, 0.05), anchorcenter-left, unitsheight, barColordodgerblue, backColorblack, borderColorgrey, lineWidth3, opacity1.0, ) clock core.Clock() while bar.progress 1: bar.progress clock.getTime() / 10.0 # 10 秒倒计时 bar.draw() win.flip()选择更新模式的原则变化是每帧连续发生时间、刺激强度就用set every frame只在跨 trial/循环边界变化计数、试次号就用set every repeat——后者还能明显减少不必要的几何重算。六、测试与质量保障仓库为 Progress 提供了专门的像素级回归测试 psychopy/tests/test_visual/test_progress.py。测试类TestProgress继承颜色、单位、序列化等多个混入类核心用例test_value的做法是构造 128×128 的测试窗口与一个size(128, 64)的 Progress 实例在 4 个进度值0、0.3、0.6、1× 6 种anchor direction布局水平 3 种锚点、垂直 3 种锚点下逐一draw()将渲染帧与测试数据目录中的基准截图比对utils.compareScreenshot(filename, self.win, crit8)。对应的基准图保存在 psychopy/tests/data/文件名形如TestProgress_testValue_horizontal_center center_0.3.png、TestProgress_testValue_vertical_bottom center_0.6.png等同时测试还指定了边框、背景槽、前景三个采样像素点borderPoint / fillPoint / forePoint以校验三部分颜色都正确绘制。这套测试保证了不同 anchor、方向、进度值组合下的渲染几何不会发生回归。![Progress 组件水平方向渲染测试基准图progress0.3anchorcenter](https://raw.gitcode.com/gh_mirrors/ps/psychopy/raw/9535622fbcaa020b683820df732b2617265ef9f1/psychopy/tests/data/TestProgress_testValue_horizontal_center center_0.3.png?utm_sourcegitcode_repo_files)![Progress 组件垂直方向渲染测试基准图progress0.6anchorbottom center](https://raw.gitcode.com/gh_mirrors/ps/psychopy/raw/9535622fbcaa020b683820df732b2617265ef9f1/psychopy/tests/data/TestProgress_testValue_vertical_bottom center_0.6.png?utm_sourcegitcode_repo_files)七、PsychoJS 在线实验支持ProgressComponent的targets [PsychoPy, PsychoJS]并实现了writeInitCodeJS因此同样的 Builder 配置可直接导出为在线版本exportHTML设置demo 中为 on Sync。导出代码将生成new visual.Progress({...})形式的 PsychoJS 对象progress、pos、size、anchor、颜色等参数一一对应Builder 的更新机制同样作用于 JSset every frame会写入每帧更新代码set every repeat写入循环重复处更新代码。也就是说你在本地用min(t/10, 1)调好的倒计时进度条发布到 Pavlovia 等在线平台后行为保持一致。八、小结通过progress这个 Feature Demo我们完整走通了 PsychoPy Progress 组件的使用链路用法上给progress赋一个 0~1 的表达式按需选择set every frame时间类或set every repeat计数类更新模式即可让进度条实时反映任何可量化的状态参数上progress、三种颜色Bar/Back/Border、lineWidth、opacity、pos/size/anchor/units/ori构成了完整的定制面anchor与direction配合决定填充方向原理上visual.Progress以背景矩形前景矩形双 ShapeStim 实现progresssetter 双向钳制到 [0,1] 后按比例缩放前景尺寸绘制顺序保证槽与填充的层次正确质量与跨端上仓库提供像素级截图回归测试保障渲染正确组件同时支持 PsychoPy 与 PsychoJS 双端导出。无论你要做一个倒计时提示、一个长实验的总进度条还是在多 block 设计中指示剩余工作量这个组件都是 Builder 中最直接、最轻量的可视化方案。想亲手体验直接用 Builder 打开 progressBar.psyexp 并按空格推进即可。赞分享科研教育【免费下载链接】psychopyFor running psychology and neuroscience experiments项目地址https://gitcode.com/gh_mirrors/ps/psychopy点击查看免费下载相关推荐Bubble Tea 动画进度条实战用 progress 组件实现平滑过渡的 TUI 进度显示Bubble Tea 动画进度条实战用 progress 组件实现平滑过渡的 TUI 进度显示本篇文章以 Bubble Tea 仓库中的 progressCLI跨平台antd Progress 迷你尺寸进度条实战用 sizesmall 在狭窄区域内优雅呈现进度antd Progress 迷你尺寸进度条实战用 sizesmall 在狭窄区域内优雅呈现进度在移动端抽屉、表格单元格、卡片头部等「放不下常规进度条」前端UI组件设计系统推荐项目Node-Progress - 实时进度条库推荐项目Node Progress 实时进度条库在开发命令行应用时一个吸引用户的亮点是能够展示实时的进度信息。就是这样一款强大的开源库它提供了简单易用的开发工具上一篇Orca 跨执行主机的 Git 兼容性策略以能力探测为核心的 Git 版本适配体系下一篇FastAPI URL参数编码轻松掌握特殊字符处理的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

PsychoPy Builder Progress 进度条组件实战：用 0~1 连续值实时呈现时间流逝与试验进度

相关推荐

MoveIt2 中的 PRBT IKFast 运动学插件：从 CHANGELOG 看闭式逆解插件的演进与源码实现

Lunar 6.2.2 更新解析：备用菜单栏图标、XDR 长按行为与主屏识别修复

多模态RAG工程：图文混检三策略+RRF融合，从失败案例看信息检索新范式

更多资讯

Raft算法实战指南：从原理到生产落地的分布式一致性详解

PAT甲级1104：连续子段求和的贡献法推导与long double精度坑

OpenAI SDK平滑迁移，如何零代码重构接入新API？

程序员英语词汇宝典精讲：consumption（消耗）——资源监控、消息消费与性能分析中的高频技术词汇

车辆动力学标定实战：从参数辨识到模型验证的完整流程

Apereo CAS 指标导出 Datadog 实战：Micrometer Registry 配置与运维指南

今日更新

防关联浏览器哪个好？三款产品实测差异解析

2026钢铁行业AI转型系统选型对比：多基地排产、大宗原燃料采购与质量追溯，六家厂商能力差异在哪里

影刀RPA深度实战：大模型Fine-tuning定制RPA专用Prompt与指令生成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？