threejs-visual-validation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Visual Validation

视觉验证

Validate claims, not polished frames. Keep each verdict scoped to one declared claim so evidence for appearance cannot substitute for mechanism, timing, or lifecycle proof. The owning subject skill defines mechanism truth and failure signatures; this skill defines how to falsify them.
验证断言而非经过修饰的画面。确保每个判定仅针对一项已声明的断言,这样外观相关的证据就无法替代机制、时序或生命周期的证明。所属主体技能定义了机制的真相和失败特征;本技能定义了如何证伪这些断言。

1. Predeclare every claim

1. 预先声明所有断言

For each claim, record:
  • class: visual, mechanism, temporal, performance, GPU attribution, resource, or lifecycle;
  • invariant and truth source;
  • observable and the diagnostic that isolates it;
  • native-domain metric, units, alignment, mask, and aggregation;
  • acceptance gate fixed before candidate inspection;
  • blocking failure and required evidence.
Label every claim-driving number
Authored
,
Derived
,
Measured
, or
Gated
and record its unit and source. Keep unknown values unknown.
This step is complete when every claim has a direct falsifier and no claim is supported only by the final image.
对于每个断言,记录:
  • 类别:视觉、机制、时序、性能、GPU归因、资源或生命周期;
  • 不变量和真相来源;
  • 可观测项以及用于隔离它的诊断方法;
  • 原生领域指标、单位、对齐方式、掩码和聚合方式;
  • 在检查候选实现前确定的验收阈值;
  • 阻塞性失败情况和所需证据。
为每个驱动断言的数值标注
Authored
Derived
Measured
Gated
,并记录其单位和来源。未知值保持未知状态。
当每个断言都有直接的证伪方法,且没有断言仅靠最终图像来支持时,此步骤完成。

2. Freeze the run

2. 冻结运行环境

Freeze the exact Three.js revision, renderer and initialized backend, target, browser/GPU, camera matrices, seed, time or deterministic step, viewport, DPR, quality state, assets, and color/output graph. Construct the renderer with timestamp tracking before initialization whenever a declared claim needs GPU timing:
js
const renderer = new WebGPURenderer( {
  trackTimestamp: gpuTimingRequirement === 'required'
} );

await renderer.init();

if ( renderer.backend.isWebGPUBackend !== true ) {
  throw new Error( 'Canonical WebGPU validation is unavailable on this target.' );
}
Record the blocker when canonical WebGPU is unavailable. Reach
$threejs-compatibility-fallbacks
only when the user explicitly asks for that branch.
This step is complete when the run can be repeated from the recorded state and initialized backend truth is captured rather than inferred.
冻结确切的Three.js版本、渲染器和初始化后的后端、目标平台、浏览器/GPU、相机矩阵、随机种子、时间或确定性步骤、视口、DPR、质量状态、资源以及颜色/输出图。当已声明的断言需要GPU时序时,在初始化前构造带有时间戳跟踪的渲染器:
js
const renderer = new WebGPURenderer( {
  trackTimestamp: gpuTimingRequirement === 'required'
} );

await renderer.init();

if ( renderer.backend.isWebGPUBackend !== true ) {
  throw new Error( 'Canonical WebGPU validation is unavailable on this target.' );
}
当标准WebGPU不可用时,记录阻塞原因。仅当用户明确要求时,才使用
$threejs-compatibility-fallbacks
分支。
当运行环境可从记录的状态重复,且已捕获初始化后的后端真相而非推断时,此步骤完成。

3. Capture the producing mechanism

3. 捕获生成机制

Capture the real pipeline under the frozen state:
  • for visual or mechanism claims, the final, no-post, and contribution views required to isolate the claimed cause;
  • only the depth, normal, velocity, field, history, mask, resource, or pass diagnostics needed by declared claims;
  • for performance, GPU-attribution, resource, or lifecycle claims without a visual/mechanism claim, only the producing trace and diagnostics required by that claim;
  • the pass/dispatch ownership graph, including histories and reset edges.
Keep HDR work scene-linear until one tone-map/output-transform owner. Diagnostic modes must switch the actual output node and invalidate the graph when required; a label-only toggle proves nothing.
This step is complete when every required artifact is traceable to the pass, dispatch, resource, and output owner that produced it.
在冻结状态下捕获真实的管线:
  • 对于视觉或机制断言,捕获用于隔离断言原因所需的最终视图、无后期处理视图和贡献视图;
  • 仅捕获已声明断言所需的深度、法线、速度、场、历史、掩码、资源或通道诊断信息;
  • 对于无视觉/机制断言的性能、GPU归因、资源或生命周期断言,仅捕获该断言所需的生成跟踪和诊断信息;
  • 通道/调度所有权图,包括历史记录和重置边。
在色调映射/输出变换的所有者处理前,保持HDR工作场景处于线性空间。诊断模式必须在需要时切换实际输出节点并使图失效;仅靠标签切换无法证明任何内容。
当每个所需工件都可追溯到生成它的通道、调度、资源和输出所有者时,此步骤完成。

4. Measure in the native domain

4. 在原生领域进行测量

Compare each observable with its declared truth using the frozen metric and gate. For visual or mechanism claims, inspect the important final and diagnostic images directly; a nonblank capture or scalar summary is only transport evidence. Store the error map or worst interval when a global statistic can hide a local failure.
When decoding a padded WebGPU texture-to-buffer copy, use the aligned-readback helper with the actual integer
bytesPerRow
supplied to the copy encoder; never recover row stride from width or total buffer length.
Read the graphics validation protocol for metric selection, aligned WebGPU readback, target timing, resource models, and lifecycle checks. Load only the sections used by the declared claims.
This step is complete when every measured value identifies its domain, unit, source, sample scope, frozen gate, and supporting artifact.
使用冻结的指标和阈值将每个可观测项与其声明的真相进行比较。对于视觉或机制断言,直接检查重要的最终图像和诊断图像;非空白捕获或标量摘要仅作为传输证据。当全局统计数据可能掩盖局部失败时,存储误差图或最差区间。
在解码带填充的WebGPU纹理到缓冲区的副本时,使用aligned-readback helper,并提供给复制编码器实际的整数
bytesPerRow
;绝不能从宽度或总缓冲区长度恢复行跨度。
阅读图形验证协议以了解指标选择、对齐的WebGPU回读、目标时序、资源模型和生命周期检查。仅加载已声明断言使用的部分。
当每个测量值都明确其领域、单位、来源、样本范围、冻结阈值和支持工件时,此步骤完成。

5. Exercise conditional state

5. 测试条件状态

Run only the branches the claims require:
  • temporal: reset, first response, steady state, invalidation/disocclusion, and recovery under deterministic camera/object/state changes;
  • performance: cold and final sustained windows on the named target;
  • GPU attribution: resolved render/compute timestamps outside the measured steady-state window;
  • resource: resident, transient, attachment, upload/readback, and traffic evidence proportional to the claim;
  • lifecycle: repeated resize/DPR, quality/debug transition, history reset, teardown, and dispose/recreate until resources plateau or trend upward.
renderer.computeAsync()
submits work; it is not proof of GPU completion. CPU-visible completion requires an actual readback/map, while GPU cost requires timestamp evidence.
This step is complete when every state transition named by a claim has the required before/after diagnostic, plus a reset policy or bounded resource outcome when that claim concerns reset or resources.
仅运行断言所需的分支:
  • 时序:在确定性相机/对象/状态变化下的重置、首次响应、稳态、失效/遮挡消除和恢复;
  • 性能:在指定目标平台上的冷启动和最终持续运行窗口;
  • GPU归因:在测量的稳态窗口之外解析渲染/计算时间戳;
  • 资源:与断言成比例的常驻、临时、附件、上传/回读和流量证据;
  • 生命周期:重复调整大小/更改DPR、质量/调试模式切换、历史重置、销毁和重新创建,直到资源使用趋于平稳或呈上升趋势。
renderer.computeAsync()
仅提交工作;不能作为GPU完成的证明。CPU可见的完成需要实际的回读/映射,而GPU成本需要时间戳证据。
当每个断言指定的状态转换都有所需的前后诊断信息,且当断言涉及重置或资源时具备重置策略或有限的资源结果时,此步骤完成。

6. Return claim-scoped verdicts

6. 返回断言范围的判定结果

Assign exactly one verdict to every claim:
  • PASS
    : every required artifact exists and all frozen gates pass;
  • FAIL
    : a blocking failure occurred or a gate failed;
  • INSUFFICIENT_EVIDENCE
    : required evidence or capability is unavailable.
Missing required GPU timestamps produce
INSUFFICIENT_EVIDENCE
for GPU-cost claims; CPU frame time and presentation cadence do not become GPU timing. Report unsupported claims and the exact evidence needed to close them.
Validation is complete when every declared claim has one verdict and every verdict resolves to direct evidence. Identify the sole output owner when the run produces rendered output; check deterministic reset for declared temporal state; require a bounded plateau only for declared resource or lifecycle claims.
为每个断言分配恰好一个判定结果:
  • PASS
    :所有所需工件存在,且所有冻结阈值均通过;
  • FAIL
    :发生阻塞性失败或未通过阈值;
  • INSUFFICIENT_EVIDENCE
    :所需证据或功能不可用。
缺少所需的GPU时间戳会导致GPU成本断言的判定结果为
INSUFFICIENT_EVIDENCE
;CPU帧时间和显示节奏不能替代GPU时序。报告不支持的断言以及完成验证所需的确切证据。
当每个已声明的断言都有一个判定结果,且每个判定结果都有直接证据支持时,验证完成。当运行生成渲染输出时,确定唯一的输出所有者;检查已声明时序状态的确定性重置;仅对已声明的资源或生命周期断言要求有限的平稳状态。