实战故障排查树、全局快捷键、数据备份与开源附录 · 工作台手册 · 文档

# 影调与色彩异常系统排障树

在胶片数字化暗房中，反相异常往往并非软件程序本身的逻辑缺陷，而是由前期光学翻拍、片基采样污染或边界框选失误所致。建立系统化的「表象症状 → 物理根因诊断 → 逐步排除路径」思维模型，能够帮助摄影师在几秒钟内定位问题核心。

下表系统梳理了最常见的影调与偏色异常排障决断树：

观察到的异常症状	物理根因诊断与排查方向	标准逐步修复路径
反相后整张正片发灰、发暗、极度缺乏对比度	① 胶片范围框入了外围 100% 透射的强光观片灯板； ② 片基采样点不慎点选到了已曝光画面区域； ③ 底片本身在拍摄冲洗时严重欠曝，缺乏有效银盐密度跨度。	1. 进入工具栏的设置胶片范围，检查四边框线，将白色透光底板与齿孔完全排除在框线外； 2. 重新点击Auto Invert； 3. 在密度范围面板中微调 Master D-Min 与 Master D-Max 端点； 4. 若画面本身是雾天或夜景，适度的平缓反差属于正常物理现象，无需强行拉爆黑白场。
画面出现顽固整体偏色，且白平衡吸管越调越脏	① 标定片基时选取的片边存在划痕、灰尘或指纹污染； ② 翻拍背光源显色指数过低（Ra < 95），光谱连续性不足； ③ 扫描仪驱动预先进行了不可逆的非线性自动色阶裁切。	1. 在胶片边缘寻找纯净、均匀透明的未曝光区域，重新进行标定片头片基； 2. 检查光源显色性，在硬件校正中核对背光光谱分布； 3. 在工作台印片灯光面板中，参考互补法则微调 Red/Green/Blue 滑块，先拉直基准再吸取中性灰。
整卷批处理后，绝大多数正常，唯独个别画面跳色严重	① 该画面在拍摄时被翻拍架微小位移带偏，导致胶片范围压住了边缘灯板； ② 该画面内容为大面积单色主体（如浓绿草地或深蓝大海），触发了单帧通道跨度过度保护； ③ 标定用的片头片基帧被误当作普通照片参与了批处理。	1. 单独选定该跳色画面，重新微调其胶片范围并保存； 2. 对该画面单独执行Auto Invert； 3. 若系单色题材，利用印片灯光单独补偿该帧的曝光偏移； 4. 确认片头参考帧带有标定角标，不参与普通画面渲染。
正片暗部反差严重丢失，呈现脏灰发雾感	① 胶片范围框入了扫描仪片夹或遮光板的死黑物理边缘； ② 镜头翻拍时未佩戴遮光罩，产生强烈的机内漫反射与眩光灰雾。	1. 收紧胶片范围，将片夹完全剔除； 2. 在细节面板中适当增加去朦胧滑块以压制漫反射灰雾。

真实低反差与算法错误的区别

如果拍摄底片本身记录的是清晨大雾、阴雨密云或昏暗室内，画面物理直方图本身就不具备纯白高光或深邃纯黑。NexFilm 的物理管线坚守真实还原，绝不会为了迎合所谓的“通透感”而盲目强行将直方图两端死死顶死。摄影师应当允许真实的低反差存在，在需要艺术强化时再通过“曲线”面板按需调整。

# 文件解码与性能排障

针对数字资产导入与实时渲染中可能遇到的技术瓶颈，处理建议如下：

1. 相机 RAW 或哈苏 .fff 文件导入报错或解码失败

检查扩展名真实性：某些第三方软件转存的 RAW 可能会伪造扩展名，确保文件由相机或扫描仪原生生成。
Nikon Z8 / Z9 高效率压缩 NEF 限制：如前所述，内置 LibRaw 暂不支持 HE 与 HE* 编码。解决途径为在相机机内改用常规无损压缩重新翻拍，或使用官方免费的 Adobe DNG Converter 批量转为标准 DNG。
哈苏 Flextight .fff 确认：自 v1.1.0 起已原生支持扫描仪 TIFF 解码管线，无需再行修改设备标识符字符串。若遇报错，检查源文件是否在 FlexColor 中保存为非标准分块格式。

2. 超大扫描仪 TIFF（数百兆至数 GB）内存占用与卡顿

扫描 8×10 大画幅生成的 16-bit TIFF 往往达到数 GB 级别。NexFilm 采用按行流式切片读取技术，在进入工作台时仅加载 2560 px 有界代理。若系统在导入阶段发生偶发卡顿，请确认系统虚拟内存页面文件（Swap/Pagefile）至少预留了 16 GB 磁盘空余空间。

3. 工作台预览与最终全尺寸导出存在微小视觉差异的原因

有界代理与全分辨率流式解算的分工：工作台预览实时运行在长边 2560 px 的高质量有界代理图上，而导出则从磁盘拉取原始高分辨率矩阵进行全图计算。
锐度与颗粒微观表现：虽然细节面板的全部锐化与清晰度半径均以长边 2560 px 严格等比换算，但在宏观上保持了完全相同的相对锐度；但在极高倍率放大下，数千万像素原始文件的微观银盐颗粒分布在抗锯齿重采样下会显现出更丰富的细节。正式批量输出前，先导出一张具有代表性的画面进行试片，是暗房操作的标准范式。

4. 从 v1.0.2 升级至 v1.1.0 后缩略图变黑或清空

在 v1.1.0 中，底层物理密度反相模型进行了重构升级。为防止旧版本中依据错误物理公式渲染的陈旧缩略图误导用户，数据库迁移程序在首次启动时会安全清空旧配方缩略图。用户只需进入胶卷，点击一次 自动反相 或 整卷批处理，系统即可瞬间按全新物理管线重建所有缩略图。

# 全局快捷键与鼠标手势全表

为保障高强度暗房作业的流畅性，NexFilm 精简并锁定了全局快捷键系统。软件严格拒绝编造未经实现的虚假热键，全系统真实受支持的 9 项核心快捷键与手势如下表所示：

按键与手势组合	具体触发功能	物理生效上下文与约束条件
`⌘`+`Z`（Windows: `Ctrl`+`Z`）	撤销上一步操作	全局有效。当光标聚焦于文字输入框（如修改备注或输入数值）时，优先响应文本撤销，不拦截系统级编辑。
`Shift`+`⌘`+`Z`（Windows: `Ctrl`+`Shift`+`Z` 或 `Ctrl`+`Y`）	恢复重做上一步操作	全局有效。在文本框外部时，恢复被撤销的调色或几何改动。
`←` / `→` 方向键	切换上一张 / 下一张底片画面	在工作台视图中且底片条可见时生效，切帧时保持画布当前缩放倍率不变。
`Enter`（回车键）	确认裁切或确认数值输入	在几何裁切编辑状态下确认裁切范围；在滑块数值输入框中确认保存新值。
`Esc`（退出键）	关闭对话框、取消菜单或退出编辑	在任何弹窗对话框打开时关闭窗口；在数值输入框中放弃修改恢复原值。
按住 `Space`（空格键）+ 鼠标拖拽	平移交互画布	在工作台主画布区域已载入画面时生效，支持任意方向平滑推移视野。
鼠标滚轮（画布区域 / 底片条区域）	以指针中心无级缩放 / 横向滚动底片条	指针在主画布上时，以当前光标像素坐标为锚点进行缩放；在底片条上时横向滚动画面序列。
鼠标滚轮（检查器滑块微调）	高精度细步长微调滑块数值	防误触安全机制：必须先用鼠标左键单机激活目标滑块，之后滚动滚轮才会微调数值。
按住 `Alt` 键 + 拖拽锐化滑块	实时切换灰度信号与二值边缘蒙版	在细节面板拖动数量/半径/细节时显示纯灰度边缘信号；拖动蒙版时显示黑白遮罩分布。松开按键即刻复原。

# 跨平台数据存储目录与备份迁移方案

理解 NexFilm 在不同操作系统下的持久化存储架构，对于保障长期胶卷资产的安全至关重要：

运行平台与版本类型	绝对数据存储目录物理路径
Windows 正式版	`%APPDATA%\NexFilm Engine\`（通常展开为 `C:\Users\<用户名>\AppData\Roaming\NexFilm Engine\`）
macOS 正式版	`~/Library/Application Support/NexFilm Engine/`
开发与 Debug 构建	本地 Git 仓库根目录工作区

核心数据库与镜像文件职责

nexfilm_user.db：应用的主 SQLite 数据库。存储了全部胶卷元数据、拍摄机身与乳剂字典、画面索引树、历史调色参数栈、输入域色彩科学记录以及长边 2560 px 有界代理缓存。该数据库不包含完整的原始图片文件副本，只记录其磁盘物理路径。
rolls.json：用于向后兼容与外部快速索引的镜像文件，在数据库提交时自动同步写入。

黄金备份与迁移准则

备份必须遵循“源片 + 数据库”双轨制

由于 NexFilm 坚决不复制原始大文件，仅备份 nexfilm_user.db 无法在原片丢失后恢复图像；反之，仅备份原图而丢失了数据库，则在重新导入后必须重新手动标定与调色。正确的备份策略为：

定期备份存储原始 RAW/TIFF 的物理磁盘目录；
同步备份上述平台对应的数据目录（特别是 nexfilm_user.db）。在更换电脑迁移数据时，只需将原图与数据目录拷贝至新设备相同路径下即可无缝继续工作。

# 已知限制诚实披露清单

作为秉承科学态度研发的开源软件，NexFilm 诚实披露当前版本存在的已知技术边界：

未购买商业机构代码签名证书：当前 Windows 安装包与 macOS .dmg 磁盘镜像均由开源社区通过自动化 CI 构建生成，未向商业认证机构付费购买昂贵的企业级代码签名证书，macOS 安装包尚未完成 Apple 官方公证。初次启动需要用户在系统安全设置中单次放行。
Nikon Z8 / Z9 HE/HE 高效率压缩 NEF 解码限制*：受限于底层开源解码器支持进度，目前尚无法原生读取高效率压缩格式，需使用 Adobe DNG Converter 转码。
老旧非主流扫描仪专有格式兼容性：全球各类中古扫描仪厂商众多，极少数老式专有格式（如某些罕见工业分光仪的专有格式）仍在持续扩展测试适配中。
暂未提供官方预编译的 Linux GUI 发行版：虽然核心 Rust 引擎与色彩管线具备完备的跨平台编译能力，但当前阶段官方发布的安装包主要聚焦于 Windows 与 macOS。
源片只读引用机制下的脱机敏感性：移动硬盘拔出或文件夹重命名会导致画面暂时脱机，需通过“定位文件”功能重新绑定路径。
硬件校正工作流的实验性状态：顶栏中的“硬件校正”模块涉及高难度光谱拟合算法，目前仍定性为实验性功能，其交互与参数模型在未来版本中仍可能持续演进。

# 开源许可、问题反馈与理论致谢

软件开源许可证

NexFilm Engine 遵循 GNU General Public License v3.0 only（GPL-3.0-only） 自由软件许可证发布。软件的全部前端代码、Rust 核心引擎、暗房着色器以及编译构建脚本均已在 GitHub 开源。用户享有自由运行、研读、修改与再分发的权利，但任何包含或衍生自本软件代码的二次分发作品，必须依据相同许可证开放完整源代码。

规范的问题反馈模板

如果在实际使用中遇到程序崩溃、解码异常或界面渲染故障，欢迎前往官方 GitHub 仓库提交 Issue。为了使维护者能够迅速复现并修复问题，请务必在提交时包含以下要素：

运行环境信息：操作系统版本（如 Windows 11 23H2、macOS Sonoma 14.5 Apple Silicon）以及当前运行的 NexFilm 版本号（如 v1.1.0）；
设备与素材类型：拍摄相机型号、翻拍微距镜头、背光光源品牌型号、源文件扩展名与精确像素尺寸；
清晰确切的复现步骤：从导入、框选到调色的完整操作流程描述，以及控制台捕获的完整错误日志堆栈。
隐私保护原则：请勿在公开 Issue 中上传包含家庭、个人敏感信息的高分辨率原片。如需提供样本排查，可提供翻拍色卡或无敏感人物的局部切片。

理论致谢与社区贡献

NexFilm 能够摆脱市面上传统软件对暴利商业预设的依赖，走向坚实的物理与数学可解释暗房，离不开开源社区的无私智慧。开发团队在此郑重致谢：

感谢知乎学者 @黄昊Haosky 与 @V777 在彩色负片无损去色罩理论、光谱重叠物理模型与光学密度对数反相领域的原创性学术探索与无私知识共享，他们的理论推导为 NexFilm 的核心管线设计提供了极为宝贵的数理灵感；
感谢所有为项目提交缺陷报告、跨平台构建脚本以及翻译建议的胶片摄影师与暗房工作者。