PsychoPy 空间单位(Spatial Units)交互演示指南:用 Builder 实验直观理解 height、norm、pix、cm 与 deg
PsychoPy 空间单位(Spatial Units)交互演示指南:用 Builder 实验直观理解 height、norm、pix、cm 与 deg
本篇指南以 PsychoPy 自带 Builder 演示实验
spatialUnits为核心,结合仓库源码深入讲解 PsychoPy 的五大空间单位体系(height、norm、pix、cm、deg)的含义、换算原理与使用场景。读完本文,你将理解"设备无关单位"为何是 PsychoPy 的核心优势,掌握如何在 Monitor Center 中校准显示器参数,并通过键盘交互实时观察同一个矩形在不同单位下的实际大小差异,从而在自己的 Builder / Coder 实验中正确选择单位。
一、为什么 PsychoPy 需要"空间单位"
大多数实验构建软件只允许以固定像素或屏幕百分比来描述刺激的大小与位置,研究者事后需要自行换算"这个刺激到底对应多少厘米、多少度视角"。PsychoPy 则不同——这是它相对于多数同类软件的关键优势:刺激可以用多种真实世界、与设备无关的单位来描述。
其核心流程是:
- 在 Monitor Center 中录入显示器的物理参数(屏幕可视宽度、观看距离、像素分辨率);
- 在实验中按自己的习惯直接以
deg(度视角)、cm(厘米)、height(窗口高度比例)等单位指定刺激; - PsychoPy 自动完成"单位 → 像素"的换算并正确渲染。
然而,初次接触这些单位时,理解它们的含义容易混淆。为此,仓库提供了一个可视化演示:一个正方形在不同单位下、不同尺寸时的实际显示效果,即本文要讲解的演示实验。
- 演示说明文档:README.md
- 演示实验文件:unitDemo.psyexp
二、演示实验结构剖析:unitDemo.psyexp
打开 unitDemo.psyexp 可以看到,它由 1 个 Routine(rectMover) 组成,包含 4 个组件:
| 组件 | 类型 | 作用 |
|---|---|---|
stim |
Polygon(矩形,4 顶点) | 被移动、缩放、切换单位的"主角"正方形 |
code |
Code | 承载键盘交互逻辑(Begin Experiment / Each Frame) |
inst |
Text | 屏幕下方的操作说明文本 |
poslog |
Text | 实时显示刺激的 pos、size 与当前 units |
实验级设置中值得注意的默认值:
- Units =
height:整个实验窗口的默认单位; - Monitor =
testMonitor:使用名为testMonitor的显示器校准文件; - Window size (pixels) =
[1080, 720]; measureFrameRate = True,采用 pyglet 后端。
poslog 组件每隔一帧更新文本,其内容由代码 f"pos: ({stim.pos[0]:.2f}, {stim.pos[1]:.2f})\nsize: ({stim.size[0]:.2f}, {stim.size[1]:.2f})\nunits: {stim.units}" 生成,因此运行期间你能实时看到"数值 + 单位"的组合变化——这正是理解各单位"数值含义"的最直接方式。
三、核心数据:mags 与 unitCodes
实验在 Begin Experiment 阶段(同时提供 Python 与自动生成的 JS 版本)定义了两张关键字典:
mags = {
'height': 0.1, # 窗口高度的 10%
'norm': 0.1, # 归一化坐标的 0.1
'pix': 100, # 100 个物理像素
'cm': 1, # 1 厘米
'deg': pi / 10, # 约 18 度视角
}
unitCodes = {
'h': 'height',
'n': 'norm',
'p': 'pix',
'c': 'cm',
'd': 'deg',
}
mags是每次按键时数值改变的步长:例如在height单位下按一次方向键,刺激移动 0.1 个窗口高度;在deg单位下移动约pi/10弧度(≈18°)。注意deg的步长用pi/10而非写死的度数,目的是让换算逻辑在 JS 端保持一致。unitCodes将按键字母映射到完整单位名,构成交互控制的"快捷键表"。
四、交互控制:完整键盘映射
实验的核心逻辑在 Each Frame 代码段中(同样提供 Python 与 Auto→JS 版本)。完整键盘映射如下:
| 按键 | 行为 |
|---|---|
↑ ↓ ← → |
沿 Y / X 轴移动刺激,步长为 mags[stim.units] |
=(等号) / -(减号) |
放大 / 缩小刺激尺寸(步长同上,且保证尺寸不小于 0) |
p |
切换到 pix 单位 |
h |
切换到 height 单位 |
n |
切换到 norm 单位 |
c |
切换到 cm 单位 |
d |
切换到 deg 单位 |
r |
重置:单位恢复 height,size=(0.1, 0.1),pos=(0, 0) |
esc |
结束当前 Routine 并退出实验 |
其 Python 实现要点如下:
keys = event.getKeys()
if keys:
if 'escape' in keys:
continueRoutine = False
break
key = keys.pop()
pol = (key in ['right', 'up', 'equal']) * 2 - 1 # 方向极性
mag = mags[stim.units] # 按当前单位取步长
if key in ['left', 'right']:
stim.pos = (stim.pos[0] + mag * pol, stim.pos[1])
if key in ['up', 'down']:
stim.pos = (stim.pos[0], stim.pos[1] + mag * pol)
if key in ['equal', 'minus']:
if stim.size[0] + mag * pol >= 0:
stim.size = (stim.size[0] + mag * pol,
stim.size[1] + mag * pol)
if key in ['h', 'p', 'n', 'c', 'd']:
stim.units = unitCodes[key] # 切换刺激单位
poslog.units = unitCodes[key] # 读数文本同步切换
if key in ['r']:
stim.units = 'height'
stim.size = (0.1, 0.1)
stim.pos = (0, 0)
值得注意的工程细节:
- 移动与缩放共用同一个
pol极性计算,right/up/equal返回+1,left/down/minus返回-1,代码非常紧凑; - 切换单位时同时更新
poslog.units,保证读数文本的数值始终以新单位解释; - 缩放时有
size[0] + mag*pol >= 0的防负保护,避免刺激尺寸变为负数; event.getKeys()每次取一个键(keys.pop()),因此按住多键时逐帧依次处理。
五、五种单位的语义与换算原理(源码级)
理解这五种单位,关键是理解 "数值 → 像素"的换算路径。PsychoPy 的全部换算集中在 psychopy/tools/monitorunittools.py,入口函数是 convertToPix(vertices, pos, units, win),它通过注册表 _unit2PixMappings 查找对应换算函数:
| 单位 | 注册函数 | 换算规则(非 Retina 屏幕) | 依赖 |
|---|---|---|---|
pix / pixels |
_pix2pix |
像素即数值本身,pos + vertices |
无 |
height |
_height2pix |
乘以窗口高度:(pos + vertices) * win.size[1],即 1.0 = 整个窗口高度 |
窗口 |
norm |
_norm2pix |
乘以 win.size / 2.0,即 x 方向映射到 [-1, 1],y 方向按比例缩放保持宽高比 |
窗口 |
cm |
_cm2pix |
cm2pix:cm * scrSizePix[0] / scrWidthCm |
显示器宽度 |
deg |
_deg2pix |
deg2pix:先 deg2cm(degrees * dist * 0.017455,即 dist * π/180),再按 cm2pix 换算 |
显示器宽度 + 观看距离 |
从 psychopy/visual/basevisual.py 的 units 属性实现可以看到:每个刺激都可以独立设置 units,若未设置则继承窗口的默认单位(self.win.units)。改变 units 只改变数值的解释方式,并不会改变刺激当前已渲染的像素大小。
5.1 height:窗口高度比例
height 单位下,数值 1.0 等于窗口的整个高度。因此演示中 size=(0.1, 0.1) 的正方形占窗口高度的 10%,与屏幕分辨率、宽高比完全无关,是最直观的"比例尺"之一。Retina 屏(useRetina=True)时换算系数会变为 win.size[1] / 2.0,此时数值 1.0 指窗口高度的一半。
5.2 norm:归一化设备坐标
norm 单位源自 OpenGL 归一化设备坐标:x 方向满屏范围是 [-1, 1],y 方向按窗口宽高比等比缩放,从而保证正方形在任意窗口下都保持正方形。换算系数为 win.size / 2.0(Retina 下为 win.size / 4.0)。注意 norm 不保证上下左右对称的满屏范围——它优先保证图形比例不变。
5.3 pix:物理像素
pix 单位即实际像素数,是唯一不依赖任何校准参数的"原始"单位。演示中按一次方向键移动 100 像素。在 Retina 屏上,pix 指逻辑像素坐标(psychopy/visual/window.py 的窗口文档中有说明)。
5.4 cm:厘米
cm 单位依赖显示器校准数据:可视屏幕宽度(cm) 与 像素分辨率。核心公式(monitorunittools.py):
def cm2pix(cm, monitor):
scrWidthCm = monitor.getWidth() # 屏幕可视宽度(cm)
scrSizePix = monitor.getSizePix() # 屏幕像素尺寸
return cm * scrSizePix[0] / float(scrWidthCm)
即"每厘米多少像素 = 屏幕横向像素数 / 屏幕横向厘米数"。演示中 mags['cm'] = 1,因此按一次方向键移动 1 厘米。
5.5 deg:度视角
deg 单位是心理学/神经科学实验最常用的单位,因为它直接对应被试的视网膜成像大小。换算分两步(monitorunittools.py 与 L246-L260):
def cm2deg(cm, monitor, correctFlat=False):
dist = monitor.getDistance()
if correctFlat:
return np.degrees(np.arctan(cm / dist))
else:
return cm / (dist * 0.017455) # 0.017455 = π/180
def deg2pix(degrees, monitor, correctFlat=False):
cmSize = deg2cm(degrees, monitor, correctFlat) # degrees * dist * 0.017455
return cmSize * scrSizePix[0] / float(scrWidthCm)
1 度视角在屏幕中心对应的物理尺寸 ≈ 观看距离 × π/180(弧度定义)。演示中 mags['deg'] = pi/10 ≈ 0.314 弧度 ≈ 18°,这个数值较大,是为了在演示时让"度"的变化肉眼可见。
若未设置 correctFlat(即 deg),屏幕被近似为"以眼为球心的球面",所有角度的像素大小一致;correctFlat=True 则按平面屏幕的几何关系修正(越靠近屏幕边缘,同样度数对应的像素间距越大),这就是下文的 degFlat 系列单位。
5.6 换算函数的可扩展性
convertToPix 通过注册表分发换算逻辑,且仓库提供了公开的注册入口 addUnitTypeConversion(unitLabel, mappingFunc)(monitorunittools.py),允许第三方为自定义单位注册换算函数,这说明单位体系是可扩展的插件式架构,而非硬编码。
六、前置条件:在 Monitor Center 校准显示器
要让 cm 和 deg 真正有意义,必须先校准显示器。实验设置中 Monitor = "testMonitor",但该名字只是一个占位符——你应当打开 Monitor Center,为当前实际使用的显示器新建/选择一个校准文件,并填写:
- 屏幕可视宽度(cm);
- 观看距离(cm);
- 屏幕像素分辨率(sizePix)。
这些参数在底层由 psychopy/monitors/calibTools.py 的 Monitor 类存取,核心方法包括:
def setSizePix(self, pixels): # 设置屏幕像素尺寸
def setWidth(self, width): # 设置可视宽度(cm)
def setDistance(self, distance):# 设置观看距离(cm)
def getSizePix(self): # 读取像素尺寸(无效时返回 None)
def getWidth(self): # 读取宽度(cm)
def getDistance(self): # 读取距离(cm)
(见 calibTools.py#L148-L161 与 L253-L276。)
若缺少必要参数,换算函数会抛出明确的错误提示("Monitor %s has no known width in cm (SEE MONITOR CENTER)" 等),提醒你回到 Monitor Center 补全数据。
关键提示:显示器校准是"物理单位"正确性的根基。若你的实验使用
deg或cm,但显示器宽度填错或未填写,所有换算结果都会失真。这也是在运行本演示前必须完成的一步。
七、在 Builder 中配置与运行
7.1 实验级默认单位
在实验设置的 Units 字段中可以指定整个实验的默认单位(本演示设置为 height)。该值最终传递给 psychopy/visual/window.py 的 Window.units,作为所有未显式指定单位刺激的默认值。窗口文档中明确说明(window.py#L331-L344):默认单位可以是 height、norm、deg、cm、pix 之一。
7.2 组件级单位覆盖
每个刺激组件(如本演示的 Polygon stim)都有独立的 Units 参数。若组件设置为 from exp settings,则继承窗口默认单位;否则使用自身指定值。basevisual.py 中每个刺激在初始化时都会记录自己的单位,后续改变窗口单位不会影响已创建的刺激。
7.3 运行方式
- 本地运行:在 Builder 中打开
unitDemo.psyexp,确保 Monitor Center 中已有名为testMonitor(或修改实验设置中 Monitor 字段)的校准文件,点击运行; - 在线运行(Pavlovia):实验设置中
exportHTML = "on Sync",且每个 Code 组件都提供了 Auto→JS 版本代码(Begin JS Experiment、Each JS Frame等),因此该演示可直接导出为 JavaScript 在浏览器运行,交互逻辑完全一致。
八、源码与测试如何验证单位体系
仓库对单位换算有系统的自动化测试覆盖,最有代表性的是 psychopy/tests/test_visual/test_all_stimuli.py:它为 pix、cm、deg、degFlat、degFlatPos 各建立一组测试类,并构造了统一的"测试显示器"参数:
mon = monitors.Monitor('testMonitor')
mon.setDistance(57) # 观看距离 57 cm
mon.setWidth(40.0) # 屏幕宽度 40 cm
mon.setSizePix([1024, 768]) # 分辨率 1024×768
其中 degFlat 测试特意把距离设为 10 cm(test_all_stimuli.py#L593),以夸大平面屏幕校正效应来验证 degFlat 与 deg 的差异。此外 psychopy/tests/test_visual/test_basevisual.py 还验证了"刺激单位 × 窗口单位"的各种组合都能无错绘制,且与非像素单位组合渲染结果一致。
从源码结构看,PsychoPy 还提供了 degFlat、degFlatPos 两个平面校正单位(注册于 monitorunittools.py#L42-L52),它们考虑了眼动注视点偏离屏幕中心时、同一度数对应的物理尺寸变化,适合对视角精度要求较高的实验。
九、实战建议与总结
结合本演示,给出单位选用的实用建议:
- 快速原型 / 界面布局:优先
height或norm,它们无需任何校准即可工作,且与分辨率无关; - 需要精确报告刺激物理尺寸:使用
cm,前提是显示器宽度校准准确; - 心理学/神经科学标准范式:使用
deg(度视角),这是论文中最通用的报告单位,前提是同时校准宽度与距离; - 精确控制单个像素:使用
pix,例如绘制逐像素的 Gabor 光栅或精确排布; - 对视角几何敏感的实验:考虑
degFlat/degFlatPos,并结合实际观看距离验证边缘位置的换算差异; - 运行本演示前:务必先在 Monitor Center 完成显示器校准,否则
c/d两种单位的换算会报错或失真。
本演示的价值在于:用最直观的"按键盘、看大小"方式,把抽象的单位换算变成可触摸的视觉经验。配合 poslog 的实时读数,你可以亲手验证"10% 窗口高度"与"18 度视角"在 1080×720 窗口、57 cm 观看距离下各自的实际像素大小,从而在正式实验中做到"心中有数"。
如需深入,可继续阅读:
- 单位换算全部实现:psychopy/tools/monitorunittools.py
- 刺激单位属性与默认继承逻辑:psychopy/visual/basevisual.py
- 窗口默认单位参数:psychopy/visual/window.py
- 显示器校准数据结构:psychopy/monitors/calibTools.py
- 单位换算测试用例:psychopy/tests/test_visual/test_all_stimuli.py