追踪小动物位置并控制光刺激|PiVR

让行为实时改变光

UCSB Louis Lab的PLOS Biology开放仪器:追踪小动物位置,实时控制光刺激。已有外部实物搭建记录;含原作者装配视频、11章图解、标准版BOM及原供应商链接,明确软件、图文与硬件许可范围和原表差异。

alan000

PLOS Biology 2020

参数信息

论文闭环更新最高频率
70 Hz

复现文档

锁定标准硬件版本

目的:固定标准灯带版:Raspberry Pi 4(2GB)、850nm 背光、红光刺激两路;不选高功率恒流驱动版。

1. 下载并记录锁定源码提交 `e563db96a116b7563d78d7590e95c8e2e4e64a0b`,保存对应 BOM 与手册。

2. 采购前核对冲突项:原库存 MOSFET 写 IRLZ44NPBF,手册及 OneClick 为 FQP30N06L;本路线按 FQP30N06L 并核对引脚。相机描述有 Pi3/Pi4 混写,滤镜亦有 800/850nm 差异,按实际料号留档。

**检查**:版本、主板、相机、滤镜和 MOSFET 型号均已记录。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/BOM.html) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![PiVR原版图解 loop.png](https://cdn.lunlunapp.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/cover/9a86ad30ba424fe7abce69835c08bbb6.png)![1_3D_printed_parts.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/3ff17d4722dd402db75b378d303cff0a.jpg)

写入系统并试装结构件

目的:按兼容 Pi4 与当前相机的说明准备系统镜像;写卡前核对镜像日期与哈希。

1. 使用明确可清空的至少 16GB Class 10 microSD 卡写入镜像,先确认写卡工具选中的目标盘。

2. 打印 7 类结构件,3MF 与 legacy STL 二选一,不重复计件;试装屏幕、Pi4 接口和相机孔位。支撑材料依对应零件文件选择,不能由旧教程推断新版 STL 均需支撑。

**检查**:树莓派能从卡启动,屏幕和相机支架孔位可试装;镜像版本及卡容量已记录。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/software_installation.html) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![PiVR原版图解 1_3D_printed_parts.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/3ff17d4722dd402db75b378d303cff0a.jpg)![PiVR原版图解 19_PiVR_complete.jpg](https://cdn.lunlunapp.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/cover/449a0d406fff478598efd9ca8d6cc2c0.jpg)

焊接并检查标准控制板

目的:准备标准版 PCB、4 个 FQP30N06L、4 个 10 kΩ 电阻、2×20 GPIO 插座、1 个 5.5/2.1 mm 输入、4 个 3.5/1.35 mm 输出和 5 针排针段。

1. 按 PCB 位号焊接;核对 GPIO 插座缺口、MOSFET 封装/引脚方向、输入输出插座和 5 针排针方向。

2. 剪除多余引脚,放大检查焊桥;用万用表检查电源与地无短路,测试前保持断电。

**检查**:器件数量、方向和焊点与标准 PCB 标记一致,电源/GND 未短接。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/manual_hardware.html#detailed-pcb-soldering-instructions-standard-version) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![PiVR原版图解 3_solderedPCB.jpg](https://cdn.lunlunapp.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/cover/aae142f08c3d448ca171852bf02172ea.jpg)![2_7_PCB_components.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/fd16478235ca4d35b456e29fec738d68.jpg)![S_4.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/33ec5d29e3fe41fcad3359df1d36d670.jpg)

安装触屏、主板与线束

目的:按图连接触屏排线和 5 针线,确认接点方向与插座标记一致。

1. 用 M2.5×10 螺钉将屏幕、树莓派和控制板固定到外壳,GPIO 排线按 1 脚标记连接。

2. 5 针线包含屏幕 5V 与地,不能接到 12V。长相机排线从外壳槽口穿出后再合后盖,避免折伤或夹线;Pi4 端口与旧照片有差异,按当前 CAD 对孔。

**检查**:屏幕和 GPIO 排线方向正确,相机排线未夹伤,5V 线路没有接入 12V。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/manual_hardware.html#building-the-standard-version) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![6_Touchscreen.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/b3016c5ef73548a899a82fb4694b6c43.jpg)![10_PCB_RPi_on_casing.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/313574fab01747c499421447b8d772d9.jpg)![12_Casing_stuffed.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/36e36c15ccf04b8fa07c1d6fe3dffb02.jpg)

组装相机塔和滤镜

目的:将塔底与塔顶用 3 根定位销连接,再用 M2.5 紧固件和对应螺母固定底座与相机支架。

1. 将 800nm 长通滤镜装到红外相机前,用 Parafilm 固定,避免污染滤镜表面;本路线按 BOM 800nm 型号记录,与论文方法中的 850nm 描述区分。

2. 将相机排线沿塔和相机架自然引出并连接,避免急弯;更换镜头/相机后重新生成畸变校正参数。

**检查**:定位销完全入位,滤镜型号已标记,排线不受拉扯且镜头视野无遮挡。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/manual_hardware.html#building-the-standard-version) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![15_TowerBottom_Dowel.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/84b047d100724d0b823613a25c37db92.jpg)![16_Camera_with_LP_filter.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/ed89b4fcb8144019ad22c806ddc72ecf.jpg)![18_Camera_attached_to_CamHolder.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/5e007ca7042243a487b184349aeb787a.jpg)

制作双通道灯场

目的:按激光切割图裁板并开 M8 孔;把 850nm 灯带按标记切点裁成约 20cm 段,按约 3cm 间距排布。

1. 将红外灯带正极并接、负极并接;红色刺激灯带间隔安装并走独立线路。每块板的实际灯带数量与总长度按灯场面积核算,5m 采购长度不等于整卷都装入。

2. 安装连接头并做绝缘,灯带不能遮住支柱孔。标准手册用 2 片扩散板,库存表有 3 片;按灯场均匀性决定是否加第三片。

**检查**:IR 和红光走独立线路,极性一致,孔位未被灯带挡住,灯带数量按实际板面记录。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/manual_hardware.html#building-the-standard-version) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![22_Arena_overview.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/7aa24f43e78342e4a03233fceb107c02.jpg)![25_arena_second_strip.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/ab14b0138e2642d0ac11ddf904548067.jpg)![26_second_plate_fastened.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/19304e3b1eab4494b61ca7711a9e3365.jpg)

制作并测量灯场电缆

目的:制作红外与红光两路电缆,各连接控制板端 3.5/1.35mm 插头与灯场端匹配的 5.5mm 插头;原示例每条约 50cm。

1. 导线规格按电流和压降选择;焊接后用热缩管绝缘。

2. 用万用表核对端到端连续性、极性和正负线之间无短路。只使用 12V DC 路线:WAU12-2000 厂商数据表输出 12VAC,不可用于 12V DC 灯带。

**检查**:两条线缆分别标明 IR/红光,插头尺寸与端口匹配,极性正确且无短路。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/manual_hardware.html) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![power.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/692264bbbad44aef846f039f1eb5d9f7.png)![27_cables_overview.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/11285d02985e473c9a0bdb1ff864f0a4.jpg)![28_cable_done.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/bb7fc5d74bd340f69c03891a957e0cac.jpg)

分别测试供电、相机和灯通道

目的:Raspberry Pi 使用匹配 Pi4 的 5.1V/3A USB-C 电源;LED 使用独立 12V DC 电源,按实际灯带功率选足电流余量。

1. 接市电前逐项检查极性与短路;首次镜像启动按手册预留 5–10 分钟。

2. 打开 PiVR 的 Optimize Image 与 Cam On,先启用 IR 背光,再测试 Channel 1 红光;分别确认相机画面和灯光响应。避免直视高亮LED;红外不可见不代表无光。

**检查**:相机画面稳定,IR 和红光通道分别响应,供电无异常发热或掉电。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/manual_hardware.html#building-the-standard-version) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![PiVR原版图解 power.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/692264bbbad44aef846f039f1eb5d9f7.png)![30_connecting_IR_cables.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/27fb2fa699ac482c9b8b8d9cb0bfc06b.jpg)![30_1_testing_IR.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/506da7e3d75049e2b0b175d0662a91a2.jpg)

调整成像并标定像素尺度

目的:将完整运动区域放入视野,调整相机高度与焦点,移除螺钉/边缘等高对比干扰。

1. 选择成像分辨率和帧率;按 UI 中的背光起始值 400000 调整至目标对比度,再关闭自动曝光以保持不同试次一致。该值是界面设定,不是光功率单位。

2. 使用 Define Pixel/mm 标定物理尺度;改变相机高度或分辨率后重新标定。若量化刺激强度,另测光强和空间均匀性。

**检查**:运动区完整入镜,曝光稳定,像素/毫米标定已保存。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/running_experiments.html) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![OptimizeImageOverview.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/68d8e79f27e64a43999e31c81189ef8e.png)![DistanceConfigurationOverview.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/56b984b5c78d4540b52dfddeb413c98c.png)

启动跟踪与虚拟场景

目的:先选择目标参数和检测方式,设置数据目录与实验时长;用普通 Tracking 模式检查分割、头尾识别和丢帧。

1. 再在 VR Arena 加载分辨率匹配的虚拟场景 CSV,检查刺激通道、位置映射和场景边界。

2. 先用无动物目标完成供电、追踪与灯场预检;后续动物实验由实验室按相应物种和批准方案执行。

**检查**:目标位置能持续更新,VR 场景范围与相机坐标匹配,指定通道响应正确。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/running_experiments.html) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![31_1_testing_channel1.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/a3a0299e07b7482e9c9b458f57891ac1.jpg)![ExperimentControlFrameVRArena.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/ed0a9e53c20c48c1a97d638b5c82515d.png)

检查数据并归档版本

目的:检查 data.csv 中逐帧时间、位置、头尾和刺激信息,并打开 Background、参数文件及所选录像。

1. 统计丢帧、实际帧率和跟踪失败;闭环延迟按原 benchmark 方法单独测量。论文报告的 70Hz 与低于 30ms 来自指定条件,不作为本配置的验收值。

2. 归档 PCB 修订、MOSFET/电源型号、镜像哈希、源码提交、光强校准、线缆极性和测试视频。

**检查**:数据文件可读,运行参数和版本信息齐全;性能数据按本机实际测量填写。

[原版完整操作说明](https://pivr.readthedocs.io/en/latest/output.html) [原图所在论文手册归档](https://doi.org/10.1371/journal.pbio.3000712.s019)

![PiVR原版图解 loop.png](https://cdn.lunlunapp.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/cover/9a86ad30ba424fe7abce69835c08bbb6.png)![5_DisplayTrackedExperiment.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/bdf1ddde-41fd-4855-97ea-8c589bb2090b/files/image/965c3a63bfbb492590c1a132bbea4387.png)