Jiangtherapee Online Complete Usage Guide

Jiangtherapee Online 完整使用指南

Jiangtherapee网站：https://y-g-jiang.github.io/JO.html

The guide is based on the current open-source codebase and focuses on real behavior implemented in App.tsx, components/*, services/*, utils/*, and bundled local subtrees. 本指南基于当前公开代码库，重点说明 App.tsx、components/*、services/*、utils/* 以及仓库内捆绑子目录里实际实现的行为。 The application is best understood as a browser-based RAW analysis workstation, measurement lab, and experimental image-processing sandbox built around sessions. 这个应用最适合被理解为一个基于浏览器的 RAW 分析工作站、测量实验室，以及围绕 session 组织的实验性图像处理沙盒。

0. Current Behavior Snapshot (2026-03-28)

0. 当前行为速览（2026-03-28）

• This snapshot reflects the current code after the recent SFR Lab, auto-plot, auto-bin, and shared-deshading updates.
• 本节反映的是最近一轮 SFR Lab、自动绘图、自动分箱与共享 deshading 更新之后的当前代码状态。
• SFR Lab now opens as a dedicated workspace centered on components/SfrLabWorkspace.tsx, with components/SfrModal.tsx serving as the embedded expert measurement core.
• SFR Lab 现在会打开为一个以 components/SfrLabWorkspace.tsx 为核心的专用工作区，而 components/SfrModal.tsx 则作为嵌入式专家测量核心存在。
• Entering SFR Lab starts a fresh lab-specific session and the workspace intentionally stays blank until a new image is loaded through the SFR Lab flow.
• 进入 SFR Lab 时会启动一个全新的实验室会话，在通过 SFR Lab 流程重新加载图像之前，工作区会刻意保持为空白状态。
• The current SFR source families are Unmix / BW, RGGB Raw, and Three-plane.
• 当前 SFR 的输入源类型是 Unmix / BW、RGGB Raw 和 Three-plane。
• RGGB Raw now defaults to Linear and supports green-phase modes Default, 1, and 2.
• RGGB Raw 现在默认按 Linear 处理，并支持 Default、1、2 三种绿色相位模式。
• In Three-plane, the manual expert panel now defaults to None, so the user must explicitly choose Luma, R, G, or B before adding a manual ROI. In Auto Block and explain, three-plane analysis defaults to luma.
• 在 Three-plane 模式下，手动专家面板现在默认是 None，因此用户必须先明确选择 Luma、R、G 或 B 之后才能添加手动 ROI；而在 Auto Block 和 explain 中，三平面的分析默认使用 luma。
• Deshading is now a shared switch: changing it in the left SFR workflow panel also refreshes the embedded analysis core, Auto Detect / Explain, auto-overlay MTF labels, and auto-plot/export data.
• Deshading 现在是共享开关：在左侧 SFR 工作流面板里切换它，也会同步刷新嵌入式分析核心、Auto Detect / Explain、自动叠加层上的 MTF 标签，以及自动绘图/导出数据。
• The left SFR workflow panel no longer exposes the old Official NR switch; normal batch work in SFR Lab treats that path as off.
• 左侧 SFR 工作流面板已经不再提供旧的 Official NR 开关；SFR Lab 的常规批处理工作流会把那条路径视为关闭。
• Auto Block now includes Auto Detect, Explain Selected ROI, canvas right-click deletion for detected edges, and Output Polar Point Sets.
• Auto Block 现在包含 Auto Detect、Explain Selected ROI、画布右键删除已检出边，以及 Output Polar Point Sets。
• The point-set / plot modal supports Polar, Image X, and Image Y; Polar further supports both MTF50 and Line Pair, plus JPG export.
• 点集 / 绘图弹窗支持 Polar、Image X 和 Image Y；其中 Polar 还进一步支持 MTF50 与 Line Pair 两种模式，并可导出 JPG。
• In auto mode, bin size is no longer typed manually in the left panel; each edge chooses its own best bin automatically.
• 在 auto 模式下，bin 尺寸不再通过左侧面板手填；每条边都会自动选择属于自己的最优 bin。
• The main canvas becomes point-to-point / pixel-perfect above 100% zoom so single-pixel inspection does not blur.
• 主画布在超过 100% 缩放时会切换为点对点 / 像素级显示，以避免单像素观察时发糊。
• Ctrl+S now quick-saves the current rendered result into JDNG: scalar or mosaic-style states export as single-plane JDNG plus CFA index, while full-color or true three-plane states export as three-plane JDNG.
• Ctrl+S 现在会把“当前界面渲染结果”快速保存为 JDNG：标量或马赛克风格状态导出为带 CFA 索引的单平面 JDNG，而全彩或真正三平面状态导出为三平面 JDNG。
• Single-plane JDNG imports default back into an unrendered raw-mosaic style view, while native three-plane JDNG imports stay three-plane.
• 单平面 JDNG 重新导入时会默认回到未渲染的 raw mosaic 风格视图，而原生三平面 JDNG 会保持三平面状态。
• The SFR UI currently keeps PTF disabled at the button level even though the lower-level math still exists in services/sfrProcessor.ts.
• 当前 SFR 界面层把 PTF 保持为不可选状态，尽管底层 services/sfrProcessor.ts 里仍然保留相关数学流程。
• The JiangBridge title-bar badge is intentionally hidden for security and compliance reasons, even though bridge-aware code still exists elsewhere in the app.
• 出于安全与合规原因，标题栏里的 JiangBridge 标识目前被刻意隐藏，但应用内其他位置仍然保留了与 bridge 相关的代码路径。

1. What This Project Is

1. 这个项目是什么

• Jiangtherapee is not a single-purpose viewer; it combines RAW decoding, display rendering, ROI measurement, spectral analysis, SFR analysis, color analysis, burst stacking, DNG export, and a lightweight Photoshop-like local adjustment system.
• Jiangtherapee 不是单一用途的看图器；它把 RAW 解码、显示渲染、ROI 测量、频谱分析、SFR 分析、色彩分析、连拍堆栈、DNG 导出以及一个轻量级类 Photoshop 局部调整系统整合在了一起。
• The codebase mixes production-style UI with many research tools, so some panels feel like lab instruments rather than consumer product dialogs.
• 这套代码同时混合了产品化界面和大量研究型工具，因此有些面板更像实验仪器而不是面向普通用户的消费级弹窗。
• The main entry point is index.tsx, which mounts App.tsx; almost every user-facing workflow eventually flows through App.tsx.
• 主入口是 index.tsx，它挂载 App.tsx；几乎所有用户可见流程最后都会经过 App.tsx。

2. Repository Layout

2. 仓库结构

• components/ contains the React UI, including the main canvas, header, sidebars, floating analysis windows, and all major lab modals.
• components/ 存放 React 界面，包括主画布、顶部栏、侧边栏、浮动分析窗口和所有主要实验室弹窗。
• services/ contains the imaging core, RAW processing, rendering backends, stacking engine, color science helpers, worker pools, DNG and TIFF writers, and persistence helpers.
• services/ 存放成像核心、RAW 处理、渲染后端、堆栈引擎、色彩科学辅助模块、worker 池、DNG/TIFF 写出器以及持久化辅助代码。
• utils/ contains reusable math, selection sizing, rotated-view mapping, projective-view math, and channel model helpers.
• utils/ 存放通用数学、选区尺寸、旋转视图映射、投影视图数学以及通道模型辅助函数。
• hooks/ currently contains useJiangBridge.ts, which monitors the external local helper bridge on http://localhost:5428/health.
• hooks/ 目前包含 useJiangBridge.ts，它负责监测位于 http://localhost:5428/health 的本地外部辅助桥接服务。
• lensfun/ stores bundled XML lens metadata used by the PS distortion-correction workflow.
• lensfun/ 存放捆绑的 XML 镜头元数据，供 PS 畸变校正流程使用。
• vendor/, LibRaw-Wasm-main/, drizzle-main/, Handheld-Multi-Frame-Super-Resolution-main/, ImageStackAlignator-master/, and code/ are bundled reference or dependency subtrees rather than the normal React application surface.
• vendor/、LibRaw-Wasm-main/、drizzle-main/、Handheld-Multi-Frame-Super-Resolution-main/、ImageStackAlignator-master/ 和 code/ 更偏向捆绑参考实现或依赖子树，而不是常规 React 应用界面层。
• dist/ is build output and node_modules/ is installed dependency content; they matter operationally but are not the primary handwritten source modules.
• dist/ 是构建产物，node_modules/ 是已安装依赖内容；它们在运行层面有意义，但并不是主要的手写源码模块。

3. How To Start The App

3. 如何启动应用

• The package name is image-noise-snr-analyzer, and the normal scripts are npm run dev, npm run build, and npm run preview.
• 包名是 image-noise-snr-analyzer，常规脚本是 npm run dev、npm run build 和 npm run preview。
• npm run dev starts the Vite development server and is the normal mode for interactive exploration and UI changes.
• npm run dev 会启动 Vite 开发服务器，是交互探索和界面开发时的常规模式。
• npm run build performs a production build and is the fastest broad regression check after UI or logic edits.
• npm run build 会执行生产构建，是修改界面或逻辑后最直接的广义回归检查。
• The application expects a browser environment with Canvas, Web Workers, and preferably WebGPU or WebGL; when those are unavailable it can fall back to CPU render paths for many operations.
• 应用预期运行在支持 Canvas、Web Worker，并最好支持 WebGPU 或 WebGL 的浏览器环境中；当这些能力不可用时，许多操作仍可回退到 CPU 渲染路径。

4. Core Mental Model

4. 核心心智模型

• The dominant state unit is a session, which usually corresponds to one loaded image or RAW file together with its decoded data, preview, metadata, and optional PS document.
• 这个应用最核心的状态单位是 session，它通常对应一张已载入图像或 RAW 文件，以及与之关联的解码数据、预览图、元数据和可选的 PS 文档。
• App.tsx keeps an array of sessions plus a currentIndex, so switching images is conceptually switching the active session.
• App.tsx 内部维护一个 session 数组和一个 currentIndex，因此切换图片本质上就是切换当前活动 session。
• Floating analysis windows such as histogram, power spectrum, quantization, and Pearson are attached to ROI rectangles and behave like tool windows over the main image.
• 直方图、功率谱、量化分析、Pearson 等浮动分析窗口都依附于 ROI 矩形，并像工具窗一样叠加在主图像之上。
• PS mode is effectively a second operating mode inside the same app, where the selected session gains masks, adjustment layers, guides, transforms, and its own preview composition path.
• PS 模式本质上是同一应用中的第二套工作模式，进入后当前 session 会拥有蒙版、调整图层、参考线、几何变换，以及自己独立的预览合成路径。

5. Typical First-Time Workflow

5. 初次上手的典型流程

• Load a RAW file or a standard image from the header, wait for decode and preview generation, then inspect the main canvas before opening any analysis labs.
• 先从顶部栏加载 RAW 文件或普通图像，等待解码和预览生成，然后先观察主画布，再决定是否打开分析实验室。
• Use the canvas to pan, zoom, and draw or adjust a region of interest; most analysis tools consume that region or a set of marked regions.
• 通过主画布进行平移、缩放，并绘制或调整感兴趣区域；大多数分析工具都以这个区域或一组标记区域为输入。
• Open Histogram, Power Spectrum, Quantization, or Pearson windows when you need single-ROI measurement, and open specialized labs such as PTC, SFR, Color Lab, or Stacking when you need structured workflows.
• 当你需要单个 ROI 测量时，打开 Histogram、Power Spectrum、Quantization 或 Pearson 窗口；当你需要结构化流程时，再打开 PTC、SFR、Color Lab 或 Stacking 等专用实验室。
• If you want local edits instead of pure analysis, switch into PS mode and work with masks, layers, guides, crop, rotate, and export.
• 如果你想做局部编辑而不是纯分析，就切换到 PS 模式，使用蒙版、图层、参考线、裁切、旋转和导出功能。

6. App.tsx As The Orchestrator

6. App.tsx 作为总控中心

• App.tsx imports nearly every visible tool in the application and is the central place where data loading, render setting updates, modal visibility, ROI windows, and PS state are coordinated.
• App.tsx 几乎导入了应用里所有可见工具，是统一协调数据加载、渲染设置更新、弹窗显示、ROI 窗口以及 PS 状态的总控位置。
• It decides when to call RAW processors, when to use GPU renderers, when to save or restore sessions, and when to block actions because PS mode is active.
• 它决定何时调用 RAW 处理器、何时使用 GPU 渲染器、何时保存或恢复 session，以及何时因为 PS 模式激活而阻止某些操作。
• If you want to understand the whole product behavior before diving into individual modules, App.tsx is the correct first file to read in depth.
• 如果你想先理解整个产品行为，再深入各个模块，那么最应该优先精读的文件就是 App.tsx。
• The practical consequence for users is that almost every tool shares the same loaded image state, display settings, and workspace persistence model.
• 对用户而言，这意味着几乎所有工具都共享同一套已加载图像状态、显示设置和工作区持久化模型。

7. Session Persistence And Workspace Restore

7. Session 持久化与工作区恢复

• The app persists workspace structure with services/workspaceStore.ts, using localStorage for the workspace index and IndexedDB for raw file buffers and PS workflows.
• 应用通过 services/workspaceStore.ts 持久化工作区结构，使用 localStorage 保存工作区索引，使用 IndexedDB 保存原始文件 buffer 和 PS 工作流。
• This means a reload can restore a surprising amount of state, including which sessions existed and which backing blobs belonged to them.
• 这意味着页面刷新后可以恢复相当多的状态，包括曾有哪些 session，以及哪些底层 blob 属于这些 session。
• The cleanup routine removes orphaned blobs when sessions disappear, which is important for keeping browser storage under control.
• 清理逻辑会在 session 消失后移除孤立 blob，这对控制浏览器存储占用非常重要。
• As a user, you should think of the app more like a lightweight desktop workspace than a disposable single-page page state.
• 作为用户，你更应该把它理解成一个轻量桌面工作区，而不是一次性单页状态。

8. Header Usage

8. 顶部栏用法

• components/Header.tsx is the main command bar for loading files, opening labs, toggling sidebar visibility, entering PS mode, and exposing app-level actions such as EXIF, database, and DNG-related workflows.
• components/Header.tsx 是主命令栏，负责加载文件、打开实验室、切换侧栏显示、进入 PS 模式，并暴露 EXIF、数据库和 DNG 相关流程等应用级操作。
• The header includes both ordinary file loading and PTC CSV import entry points, so not every import action goes through the same hidden input element.
• 顶部栏同时提供普通文件加载和 PTC CSV 导入入口，因此并不是所有导入动作都走同一个隐藏输入框。
• Several actions are deliberately blocked or guarded while PS mode is open, because PS mode introduces its own editing context and consistency requirements.
• 某些操作在 PS 模式打开时会被明确阻止或保护，因为 PS 模式引入了独立的编辑上下文和一致性要求。
• If a feature feels “missing,” always check the header first, because many major tools are launched there instead of from the sidebar.
• 如果你觉得某个功能“找不到”，先检查顶部栏，因为许多大功能是从这里启动的，而不是从侧边栏。

9. Main Canvas Usage

9. 主画布用法

• components/ImageCanvas.tsx is where image display, pan and zoom interaction, ROI drawing, marker interaction, PS mask overlay drawing, guide drawing, ellipse drafting, and brush painting all converge.
• components/ImageCanvas.tsx 是图像显示、平移缩放交互、ROI 绘制、标记交互、PS 蒙版叠加绘制、参考线绘制、椭圆草绘和笔刷涂抹的汇合点。
• The canvas is not just a display surface; it is also the geometric input device for most measurement and PS editing tasks.
• 这个画布不仅是显示表面，同时也是多数测量与 PS 编辑任务的几何输入设备。
• Offscreen canvas caching is used to keep redraw behavior responsive, especially when overlays and transforms become dense.
• 为了在叠加元素和几何变换变多时仍保持重绘流畅，内部使用了离屏 canvas 缓存。
• Selection geometry also passes through helpers such as rotated-view mapping and power-of-two sizing, so the rectangle you see may be constrained by mode-specific rules.
• 选区几何还会经过旋转视图映射和二次幂尺寸约束等辅助逻辑，因此你看到的矩形可能会受到模式特定规则的限制。

10. Zoom, Rotation, And Selection Behavior

10. 缩放、旋转与选区行为

• components/ZoomControls.tsx gives explicit zoom control, but the deeper selection math lives in utils/viewRotation.ts and utils/selectionSizing.ts.
• components/ZoomControls.tsx 提供显式缩放控制，但更底层的选区数学逻辑位于 utils/viewRotation.ts 和 utils/selectionSizing.ts。
• In the current canvas implementation, zoom ratios above 100% deliberately disable smoothing and switch to point-to-point display so one image pixel maps to a crisp block instead of a soft interpolated patch.
• 在当前画布实现中，超过 100% 的缩放会刻意关闭平滑插值并切换到点对点显示，因此单个图像像素会变成清晰的方块，而不是柔化后的插值斑块。
• That policy is paired with device-pixel-ratio-aware backing-store sizing, which reduces high-DPI blur when you inspect a file at large zoom ratios.
• 这套策略还配合了基于 device pixel ratio 的 backing store 尺寸处理，因此在高 DPI 屏幕上放大查看时也能减少额外模糊。
• viewRotation.ts handles normalized angle logic and coordinate conversion between image space and rotated view space.
• viewRotation.ts 负责标准化角度逻辑，以及图像坐标和旋转后视图坐标之间的转换。
• selectionSizing.ts provides power-of-two clamping and snapping helpers, which matter for FFT-style analysis that benefits from power-of-two ROI dimensions.
• selectionSizing.ts 提供二次幂约束与吸附辅助函数，这对偏好二次幂 ROI 尺寸的 FFT 类分析尤其重要。
• If your ROI seems to “snap” or resist free resize, it is often because power-of-two locking or lab-specific geometry assumptions are active.
• 如果你的 ROI 看起来会“吸附”或不允许自由缩放，通常是因为启用了二次幂锁定，或者某个实验室对几何尺寸有特定假设。

11. Sidebar System Overview

11. 侧栏系统总览

• components/ControlPointSliders.tsx is the wrapper that switches between GUI mode and terminal mode, delegating to GuiSidebar.tsx and TerminalSidebar.tsx.
• components/ControlPointSliders.tsx 是侧栏总包装器，它在 GUI 模式和终端模式之间切换，并把工作分别委托给 GuiSidebar.tsx 和 TerminalSidebar.tsx。
• It also auto-detects black levels from EXIF or decoded RAW metadata and can auto-apply them when bridge-connected RAW sessions are loaded.
• 它还会尝试从 EXIF 或已解码 RAW 元数据中自动识别黑电平，并在桥接可用的 RAW session 加载后自动应用。
• This means the sidebar is not a dumb control collection; it contains policy about what settings should be inferred and when.
• 这意味着侧栏并不是简单的控件合集；它内部还包含了“何时推断设置、推断什么设置”的策略逻辑。
• If display settings unexpectedly prefill themselves, the first place to inspect is the auto-apply logic inside ControlPointSliders.tsx.
• 如果显示设置会意外自动填充，首先应该检查 ControlPointSliders.tsx 中的自动应用逻辑。

12. GUI Sidebar In Daily Use

12. GUI 侧栏的日常用法

• components/GuiSidebar.tsx is one of the biggest files in the project because it centralizes display settings, lab controls, chart calibration, batch tools, PS controls, and lens-related parameter entry.
• components/GuiSidebar.tsx 是整个项目里最大的文件之一，因为它把显示设置、实验室控制、色卡校准、批处理工具、PS 控制以及镜头相关参数输入都集中到了同一个界面。
• In normal use, start from exposure, white balance, black level, render mode, and demosaic-related controls before touching advanced experimental panels.
• 日常使用时，建议先从曝光、白平衡、黑电平、渲染模式和 demosaic 相关控件开始，再进入更高级的实验性面板。
• The sidebar also exposes entry points for DR Lab, FFT Lab, SFR Lab, Color Lab, stacking, DNG export, and batch workflows, so it acts like a mission control console.
• 侧栏还提供 DR Lab、FFT Lab、SFR Lab、Color Lab、堆栈、DNG 导出和批处理流程的入口，因此它更像一个任务控制台。
• Lensfun XML loading is wired here through import.meta.glob('../lensfun/*.xml'), which matters for PS lens distortion correction.
• Lensfun XML 的加载也在这里通过 import.meta.glob('../lensfun/*.xml') 接好，这对 PS 镜头畸变校正功能很关键。

13. DR Lab And Chart Marking

13. DR Lab 与标记流程

• The DR Lab workflow is built around marking corners or ROIs on the canvas and then generating or analyzing structured patch sets.
• DR Lab 流程的核心是在画布上标记角点或 ROI，然后生成或分析结构化 patch 集合。
• GuiSidebar.tsx exposes controls for DR ROI size, grid rows and columns, start-marking actions, test-pattern generation, and batch processing of single files or pairs.
• GuiSidebar.tsx 提供了 DR ROI 尺寸、网格行列数、开始标记、测试图生成以及单文件或成对文件批处理等控件。
• This lab is useful when you want repeated measurements over a grid instead of a single freehand ROI.
• 当你希望在网格上做重复测量，而不是只测一个自由 ROI 时，这个实验室就很有用。
• The practical trick is to settle geometry first, because later measurement quality depends more on stable marking than on tiny display-setting differences.
• 实际操作时最重要的技巧是先把几何位置定稳，因为后续测量质量往往比起细小显示参数差异，更依赖标记是否稳定。

14. FFT Lab And Frequency-Domain Workflows

14. FFT Lab 与频域流程

• FFT Lab is oriented around pair or stack analysis and eventually feeds tools such as the power spectrum windows and cross-calculation helper.
• FFT Lab 主要面向成对或堆栈分析，最终会服务于功率谱窗口和交叉计算辅助工具等功能。
• The sidebar can process image pairs, batch differences, and stack FFT jobs, while the terminal mode exposes scripted commands for loading pair A or B and running FFT operations.
• GUI 侧栏可以处理图像对、批量差分和堆栈 FFT 任务，而终端模式则提供加载 A/B 图和执行 FFT 的脚本式命令。
• Because frequency analysis is sensitive to ROI shape, the power-of-two selection lock often makes more sense here than in purely visual workflows.
• 由于频域分析对 ROI 形状很敏感，因此在这里启用二次幂选区锁定通常比在纯视觉流程中更合理。
• If you want consistent spectral comparisons across files, reuse the same ROI size and avoid changing rendering assumptions between runs.
• 如果你想在多个文件之间做一致的频谱比较，就应复用同样的 ROI 尺寸，并避免在不同运行之间改动渲染假设。

15. X-Trans Controls

15. X-Trans 控制

• The app contains explicit X-Trans support hooks, including forced X-Trans mode and phase controls exposed in the sidebar and terminal.
• 应用内置了明确的 X-Trans 支持入口，包括在侧栏和终端中可见的强制 X-Trans 模式与相位控制。
• rawProcessor.ts also exports convertXTransToDNG, which shows that X-Trans handling is not only for display but also for conversion workflows.
• rawProcessor.ts 还导出了 convertXTransToDNG，这说明 X-Trans 处理不仅用于显示，也用于转换工作流。
• If your loaded mosaic does not decode correctly, phase adjustment is one of the first advanced controls worth testing.
• 如果你加载的马赛克解码结果不正确，相位调整就是最值得优先尝试的高级控制之一。
• Treat X-Trans mode as a sensor-layout override rather than a cosmetic switch, because it changes the interpretation of the RAW data structure.
• 应把 X-Trans 模式理解为一种传感器布局覆盖，而不是视觉开关，因为它会改变 RAW 数据结构的解释方式。

16. Terminal Sidebar

16. 终端侧栏

• components/TerminalSidebar.tsx provides a CLI-like interface for users who prefer exact commands instead of many UI controls.
• components/TerminalSidebar.tsx 为喜欢精确命令而不是大量图形控件的用户提供了类 CLI 界面。
• Supported commands include help, ev, wb, bl, demo, matrix, xtrans, render, sel, mark, gen test, fft load, fft run, crosscalc, and cls.
• 已支持的命令包括 help、ev、wb、bl、demo、matrix、xtrans、render、sel、mark、gen test、fft load、fft run、crosscalc 和 cls。
• The terminal keeps a local settings buffer so you can stage multiple parameter changes and only push them to the main app when you run render or apply.
• 终端内部维护一份本地设置缓冲区，因此你可以先连续修改多个参数，再通过 render 或 apply 一次性推送到主应用。
• ROI stats are also printed back into the terminal when selection changes, so it doubles as a lightweight logging surface.
• 当选区变化时，ROI 统计也会被回写到终端，因此它同时还是一个轻量日志界面。
• Use terminal mode when you want reproducible typed workflows or when exploring parameter combinations faster than clicking through the GUI.
• 当你需要可复现的文本化工作流，或者想比点 GUI 更快地试参数组合时，就适合使用终端模式。

17. Floating Window System

17. 浮动窗口系统

• Histogram, power spectrum, quantization, and Pearson windows are not full-screen pages; they are floating measurement panels that coexist with the main canvas.
• 直方图、功率谱、量化分析和 Pearson 窗口并不是全屏页面，而是与主画布共存的浮动测量面板。
• components/DraggablePanel.tsx provides the shared drag shell for many windows, including touch and mouse dragging, focus changes, and boundary clamping.
• components/DraggablePanel.tsx 为许多窗口提供了统一的可拖拽外壳，支持触摸与鼠标拖动、焦点切换和边界限制。
• The drag surface intentionally ignores button and input descendants, which prevents accidental panel moves while using controls.
• 拖拽层会刻意避开按钮和输入框后代元素，从而防止你在操作控件时误拖整个窗口。
• Operationally, this means the UI behaves more like a desktop measurement environment than a linear wizard.
• 在操作体验上，这让整个界面更像桌面测量环境，而不是线性的向导式页面。

18. Histogram Modal

18. 直方图窗口

• components/HistogramModal.tsx analyzes the current ROI and can also work in stack mode when multiple files are supplied.
• components/HistogramModal.tsx 用于分析当前 ROI，在传入多个文件时也支持堆栈模式。
• It can call plain calculateHistogram logic or leverage stackAnalysisWebgpu for stack-aware processing depending on context and available backend support.
• 它会根据上下文和后端能力，在普通 calculateHistogram 逻辑和支持堆栈的 stackAnalysisWebgpu 之间切换。
• Key controls include channel selection, min and max range, bin count, point-to-point mode, and a theoretical Gaussian overlay.
• 关键控制项包括通道选择、最小值与最大值范围、bin 数量、point-to-point 模式以及理论高斯叠加。
• Use histogram mode when you want distribution shape, clipping behavior, or noise spread rather than spatial structure.
• 当你关注分布形状、截断行为或噪声扩散，而不是空间结构时，应使用直方图模式。

19. Power Spectrum Modal

19. 功率谱窗口

• components/PowerSpectrumModal.tsx is one of the most sophisticated analysis windows in the codebase and supports multiple processing strategies.
• components/PowerSpectrumModal.tsx 是整个代码库里最复杂的分析窗口之一，并支持多种处理策略。
• It uses calculatePowerSpectrum, stackAnalysisWebgpu, decoded stack-frame helpers, and the powerSpectrumWorkerPool depending on whether you analyze a single ROI, a batch stack, or a heavy multi-file workflow.
• 它会根据你是在分析单个 ROI、批量堆栈还是较重的多文件流程，在 calculatePowerSpectrum、stackAnalysisWebgpu、已解码堆栈帧辅助工具和 powerSpectrumWorkerPool 之间切换。
• Feature switches include Hanning windows, Welch segmentation, H and V curve display, row or column interlace views, integration modes, and theoretical overlays for sigma, kernel, or noise models.
• 它的功能开关包括 Hanning 窗、Welch 分段、水平与垂直曲线显示、行列交错视图、积分模式，以及 sigma、kernel 或噪声模型的理论叠加。
• Backend preference is roughly true WebGPU batch first, then worker-assisted methods, then local CPU fallback, which is why performance can vary dramatically by browser and dataset size.
• 后端优先级大致是先尝试真正的 WebGPU 批处理，再尝试 worker 辅助方法，最后回退到本地 CPU，因此不同浏览器和数据规模下性能差异会非常明显。

20. 2D Spectrum Modal

20. 二维频谱窗口

• components/TwoDSpectrumModal.tsx complements the main power spectrum view by showing two-dimensional spectrum structure instead of only reduced curves.
• components/TwoDSpectrumModal.tsx 是主功率谱视图的补充，它展示的是二维频谱结构，而不仅仅是降维后的曲线。
• Use it when you need to inspect anisotropy, directional artifacts, repeating texture signatures, or row and column imbalance that curves can hide.
• 当你需要检查各向异性、方向性伪影、重复纹理特征，或曲线容易掩盖的行列不平衡时，应使用它。
• This window is conceptually downstream of the same spectral math but better suited for diagnosing structured artifacts than for quoting a single summary value.
• 这个窗口在概念上建立在同一套频谱数学之上，但它比起给出单个摘要数值，更适合诊断结构化伪影。

21. Quantization Modal

21. 量化分析窗口

• components/QuantizationModal.tsx focuses on quantization-related statistics rather than general noise distribution or spectral content.
• components/QuantizationModal.tsx 聚焦的是量化相关统计，而不是一般噪声分布或频谱内容。
• Its underlying math comes from calculateQuantizationStats in services/rawProcessor.ts, so the modal is tightly coupled to raw-domain sample interpretation.
• 它底层依赖的是 services/rawProcessor.ts 里的 calculateQuantizationStats，因此这个窗口与 RAW 域样本解释紧密耦合。
• Use this tool when you need to understand step sizes, level occupancy, or whether an image region is dominated by discrete code values.
• 当你需要理解步进大小、码值占用情况，或者判断某个区域是否被离散码值主导时，就应该使用这个工具。

22. Pearson Modal

22. Pearson 窗口

• components/PearsonModal.tsx is for correlation-style analysis, powered by Pearson accumulators and finalization logic exported from rawProcessor.ts.
• components/PearsonModal.tsx 用于相关性分析，底层由 rawProcessor.ts 导出的 Pearson 累积器和最终计算逻辑提供支持。
• This is useful when you want to quantify relationships between paired data streams or channels rather than just inspect each one independently.
• 当你想量化成对数据流或不同通道之间的关系，而不是分别独立观察它们时，这个工具就很有价值。
• It belongs to the “measurement instrument” category of modules and is best used with carefully chosen ROIs and controlled preprocessing assumptions.
• 它属于“测量仪器型”模块，最适合配合精心选择的 ROI 和受控预处理假设一起使用。

23. About, EXIF, Database, And CrossCalc

23. About、EXIF、数据库与 CrossCalc

• AboutModal.tsx is a resource hub that links to related external tools and also displays obfuscated view statistics pulled from hidden DOM counters.
• AboutModal.tsx 更像一个资源中心，它链接到若干外部相关工具，并显示从隐藏 DOM 计数器读取的混淆访问统计。
• ExifModal.tsx exposes file metadata for inspection and is the place to verify camera model, black-level tags, or other decode-relevant metadata.
• ExifModal.tsx 用来查看文件元数据，是核对相机型号、黑电平标签或其他解码相关元数据的主要位置。
• DatabaseModal.tsx is a searchable black-level database UI backed by services/cameraData.ts, with SearchBar.tsx and CameraCard.tsx providing filtering and presentation.
• DatabaseModal.tsx 是一个可搜索的黑电平数据库界面，底层依赖 services/cameraData.ts，并由 SearchBar.tsx 与 CameraCard.tsx 负责筛选和呈现。
• CrossCalcModal.tsx is a compact calculator that estimates original white-noise sigma from horizontal and vertical measurement inputs.
• CrossCalcModal.tsx 是一个小型计算器，用于根据水平和垂直测量输入估算原始白噪声 sigma。
• These modules are smaller than the main labs, but together they support the app’s role as a measurement workstation rather than only an editor.
• 这些模块虽然比主要实验室更小，但组合起来强化了应用作为测量工作站而不仅仅是编辑器的定位。

24. Color Lab

24. Color Lab

• components/ColorLabModal.tsx expects 24 patch statistics and computes a color matrix using services/colorLab.ts.
• components/ColorLabModal.tsx 预期接收 24 个色块统计值，并通过 services/colorLab.ts 计算颜色矩阵。
• It lets you toggle between RGGB and BGGR, adjust patch sampling size, enter or revise four black-level values, and copy the resulting matrix string for use as a custom matrix.
• 它允许你在 RGGB 和 BGGR 之间切换、调整色块采样尺寸、输入或修正四通道黑电平，并把结果矩阵字符串复制出去作为自定义矩阵使用。
• On open, it tries to infer black levels from patch 24, treating the last patch as a black patch heuristic.
• 打开后它会尝试从第 24 个 patch 反推黑电平，也就是把最后一个色块当作黑块做启发式估计。
• The tool is best used after reliable chart marking, because the matrix result depends much more on correct patch geometry than on UI cosmetics.
• 这个工具最适合在可靠的色卡标记完成后使用，因为矩阵结果对 patch 几何是否正确的依赖远大于对界面细节的依赖。

25. SFR Lab

25. SFR 实验室

• The current SFR UI is split into two layers: components/SfrLabWorkspace.tsx provides the dedicated workspace shell, while components/SfrModal.tsx remains the embedded expert measurement panel.
• 当前 SFR 界面分成两层：components/SfrLabWorkspace.tsx 提供专用工作区外壳，而 components/SfrModal.tsx 继续承担嵌入式专家测量面板的职责。
• Opening SFR Lab no longer means simply reusing the old floating-window flow; it opens a lab-specific page-like workspace with its own loading cadence, controls, auto-block workflow, and plot/export staging.
• 打开 SFR Lab 现在不再只是复用旧的浮窗流程；它会打开一个更像独立页面的实验室工作区，并拥有自己的加载节奏、控件组织、自动找边流程和绘图/导出分层。
• The workspace is designed around three source families: Unmix / BW, RGGB Raw, and Three-plane.
• 这个工作区围绕三类输入源组织：Unmix / BW、RGGB Raw 和 Three-plane。
• RGGB Raw is the Bayer-green measurement path. It now defaults to Linear, and its phase selector offers Default, 1, and 2.
• RGGB Raw 是 Bayer 绿通道测量路径。它现在默认按 Linear 处理，并提供 Default、1、2 三种绿相位选择。
• Three-plane is the direct color-input path. In the expert panel it now starts from None, so the user must explicitly choose Luma, R, G, or B before adding a manual ROI. In Auto Block, three-plane analysis defaults to luma.
• Three-plane 是直接彩色输入路径。在专家面板里它现在从 None 开始，因此用户必须先明确选择 Luma、R、G 或 B 之后才能添加手动 ROI；而在 Auto Block 中，三平面的分析默认使用 luma。
• Unmix / BW is treated as a single-channel source. If raw-domain unmix data exists, SFR uses that linear signal; otherwise it falls back to the BW-style single-channel preview path.
• Unmix / BW 会被视为单通道输入；如果 raw 域 unmix 数据存在，SFR 会优先使用那条线性信号，否则回退到 BW 风格的单通道预览路径。
• Auto Block is now a first-class part of SFR Lab: it can auto-detect usable blocks, explain why a selected ROI failed, remove a detected edge by right-clicking it on the canvas, and open the dedicated point-set / plot export modal.
• Auto Block 现在已经是 SFR Lab 的一等公民：它可以自动检测可用块、解释某个已选 ROI 为什么失败、在画布上右键删除某条已检出边，并打开专门的点集 / 绘图导出弹窗。
• The dedicated point-set / plot modal can output Polar, Image X, and Image Y plots. Polar supports both MTF50 and Line Pair, supports center picking and confirmation, and can export JPG.
• 专用点集 / 绘图弹窗可以输出 Polar、Image X、Image Y 三类图；其中 Polar 同时支持 MTF50 和 Line Pair，支持场中心选择与确认，并可导出 JPG。
• Deshading is now shared across the left workflow panel and the embedded expert core, so changing it refreshes current SFR numbers, plot data, auto-overlay labels, and auto-derived export values together.
• Deshading 现在在左侧工作流面板与嵌入式专家核心之间共享，因此切换它会同时刷新当前 SFR 数值、绘图数据、自动叠加标签以及自动导出数值。
• The left workflow panel no longer exposes the old Official NR toggle. In normal SFR Lab batch work that path is treated as off.
• 左侧工作流面板已经不再提供旧的 Official NR 开关；在当前 SFR Lab 的常规批处理工作流里，这条路径按关闭处理。
• The Auto Detection Tuning panel still exists, but it should mainly be understood as a candidate-screening and measurement-region panel rather than the main place to learn SFR math.
• Auto Detection Tuning 面板仍然存在，但更适合把它理解为候选筛选与测量区域控制面板，而不是理解 SFR 数学本体的主要入口。

26. PTC Modal

26. PTC 拟合窗口

• components/PTCModal.tsx is a large, specialized workflow for photon transfer curve style fitting and visualization.
• components/PTCModal.tsx 是一个大型专用工作流，用于光子转移曲线风格的拟合与可视化。
• The modal handles plotting, fit-range selection, draggable fit bounds, export of plotted images, and optional fluorescent point styling for exported charts.
• 这个窗口负责绘图、拟合区间选择、可拖拽拟合边界、图表图片导出，以及导出图中可选的荧光点样式。
• In the current code, the fit-range blue lines are draggable and the export path can prompt for whether the PTC point cloud should use enlarged glow rendering.
• 在当前代码中，拟合区间的蓝色边界线可以拖动，而导出流程也可以让你选择 PTC 点云是否采用放大的荧光渲染。
• Use this module when you need a more guided and presentation-ready workflow than the generic measurement windows provide.
• 当你需要比通用测量窗口更有引导性、也更适合展示输出的流程时，就该使用这个模块。

27. DNG Export Modal

27. DNG 导出窗口

• components/DngExportModal.tsx is a browser-side DNG writer built around Pyodide and an embedded Python script.
• components/DngExportModal.tsx 是一个运行在浏览器端的 DNG 写出器，核心依赖 Pyodide 和内嵌 Python 脚本。
• It lets you control bit shift, linear shift, black level, color matrix, CFA pattern, watermark behavior, and batch export behavior.
• 它允许你控制 bit shift、线性偏移、黑电平、颜色矩阵、CFA 模式、水印行为和批量导出行为。
• The modal uses decoded RAW-domain data via processRawDataOnly, so it is closer to a technical export path than a generic “save image” dialog.
• 这个窗口通过 processRawDataOnly 使用已解码的 RAW 域数据，因此它更像一个技术型导出通道，而不是普通的“保存图片”对话框。
• Use it when you need to preserve or synthesize sensor-domain structure for external software rather than only export a rendered preview.
• 当你希望为外部软件保留或合成传感器域结构，而不仅仅导出渲染预览时，就应该使用它。

28. Save Z8 Modal

28. Save Z8 窗口

• components/SaveZ8Modal.tsx is a highly specialized rescue/export workflow aimed at Nikon Z8 style data repair and DNG generation.
• components/SaveZ8Modal.tsx 是一个高度专门化的修复与导出流程，目标是面向 Nikon Z8 风格数据的处理与 DNG 生成。
• It loads Pyodide, processes RAW data, analyzes specific count values such as 1006, 1007, and 1008, applies corrective logic, and then runs a custom Python DNG writer.
• 它会加载 Pyodide、处理 RAW 数据、分析 1006、1007、1008 等特定码值、应用修正逻辑，然后运行自定义 Python DNG 写出器。
• Constants such as Z8_MATRIX, Z8_BLACK, and Z8_SHIFT are hard-coded, which tells you this is not a generic converter but a task-driven utility.
• Z8_MATRIX、Z8_BLACK 和 Z8_SHIFT 这类常量是硬编码的，这说明它不是通用转换器，而是面向特定任务的专用工具。
• Use this module only when your workflow matches that rescue assumption set; otherwise the general DNG export path is more appropriate.
• 只有当你的工作流确实符合这组修复假设时才应使用这个模块；否则更适合走通用 DNG 导出流程。

29. Stacking Modal

29. 堆栈窗口

• components/StackingModal.tsx is the user-facing control panel for burst stacking and multi-frame processing.
• components/StackingModal.tsx 是连拍堆栈和多帧处理的用户控制面板。
• It exposes formula entry, black levels, plus-plus frame ranges, output mode selection such as dng16 or jdngf32, and alignment settings.
• 它提供公式输入、黑电平、++ 帧范围、输出模式选择（如 dng16 或 jdngf32）以及对齐设置。
• The underlying services/stackingProcessor.ts is huge and supports ECC motion models, OpenCV-assisted paths, optional APAP-style logic, and output serialization.
• 底层的 services/stackingProcessor.ts 体量很大，支持 ECC 运动模型、OpenCV 辅助路径、可选的 APAP 风格逻辑以及输出序列化。
• This workflow is best thought of as an experimental burst lab, not a one-click consumer “stack photos” button.
• 这个流程最好被理解为一个实验性连拍实验室，而不是面向普通用户的一键“叠照片”按钮。

30. PS Mode Overview

30. PS 模式总览

• PS mode is a substantial subsystem, not a cosmetic edit layer, and its state lives inside the session as a PsDocument.
• PS 模式是一个完整子系统，而不是简单的视觉编辑层，它的状态以 PsDocument 的形式存放在 session 内部。
• The central logic lives in services/psDocument.ts, while UI surfaces are spread across ImageCanvas.tsx, PsEditorPanel.tsx, GuiSidebar.tsx, and App.tsx.
• 核心逻辑位于 services/psDocument.ts，而界面层则分散在 ImageCanvas.tsx、PsEditorPanel.tsx、GuiSidebar.tsx 和 App.tsx 中。
• When PS mode is open, the app protects certain global actions because masks, layers, transforms, and history create a different editing contract.
• 当 PS 模式打开时，应用会保护某些全局操作，因为此时蒙版、图层、几何变换和历史记录构成了不同的编辑契约。
• Enter PS mode when you want local adjustment, masking, crop, rotate, guide-based correction, or export of an adjusted composition instead of only analysis.
• 当你需要局部调整、蒙版、裁切、旋转、基于参考线的校正，或导出调整后的合成图，而不仅是做分析时，就应进入 PS 模式。

31. PS Masks, Layers, And Guides

31. PS 蒙版、图层与参考线

• psDocument.ts can create initial documents, ensure a global adjustment layer, add masks, add ellipse masks, append brush strokes, and bind masks to layers.
• psDocument.ts 可以创建初始文档、确保全局调整图层、添加蒙版、添加椭圆蒙版、追加笔刷笔触，并把蒙版绑定到图层。
• Layer data includes basic adjustments, mixer controls, curves, blend mode, and opacity, making the local editor more than a simple alpha mask painter.
• 图层数据包含基础调整、色彩混合器、曲线、混合模式和不透明度，因此这个局部编辑器远不止一个简单的 alpha 蒙版画笔。
• Guide operations include adding, selecting, setting endpoints, and deleting guides, which then feed upright or projective correction workflows.
• 参考线操作包括新增、选择、设置端点和删除，而这些参考线又会进一步服务于拉直或投影校正流程。
• The best usage pattern is to define selection logic first, then create masks or guides, then refine geometry, and only then fine-tune layer adjustments.
• 最好的使用顺序通常是先定义选区逻辑，再建立蒙版或参考线，再修几何，最后才细调图层参数。

32. PS Transforms And Export

32. PS 变换与导出

• psDocument.ts supports crop, rotate, horizontal flip, vertical flip, Lensfun distortion correction, upright-from-guides, and generic projective-view transforms.
• psDocument.ts 支持裁切、旋转、水平翻转、垂直翻转、Lensfun 畸变校正、基于参考线的拉直，以及通用投影视图变换。
• Preview composition is handled by composePsDocumentPreview and composePsDocumentPreviewDirty, which enables full recomposition or dirty-rect updates.
• 预览合成由 composePsDocumentPreview 和 composePsDocumentPreviewDirty 负责，从而支持完整重算或脏矩形局部更新。
• GPU-assisted display for PS mode is provided by psWebgpuRenderer.ts and psWebglRenderer.ts, but the document model itself stays renderer-agnostic.
• PS 模式下的 GPU 显示由 psWebgpuRenderer.ts 和 psWebglRenderer.ts 提供，但文档模型本身仍保持与渲染器解耦。
• The user-level implication is that PS export quality depends on both document math and renderer availability, but the edit structure remains consistent.
• 对用户而言，这意味着 PS 导出质量既受文档数学也受渲染器可用性影响，但编辑结构本身保持一致。

33. RAW Processing Core

33. RAW 处理核心

• services/rawProcessor.ts is the imaging backbone of the project and contains decoding-adjacent helpers, render modes, measurement routines, and export-oriented transforms.
• services/rawProcessor.ts 是整个项目的成像骨架，内部集成了解码相关辅助、渲染模式、测量例程和面向导出的变换逻辑。
• It provides region stats, histogram, power spectrum, 2D spectrum, quantization stats, Pearson support, unmixed ROI extraction, official and zero-dependency renders, and CPU fallback rendering.
• 它提供区域统计、直方图、功率谱、二维频谱、量化统计、Pearson 支持、unmixed ROI 提取、official 与 zero-dependency 渲染，以及 CPU 回退渲染。
• Render functions include renderZeroDependency, renderBasicColorZeroDep, renderAdvancedZeroDep, renderRawWithOfficial16, renderFor16BitExport, and PS-oriented float RGB conversion.
• 渲染函数包括 renderZeroDependency、renderBasicColorZeroDep、renderAdvancedZeroDep、renderRawWithOfficial16、renderFor16BitExport 以及面向 PS 的 float RGB 转换。
• If you ever wonder “where the image actually becomes pixels,” the answer is usually here or in one of the renderer modules that consume its outputs.
• 如果你想追问“图像究竟是在什么地方真正变成像素的”，答案通常就在这里，或者是在消费其输出的那些渲染模块里。

34. GPU And CPU Render Backends

34. GPU 与 CPU 渲染后端

• The main display path can use services/webgpuRenderer.ts or services/webglRenderer.ts, exported as singletons webgpuRenderer and webglRenderer.
• 主显示路径可以使用 services/webgpuRenderer.ts 或 services/webglRenderer.ts，并以单例 webgpuRenderer 和 webglRenderer 对外提供。
• PS mode has parallel specialized renderers in psWebgpuRenderer.ts and psWebglRenderer.ts, which suggests the editor preview needs different shader or composition behavior.
• PS 模式在 psWebgpuRenderer.ts 和 psWebglRenderer.ts 中拥有并行的专用渲染器，这说明编辑器预览需要不同的着色器或合成行为。
• When GPU support is missing or unsuitable, the app can fall back to CPU-based rendering paths exported from rawProcessor.ts.
• 当 GPU 支持缺失或不适用时，应用可以回退到 rawProcessor.ts 导出的 CPU 渲染路径。
• For users, this means correctness usually survives weak hardware better than speed does.
• 对用户而言，这意味着在硬件较弱时，通常首先牺牲的是速度，而不是正确性。

35. Stack Analysis Infrastructure

35. 堆栈分析基础设施

• services/stackFrameCache.ts caches decoded frames with a memory budget and provides getDecodedStackFrame, getDecodedStackFrames, and prefetchStackFrames.
• services/stackFrameCache.ts 在内存预算下缓存已解码帧，并提供 getDecodedStackFrame、getDecodedStackFrames 和 prefetchStackFrames。
• services/powerSpectrumWorkerPool.ts distributes heavy spectral jobs across workers and can restart workers when they crash.
• services/powerSpectrumWorkerPool.ts 会把较重的频谱任务分发到多个 worker 上，并能在 worker 崩溃时重启。
• services/powerSpectrumWorker.ts, services/histogramWorker.ts, services/rawDecodeWorker.ts, and services/renderWorker.ts are narrow worker modules for parallel or off-main-thread tasks.
• services/powerSpectrumWorker.ts、services/histogramWorker.ts、services/rawDecodeWorker.ts 和 services/renderWorker.ts 都是面向并行或主线程外任务的窄职责 worker 模块。
• services/stackAnalysisWebgpu.ts is a dedicated heavy module for GPU-accelerated stack analysis and is one reason the app scales to more demanding measurement workflows.
• services/stackAnalysisWebgpu.ts 是一个专门用于 GPU 加速堆栈分析的重模块，也是应用能扩展到更高负载测量流程的重要原因之一。

36. Bridge, External Helpers, And Environment Assumptions

36. Bridge、外部辅助与环境假设

• hooks/useJiangBridge.ts polls a local bridge health endpoint and reports whether a helper service is connected, which can affect available workflows and auto-application logic.
• hooks/useJiangBridge.ts 会轮询本地 bridge 健康检查端点并汇报辅助服务是否连接，这会影响某些工作流和自动应用逻辑是否可用。
• Some features are more comfortable when the local helper is present, but much of the application still works entirely in-browser.
• 某些功能在本地辅助服务存在时体验更完整，但应用中相当多的部分仍然可以完全在浏览器内运行。
• You should therefore think in two layers: a browser-native analysis core and an optional local helper ecosystem.
• 因此你最好把这个项目理解为两层结构：一层是浏览器原生分析核心，另一层是可选的本地辅助生态。
• This also explains why some controls refer to bridge status directly in the UI.
• 这也解释了为什么界面中有些控件会直接显示或引用 bridge 状态。

37. Data, Calibration, And Science Modules

37. 数据、标定与科学计算模块

• services/chartCalibration.ts defines reference chart corners and ROIs and exports homography helpers used to turn user-marked chart points into structured sampling rectangles.
• services/chartCalibration.ts 定义参考色卡角点和 ROI，并导出单应矩阵辅助函数，用于把用户标记的图表点转换成结构化采样矩形。
• services/colorLab.ts contains CC24_REF_LINEAR, color-grid generation, and color-result calculation used by the Color Lab modal.
• services/colorLab.ts 包含 CC24_REF_LINEAR、颜色网格生成以及 Color Lab 弹窗所用的色彩结果计算逻辑。
• services/colorScience.ts provides precomputed scientific data, lens-curve generation, and camera-data calculations from matrices and illuminants.
• services/colorScience.ts 提供预计算科学数据、镜头曲线生成，以及基于矩阵和光源的相机数据计算。
• services/colorData.ts, services/cameraMatrices.ts, and services/cameraData.ts are static or semi-static data sources that feed UI databases and technical calculations.
• services/colorData.ts、services/cameraMatrices.ts 和 services/cameraData.ts 是静态或半静态数据源，供界面数据库和技术计算使用。
• These files matter because much of the app’s value comes from pairing user interaction with domain reference data rather than from pure generic image editing.
• 这些文件之所以重要，是因为这个应用的价值很大一部分来自“把用户交互与领域参考数据结合起来”，而不只是做通用图像编辑。

38. File Format Modules

38. 文件格式模块

• services/jdng.ts defines a custom float32 JDNG container, parsing and rendering helpers, and is used in stacking and float export workflows.
• services/jdng.ts 定义了自定义的 float32 JDNG 容器、解析与渲染辅助逻辑，并被用于堆栈和浮点导出流程。
• services/dngGenerator.ts exports createFakeDNG, which is useful when the app needs a DNG-like wrapper around processed data.
• services/dngGenerator.ts 导出 createFakeDNG，适用于应用需要为处理后数据包上一层 DNG 风格封装的场景。
• services/tiffGenerator.ts exports 16-bit and 32-bit TIFF writers plus a float32 DNG-like helper.
• services/tiffGenerator.ts 导出 16 位和 32 位 TIFF 写出器，以及一个 float32 的 DNG-like 辅助函数。
• Together, these modules show that export is not treated as a single image-save endpoint but as a family of technical serialization strategies.
• 综合来看，这些模块说明“导出”在本项目里并不是单一的保存图片入口，而是一组技术性序列化策略。

39. Utility Modules

39. 工具模块

• utils/math.ts contains matrix operations, spline generation, LUT generation, and FFT-related helpers that support both rendering and analysis.
• utils/math.ts 包含矩阵运算、样条生成、LUT 生成和 FFT 相关辅助函数，同时支撑渲染与分析。
• utils/projectiveView.ts contains projective transform composition, warping, and upright-view helpers used by PS geometry tools.
• utils/projectiveView.ts 包含投影变换组合、图像扭曲以及拉正视图辅助函数，供 PS 几何工具使用。
• utils/viewRotation.ts converts between image coordinates and rotated display coordinates.
• utils/viewRotation.ts 负责图像坐标与旋转显示坐标之间的转换。
• utils/selectionSizing.ts constrains or snaps ROI geometry, especially for power-of-two workflows.
• utils/selectionSizing.ts 负责约束或吸附 ROI 几何，尤其服务于二次幂工作流。
• utils/channelModel.ts gives consistent channel naming and availability logic for Bayer and three-plane data.
• utils/channelModel.ts 为 Bayer 数据和三平面数据提供统一的通道命名与可用性逻辑。

40. Complete Component Inventory

40. 组件总清单

• Header.tsx, ImageCanvas.tsx, ControlPointSliders.tsx, GuiSidebar.tsx, and TerminalSidebar.tsx form the main interactive shell of the application.
• Header.tsx、ImageCanvas.tsx、ControlPointSliders.tsx、GuiSidebar.tsx 和 TerminalSidebar.tsx 共同构成应用的主交互外壳。
• HistogramModal.tsx, PowerSpectrumModal.tsx, TwoDSpectrumModal.tsx, QuantizationModal.tsx, PearsonModal.tsx, SfrLabWorkspace.tsx, SfrModal.tsx, PTCModal.tsx, ColorLabModal.tsx, DngExportModal.tsx, StackingModal.tsx, and SaveZ8Modal.tsx are the major lab or analysis surfaces.
• HistogramModal.tsx、PowerSpectrumModal.tsx、TwoDSpectrumModal.tsx、QuantizationModal.tsx、PearsonModal.tsx、SfrLabWorkspace.tsx、SfrModal.tsx、PTCModal.tsx、ColorLabModal.tsx、DngExportModal.tsx、StackingModal.tsx 和 SaveZ8Modal.tsx 是主要实验室或分析界面。
• SfrLabWorkspace.tsx is the dedicated SFR workspace shell, while SfrModal.tsx now acts more like the inner expert panel used inside that workspace.
• SfrLabWorkspace.tsx 是专用的 SFR 工作区外壳，而 SfrModal.tsx 现在更像是在该工作区内部使用的专家面板。
• AboutModal.tsx, ExifModal.tsx, DatabaseModal.tsx, CrossCalcModal.tsx, and ConfirmationModal.tsx are supporting dialogs for metadata, references, database lookup, calculation, and guarded actions.
• AboutModal.tsx、ExifModal.tsx、DatabaseModal.tsx、CrossCalcModal.tsx 和 ConfirmationModal.tsx 是辅助对话框，分别服务于元数据、参考资源、数据库查询、计算和受保护操作。
• PsEditorPanel.tsx is the dedicated PS editing side panel, and DraggablePanel.tsx is the shared floating-window shell.
• PsEditorPanel.tsx 是专门的 PS 编辑侧面板，而 DraggablePanel.tsx 是共享的浮动窗口外壳。
• ZoomControls.tsx, ThemeSwitcher.tsx, MatrixControls.tsx, LensCurveChart.tsx, LensDataInput.tsx, BlackLevelChart.tsx, CameraCard.tsx, and SearchBar.tsx are focused helper UI pieces that support larger flows.
• ZoomControls.tsx、ThemeSwitcher.tsx、MatrixControls.tsx、LensCurveChart.tsx、LensDataInput.tsx、BlackLevelChart.tsx、CameraCard.tsx 和 SearchBar.tsx 都是支撑大型流程的定向辅助 UI 组件。
• ChromaticityChart.tsx is currently a minimal placeholder, and Controls.tsx is empty in the current tree.
• ChromaticityChart.tsx 目前只是极简占位文件，而 Controls.tsx 在当前代码树中是空文件。

41. Complete Service Inventory

41. 服务层总清单

• rawProcessor.ts, webgpuRenderer.ts, webglRenderer.ts, psWebgpuRenderer.ts, and psWebglRenderer.ts are the display and imaging core.
• rawProcessor.ts、webgpuRenderer.ts、webglRenderer.ts、psWebgpuRenderer.ts 和 psWebglRenderer.ts 构成显示与成像核心。
• psDocument.ts is the local-adjustment document engine, while workspaceStore.ts is the persistence engine.
• psDocument.ts 是局部调整文档引擎，而 workspaceStore.ts 是持久化引擎。
• stackingProcessor.ts, stackFrameCache.ts, stackAnalysisWebgpu.ts, and powerSpectrumWorkerPool.ts provide the heavy infrastructure for stack and batch analysis.
• stackingProcessor.ts、stackFrameCache.ts、stackAnalysisWebgpu.ts 和 powerSpectrumWorkerPool.ts 提供了堆栈与批量分析所需的重型基础设施。
• sfrProcessor.ts, chartCalibration.ts, colorLab.ts, colorScience.ts, colorData.ts, cameraMatrices.ts, and cameraData.ts supply the scientific and calibration logic.
• sfrProcessor.ts、chartCalibration.ts、colorLab.ts、colorScience.ts、colorData.ts、cameraMatrices.ts 和 cameraData.ts 提供科学计算与标定逻辑。
• jdng.ts, dngGenerator.ts, and tiffGenerator.ts cover technical export formats.
• jdng.ts、dngGenerator.ts 和 tiffGenerator.ts 负责技术型导出格式。
• histogramWorker.ts, powerSpectrumWorker.ts, rawDecodeWorker.ts, and renderWorker.ts are narrow worker entry modules.
• histogramWorker.ts、powerSpectrumWorker.ts、rawDecodeWorker.ts 和 renderWorker.ts 是职责单一的 worker 入口模块。
• joraw.js and joraw.wasm are bundled decode/runtime assets that the RAW pipeline relies on.
• joraw.js 和 joraw.wasm 是 RAW 管线依赖的捆绑解码运行时资源。

42. Bundled Subtrees And What They Mean

42. 捆绑子目录及其意义

• LibRaw-Wasm-main/ is a bundled WebAssembly-oriented RAW decoding subtree and helps explain some of the project’s decode assumptions and worker patterns.
• LibRaw-Wasm-main/ 是一个面向 WebAssembly 的捆绑 RAW 解码子树，有助于理解项目的一些解码假设和 worker 模式。
• Handheld-Multi-Frame-Super-Resolution-main/, ImageStackAlignator-master/, drizzle-main/, and code/ indicate that the project has been built in dialogue with burst, alignment, drizzle, and HDR-style reference implementations.
• Handheld-Multi-Frame-Super-Resolution-main/、ImageStackAlignator-master/、drizzle-main/ 和 code/ 说明这个项目在构建过程中持续参考了连拍、对齐、drizzle 和 HDR 风格的实现。
• lensfun/ is a functional bundled data directory, not just documentation, because PS lens correction loads from it.
• lensfun/ 是功能性数据目录，而不只是文档资源，因为 PS 镜头校正会直接从这里加载数据。
• vendor/libraw-wasm/ stores dependency-style WASM assets, media/ stores media resources, and dist/ stores built output.
• vendor/libraw-wasm/ 存放依赖风格的 WASM 资源，media/ 存放媒体资源，而 dist/ 存放构建输出。
• node_modules/ is large and operationally necessary, but it should be treated as installed dependency material rather than part of the authorial architecture description.
• node_modules/ 体量巨大且在运行上必不可少，但在架构说明中应把它视为已安装依赖，而不是作者手写设计的一部分。

43. Recommended Reading Order For Developers

43. 给开发者的推荐阅读顺序

• Read App.tsx first to understand session flow, modal ownership, and shared state.
• 先读 App.tsx，理解 session 流、弹窗归属和共享状态。
• Read types.ts second so the data contracts for sessions, RAW images, regions, PS masks, and documents become concrete.
• 第二步读 types.ts，这样 session、RAW 图像、区域、PS 蒙版和文档的数据契约会变得清晰。
• Then read ImageCanvas.tsx, Header.tsx, and ControlPointSliders.tsx to understand user interaction entry points.
• 然后阅读 ImageCanvas.tsx、Header.tsx 和 ControlPointSliders.tsx，理解用户交互入口。
• After that, read rawProcessor.ts, psDocument.ts, and stackingProcessor.ts, because those three files explain most of the nontrivial computational behavior.
• 之后再读 rawProcessor.ts、psDocument.ts 和 stackingProcessor.ts，因为这三个文件解释了大多数非平凡计算行为。
• Finally, read the individual lab modals that matter to your task, then the worker and utility modules.
• 最后再去读与你任务最相关的各实验室弹窗，以及对应的 worker 和工具模块。

44. Recommended Practical Workflows

44. 推荐的实际操作流程

• For quick inspection, load one RAW file, check EXIF and black levels, draw an ROI, then open Histogram and Power Spectrum.
• 如果只是快速检查，就先加载一张 RAW，查看 EXIF 和黑电平，画一个 ROI，然后打开 Histogram 和 Power Spectrum。
• For chart-based work, mark the chart carefully, verify geometry, then open Color Lab or SFR instead of rushing straight into calculation.
• 如果是基于色卡的工作，应先仔细标记色卡并核对几何，再进入 Color Lab 或 SFR，而不要急于直接计算。
• For burst research, preload or decode the stack, keep ROI definitions stable, then use stack-aware spectral or stacking tools.
• 如果是连拍研究，就先预取或解码堆栈，保持 ROI 定义稳定，再使用支持堆栈的频谱或堆栈工具。
• For local editing, enter PS mode only after the source image and viewing geometry are stable enough that you are ready to build masks and guides.
• 如果是做局部编辑，最好等源图像和观察几何都稳定后再进入 PS 模式，这样你建立的蒙版和参考线才更可靠。
• For export-heavy workflows, decide early whether you need a rendered image, a DNG-like technical export, a TIFF, or a JDNG float container.
• 如果导出是重点流程，就应尽早判断你需要的是渲染图、DNG-like 技术导出、TIFF，还是 JDNG 浮点容器。

45. Important Limitations And Expectations

45. 重要限制与使用预期

• This project is powerful but heterogeneous, so not every panel follows identical UX conventions or validation rigor.
• 这个项目功能强，但风格异构，因此并不是每个面板都遵循完全一致的交互规范或输入校验强度。
• Some modules are clearly research-oriented or author-task-specific, especially rescue and advanced stacking paths.
• 某些模块明显更偏研究用途或作者特定任务场景，尤其是修复类工具和高级堆栈路径。
• Performance depends strongly on browser capabilities, dataset size, and whether WebGPU, WebGL, workers, or CPU fallback are used.
• 性能高度依赖浏览器能力、数据规模，以及当前是否走 WebGPU、WebGL、worker 或 CPU 回退路径。
• Because the app persists workspace state, unusual behavior after reload can sometimes come from restored sessions rather than your latest click alone.
• 由于应用会持久化工作区状态，因此刷新后的异常表现有时来自被恢复的旧 session，而不只是你最后一次点击。
• The safest mindset is to treat the app as a technical workstation where you validate assumptions, not as a black-box automatic enhancer.
• 最稳妥的心态是把它当作一个需要验证假设的技术工作站，而不是黑箱式自动增强器。

46. Final Summary

46. 最终总结

• The shortest accurate summary is that this repository is a session-driven RAW analysis and experimental imaging platform with strong ROI tooling, serious measurement windows, a PS-style local editor, and multiple technical export paths.
• 最简洁而准确的总结是：这个仓库是一个以 session 为核心的 RAW 分析与实验成像平台，拥有很强的 ROI 工具、严肃的测量窗口、类 PS 局部编辑器以及多条技术型导出路径。
• If you are using it rather than modifying it, focus first on loading, ROI discipline, the correct lab for your measurement goal, and the difference between rendered output and raw-domain export.
• 如果你是在使用它而不是修改它，最该优先掌握的是加载、ROI 纪律、与你测量目标匹配的实验室，以及“渲染输出”和“RAW 域导出”的区别。
• If you are extending it, anchor your understanding in App.tsx, rawProcessor.ts, psDocument.ts, and the specific modal or worker closest to your feature.
• 如果你要扩展它，就把理解锚点放在 App.tsx、rawProcessor.ts、psDocument.ts，以及离你目标功能最近的那个 modal 或 worker 上。
• Used that way, the codebase becomes much more coherent than its size first suggests.
• 只要按这个方式去使用和阅读，这个代码库会比它初看上去更有整体性。

47. SFR Lab Detailed Implementation

47. SFR Lab 具体实现细解

• The current SFR stack is distributed across components/SfrLabWorkspace.tsx, components/SfrModal.tsx, services/sfrProcessor.ts, plus ROI extraction and session glue inside App.tsx.
• 当前的 SFR 实现分布在 components/SfrLabWorkspace.tsx、components/SfrModal.tsx、services/sfrProcessor.ts，以及 App.tsx 里的 ROI 提取与会话衔接逻辑上。
• SfrLabWorkspace.tsx owns the lab shell, source and encoding controls, the batch/template panels, the Auto Block section, and the launcher for the point-set / plot export modal.
• SfrLabWorkspace.tsx 负责实验室外壳、source 与 encoding 控件、batch/template 面板、Auto Block 区，以及点集 / 绘图导出弹窗的入口。
• SfrModal.tsx still contains the expert measurement panel: manual ROI accumulation, manual binning, deshading options, three-plane source selection, CSV export, model fitting, and manual edge-line hooks.
• SfrModal.tsx 仍然包含专家测量面板本体：手动 ROI 累积、手动 bin、deshading 选项、三平面源选择、CSV 导出、模型拟合，以及手动画边相关钩子。
• App.tsx owns the SFR session glue: current ROI, shared deshading state, auto-measurement labels, explain cards, the auto-plot modal, and canvas interactions such as right-click deletion of detected edges.
• App.tsx 负责 SFR 的会话衔接层：当前 ROI、共享 deshading 状态、自动测量标签、explain 结果卡、自动绘图弹窗，以及画布上的右键删边等交互。
• services/sfrProcessor.ts remains the computational core: edge extraction, line fitting/refinement, ESF/LSF generation, MTF computation, auto-block measurement, and explain diagnostics all converge there.
• services/sfrProcessor.ts 仍然是计算核心：找边、直线拟合/精修、ESF/LSF 生成、MTF 计算、自动块测量以及 explain 诊断最终都会汇聚到这里。
• The current implementation deliberately separates candidate screening and UI explanation from the actual SFR math, so tuning the detection panel does not mean rewriting the underlying MTF pipeline.
• 当前实现刻意把候选筛选 / UI 解释与真正的 SFR 数学分开，因此调检测面板并不等于重写底层 MTF 流水线。

48. SFR Input Paths

48. SFR 的输入路径

• The current source families are Unmix / BW, RGGB Raw, and Three-plane, rather than the older Rendered RGB versus Scalar Unmix split.
• 当前的输入源类型是 Unmix / BW、RGGB Raw 和 Three-plane，而不再是旧文档里的 Rendered RGB 对 Scalar Unmix 二分法。
• Unmix / BW is treated as a single-channel measurement source. If scalar-unmix data exists, SFR uses the unmixed linear ROI; otherwise it falls back to the BW-style single-channel path.
• Unmix / BW 会被视为单通道测量源；如果已经有 scalar-unmix 数据，SFR 会优先使用 unmix 后的线性 ROI，否则回退到 BW 风格的单通道路径。
• RGGB Raw is treated as single-plane Bayer data. It now defaults to Linear, and its final projection uses only real green samples from the selected phase.
• RGGB Raw 会被视为单平面 Bayer 数据。它现在默认按 Linear 处理，最终投影只使用所选相位里的真实绿采样点。
• In RGGB Raw, Default follows the RAW CFA pattern, 1 forces the top-left / bottom-right green phase, and 2 forces the top-right / bottom-left green phase.
• 在 RGGB Raw 模式中，Default 跟随 RAW 自带 CFA pattern，1 强制使用左上 / 右下绿相位，2 强制使用右上 / 左下绿相位。
• Three-plane operates directly on true three-plane input when available. In the manual expert panel it starts from None, and the user must choose Luma, R, G, or B before a manual ROI can be added.
• Three-plane 在有真实三平面输入时会直接以其为源。在手动专家面板里它从 None 开始，用户必须先选择 Luma、R、G 或 B 之后才能添加手动 ROI。
• In Auto Block and explain, the three-plane default is luma, so automatic workflows do not silently fall back to the old green-channel assumption.
• 在 Auto Block 和 explain 中，三平面的默认值是 luma，因此自动工作流不会再悄悄回退到旧的绿通道假设。
• The separate Encoding selector (Auto, Linear, sRGB) controls whether rendered or three-plane input should be linearized before edge analysis. RGGB Raw itself already has a dedicated raw-style path and therefore defaults to Linear.
• 独立的 Encoding 选择器（Auto、Linear、sRGB）用于决定在边缘分析前是否要对 rendered 或 three-plane 输入做线性化；而 RGGB Raw 本身已经有专用的 raw 风格路径，因此默认就是 Linear。
• The workspace also supports a manual two-point edge-line mode, so edge geometry can come directly from the user instead of only from automatic detection.
• 工作区还支持手动“两点一线”边缘模式，因此边缘几何也可以直接由用户指定，而不必完全依赖自动识别。

49. How One ROI Becomes Edge Data

49. 单个 ROI 如何变成 Edge Data

• handleAddROI() in SfrModal.tsx is the main manual-ingestion point: it checks the current source family, crops the appropriate data, and then funnels that crop into calculateEdgeData(...) or calculateEdgeDataWithManualLine(...).
• SfrModal.tsx 里的 handleAddROI() 是主要的手动接收入口：它会先判断当前输入源类型，裁出对应数据，然后统一把裁剪结果送进 calculateEdgeData(...) 或 calculateEdgeDataWithManualLine(...)。
• If the user enabled Pick Edge Line, geometry comes from the two selected canvas points; otherwise the processor estimates the edge from image content.
• 如果用户启用了 Pick Edge Line，几何信息就来自画布上手动点出的两点；否则处理器会从图像内容里自行估计边缘。
• For three-plane input, the processor either picks one RGB channel or computes luma from 0.2126 R + 0.7152 G + 0.0722 B.
• 对于三平面输入，处理器要么直接选一个 RGB 通道，要么用 0.2126 R + 0.7152 G + 0.0722 B 计算亮度。
• For scalar Bayer input in green-only work, the processor builds two related datasets: an interpolated green guide plane used for locating the edge, and a separate set of real green samples used later for projection and ESF/LSF.
• 对于 Bayer 绿通道测量，处理器会构建两套相关数据：一套是用于定位边缘的插值绿引导平面，另一套是后续用于投影和 ESF/LSF 的真实绿采样点。
• Auto Block measurements also end up as EdgeData; the difference is only that those ROIs come from the detection pipeline rather than from manually drawn rectangles.
• Auto Block 里的自动测量最终也会落成 EdgeData；区别只在于这些 ROI 来自检测流程，而不是手动画出的矩形。

50. Edge Orientation And Edge-Line Fitting

50. 边缘方向判断与边缘直线拟合

• calculateEdgeData() first estimates whether the edge is more horizontal or more vertical by comparing accumulated gradients, and then normalizes the ROI into a common working orientation.
• calculateEdgeData() 会先通过累计梯度判断边缘更偏水平还是更偏垂直，然后把 ROI 归一到统一的工作朝向。
• In the generic manual path, orientation normalization is followed by the familiar row-wise or column-wise local-derivative centroid collection and straight-line regression.
• 在通用手动路径里，方向归一之后仍然会沿用熟悉的逐行或逐列局部导数质心收集，再做直线回归。
• In the Bayer-green path, edge location is guided by the interpolated green image, but final projection still uses only the true green phase samples.
• 在 Bayer 绿通道路径中，边缘位置由插值绿图引导，但最终投影仍然只使用真实绿相位采样。
• In the newer gray / BW / three-plane auto-refine path, the code refines each side by sweeping scan lines along the edge tangent, finding derivative centroids along the normal, and then fitting the final line only from those centroid points.
• 在较新的灰度 / BW / 三平面自动精修路径中，代码会沿边的切向扫出一组扫描线，在法向上寻找导数质心点，然后只用这些质心点来拟合最终直线。
• That change is important because it is more robust than letting a loose cloud of edge pixels directly dominate the final line, especially in three-plane work.
• 这个变化很重要，因为它比直接让一团松散边缘像素主导最终直线更稳健，尤其是在三平面测量里更明显。
• If too few valid rows, scans, or centroids survive, the ROI is rejected as not containing a reliable measurable edge.
• 如果保留下来的有效行、扫描线或质心点太少，ROI 就会被判定为不含可靠可测边缘而被拒绝。

51. Distance Projection, Binning, And ESF

51. 距离投影、分箱与 ESF

• Once the edge line is known, each accepted sample is projected onto the edge-normal direction, producing a signed distance from the edge.
• 一旦边缘直线确定下来，每个被接受的样本都会被投影到边缘法线方向，从而得到一个相对边缘的有符号距离。
• These distances are sorted and binned into an oversampled edge spread function, or ESF.
• 这些距离会被排序并分箱，形成一个过采样的边缘扩展函数，也就是 ESF。
• In the expert manual panel, Bin still supports Manual entry; when enabled, the value is clamped into [0.01, 0.5].
• 在专家手动面板里，Bin 仍然支持 Manual 输入；启用后，该数值会被夹到 [0.01, 0.5] 区间内。
• Auto mode no longer exposes a manual bin box in the left panel. Instead, each detected edge chooses its own best bin automatically.
• auto 模式在左侧面板里已经不再暴露手动 bin 输入框；取而代之的是每条已检测边都自动选择自己的最优 bin。
• The current auto rule is: choose the finest bin that produces no empty bins inside the central range center ± 0.25 * ROI short-side pixels, but never go finer than 0.125.
• 当前 auto 规则是：在 中心 ± 0.25 * ROI 短边像素数 的范围内，选择“不会产生空箱”的最细 bin，但不会细于 0.125。
• Empty bins are still back-filled using the previous valid value so ESF remains differentiable enough for later steps; there is no extra instability-smoothing layer beyond that.
• 空 bin 仍然会用前一个有效值回填，以保证 ESF 在后续步骤中仍足够可求导；除此之外不会额外套一层“不稳定 bin 平滑”。
• If the early bins are brighter than the late bins, ESF polarity is flipped so edge direction remains consistent.
• 如果前面的 bin 比后面的 bin 更亮，函数就会翻转 ESF 极性，以保证边缘方向保持一致。

52. From ESF To LSF

52. 从 ESF 到 LSF

• After ESF is built, the code computes the line spread function lsfFull using a centered finite difference.
• ESF 构建完成后，代码会用中心差分来计算线扩展函数 lsfFull。
• This derivative step stays intentionally simple and stable; more advanced compensation happens later during SFR computation rather than here.
• 这一步导数实现刻意保持简单稳定；更复杂的补偿不在这里做，而是在后面的 SFR 计算阶段完成。
• The returned EdgeData object contains the ESF/LSF pair, bin size, orientation, and fitted edge geometry, which is enough for later averaging and frequency-domain analysis.
• 返回的 EdgeData 对象包含 ESF/LSF、bin size、方向以及拟合好的边缘几何，这已经足够供后续做平均与频域分析。

53. How computeSFR() Works

53. computeSFR() 的具体工作方式

• computeSFR() accepts one or more EdgeData samples, so the modal can accumulate multiple ROIs and average them into one result.
• computeSFR() 接受一个或多个 EdgeData 样本，因此这个面板可以累积多个 ROI 并把它们平均成一个结果。
• The function uses a fixed FFT size of 4096 and a common output frequency grid with 501 points.
• 这个函数固定使用大小为 4096 的 FFT，并建立一个含 501 个点的统一输出频率轴。
• If pixel pitch is available, frequencies are scaled into lp/mm; otherwise they remain in cy/px.
• 如果像元尺寸可用，频率会被换算成 lp/mm；否则就保持在 cy/px。
• The code always computes out to 2x Nyquist internally, while the UI can later choose whether to show the normal range or the extended range.
• 代码在内部总是把频率算到 2x Nyquist，而界面层之后再决定是只显示常规范围还是扩展范围。
• Auto-overlay MTF50 labels, batch SFR results, the embedded expert plots, and the point-set / export modal all ultimately rely on computeSFR().
• 自动叠加层上的 MTF50 标签、批量 SFR 结果、嵌入式专家图表以及点集 / 导出弹窗，本质上最终都依赖 computeSFR()。
• The Line Pair view in the plot modal is not a separate measurement pipeline; it samples the current MTF curve at fixed spatial frequencies such as 10 / 20 / 40 / 80 lp/mm once pixel size is known.
• 绘图弹窗里的 Line Pair 视图并不是一条独立测量流水线；它是在已知像元尺寸之后，从当前 MTF 曲线上读取 10 / 20 / 40 / 80 lp/mm 等固定空间频率处的数值。

54. Peak Detection, Deshading, And Radius Selection

54. 峰值检测、去渐晕与半径选择

• For each edge, computeSFR() locates the LSF peak and estimates a width using the points where LSF falls below 20% of that peak.
• 对每条边，computeSFR() 会先找到 LSF 峰值，然后通过 LSF 下降到峰值 20% 以下的位置估计一个宽度。
• If Deshading is enabled, the function performs a linear detrend on the LSF tails outside an exclusion band around the peak.
• 如果启用了 Deshading，函数就会在峰值附近排除一段区域，然后对两侧尾部做线性去趋势。
• If Limit Fit is enabled in the UI, the tail detrend uses only a bounded fitting width; otherwise it uses all eligible tail samples.
• 如果在界面里启用了 Limit Fit，尾部去趋势就只会使用有限宽度的拟合区；否则会使用所有符合条件的尾部样本。
• The embedded expert core still exposes Jiang's official NR, which is the current auto-radius mode. Turning it off switches to manual radius control.
• 嵌入式专家核心里仍然保留 Jiang's official NR，它就是当前的自动半径模式；关闭后则切换到手动半径控制。
• In contrast, the left SFR workflow panel no longer exposes a separate Official NR toggle, and the normal batch-workflow path treats NR as off.
• 与此相对，左侧 SFR 工作流面板已经不再提供单独的 Official NR 开关，常规批处理流程会把 NR 按关闭处理。
• Deshading is now shared between the left workflow panel and the embedded core. Toggling it also refreshes auto-measurement labels, explain runs, and the point-set / plot export data.
• Deshading 现在在左侧工作流面板和嵌入式核心之间共享；切换它时，也会同步刷新自动测量标签、explain 结果以及点集 / 绘图导出数据。
• Candidate purity, coverage, and similar auto-detection thresholds are screening logic for whether a block should enter measurement; they are not the main MTF computation itself.
• 候选纯净度、覆盖率之类的 auto 检测阈值，本质上属于“这个块应不应该进入测量”的筛选逻辑，而不是主 MTF 计算本体。

55. FFT Preparation, Hann Window, And MTF/PTF

55. FFT 准备、Hann 窗以及 MTF/PTF

• The cropped LSF is not sent directly into FFT in-place; the code first circularly shifts the local LSF peak to index 0.
• 被裁剪后的 LSF 并不会原样送进 FFT；代码会先把局部峰值循环平移到索引 0。
• This circular shift is an important implementation detail because it removes a large linear phase ramp and keeps the phase response interpretable.
• 这个循环平移是一个很关键的实现细节，因为它能消除很大的线性相位斜坡，让相位响应更可解释。
• If Hann On is enabled, a Hann window is multiplied into the cropped LSF before the FFT.
• 如果启用了 Hann On，则会在 FFT 之前先把 Hann 窗乘到裁剪后的 LSF 上。
• The FFT magnitude becomes the raw MTF, and the complex angle becomes the raw phase used later for PTF.
• FFT 的幅值会变成原始 MTF，而复数相角则会成为后续 PTF 的原始相位来源。
• MTF is normalized by the DC component and then interpolated onto the common frequency grid so multiple ROIs can be accumulated consistently.
• MTF 会先用直流分量做归一化，然后插值到统一频率轴上，这样多个 ROI 才能被一致地叠加平均。
• PTF is taken only from the first valid ROI and then processed by phase unwrapping plus linear detrending before interpolation to the same frequency axis.
• PTF 只从第一个有效 ROI 里提取，然后先做相位展开，再做线性去趋势，最后插值到同一条频率轴上。
• In the current UI, however, the PTF toggle is intentionally disabled because that presentation path is considered not final yet even though the lower-level computation still exists.
• 不过在当前界面里，PTF 开关被有意设为不可用，因为这条展示路径目前被视为尚未定稿，尽管底层计算仍然存在。

56. How MTF50 Is Computed

56. MTF50 是怎么求出来的

• After averaging all normalized ROI MTF curves, computeSFR() searches for the first crossing where the MTF falls from above 0.5 to below 0.5.
• 在把所有归一化 ROI 的 MTF 曲线平均之后，computeSFR() 会寻找第一处从高于 0.5 掉到低于 0.5 的交点。
• The exact MTF50 value is then linearly interpolated between those two neighboring samples.
• 然后再在这两个相邻采样点之间做线性插值，得到精确的 MTF50。
• This means the displayed MTF50 is not just the nearest sampled bin, but a continuous estimate derived from the sampled curve.
• 这意味着界面上显示的 MTF50 不是最接近的离散 bin，而是从采样曲线插值得到的连续估计值。

57. What The SFR UI Actually Exposes

57. SFR 界面实际暴露了什么

• Pixel Pitch changes the x-axis unit from cy/px to lp/mm, and Image Height enables an additional LW/PH style derivation from the measured MTF50.
• Pixel Pitch 会把横轴单位从 cy/px 转成 lp/mm，而 Image Height 则允许在 MTF50 基础上进一步推导出 LW/PH 风格指标。
• The Bin box shows the current oversampling step and warns when the automatic bin reaches its upper limit, which the UI interprets as a hint that the ROI may be too small.
• Bin 区块会显示当前的过采样步长；如果自动 bin 已经顶到上限，界面会把它解释为“ROI 可能过小”的提示。
• G-Only is shown only for Bayer-like scalar data; in three-plane mode that control is replaced by explicit source selection.
• G-Only 只会在 Bayer 风格的标量数据上出现；一旦进入三平面模式，这个开关就会被明确的数据源选择控件替代。
• Add Current ROI appends another edge sample to the current SFR stack instead of replacing the existing result.
• Add Current ROI 不是覆盖当前结果，而是把新边缘样本继续追加到当前 SFR 样本堆里。
• Export CSV writes Frequency, MTF, Phase columns, while Copy Pos/MTF50 copies the ROI center and current MTF50 in a compact tuple form.
• Export CSV 会写出 Frequency, MTF, Phase 三列，而 Copy Pos/MTF50 会把 ROI 中心和当前 MTF50 以紧凑 tuple 形式复制出去。

58. Built-In Optical Model And Auto Fit

58. 内建光学模型与自动拟合

• SfrModal.tsx contains a forward optical MTF model with parameters such as aperture, olpfSeparationPx, fillFactor, coreSigmaPx, haloSigmaPx, haloWeight, wavelengthUm, and rolloff.
• SfrModal.tsx 内置了一套正向光学 MTF 模型，参数包括 aperture、olpfSeparationPx、fillFactor、coreSigmaPx、haloSigmaPx、haloWeight、wavelengthUm 和 rolloff。
• The UI lets the user lock any subset of these parameters so fitting can optimize only the unlocked subset.
• 界面允许用户锁定任意子集参数，使拟合过程只优化未锁定的那部分。
• The fit objective is a weighted squared error between measured and modeled MTF, with a small regularization penalty on some parameters.
• 拟合目标函数是测量 MTF 和模型 MTF 之间的加权平方误差，并对某些参数附加轻微正则化惩罚。
• The optimizer is a custom Nelder-Mead implementation with 7 restarts and 320 iterations per restart, seeded by the current UI parameter values plus random jitter for restart diversity.
• 优化器是自定义的 Nelder-Mead 实现，使用 7 次重启、每次 320 轮迭代；其初值来自当前界面参数，并在重启时加入随机抖动以提升搜索多样性。
• The fit range is user-bounded by fitMinFreq and fitMaxFreq, and the modal refuses fitting if fewer than 10 MTF samples remain inside the chosen interval.
• 拟合频段由 fitMinFreq 和 fitMaxFreq 约束；如果所选区间里剩下的 MTF 采样点少于 10 个，弹窗会拒绝执行拟合。

59. Auto SFR Detection Pipeline

59. 自动 SFR 检测流水线

• autoDetectAndComputeSFR() in sfrProcessor.ts is the batch-style auto-detection path.
• sfrProcessor.ts 里的 autoDetectAndComputeSFR() 就是批量风格的自动检测路径。
• It scans the rendered image in 10x10 blocks, computes a Sobel-like local gradient from the RGBA preview, and keeps only blocks whose gradient magnitude and angle fall inside user-provided thresholds.
• 它会以 10x10 的 block 扫描渲染后的图像，用类似 Sobel 的局部梯度从 RGBA 预览中求边缘，并只保留那些梯度强度和角度落在用户阈值范围内的 block。
• Edge orientation is normalized into a 0 to 90 effective-angle measure so that near-horizontal and near-vertical edge families can be filtered symmetrically.
• 边缘方向会被归一到 0 到 90 的有效角度空间里，这样接近水平和接近垂直的边缘就能被对称地筛选。
• Neighboring accepted blocks are merged with a BFS-style grouping step, but only when their angles are close enough, specifically with a difference under 15 degrees or the wraparound equivalent.
• 相邻的合格 block 会通过 BFS 风格的聚类步骤合并，但前提是它们的角度足够接近，具体条件是角差小于 15 度或满足绕回等价条件。
• Each merged group is converted into a candidate ROI whose aspect ratio depends on whether the average edge is more vertical-like or horizontal-like.
• 每个聚合后的 group 都会被转换成一个候选 ROI，而这个 ROI 的宽高比例会根据平均边缘更偏垂直还是更偏水平来决定。
• The function then reruns the normal calculateEdgeData() plus computeSFR() pipeline on each candidate ROI and returns only those groups that successfully produce a numeric mtf50.
• 接着，函数会对每个候选 ROI 再次运行标准的 calculateEdgeData() 加 computeSFR() 流程，并只保留那些成功得到数值型 mtf50 的 group。

60. Practical Reading Of The SFR Design

60. 对这套 SFR 设计的实际理解

• The SFR Lab is therefore not a single “measure sharpness” function; it is a layered system consisting of source normalization, edge extraction, oversampled ESF construction, derivative-based LSF generation, optional detrending, FFT-based MTF/PTF generation, multi-ROI averaging, and optional forward-model fitting.
• 因此 SFR Lab 并不是一个单独的“测锐度”函数；它实际上是一个分层系统，由输入源归一化、边缘提取、过采样 ESF 构建、基于导数的 LSF 生成、可选去趋势、基于 FFT 的 MTF/PTF 生成、多 ROI 平均以及可选的正向模型拟合共同组成。
• The most important user-facing implication is that ROI quality, source-path choice, and preprocessing switches can change the result at least as much as the final FFT step.
• 对用户而言最重要的一点是，ROI 质量、输入路径选择和预处理开关，对结果的影响至少和最后的 FFT 步骤一样大。
• The most important developer-facing implication is that almost every SFR number shown in the UI is the end product of several explicit geometric and signal-processing decisions that are all inspectable in code.
• 对开发者而言最重要的一点是，界面里显示的几乎每一个 SFR 数字，都是多个明确的几何与信号处理决策共同作用后的结果，而且这些决策都可以在代码里逐项追踪。

61. PTC Modal Detailed Implementation

61. PTC 窗口具体实现细解

• PTCModal.tsx is a large self-contained analysis workstation for photon-transfer style data, not just a chart widget.
• PTCModal.tsx 是一个大型的自包含分析工作站，用于处理光子转移风格数据，而不只是一个画图控件。
• Its base input type is PTCPoint, which stores channel, mean, std, and optional file or grid provenance fields.
• 它的基础输入类型是 PTCPoint，里面保存了 channel、mean、std，以及可选的文件来源或网格来源字段。
• The modal supports three top-level view families, Noise, SNR, and Linear, which means one imported dataset can be reinterpreted through multiple plotting lenses.
• 这个弹窗支持三类顶层视图，分别是 Noise、SNR 和 Linear，也就是说同一批导入数据可以被用多种绘图视角重新解释。
• It also layers filtering (default, top3, raw), visible-channel gating, manual black-level overrides, saturation picking, fit-range selection, and export styling on top of the same base points.
• 它还会在同一批基础点之上叠加过滤模式（default、top3、raw）、通道可见性、手动黑电平覆盖、饱和点选择、拟合区间选择和导出样式。

62. PTC Data Conditioning And Dominant Channel Logic

62. PTC 数据整形与主导通道逻辑

• The modal computes baseData, downsampled display groups, and a fittingDataset separately, which is an important design choice.
• 这个弹窗会分别计算 baseData、用于显示的降采样分组，以及 fittingDataset，这是一个很关键的设计选择。
• Display rendering is aggressively downsampled to prevent chart DOM overload, but fitting uses a deeper signal-aware dataset rather than the tiny display subset.
• 为了防止图表 DOM 过载，显示层会做强力降采样，但拟合层使用的是更深、更偏信号意义的数据集，而不是只用界面上的那几十个点。
• The dominantChannel concept is used throughout the fitting and derived-statistic pipeline, because many downstream values such as gain and DR are defined against the channel judged most representative or saturating.
• dominantChannel 这个概念贯穿整个拟合与派生统计流程，因为后续很多值，比如增益和动态范围，都是相对于被认为最有代表性或最先饱和的那个通道来定义的。
• If the dominant channel has too few usable points, the fit can fall back to the wider baseData, which makes the system more robust to sparse channel-specific datasets.
• 如果主导通道的可用点太少，拟合会退回更宽泛的 baseData，这让系统在某个通道数据过稀时仍能工作。

63. PTC Noise Model Fitting

63. PTC 噪声模型拟合

• The fitting model is a constrained quadratic variance model of the form variance = a + b * signal + c * signal^2.
• 这套拟合模型本质上是一个受约束的二次方差模型，形式是 variance = a + b * signal + c * signal^2。
• In that interpretation, a maps to read-noise variance, b maps inversely to gain, and c maps to PRNU energy.
• 在这个解释下，a 对应读出噪声方差，b 与增益成反比，而 c 对应 PRNU 能量。
• The implementation first selects points inside a percentage-of-max-signal fit range, converts standard deviation into variance, and then balances the sample set by signal-density weighting.
• 实现上会先按“占最大信号百分比”的拟合区间筛点，把标准差转换成方差，再通过信号密度平衡权重来防止某一段信号区间过度主导拟合。
• It then solves a constrained quadratic system, allowing any subset of a, b, and c to be fixed by parameter locks.
• 接着它会求解一个受约束的二次系统，并允许通过参数锁把 a、b、c 中的任意子集固定住。
• A robust iterative reweighting loop follows, using normalized residuals, MAD-derived scale estimation, and Huber-like weighting to suppress outliers.
• 之后还会进入一个稳健迭代重加权循环，利用归一化残差、基于 MAD 的尺度估计，以及类似 Huber 的权重来压制离群点。
• The gain-density side panel is not decorative; it is built from effective per-point gain samples derived after subtracting read-noise and PRNU variance components.
• 增益密度侧图并不是装饰，它是从逐点有效增益样本构建出来的，而这些样本是在扣除读噪和 PRNU 方差项之后得到的。

64. PTC Range Selection, Theoretical Curves, And Export

64. PTC 区间选择、理论曲线与导出

• The fit range is represented as a percentage of the current maximum signal and can be edited numerically, by clicking selection mode, or by dragging chart handles.
• 拟合区间以“当前最大信号的百分比”表示，可以通过数值输入、点击选择模式，或直接拖拽图表手柄来修改。
• Internally, chart dragging is converted back into signal-space and then back into fit-range percentages, so the UI is geometric but the model remains signal-relative.
• 在内部，图表拖拽会先被还原到信号空间，再换算回拟合区间百分比，因此界面是几何式的，但模型仍保持相对信号的定义方式。
• The modal can overlay theoretical read, shot, PRNU, total, and fit-range guides over the measured point cloud.
• 这个弹窗可以把理论读噪、shot、PRNU、总噪声以及拟合区间引导线叠加到实测点云之上。
• Export is handled by a custom canvas renderer rather than by screenshotting the DOM, which is why exported JPGs can use special fluorescent scatter rendering and summary annotations.
• 导出并不是简单地截图 DOM，而是走自定义 canvas 渲染器，因此导出的 JPG 才能应用特殊的荧光散点样式和摘要注释。
• The current code also supports a dedicated export settings panel where the user can choose whether to enable enlarged glow points before generating the final JPG.
• 当前代码还支持一个专门的导出设置面板，用户可以在真正生成 JPG 之前决定是否启用放大的 glow 点样式。

65. Stacking Modal Detailed Implementation

65. 堆栈窗口具体实现细解

• StackingModal.tsx is the operator console for a formula-driven multi-frame processing engine.
• StackingModal.tsx 是一个面向公式驱动多帧处理引擎的操作台。
• The user does not merely load a folder and press merge; instead, files are mapped to symbolic identifiers like A, B, C, and then a textual formula decides how they are combined.
• 用户并不是简单地加载一个文件夹然后点合并；相反，文件会先映射到诸如 A、B、C 这样的符号标识，再由一条文本公式决定它们如何组合。
• The modal stores that formula in localStorage, validates black levels, validates alignment parameters, logs an execution trace, and finally calls processStacking(...).
• 这个弹窗会把公式持久化到 localStorage，校验黑电平，校验对齐参数，记录执行日志，最后再调用 processStacking(...)。
• The output mode can be either mosaic-oriented dng16 or RGB-oriented jdngf32, and that choice changes not only file format but also the legal internal data path.
• 输出模式可以是面向马赛克的 dng16，也可以是面向 RGB 的 jdngf32；这个选择改变的不只是文件格式，还会改变内部允许的数据路径。

66. Stacking Formula Engine And Decode Phase

66. 堆栈公式引擎与解码阶段

• processStacking() begins by tokenizing the user formula, converting it to RPN, and collecting the exact image identifiers actually referenced by the expression.
• processStacking() 会先对用户公式做词法切分，再转成逆波兰表达式，并提取出这个表达式真正引用到的图像标识符。
• This means the engine does not blindly decode every loaded file; it decodes only the slots the expression really needs.
• 这意味着这个引擎不会盲目解码所有已加载文件，而是只解码表达式真正需要的那些 slot。
• Each referenced file is decoded into a RawSlot with dimensions, channel count, CFA pattern, original mask, and float work buffer.
• 每个被引用的文件都会被解码成一个 RawSlot，其中包含尺寸、通道数、CFA 模式、原始掩码和浮点工作缓冲区。
• RAW-like files go through processRawDataOnly, while ordinary images can go through processStandardImage, so the stacker can operate on more than one input class.
• RAW 风格文件会走 processRawDataOnly，而普通图像则可以走 processStandardImage，因此这个堆栈器并不只面向单一输入类型。
• A hard dimension-consistency check then guarantees all referenced slots share the same width and height before any alignment or arithmetic happens.
• 在任何对齐或算术操作开始之前，系统还会执行一次严格的尺寸一致性检查，确保所有被引用的 slot 具有相同宽高。

67. Stacking Alignment Modes

67. 堆栈对齐模式

• The code explicitly enforces that at most one alignment family can be enabled at a time: align1, align2, or align3.
• 代码会显式强制最多只能启用一种对齐家族：align1、align2 或 align3。
• align1 is described as strict HDR+ style block matching.
• align1 被描述为严格的 HDR+ 风格块匹配。
• align2 is the dense-flow style path with a robustness threshold.
• align2 是带有稳健阈值的密集光流风格路径。
• align3 is the most advanced path and can be either ecc or apap, both of which depend on OpenCV.
• align3 是最高级的路径，可以选择 ecc 或 apap，两者都依赖 OpenCV。
• ECC mode builds guide planes, downsamples them to a controlled dimension, optionally normalizes illumination globally, and then estimates a warp with findTransformECC.
• ECC 模式会先构建引导平面，再把它们缩放到受控尺寸，可选地做全局照明归一化，然后通过 findTransformECC 估计变换矩阵。
• APAP mode instead detects features, matches them, solves a locally adaptive warp field, and then remaps the source through those spatially varying maps.
• APAP 模式则会检测特征、进行匹配、求解局部自适应变换场，然后再通过这张空间变化的映射场去重映射源图像。
• The alignment subsystem is therefore not a cosmetic pre-pass; it directly determines how per-frame information lands in the later arithmetic evaluation.
• 因此对齐子系统绝不是一个装饰性的预处理，它会直接决定每帧信息在后续算术求值中的落位方式。

68. Stacking Evaluation And Output Packing

68. 堆栈求值与输出封装

• After alignment, evalRPN(...) computes the user expression in the float domain and returns both the merged data and a source map.
• 对齐完成后，evalRPN(...) 会在浮点域里计算用户表达式，并同时返回合并后的数据以及一张 source map。
• An optional legacy-style highlight stretch rescales the entire result so the brightest value fits the output container headroom after output black level is considered.
• 还有一个可选的传统式高光拉伸步骤，会在考虑输出黑电平之后，把整个结果重新缩放到适合输出容器头部空间的范围内。
• If the user chose jdngf32, the result is first converted through a drizzle-style RGB kernel approximation, then output black level is added, and finally the data is packed into a custom Float32 JDNG container.
• 如果用户选择的是 jdngf32，结果会先经过一种 drizzle 风格的 RGB kernel 近似，再加上输出黑电平，最后被打包进自定义的 Float32 JDNG 容器。
• If the user chose dng16, the result must remain single-channel mosaic data; otherwise the processor throws and asks the user to use Float32 JDNG instead.
• 如果用户选择的是 dng16，结果就必须保持单通道马赛克数据；否则处理器会直接报错，并要求用户改用 Float32 JDNG。
• Final dng16 packing is done through Pyodide with a Python DNG packer, which mirrors the project’s broader pattern of mixing browser-side JS with targeted Python serialization helpers.
• 最终的 dng16 封装是通过 Pyodide 调用 Python DNG 打包器完成的，这延续了整个项目“浏览器端 JS 加定向 Python 序列化辅助”的总体风格。

69. PS Mode Architecture In App

69. App 中的 PS 模式架构

• PS mode is orchestrated from App.tsx, where the current session can lazily acquire or restore a PsDocument.
• PS 模式由 App.tsx 统一调度，当前 session 会在这里按需创建或恢复一个 PsDocument。
• App.tsx also owns PS-specific history state, transient painting state, preview caches, GPU renderer fallbacks, and the event handlers that bridge UI gestures into document mutations.
• App.tsx 同时还掌管 PS 专属历史状态、临时绘画状态、预览缓存、GPU 渲染回退策略，以及把 UI 手势桥接成文档变更的那些事件处理器。
• This means psDocument.ts is the pure document engine, but App.tsx is the runtime shell that makes the engine interactive.
• 这意味着 psDocument.ts 是纯文档引擎，而 App.tsx 则是让这个引擎真正可交互的运行时外壳。
• The separation is deliberate: document math lives in services, while session ownership, history, preview invalidation, and input routing live in the app layer.
• 这种分离是有意设计的：文档数学逻辑放在 services 层，而 session 归属、历史记录、预览失效和输入路由放在应用层。

70. PS Document Data Model

70. PS 文档数据模型

• createInitialPsDocument() creates a document with dimensions, a global adjustment layer, empty masks, empty guides, and a seeded history entry.
• createInitialPsDocument() 会创建一个带尺寸、全局调整图层、空蒙版、空参考线以及初始历史条目的文档。
• The global adjustment layer is identified by PS_GLOBAL_LAYER_MASK_ID and is conceptually applied before all mask-bound layers.
• 全局调整图层通过 PS_GLOBAL_LAYER_MASK_ID 标识，在概念上它会先于所有绑定到蒙版的图层生效。
• Ordinary masks are separate from layers, but helper functions like addMaskWithLayer() and ensureLayerForMask() keep the common one-mask-one-layer pattern easy to maintain.
• 普通蒙版本身和图层是分离的，但像 addMaskWithLayer() 和 ensureLayerForMask() 这类辅助函数会把常见的一蒙版一图层模式维持得很顺手。
• Each mask can hold multiple items, such as brush strokes or ellipse items, and the alpha plane is rebuilt from those items instead of being treated as a blind bitmap forever.
• 每个蒙版都可以包含多个 item，比如笔刷笔触或椭圆 item，而且 alpha 平面会根据这些 item 被重建，而不是永远只是一个盲目的位图。
• Each layer carries basic adjustments, mixer settings, curves, blend mode, opacity, and enabled state, so the document is closer to a structured local-adjustment stack than to a raster paint layer list.
• 每个图层都携带基础调整、色彩混合器、曲线、混合模式、不透明度和启用状态，因此这个文档更像是结构化的局部调整栈，而不是传统意义上只会堆栈像素的画图层列表。

71. PS Masks, Brush, Ellipse, And Guides

71. PS 蒙版、笔刷、椭圆与参考线

• paintSelectedMask() directly modifies the selected mask alpha in a local dab region, while appendBrushStrokeItemToSelectedMask() records brush strokes as reusable mask items.
• paintSelectedMask() 会在局部笔刷范围内直接修改当前选中蒙版的 alpha，而 appendBrushStrokeItemToSelectedMask() 则会把笔刷轨迹记录成可复用的 mask item。
• addEllipseMaskWithLayer() creates or reuses the selected mask and appends an ellipse item with center, radii, rotation, feather, and add/subtract mode.
• addEllipseMaskWithLayer() 会创建或复用当前蒙版，并追加一个包含中心、半径、旋转、羽化以及 add/subtract 模式的椭圆 item。
• Guides are first-class document objects with endpoints, selection, and removal operations, not just visual rulers.
• 参考线是具备端点、选择与删除操作的一等文档对象，而不只是视觉标尺。
• PsEditorPanel.tsx exposes all of this through expandable mask lists, item lists, overlay toggles, layer controls, mixer-band pickers, and per-channel curve editors.
• PsEditorPanel.tsx 通过可展开的蒙版列表、item 列表、叠加层开关、图层控制、混色器频段选择器和分通道曲线编辑器把这些能力全部暴露给用户。
• That panel also distinguishes preview callbacks from commit callbacks, which is how the UI can scrub a slider responsively before finalizing the edit into document state.
• 这个面板还把 preview 回调和 commit 回调区分开来，因此用户拖动滑条时可以先做流畅预览，最后再把结果正式提交进文档状态。

72. PS Preview, History, And Dirty Updates

72. PS 预览、历史与脏区更新

• App.tsx maintains a separate history stack per session, and each history entry stores a deep-cloned document plus transform-operation metadata.
• App.tsx 会为每个 session 维护独立的历史栈，而且每个历史条目都会保存一份深拷贝文档以及对应的变换操作元数据。
• updateCurrentPsDocument(...) is the central mutation gateway; if history tracking is enabled, it appends a new history entry, applies limits, and injects history metadata back into the live document.
• updateCurrentPsDocument(...) 是中心化的文档变更入口；当启用历史追踪时，它会追加新历史条目、执行长度限制，并把历史元数据重新写回当前文档。
• Undo and arbitrary history jumps restore a historical document snapshot and also clear or preserve transient preview state depending on whether the preview fingerprint changed.
• 撤销和任意历史跳转会恢复历史快照，同时还会根据预览指纹是否变化来决定清理还是保留临时预览状态。
• Preview rendering first tries PS WebGPU, then PS WebGL, and finally falls back to CPU composition if GPU paths are unavailable or temporarily busy.
• 预览渲染会先尝试 PS WebGPU，再尝试 PS WebGL，最后在 GPU 不可用或暂时忙碌时回退到 CPU 合成。
• If only a mask region changed and an older preview frame exists, composePsDocumentPreviewDirty() can update only the dirty rect instead of recomposing the whole image.
• 如果只是蒙版局部发生变化且旧预览帧仍存在，composePsDocumentPreviewDirty() 就能只更新脏矩形，而不必整张图完全重算。
• That dirty-rect path is one of the main reasons brush and mask interactions can stay responsive despite the complexity of the document model.
• 这个脏区更新路径是笔刷和蒙版交互在文档模型相当复杂时仍能保持响应的重要原因之一。

73. PS Geometric Transform Pipeline

73. PS 几何变换流水线

• Document transforms are not handled only as view tricks; they can be materialized into the actual document through crop, rotate, flip, upright, lens correction, and projective transform functions.
• 文档变换并不只是界面层的观察技巧；它们可以通过裁切、旋转、翻转、拉直、镜头校正和投影变换真正固化进文档。
• materializePsViewDocument() in App.tsx shows the intended order: upright transform, flips, then view rotation.
• App.tsx 里的 materializePsViewDocument() 很清楚地展示了预期顺序：先 upright 变换，再翻转，最后才是视图旋转。
• Crop-to-ROI uses that materialized view document so the crop is applied to what the user is actually seeing, not to some hidden pre-transform coordinate frame.
• 裁切到 ROI 会基于这个已经物化的视图文档执行，因此裁切的是用户真正看到的画面，而不是某个隐藏的未变换坐标系。
• Guide-based upright correction and Lensfun distortion correction are therefore integrated into the same broader transform history instead of living as disconnected display hacks.
• 因此，基于参考线的拉直校正和 Lensfun 畸变校正都被并入同一条更大的变换历史链，而不是孤立存在的显示技巧。

74. RAW Render Path Overview

74. RAW 渲染路径总览

• rawProcessor.ts contains several render families, and the most important distinction is between standard LibRaw-like rendering and the project’s own zero-dependency render families.
• rawProcessor.ts 内部有多条渲染家族，最重要的区别在于 standard 的类 LibRaw 渲染路径，与项目自己实现的 zero-dependency 渲染家族之间的差异。
• In App.tsx, this split matters operationally because GPU preview/export paths are used mainly for zero-dependency modes, while standard mode is treated as a distinct decode logic.
• 在 App.tsx 里，这种分裂在运行上非常重要，因为 GPU 预览和导出主要服务于 zero-dependency 模式，而 standard 模式则被视为一套独立的解码逻辑。
• For raw-like Bayer input, the available choices are roughly grayscale zero-dependency, basic color zero-dependency, advanced scalar-unmix zero-dependency, and official standard render.
• 对于 RAW 风格的 Bayer 输入，可用选项大致包括灰度 zero-dependency、彩色 zero-dependency、advanced scalar-unmix zero-dependency，以及官方式的 standard 渲染。
• For three-plane inputs, the CPU fallback uses a dedicated three-plane renderer rather than trying to pretend the data is mosaic.
• 对于三平面输入，CPU 回退会使用专门的三平面渲染器，而不会强行把它伪装成马赛克数据。

75. Standard Official Render Path

75. Standard 官方渲染路径

• renderRawWithOfficial16() uses joraw.js or joraw.wasm through the JoRaw class and asks that runtime to perform a 16-bit decode.
• renderRawWithOfficial16() 会通过 JoRaw 类调用 joraw.js 或 joraw.wasm，让这套运行时执行 16 位解码。
• It configures demosaic quality, optional custom black levels, exposure behavior, and a custom color-matrix path if the user provided an invertible customMatrix.
• 它会配置 demosaic 质量、可选的自定义黑电平、曝光行为，以及在用户提供可逆 customMatrix 时启用的自定义颜色矩阵路径。
• In the normal case, JoRaw can output camera-WB-driven sRGB-like RGB directly.
• 在普通情况下，JoRaw 可以直接输出基于相机白平衡的类似 sRGB 的 RGB 结果。
• In the custom-matrix case, the function instead requests a camera-space style output, multiplies it by a derived matrix chain, applies exposure scaling, and then applies sRGB gamma manually.
• 而在自定义矩阵情况下，这个函数会改为请求更接近相机空间的输出，然后自己乘上推导出的矩阵链、应用曝光缩放，并手动施加 sRGB gamma。
• This path is the reason standard mode can preserve a LibRaw-like look that is intentionally distinct from the project’s custom renderers.
• 正是这条路径，让 standard 模式能够保留一种接近 LibRaw 的外观风格，并与项目自定义渲染器保持有意区分。

76. Zero-Dependency Render Families

76. Zero-Dependency 渲染家族

• renderZeroDependencyFromRawImage() is the simplest path: it interprets each mosaic site independently, subtracts black level, applies exposure and simple Bayer-position white balance, and displays the result as grayscale.
• renderZeroDependencyFromRawImage() 是最简单的路径：它逐个解释马赛克采样点，减去黑电平，应用曝光和基于 Bayer 位置的简单白平衡，然后把结果以灰度形式显示出来。
• renderBasicColorZeroDepFromRawImage() is the project’s own full-color path, including normalization, white balance, optional RGGB or BGGR interpretation, a bilinear or AMAZE-like demosaic choice, and a camera-to-sRGB matrix stage.
• renderBasicColorZeroDepFromRawImage() 是项目自带的全彩路径，包含归一化、白平衡、可选的 RGGB 或 BGGR 解释、双线性或类 AMAZE 的 demosaic 选择，以及相机到 sRGB 的矩阵阶段。
• renderAdvancedZeroDepFromRawImage() is the scalar-unmix path, which uses user-provided bl, bg, and fg references to remap each mosaic sample into a common reference brightness domain.
• renderAdvancedZeroDepFromRawImage() 是 scalar-unmix 路径，它利用用户提供的 bl、bg 和 fg 参考，把每个马赛克采样重映射到统一参考亮度域中。
• That advanced mode does not just change color; it changes the signal interpretation itself by computing an alpha between background and foreground references and then extrapolating outside the calibrated range when needed.
• 这种 advanced 模式并不只是改颜色，而是会改变信号解释本身：它通过计算背景与前景参考之间的 alpha，并在需要时对标定范围外进行外推。
• This is why the same RAW file can look radically different between standard, zero-dependency, zero-dep-color, and advanced-zero-dep.
• 这也就是为什么同一张 RAW 在 standard、zero-dependency、zero-dep-color 和 advanced-zero-dep 之间会呈现出非常不同的结果。

77. Export-Oriented Render Paths

77. 面向导出的渲染路径

• Export behavior has changed materially: Ctrl+S is now a quick-save path for the current rendered result and exits through JDNG rather than only invoking the older generic save-modal flow.
• 导出行为现在已经有了实质变化：Ctrl+S 会把当前渲染结果走一条 JDNG 快速保存路径，而不是只唤起旧的通用保存弹窗流程。
• For scalar or mosaic-style states, the quick-save path writes a single-plane JDNG and preserves CFA index or pattern information so later raw-domain work can still recover phase semantics.
• 对于标量或马赛克风格状态，这条快速保存路径会写出单平面 JDNG，并保留 CFA 索引 / pattern 信息，以便后续 RAW 域工作仍能恢复相位语义。
• For full-color or true three-plane states, the quick-save path writes a three-plane JDNG instead of collapsing the view back into a single-plane mosaic container.
• 对于全彩或真正三平面状态，这条快速保存路径会写出三平面 JDNG，而不会再把当前画面硬压回单平面马赛克容器。
• The goal of this path is to preserve the current rendered result in a linear, non-stretched form that matches the visible render semantics more closely than the older export split did.
• 这条路径的目标，是以线性、未拉伸的形式保留“当前界面渲染结果”，让导出语义比旧导出分叉更贴近屏幕上正在看的那种渲染含义。
• JDNG import logic is paired with that export design: single-plane JDNG reopens as an unrendered raw-mosaic style session, while native three-plane JDNG reopens as three-plane data.
• 与之配套的 JDNG 导入逻辑也已经同步：单平面 JDNG 重新打开时会进入未渲染的 raw mosaic 风格会话，而原生三平面 JDNG 则会保持三平面状态。
• Traditional DNG or TIFF service helpers still exist for other workflows, but they are no longer the best mental model for understanding what Ctrl+S does today.
• 传统 DNG / TIFF 服务函数仍然服务于其他工作流，但它们已经不再是理解当下 Ctrl+S 行为的最佳心智模型。

78. How To Choose Among Render Modes

78. 如何在几种渲染模式之间做选择

• Choose standard when you want the closest thing this app has to an official RAW developer look and do not mind depending on the JoRaw runtime.
• 当你想要最接近“官方 RAW 显影器观感”的结果，并且不介意依赖 JoRaw 运行时时，应选择 standard。
• Choose grayscale zero-dependency when you want raw-site brightness inspection without committing to full demosaic color interpretation.
• 当你想观察 RAW 采样点亮度，而不想过早进入全彩 demosaic 解释时，应选择灰度 zero-dependency。
• Choose zero-dep-color when you want a full-color result but still want the project’s own demosaic and color pipeline instead of the JoRaw output look.
• 当你想得到全彩图像，但又希望使用项目自己的 demosaic 和颜色管线，而不是 JoRaw 的输出风格时，应选择 zero-dep-color。
• Choose advanced-zero-dep when the whole task is built around scalar unmixing, foreground and background references, or measurements that need that remapped signal domain.
• 当整个任务围绕 scalar unmixing、前景/背景参考，或者需要这种重映射信号域的测量展开时，就应选择 advanced-zero-dep。
• In other words, render mode here is not a cosmetic preset; it changes the mathematical story of what the pixels mean.
• 换句话说，这里的 render mode 不是视觉预设，而是在改变像素背后的数学含义。

79. Using DNG Export For Black-Level Fine Tuning

79. 用 DNG Export 做黑电平微调

• DngExportModal.tsx is one of the most direct places in the app for black-level micro-adjustment because it lets you write a fresh 16-bit DNG container with explicit manual black levels.
• DngExportModal.tsx 是整个应用里最直接的黑电平微调入口之一，因为它允许你用显式手动黑电平重新写出一个新的 16 位 DNG 容器。
• The 16bit Black Level (Manual Fill) field accepts either one number or four numbers.
• 16bit Black Level (Manual Fill) 这个输入框既可以接受一个数，也可以接受四个数。
• If you enter one number, the code expands it to four identical values; if you enter fewer than four values, the code pads the rest with zero.
• 如果你只输入一个数，代码会把它扩展成四个相同值；如果你输入不足四个值，代码会把剩余位置补零。
• That means you can use it both for coarse global tuning and for per-channel tuning when one quadrant or channel family sits differently.
• 这意味着你既可以用它做粗略的全局微调，也可以在某个象限或某类通道位置偏移不一致时做分通道微调。
• In the Python DNG packer, these values are written into the BlackLevel tag together with BlackLevelRepeatDim = [2, 2], so they become metadata-level black offsets rather than just display-side offsets.
• 在 Python DNG 打包器里，这些值会和 BlackLevelRepeatDim = [2, 2] 一起被写入 BlackLevel 标签，因此它们是元数据层面的黑电平偏置，而不仅仅是显示层偏置。
• The practical workflow is to export several nearby DNG variants, re-open them, and compare dark ROI means, shadow neutrality, and clipping headroom until the result stabilizes.
• 最实用的流程是连续导出几份相邻数值的 DNG 变体，再重新载入比较暗场 ROI 均值、阴影中性度和高光余量，直到结果稳定为止。
• If the problem is mostly global pedestal, change all four numbers together.
• 如果问题主要是全局 pedestal 偏移，就四个数一起改。
• If the problem looks like Bayer-position imbalance, change the four values independently and observe whether one color cast or checkerboard asymmetry disappears.
• 如果问题更像 Bayer 位置不平衡，就把四个值拆开独立调整，并观察某种色偏或棋盘状不对称是否消失。
• Bit Shift and Offset (+) are separate from black-level tuning and should not be confused with it.
• Bit Shift 和 Offset (+) 与黑电平微调是两回事，不应混为一谈。
• Bit Shift scales the raw code range upward into 16-bit container space, while Offset (+) adds a literal constant after that shift.
• Bit Shift 的作用是把原始码值范围放大到 16 位容器尺度，而 Offset (+) 则是在位移之后再直接加一个常数。
• In other words, Black Level changes the DNG metadata meaning, but Offset (+) changes the stored pixel values themselves.
• 换句话说，Black Level 改的是 DNG 元数据层的解释，而 Offset (+) 改的是实际写入的像素值本身。
• For black-level micro-tuning, prefer changing Black Level first, and only use Offset (+) when you intentionally want to move the entire stored signal up or down.
• 在做黑电平微调时，应优先调整 Black Level；只有在你明确想把整张图的实际存储信号整体抬高或压低时，才去用 Offset (+)。
• A good verification habit is to reopen the exported DNG, inspect EXIF-like black-level interpretation externally if needed, and then measure central dark ROIs again in this app.
• 一个很好的验证习惯是把导出的 DNG 重新打开，必要时去外部软件检查黑电平解释，然后再回到本应用重新测量中央暗场 ROI。

80. DNG Export Button-Level Manual

80. DNG Export 按钮级手册

• Width (Read Only) and Height (Read Only) are inspection fields only; they help you confirm you are packaging the intended frame dimensions.
• Width (Read Only) 和 Height (Read Only) 只是只读检查项；它们帮助你确认当前打包的确实是你想要的那张尺寸。
• Bit Shift (<<) multiplies the raw codes by 2^shift before DNG packing.
• Bit Shift (<<) 会在打包前把原始码值乘以 2^shift。
• Offset (+) adds a constant after bit shifting and before clipping to the 16-bit range.
• Offset (+) 会在位移之后、裁切到 16 位范围之前再加上一个常数。
• Pattern chooses the CFA pattern written into the DNG metadata.
• Pattern 决定写入 DNG 元数据的 CFA pattern。
• 16bit Black Level (Manual Fill) fills the exported DNG BlackLevel tag and is the main black-level micro-tuning control.
• 16bit Black Level (Manual Fill) 用来填充导出 DNG 的 BlackLevel 标签，是最主要的黑电平微调控件。
• Color Matrix (XYZ to Raw - 9 Values) writes the exported color matrix, and the camera dropdown can preload known matrices from cameraMatrices.ts.
• Color Matrix (XYZ to Raw - 9 Values) 用于写入导出时的颜色矩阵，而相机下拉框则可以从 cameraMatrices.ts 中预载已知矩阵。
• Enable Watermark switches on the watermark path, which actually edits the pixel buffer by adding watermarkDepth where the text mask is white.
• Enable Watermark 会启用水印路径，这条路径会在文字遮罩为白的位置真正修改像素缓冲区，并加上 watermarkDepth。
• Size, Depth, Center X, and Center Y only affect the watermark path.
• Size、Depth、Center X 和 Center Y 只影响水印路径。
• Batch Export opens a hidden file input, then loops over selected files and applies the current modal settings to every one of them.
• Batch Export 会打开隐藏文件选择框，然后把当前弹窗里的设置批量应用到每一个选中文件。
• Generate DNG runs the current single-image export immediately for the currently loaded rawImageData.
• Generate DNG 会立刻对当前已加载的 rawImageData 执行单张导出。
• If you are tuning black level, keep the matrix and watermark fixed while iterating black-level values, otherwise you make comparison harder than it needs to be.
• 如果你是在调黑电平，建议在多次导出比较时把矩阵和水印保持不变，否则会让比较变得不必要地困难。

81. Header Button-Level Manual

81. 顶部栏按钮级手册

• TOOLS opens the multi-lab dropdown and is the main launcher for PS Mode, DR Lab, Color Lab, SFR Lab, Stack Lab, Save Z8, pattern DNG generation, PTC generation, and external contour tools.
• TOOLS 会打开多实验室下拉菜单，是 PS Mode、DR Lab、Color Lab、SFR Lab、Stack Lab、Save Z8、测试图 DNG 生成、PTC 生成和外部 contour 工具的主发射器。
• PS Mode in that dropdown switches the app into the local-adjustment editor and turns off other mutually exclusive lab modes.
• 下拉菜单里的 PS Mode 会把应用切到局部调整编辑器，并关闭其他互斥实验室模式。
• DR Lab, Color Lab, SFR Lab, and Stack Lab are mode toggles, not one-shot actions.
• DR Lab、Color Lab、SFR Lab 和 Stack Lab 都是模式切换，不是一次性动作。
• Save Z8 opens the rescue-oriented Nikon Z8 workflow.
• Save Z8 会打开面向 Nikon Z8 修复的专用流程。
• Generate Pattern DNG creates a synthetic test-pattern DNG.
• Generate Pattern DNG 用来生成测试图案 DNG。
• Generate PTC opens the file input for CSV-based PTC generation.
• Generate PTC 会打开用于 PTC 的 CSV 输入入口。
• Load Image opens another dropdown with two choices.
• Load Image 还会再打开一个二级下拉菜单，其中有两种加载方式。
• Load Image (Direct) loads the chosen file directly.
• Load Image (Direct) 会直接加载所选文件。
• Convert to Adobe DNG & Load uses the converter-assisted path and therefore depends on JiangBridge plus Adobe DNG Converter being available.
• Convert to Adobe DNG & Load 走的是转换后再加载路径，因此依赖 JiangBridge 和 Adobe DNG Converter 可用。
• EXIF opens the metadata viewer for the current file.
• EXIF 会打开当前文件的元数据查看器。
• About/Tools opens the about-and-resources modal.
• About/Tools 会打开关于与资源入口弹窗。
• 教程 opens the external tutorial page.
• 教程 会打开外部教程页面。
• Hide Panel or Show Panel toggles the main control sidebar.
• Hide Panel 或 Show Panel 用于切换主控制侧栏显示。
• The small active pills such as DR Lab On, Color Lab On, FFT Lab On, SFR Lab On, and PS Mode On are quick status indicators and, for most labs, quick off toggles.
• 顶部那些诸如 DR Lab On、Color Lab On、FFT Lab On、SFR Lab On 和 PS Mode On 的小状态条既是状态提示，也是多数实验室的快速关闭开关。

82. Sidebar Display Controls Button Manual

82. 侧栏 Display Controls 按钮级手册

• Apply Settings / Render applies the current display settings through the zero-dependency path and is the main “commit my current display-control edits” button.
• Apply Settings / Render 会通过 zero-dependency 路径应用当前显示设置，是最主要的“提交我现在这些显示参数”的按钮。
• Try Official Render opens the standard-render options modal and then renders through the official-style path instead of the analysis-first custom path.
• Try Official Render 会打开 standard render 选项弹窗，然后改走官方风格渲染路径，而不是分析优先的自定义路径。
• Generate 16bit DNG opens the manual DNG export workstation.
• Generate 16bit DNG 会打开手动 DNG 导出工作站。
• Reset Defaults (Local) resets the local UI fields in the sidebar without promising to reset every persisted application state.
• Reset Defaults (Local) 会重置侧栏里的本地 UI 字段，但并不意味着会重置所有持久化应用状态。
• In the zero-dependency selection modal, RGGB and BGGR choose Bayer interpretation.
• 在 zero-dependency 选择弹窗里，RGGB 和 BGGR 用来选择 Bayer 解释方式。
• Bilinear and AMaZE (Default) choose the color demosaic method for the basic-color zero-dependency renderer.
• Bilinear 和 AMaZE (Default) 用来选择 basic-color zero-dependency 渲染器的彩色 demosaic 方法。
• Raw Mosaic renders the checkerboard-like grayscale inspection view.
• Raw Mosaic 会渲染棋盘风格的灰度检查视图。
• Basic Color renders the project’s custom color pipeline.
• Basic Color 会渲染项目自带的彩色管线。
• In the official-render modal, Demosaic Method chooses the algorithm passed into the JoRaw/official path.
• 在 official-render 弹窗里，Demosaic Method 决定传给 JoRaw/official 路径的算法。

83. Sidebar Analysis And Lab Button Manual

83. 侧栏分析与实验室按钮级手册

• Spot WB computes white-balance gains from the current ROI while considering the current color matrix.
• Spot WB 会基于当前 ROI 计算白平衡增益，并把当前颜色矩阵考虑进去。
• [about] beside black level opens the black-level info modal and can redirect you to the camera black-level database.
• 黑电平旁边的 [about] 会打开黑电平说明弹窗，并可跳转到相机黑电平数据库。
• RUN UNMIXING (ADV ZERO-DEP) executes scalar unmixing with the current BL/BG/FG inputs.
• RUN UNMIXING (ADV ZERO-DEP) 会用当前的 BL/BG/FG 输入执行 scalar unmixing。
• Pick next to BG or FG fills those fields from the current ROI mean values.
• BG 或 FG 旁边的 Pick 会用当前 ROI 的均值自动填充这些输入框。
• In FFT Lab, Load Image A, Load Image B, and Generate Diff & Load form the pair-difference path.
• 在 FFT Lab 里，Load Image A、Load Image B 和 Generate Diff & Load 组成成对差分路径。
• Batch Diffs (Auto Download) runs multiple pair differences in batch.
• Batch Diffs (Auto Download) 用于批量执行多组成对差分。
• Select Sequence Files in Stack FFT (Avg PSD) starts the stack spectral workflow.
• Stack FFT (Avg PSD) 里的 Select Sequence Files 会启动堆栈频谱流程。
• Cross-Compensation Calc opens the sigma calculator.
• Cross-Compensation Calc 会打开 sigma 计算器。
• General Stack opens the general stacking workstation.
• General Stack 会打开通用堆栈工作站。
• In DR Lab, Generate Test Pic creates the synthetic DR test pattern.
• 在 DR Lab 中，Generate Test Pic 会生成合成动态范围测试图。
• Mark Corners begins the four-corner marking workflow for DR calibration.
• Mark Corners 会启动四角点标记流程，用于 DR 标定。
• Reuse Last & Batch opens the batch reuse menu built on the most recent marker layout.
• Reuse Last & Batch 会打开基于最近一次标记布局的批处理复用菜单。
• Convert Format (.txt -> .csv) is a utility converter for data format cleanup.
• Convert Format (.txt -> .csv) 是一个用于整理数据格式的辅助转换按钮。
• In Color Lab, Start Marking begins the ColorChecker marking workflow.
• 在 Color Lab 中，Start Marking 会启动 ColorChecker 标记流程。

84. SFR Lab Button-Level Manual

84. SFR Lab 按钮级手册

• Source chooses among Unmix / BW, RGGB Raw, and Three-plane.
• Source 用于在 Unmix / BW、RGGB Raw 和 Three-plane 之间切换。
• Encoding chooses Auto, Linear, or sRGB. Auto is only selectable when the app can infer the source encoding with enough confidence.
• Encoding 用于选择 Auto、Linear 或 sRGB。只有当程序能较可靠判断当前源编码时，Auto 才可选。
• In RGGB Raw, the green-phase selector offers Default, 1, and 2. Default follows the RAW CFA pattern, 1 means the top-left / bottom-right green phase, and 2 means the top-right / bottom-left green phase.
• 在 RGGB Raw 模式下，绿色相位选择器提供 Default、1 和 2。Default 跟随 RAW 自带 CFA pattern，1 表示左上 / 右下绿相位，2 表示右上 / 左下绿相位。
• Output Polar Point Sets opens the dedicated point-set / plot modal for current auto-detected edges.
• Output Polar Point Sets 会为当前自动检测到的边打开专门的点集 / 绘图弹窗。
• Auto Detect runs block detection and generates auto-measured edges. Clear Auto removes the current auto-detection result.
• Auto Detect 会运行块检测并生成自动测量边；Clear Auto 会清掉当前自动检测结果。
• On the canvas, right-clicking an auto-detected edge deletes that edge from the current auto result set.
• 在画布上，对某条自动检测边执行右键会把它从当前自动结果集中删除。
• Auto Detection Tuning controls candidate screening and edge-measurement region settings. Lower thresholds usually increase recall and also increase false positives; Sample Half Width Ratio directly changes the per-edge measurement strip width.
• Auto Detection Tuning 用于控制候选筛选和边缘测量区域设置。阈值调低通常会提高检出率，但也会增加误检；Sample Half Width Ratio 会直接改变每条边的测量条带宽度。
• Explain Selected ROI explains why the currently selected ROI passed or failed. Clear Explain removes the current explanation overlay and card.
• Explain Selected ROI 用于解释当前选中 ROI 为什么通过或失败；Clear Explain 会清除当前 explain 叠加层和结果卡。
• Standard Chart starts the four-corner calibration flow for batch chart work. During calibration it changes to Corner 1/4, Corner 2/4, and so on.
• Standard Chart 会启动批量图卡工作里的四角校准流程；在校准过程中，它会依次显示为 Corner 1/4、Corner 2/4 等状态。
• Manual Marking turns repeated manual ROI marking on or off. When active, the canvas stays in batch-marking mode.
• Manual Marking 用于打开或关闭重复手动 ROI 标记；启用后，画布会停留在批量标记模式。
• Compute Batch measures all currently marked ROIs using the current SFR source settings. Clear ROIs clears the marked ROI set.
• Compute Batch 会使用当前 SFR 源设置去测量所有已标记 ROI；Clear ROIs 会清空这些标记。
• The left-panel Deshading checkbox is now shared with the embedded expert core and the auto plot/export path. Toggling it updates all of those together.
• 左侧面板里的 Deshading 复选框现在和嵌入式专家核心、自动绘图/导出路径共享；切换它时，这几处会一起更新。
• Green Only only matters for non-fixed paths; in RGGB Raw it is shown as fixed because that source family is already defined around green-sample measurement.
• Green Only 只在非固定路径里有实际意义；在 RGGB Raw 中它会显示为固定状态，因为这条输入路径本来就是围绕绿采样测量定义的。
• Under Templates, Export CSV saves the current ROI layout and Import CSV restores a previously saved layout.
• 在 Templates 区里，Export CSV 会保存当前 ROI 布局，Import CSV 会恢复之前保存的布局。
• In the embedded expert core, Bin sets the oversampling step. The adjacent Manual checkbox enables manual entry; otherwise the processor chooses bin size automatically for that manual ROI measurement.
• 在嵌入式专家核心里，Bin 用于控制过采样步长；旁边的 Manual 复选框用于启用手动输入，否则处理器会为那次手动 ROI 测量自动选择 bin。
• The embedded Deshading checkbox controls LSF tail detrending for the expert measurement panel, and because deshading is now shared, it also follows the left-panel state.
• 嵌入式 Deshading 复选框用于控制专家测量面板的 LSF 尾部去趋势；由于 deshading 现在是共享的，它也会跟随左侧面板状态。
• Limit Fit narrows the width used by that tail detrend fit.
• Limit Fit 会限制尾部去趋势拟合所使用的宽度。
• In Three-plane, 3P Source now starts from None. You must choose Luma, R, G, or B before Add Current ROI becomes available.
• 在 Three-plane 模式下，3P Source 现在从 None 开始；必须先选择 Luma、R、G 或 B，Add Current ROI 才会可用。
• Hann On applies a Hann window before FFT. 2x Freq extends the displayed frequency range. Show PTF (temp disabled) is currently intentionally unavailable in normal UI use.
• Hann On 会在 FFT 前乘上 Hann 窗；2x Freq 会扩展显示频率范围；Show PTF (temp disabled) 当前仍然是刻意不可用的普通 UI 入口。
• Jiang's official NR switches between adaptive radius selection and manual radius control inside the embedded expert panel.
• Jiang's official NR 用于在嵌入式专家面板里切换自适应半径选择与手动半径控制。
• Pick Edge Line arms two-point edge picking on the canvas. Once two points are chosen, the current manual ROI will use that line geometry instead of pure auto edge fitting.
• Pick Edge Line 会让画布进入两点选边模式；选完两点后，当前手动 ROI 会使用这条线的几何信息，而不是完全依赖自动拟合。
• Add Current ROI appends the current manual ROI sample. In three-plane mode, the same button becomes Choose 3P Source when no channel/luma choice has been made yet.
• Add Current ROI 会把当前手动 ROI 样本追加进去；在三平面模式下，如果还没有选 channel/luma，同一个按钮会显示为 Choose 3P Source。
• Copy Pos/MTF50 copies ROI center and MTF50. Export CSV exports the current frequency-domain result. Clear clears the accumulated ROI set and current result.
• Copy Pos/MTF50 会复制 ROI 中心坐标和 MTF50；Export CSV 会导出当前频域结果；Clear 会清空已累积的 ROI 集合和当前结果。
• Show Model Line overlays the optical forward model. The small dot locks beside model parameters decide whether Auto Fit is allowed to move those parameters.
• Show Model Line 会叠加显示光学正向模型；模型参数旁边的小圆点锁决定 Auto Fit 是否允许改动对应参数。
• Auto Fit runs the model fit on the selected frequency interval using the currently unlocked parameters.
• Auto Fit 会在选定频段上使用当前未锁定参数运行模型拟合。
• Inside the point-set / plot modal, Polar, Image X, and Image Y switch the horizontal-axis definition.
• 在点集 / 绘图弹窗里，Polar、Image X 和 Image Y 用于切换横轴定义方式。
• In Polar, the inner mode switch chooses between MTF50 and 线对. 线对 additionally requires Pixel Size (um) because it samples the MTF curve at fixed lp/mm frequencies.
• 在 Polar 模式下，内部模式开关可以在 MTF50 和 线对 之间切换；其中 线对 还要求填写 Pixel Size (um)，因为它需要在固定 lp/mm 频率处读取 MTF 曲线数值。
• Pick Center On Canvas starts center picking. Reset To Image Center returns the field center to the image center. 确认中心 confirms the currently chosen center and redraws the plot.
• Pick Center On Canvas 会启动中心点选取；Reset To Image Center 会把场中心重置回图像中心；确认中心 会确认当前中心并重新绘图。
• Tester and Lens are free-text fields stored locally and shown in the plot/export result.
• Tester 和 Lens 是会保存在本地的自由文本输入框，并会显示在绘图 / 导出结果上。
• Copy Visible Sets copies the currently visible point sets. In Polar + MTF50, the dialog also offers separate Radial / 法向 and Tangential / 切向 CSV text blocks.
• Copy Visible Sets 会复制当前可见点集；在 Polar + MTF50 模式下，弹窗还会额外提供分开的 Radial / 法向 与 Tangential / 切向 CSV 文本块。
• 点列质量筛选 enables the quality filter used by the plot modal before binning/curve display. 画折线 controls whether the chart draws connecting lines on top of the points.
• 点列质量筛选 用于开启绘图弹窗在分箱 / 画线之前使用的质量筛选；画折线 用于控制图表是否在点上方绘制连接折线。
• Export JPG exports the current plot view with the current mode, center, tester/lens labels, watermark, and line/scatter settings.
• Export JPG 会按当前模式、当前中心、tester/lens 标签、水印以及折线 / 散点设置来导出当前图表视图。

85. PTC Button-Level Manual

85. PTC 按钮级手册

• Noise, SNR, and Linear (PTC) switch the chart between the three main interpretations of the same measurement dataset.
• Noise、SNR 和 Linear (PTC) 用来在同一批测量数据的三种主解释视图之间切换。
• Top3 style filtering keeps a lighter rendering subset, while Raw aims to show the rawest point cloud behavior.
• Top3 之类的过滤会保留更轻量的显示子集，而 Raw 则更倾向于显示最原始的点云行为。
• The gain-range Select workflow lets you pick min and max fit bounds directly from the chart by clicking points.
• 增益区间的 Select 流程允许你直接从图上点选拟合下界和上界。
• Recalculate reruns the constrained fit using current black level, locks, and range settings.
• Recalculate 会基于当前黑电平、锁定状态和区间设置重新执行受约束拟合。
• Parameter lock buttons for read noise, gain, and PRNU determine which fit variables are frozen.
• 读噪、增益和 PRNU 旁边的锁按钮决定哪些拟合变量会被冻结。
• Export PTC JPG opens the export settings panel instead of immediately downloading.
• Export PTC JPG 不会立刻下载，而是先打开导出设置面板。
• Glow in that panel enables enlarged fluorescent point rendering in the exported JPG.
• 导出设置里的 Glow 会启用放大的荧光点导出样式。
• The draggable Min and Max blue fit handles on the chart are also part of the button-level interaction model, even though they are not HTML buttons.
• 图里的 Min 和 Max 蓝色拟合手柄虽然不是 HTML 按钮，但同样属于按钮级交互的一部分。

86. Stacking Button-Level Manual

86. 堆栈窗口按钮级手册

• Load Files brings frames into the symbolic file map used by the formula engine.
• Load Files 会把帧载入供公式引擎使用的符号文件映射。
• Clear clears the current file map and status log.
• Clear 会清空当前文件映射和状态日志。
• Auto Formula generates an average-style formula from the currently loaded files.
• Auto Formula 会根据当前已加载文件自动生成一条平均风格公式。
• Align1, Align2, and Align3 are mutually exclusive alignment family toggles.
• Align1、Align2 和 Align3 是互斥的对齐家族开关。
• Inside Align3, ecc and apap choose the high-end alignment backend.
• 在 Align3 内部，ecc 和 apap 用于选择高阶对齐后端。
• Process & Save DNG runs the whole stack pipeline and writes dng16.
• Process & Save DNG 会跑完整条堆栈流水线并写出 dng16。
• Process & Save Float32 JDNG runs the same front half but exits through the float JDNG path instead.
• Process & Save Float32 JDNG 会走相同的前半段流程，但最后从浮点 JDNG 路径退出。

87. PS Editor Button-Level Manual

87. PS 编辑器按钮级手册

• Undo steps one history entry backward in the current session’s PS document.
• Undo 会把当前 session 的 PS 文档回退一个历史条目。
• Export Flow JSON writes the PS workflow state for reuse or inspection.
• Export Flow JSON 会导出 PS 工作流状态，供复用或检查。
• Import Flow restores a saved workflow description.
• Import Flow 会恢复保存过的工作流描述。
• Export PNG and Export JPEG export the current composed PS result.
• Export PNG 和 Export JPEG 会导出当前合成后的 PS 结果。
• + Mask creates a new mask-plus-layer pair.
• + Mask 会创建一对新的蒙版与图层。
• Brush Add/Subtract chooses whether new brush paint grows or removes the selected mask.
• Brush Add/Subtract 决定新的笔刷涂抹是增加还是减去当前蒙版。
• Ellipse Tool switches into ellipse-creation mode.
• Ellipse Tool 会切换到椭圆创建模式。
• Cancel Ellipse exits ellipse creation without committing a new item.
• Cancel Ellipse 会退出椭圆创建而不提交新 item。
• The expand arrow on each mask opens the item list for that mask.
• 每个蒙版前面的展开箭头会打开该蒙版的 item 列表。
• Clicking a mask name selects that mask and its bound layer context.
• 点击蒙版名称会选中该蒙版及其绑定图层上下文。
• The red overlay toggle button on a mask row shows or hides that mask’s red preview overlay.
• 蒙版行上的红色 overlay 开关会显示或隐藏该蒙版的红色预览叠加层。
• Clicking a mask item selects that brush stroke or ellipse item for editing.
• 点击某个 mask item 会选中那条笔刷笔触或那个椭圆 item 进行编辑。
• In PS Upright / Crop, Flip Left-Right and Flip Up-Down apply horizontal or vertical flips.
• 在 PS Upright / Crop 区域，Flip Left-Right 和 Flip Up-Down 会施加水平或垂直翻转。
• Crop To ROI crops to the currently visible PS ROI rather than raw-file coordinates.
• Crop To ROI 会裁到当前可见的 PS ROI，而不是 RAW 原始坐标。
• + H Guide and + V Guide add horizontal or vertical guides.
• + H Guide 和 + V Guide 会新增水平或垂直参考线。
• Pick P1, Pick P2, and Cancel Pick are guide endpoint-picking controls.
• Pick P1、Pick P2 和 Cancel Pick 是参考线端点拾取控制。
• Delete Guide removes the currently selected guide.
• Delete Guide 会删除当前选中的参考线。
• Rotate -90, Rotate +90, and Reset Rotation control the PS canvas rotation state.
• Rotate -90、Rotate +90 和 Reset Rotation 用来控制 PS 画布旋转状态。
• Apply Upright (4 Guides) computes and applies a guide-based upright correction when the guide geometry is ready.
• Apply Upright (4 Guides) 会在参考线几何条件满足时计算并应用基于参考线的拉直校正。
• Load Lensfun XML loads user-specified Lensfun data, while Apply Lens Correction applies the selected distortion profile.
• Load Lensfun XML 会载入用户指定的 Lensfun 数据，而 Apply Lens Correction 会把选中的畸变 profile 真正应用到文档上。

88. Panel-By-Panel Manual Overview

88. 逐面板说明书总览

• The button-level sections above tell you what the main actions do, but this section goes one layer deeper and treats each panel more like an operating console.
• 上面的按钮级章节主要解释“按下去会发生什么”，而这一节会再往里走一层，把每个面板当成一台操作台来讲。
• The goal is to help you read an entire panel from top to bottom without guessing which fields are merely cosmetic and which ones actually change data interpretation.
• 目标是让你能够从上到下读懂整个面板，而不用猜哪些字段只是装饰，哪些字段会真正改变数据解释方式。
• In practical use, this distinction matters a lot in this project because many controls are mathematical assumptions, not just display preferences.
• 在这个项目里，这种区分非常重要，因为很多控件本质上是数学假设，而不只是显示偏好。

89. Header Panel Reading Order

89. 顶部栏的阅读顺序

• Read the header from left to right as: session loading, lab switching, metadata and tool access, then sidebar visibility.
• 理解顶部栏时，建议按从左到右的顺序去看：先是 session 加载，再是实验室切换，然后是元数据与工具入口，最后才是侧栏可见性。
• If you are unsure whether an action changes the current session or opens a separate tool, the rule of thumb is that Load, Convert & Load, and PS toggles change the working session, while most others open modals or labs around it.
• 如果你不确定某个操作是改当前 session，还是打开一个独立工具，一个经验规则是：Load、Convert & Load 和 PS 切换会改变工作 session，而多数其他按钮只是围绕它打开 modal 或实验室。
• The header is also where the app communicates global constraints, such as PS mode locking and bridge availability.
• 顶部栏还是应用表达全局约束的位置，比如 PS 模式锁定和 bridge 可用状态。
• If a button looks disabled for no obvious reason, first check whether PS mode is active or whether the bridge-dependent path is currently unavailable.
• 如果某个按钮看起来无缘无故不可用，先检查是不是 PS 模式正在激活，或者 bridge 依赖路径当前不可用。

90. Display Controls Panel Field Guide

90. Display Controls 面板字段导读

• Exposure is the fast global brightness scaling control and is usually the first thing to adjust when the image is not in a readable range.
• Exposure 是最快的全局亮度缩放控制项，通常在图像亮度不在可读范围时应最先调整。
• WB Gains changes red and blue scaling relative to green and is mainly a diagnostic or neutralization tool rather than a final color-grading tool.
• WB Gains 会改变红蓝相对绿色的缩放，更适合做诊断或中性化，而不是最终调色。
• Black Level is one of the highest-impact controls in the whole app because it affects normalization, ROI statistics, SNR, and several downstream labs.
• Black Level 是整个应用里影响最大的控件之一，因为它会影响归一化、ROI 统计、SNR，以及多个后续实验室。
• Subtract Black Level From Stats only changes how ROI means are displayed and interpreted in stats, not the raw source file itself.
• Subtract Black Level From Stats 只会改变 ROI 均值在统计中的显示与解释方式，并不会改动原始文件本身。
• Custom Matrix is where camera-to-display color interpretation can be overridden and should be treated carefully because it changes color meaning, not just saturation.
• Custom Matrix 用于覆盖相机到显示空间的颜色解释，应当谨慎使用，因为它改变的是颜色含义，而不只是饱和度。
• Apply Settings / Render uses the current local values, so make a habit of finishing edits in this panel before opening measurement tools that depend on the displayed interpretation.
• Apply Settings / Render 使用的是当前面板里的本地值，因此建议在打开依赖显示解释的测量工具前，先把这一面板的编辑完成。

91. Selection Tools Panel Field Guide

91. Selection Tools 面板字段导读

• Selection Size defines the default quick-select size and interacts directly with the power-of-two lock setting.
• Selection Size 定义默认快速选区尺寸，并且会直接受到二次幂锁定设置的影响。
• Power-of-Two Lock is especially important for FFT and spectral workflows, because it changes not only convenience but also the frequency-analysis geometry.
• Power-of-Two Lock 对 FFT 和频谱流程尤其重要，因为它改变的不只是操作便利性，还会影响频域分析的几何条件。
• Center Rect creates a centered ROI of the chosen size.
• Center Rect 会创建一个位于图像中心、尺寸为当前设定值的 ROI。
• Full Image turns the entire image into the active ROI.
• Full Image 会把整张图像直接设为活动 ROI。
• If a downstream tool seems to “do nothing,” always verify that the ROI actually exists and is not zero-sized or clipped by view transforms.
• 如果后续工具看起来“没反应”，一定先确认 ROI 真的存在，而且没有因为视图变换被裁成零尺寸。

92. DNG Export Panel Field Guide

92. DNG Export 面板字段导读

• Use the top read-only dimensions as a sanity check before touching any numeric fields.
• 在改任何数值字段之前，先用顶部的只读尺寸做一次 sanity check。
• Set Bit Shift according to source bit depth first, because all later pixel-domain tuning happens after that scale choice.
• 先根据源位深设置 Bit Shift，因为后续一切像素域微调都是在这个尺度选择之后发生的。
• Use Offset (+) sparingly; it is best reserved for explicit container-space pedestal movement rather than normal black-level correction.
• Offset (+) 应当节制使用；它更适合拿来做容器空间里的整体 pedestal 平移，而不是常规黑电平校正。
• Fill 16bit Black Level when your goal is DNG metadata-level black calibration.
• 当你的目标是 DNG 元数据层的黑电平校准时，应填写 16bit Black Level。
• Fill Color Matrix when you want the exported DNG to carry a known matrix into downstream RAW software.
• 当你希望导出的 DNG 能把某个已知矩阵带入后续 RAW 软件时，应填写 Color Matrix。
• Turn on the watermark block only after your black-level tuning is stable, because watermarking physically edits the exported buffer.
• 只有在黑电平调整已经稳定之后才建议打开水印模块，因为水印会真实修改导出的像素缓冲区。
• Prefer single-image export while tuning and batch export only after the settings are stable enough to apply across a whole sequence.
• 调参阶段应优先使用单张导出，只有在参数已经足够稳定、适合推广到整组序列时，再使用批量导出。

93. Stacking Panel Field Guide

93. 堆栈面板字段导读

• The file list area is not just inventory; it defines the symbol table that the formula parser is allowed to use.
• 文件列表区域不仅是个清单，它同时定义了公式解析器允许使用的符号表。
• Input Black Level and Output Black Level are conceptually different.
• Input Black Level 和 Output Black Level 在概念上是两回事。
• Input Black Level affects how source slots are normalized for stacking.
• Input Black Level 会影响源 slot 在堆栈前如何被归一化。
• Output Black Level affects the pedestal written into the final result.
• Output Black Level 会影响最终结果写出的 pedestal。
• ++ Range matters only if your formula uses ++.
• ++ Range 只有在你的公式里用了 ++ 时才有意义。
• Stretch Highlights To Max is a final remapping convenience, not part of the core merge math.
• Stretch Highlights To Max 属于最终重映射便利项，而不是核心合并数学的一部分。
• Output Mode decides whether the result must remain mosaic-compatible or may become RGB float data.
• Output Mode 决定结果是否必须保持马赛克兼容，还是可以变成 RGB 浮点数据。
• The alignment parameter blocks should be treated like algorithm configuration pages, not casual toggles.
• 那些对齐参数区块应被视为算法配置页，而不是随手点点的开关。
• If you are not actively debugging alignment, leave most Align3 advanced fields at their defaults and only vary one family of parameters at a time.
• 如果你不是在主动调试对齐，就尽量把 Align3 的高级字段留在默认值，并且一次只改一类参数。

94. PTC Panel Field Guide

94. PTC 面板字段导读

• Read the PTC panel in this order: choose view mode, inspect point-cloud health, set black level and saturation assumptions, then configure fit parameters and export.
• 理解 PTC 面板时，建议按这个顺序：先选视图模式，再检查点云健康状况，然后设置黑电平和饱和假设，最后再配置拟合参数与导出。
• The chart itself is both a display and an input surface, because point clicking, fit-range dragging, and export styling decisions all depend on it.
• 图表本身既是显示区也是输入区，因为点选、拟合区间拖拽和导出样式决策都会依赖它。
• Manual BL, Manual Sat, and target-SNR related fields all affect derived DR or fit interpretations.
• Manual BL、Manual Sat 以及与目标 SNR 相关的字段都会影响派生 DR 或拟合解释。
• The fitting section is the real analytical core, so lock only the parameters you genuinely trust and let the others move.
• 拟合区块才是真正的分析核心，因此只有在你确实信任某个参数时才应把它锁住，其他参数应允许它们移动。
• Use the gain-density subview as a confidence visualization rather than as an isolated truth source.
• 增益密度子图更适合作为一种置信可视化，而不是孤立的真值来源。

95. PS Editor Panel Field Guide

95. PS 编辑器面板字段导读

• Read the PS editor as four layers: document/history tools, mask creation tools, selected-mask editing tools, and geometry tools.
• 阅读 PS 编辑器时，可以把它分成四层：文档/历史工具、蒙版创建工具、当前蒙版编辑工具，以及几何工具。
• If you are new to the editor, avoid touching curves, mixer, and guide-based upright all at once.
• 如果你刚接触这个编辑器，不要一上来同时动曲线、mixer 和基于参考线的 upright。
• Start with one mask, one layer, and one adjustment family so you can build an intuition for what is global, what is mask-bound, and what is geometric.
• 最好从一个蒙版、一个图层、一个调整家族开始，这样你更容易建立“哪些是全局、哪些是蒙版绑定、哪些是几何”的直觉。
• The selected-mask block is contextual, so if you think the panel is “missing controls,” check whether a mask, item, or layer is actually selected.
• 当前蒙版编辑区是上下文相关的，因此如果你觉得某些控件“消失了”，先检查是否真的选中了某个蒙版、item 或图层。
• Guides and lens correction live lower in the panel because they are structural operations and should usually happen after local tonal edits are roughly under control.
• 参考线和镜头校正被放在面板较下方，是因为它们属于结构性操作，通常应在局部明暗调整大体稳定后再进行。

96. New User Workflow: Black Level Tuning

96. 新手流程：黑电平微调

• Load one RAW file directly and open EXIF first.
• 先直接加载一张 RAW，并先打开 EXIF。
• If EXIF black level looks reasonable, enter the same values in the sidebar and inspect one dark ROI near the center.
• 如果 EXIF 黑电平看起来合理，就先把同样数值放进侧栏，然后在画面中央附近选一个暗场 ROI 检查。
• Open the ROI stats and verify whether the mean after black-level subtraction sits close to where you expect.
• 打开 ROI 统计，确认减黑电平后的均值是否接近你的预期。
• Then open Generate 16bit DNG and export several variants with slightly different 16bit Black Level values.
• 然后打开 Generate 16bit DNG，导出几份黑电平略有差异的版本。
• Reopen those DNGs and compare central dark-region behavior instead of trusting a single export blindly.
• 把这些 DNG 重新载入比较中央暗场表现，而不要盲信某一次导出。
• Stop when the dark pedestal is stable, shadow neutrality is improved, and you are no longer correcting obvious checkerboard-position imbalance.
• 当暗部 pedestal 稳定、阴影中性度改善，而且不再看到明显的 Bayer 位置不平衡时，就可以停下来。

97. New User Workflow: Single-ROI SFR

97. 新手流程：单 ROI 的 SFR

• Open SFR Lab and load the image through the lab flow so the workspace starts from a clean SFR-specific state.
• 打开 SFR Lab 后，最好通过实验室自身的加载流程重新载入图像，这样工作区会从一个干净的 SFR 专属状态开始。
• Choose Unmix / BW, RGGB Raw, or Three-plane according to the signal semantics you actually want to measure.
• 按照你真正想测量的信号语义去选择 Unmix / BW、RGGB Raw 或 Three-plane。
• For Bayer sharpness work, start with RGGB Raw and leave green phase at Default unless you intentionally want to force phase 1 or 2.
• 对于 Bayer 锐度测量，建议先从 RGGB Raw 开始，并把绿色相位保持在 Default，除非你是有意想强制切到 1 或 2 相位。
• Confirm Encoding before measuring: use Auto when available, otherwise choose Linear or sRGB explicitly instead of trusting a stale assumption.
• 在测量前先确认 Encoding：如果 Auto 可用就优先用它，否则请显式选择 Linear 或 sRGB，不要依赖可能已经过时的隐含假设。
• Draw a clean ROI around a strong slanted edge, or use Pick Edge Line if automatic edge localization seems ambiguous.
• 围绕一条清晰的斜边画一个干净 ROI；如果自动找边看起来不够可靠，就改用 Pick Edge Line 手动画边。
• Add the ROI, inspect ESF and LSF shape first, and only then quote MTF50.
• 先添加 ROI，先看 ESF 和 LSF 形状，再去引用 MTF50。
• If the result is unstable, enlarge the ROI slightly, choose a cleaner edge, or switch to manual edge-line definition before trying to “fix” it with model fitting.
• 如果结果不稳定，先把 ROI 稍微放大、换一条更干净的边，或者切到手动画边，再考虑是否要用模型拟合去“修”。

98. New User Workflow: PTC

98. 新手流程：PTC

• Import the CSV dataset, then start in Noise mode.
• 先导入 CSV 数据，然后从 Noise 模式开始。
• Make sure the visible channel set and filter mode let you see the actual point-cloud structure.
• 先确保当前可见通道和过滤模式能让你看清真实点云结构。
• Set black level carefully before trusting any fit parameter.
• 在信任任何拟合参数之前，先把黑电平设对。
• Choose or drag a fit range that clearly avoids dead-shadow clutter and obvious saturation collapse.
• 选择或拖出一个拟合区间，明确避开死黑区域的杂点和明显的饱和塌陷区。
• Only then run or refine the fit and compare read noise, gain, PRNU, and DR readouts together rather than one by one.
• 然后再去运行或微调拟合，并且要把读噪、增益、PRNU 和 DR 一起看，而不是孤立看单个数字。
• When exporting, turn on glow only if the output is for presentation or visual communication rather than raw analysis.
• 导出时，只有当图片主要用于展示或沟通，而不是纯分析时，才建议打开 glow。

99. New User Workflow: DNG Export

99. 新手流程：DNG 导出

• Load one RAW and open Generate 16bit DNG.
• 加载一张 RAW，然后打开 Generate 16bit DNG。
• Confirm width, height, CFA pattern, and bit shift first.
• 先确认宽高、CFA pattern 和 bit shift。
• Fill black level and color matrix only if you have a concrete reason or reference.
• 只有在你有明确理由或参考时，才填写黑电平和颜色矩阵。
• Export one single DNG and verify it in this app or another RAW-aware tool.
• 先导出一张单独 DNG，并在本应用或其他 RAW 软件里验证。
• Once satisfied, switch to batch export and apply the exact same settings across the set.
• 满意后再切到批量导出，把完全相同的设置应用到整组文件。

100. New User Workflow: Stacking

100. 新手流程：堆栈

• Load a small set of files first rather than jumping straight into a huge burst.
• 先加载一小组文件，而不要一上来就丢一个超大的 burst。
• Generate or type a simple average formula and keep alignment off on the first pass.
• 第一次尝试时，先生成或输入一个简单平均公式，并先关闭对齐。
• Verify that output black level and output mode are correct for your intended destination.
• 先确认输出黑电平和输出模式符合你的目标用途。
• If the frames are misregistered, enable only one alignment family and test again.
• 如果帧没有对齐，再只启用一种对齐家族重新测试。
• Move to ECC or APAP only after you understand whether the motion is mostly rigid or locally varying.
• 只有在你判断出运动更像刚体还是局部变化之后，再决定是否进入 ECC 或 APAP。
• Use jdngf32 when you want float-domain postprocessing headroom, and use dng16 when you need mosaic-style compatibility.
• 当你需要浮点域后处理余量时使用 jdngf32，当你需要马赛克式兼容性时使用 dng16。

101. New User Workflow: PS Local Editing

101. 新手流程：PS 局部编辑

• Enter PS Mode only after the source image, crop intent, and viewing geometry are reasonably settled.
• 最好等源图、裁切意图和观察几何基本稳定后，再进入 PS 模式。
• Add one mask first, choose brush add mode, and paint a simple region.
• 先添加一个蒙版，选择 brush add 模式，并先涂一个简单区域。
• Adjust one or two basic sliders like exposure or contrast on the bound layer and observe the effect.
• 在绑定图层上先调整一两个基础滑条，比如 exposure 或 contrast，观察效果。
• Then try one ellipse item so you understand the difference between geometric mask items and brush strokes.
• 然后再试一次椭圆 item，这样你就能理解几何 mask item 和笔刷笔触之间的区别。
• Use guides and upright only after you are comfortable with selection, mask binding, and history.
• 只有在你已经熟悉选区、蒙版绑定和历史记录之后，再去使用 guides 和 upright。
• Export PNG or JPEG only after you have verified the preview reflects the intended history state.
• 只有在你确认预览确实反映了你想要的历史状态之后，再导出 PNG 或 JPEG。