AnyImage/openspec/specs/frame-tool/spec.md

frame-tool Specification

Purpose

TBD - created by archiving change support-frame-view-plane-intersections. Update Purpose after archive.

Requirements

Requirement: Frame samples every valid view-plane intersection

Frame SHALL 根据当前投影模式，以 Frame 屏幕位置对应的观察射线与每个参与 Image Empty 平面求交，并 SHALL 以有限且位于图片显示边界内的交点计算源像素坐标和几何深度。系统 SHALL NOT 仅因 Image Empty 的一个或多个角位于观察平面另一侧而取消整个操作。

Scenario: User finishes a frame in orthographic view at a non-positive view depth

• WHEN active Image Empty 在正交视图中具有有限稳定的屏幕投射，但其视图深度不为正
• AND Frame 与 active 图片的有效投射存在正面积交叠
• THEN 系统完成 Frame
• AND 结果保持操作时的正交屏幕图案

Scenario: Orthographic rays are parallel to the image plane

• WHEN 正交观察射线与 active Image Empty 平面平行，无法形成稳定的有限交点
• THEN 系统取消 Frame
• AND 所有参与对象保持不变

Scenario: A perspective image partially crosses the view plane

• WHEN Image Empty 的一部分位于透视观察方向前方，另一部分越过观察原点
• AND Frame 与 active 图片的有效前方投射存在正面积交叠
• THEN 系统采样 Frame 内观察方向前方的稳定平面交点
• AND 位于观察方向后方、与射线平行或超出图片边界的源样本为透明
• AND 系统不因完整图片无法形成有限凸四边形而取消操作

Scenario: A perspective image is extremely close but remains in front

• WHEN Image Empty 的有效交点位于透视观察方向前方且非常接近观察原点
• AND 屏幕到图片平面的映射仍可稳定求解
• THEN 系统允许该投射参与 Frame
• AND 系统不使用固定世界距离阈值拒绝整张图片

Scenario: A frame contains a ray parallel to one source plane

• WHEN Frame 中部分屏幕位置的观察射线与某个参与 Image Empty 平面平行
• THEN 该源在对应位置贡献透明样本
• AND 其他稳定位置及其他参与源继续正常采样与合成

Requirement: Frame validates active overlap from the valid projection region

Frame SHALL 使用 active Image Empty 在当前投影模式下可稳定求交的连续几何区域判断 Frame 交叠。交叠 SHALL 具有正面积，且 SHALL 独立于 active 图片的 Alpha 和离散输出像素是否恰好命中该区域。

Scenario: The complete active projection is unbounded but its valid part overlaps the frame

• WHEN active Image Empty 跨越透视观察原点，其完整角点投影无法表示为有限凸 Quad
• AND 其观察方向前方的有效投射与 Frame 存在正面积交叠
• THEN 系统接受该 active 交叠并继续 Frame

Scenario: Only invalid or rear-facing intersections overlap the frame

• WHEN Frame 内不存在 active Image Empty 的稳定前方透视交点，或不存在稳定的正交交点
• THEN 系统以 warning 提醒用户 Frame 没有与 active Image Empty 的有效投射交叠
• AND 系统取消操作并保持所有参与对象不变

Scenario: A narrow valid overlap falls between output pixel centers

• WHEN Frame 与 active 有正面积有效几何交叠，但当前输出尺寸的像素中心没有命中该区域
• THEN 系统仍将该 Frame 视为具有 active 交叠
• AND 离散输出像素可以按实际采样结果保持透明

Requirement: Perspective Frame uses a visible result depth

Frame SHALL 在透视视图中优先使用 active Image Empty 世界原点的正视图深度放置 view-facing 结果。当 active 原点不在观察方向前方、但 active 图片存在有效前方交叠时，系统 SHALL 使用 active 有效交叠区域屏幕几何中心对应的稳定正交点深度放置结果。系统 SHALL NOT 以任意常量深度替代无法求解的结果位置。

Scenario: Active origin remains in front of the perspective view

• WHEN active Image Empty 世界原点位于透视观察方向前方
• THEN 结果平面继续使用 active 原点的视图深度

Scenario: Active origin is behind while part of the image remains visible

• WHEN active Image Empty 世界原点不在透视观察方向前方
• AND active 图片的有效前方投射与 Frame 存在正面积交叠
• THEN 系统使用有效交叠区域屏幕几何中心与 active 图片平面的交点深度
• AND 结果 Image Empty 位于观察方向前方并覆盖用户所画 Frame

Scenario: No stable representative depth exists

• WHEN active 原点不能提供正深度，且有效交叠区域的代表射线无法稳定取得正交点深度
• THEN 系统取消 Frame
• AND 所有参与对象保持不变

Requirement: Frame replaces Crop Box

系统 SHALL 以 Frame 替换 Crop Box，并 SHALL 在 Crop Tool 组中按 Frame、Crop Lasso、Crop Polyline、Crop Perspective 的顺序注册四个子工具。Frame 的显示名称、Tool ID、Operator、激活入口、源码边界和文档 SHALL 统一使用 Frame 术语，不得保留 Crop Box 的公开入口或兼容名称。

Scenario: User opens the Crop Tool group

• WHEN 用户展开 Crop Tool 组
• THEN 首个子工具显示为 Frame
• AND 其后依次为 Crop Lasso、Crop Polyline 和 Crop Perspective
• AND 工具组中不再显示 Crop Box

Scenario: User activates the crop entry

• WHEN 用户从 AnyImage 菜单激活 Crop Tool
• THEN 系统激活 Frame

Requirement: Frame defines the complete output canvas

Frame SHALL 将用户在当前 3D Viewport 中拖出的矩形定义为结果图片的完整矩形 Canvas。该矩形可以小于或大于选中 Image Empty 的当前屏幕投射范围；Canvas 位于所有参与源投射范围外的像素 SHALL 使用透明 RGBA，系统 SHALL NOT 根据可见 Alpha 再次紧裁结果。

Scenario: User draws a smaller frame

• WHEN 用户围绕选中 Image Empty 当前投射的一部分拖出 Frame
• THEN 结果图片只包含 Frame 内采样到的投射图案
• AND 结果 Canvas 严格对应用户所画 Frame

Scenario: User draws a larger frame

• WHEN 用户拖出的 Frame 超出所有参与 Image Empty 的当前投射范围
• THEN 结果图片保留 Frame 的完整范围
• AND 未被源投射覆盖的区域为透明
• AND 系统不移除这些透明边缘

Requirement: Frame bakes and composites selected viewport projections

Frame SHALL 使用完成矩形手势时的 Viewport 投影、视图朝向、区域尺寸和每个参与 Image Empty 的世界变换，把所有参与图片的当前投射重采样为结果 RGBA。每个输出像素 SHALL 按观察射线上的几何深度将有效样本从远到近排序，再使用预乘 Alpha source-over 合成；active Image Empty SHALL 在相同深度的样本中位于其他参与对象之上。采样 SHALL 使用预乘 Alpha 插值，源图片范围外 SHALL 采样为透明。

Scenario: One selected image is oblique to the view

• WHEN 倾斜的选中 Image Empty 在当前透视视图中呈现为梯形投射，用户完成 Frame
• THEN 结果图片烘焙该梯形投射在 Frame 内的当前可见外观
• AND 操作完成瞬间的屏幕图案与操作前一致

Scenario: Selected images overlap in depth

• WHEN 多个参与 Image Empty 的投射在 Frame 内重叠
• THEN 系统逐像素按空间深度从远到近合成 RGBA
• AND 较近图片的透明区域仍显示后方图片

Scenario: Active image overlaps another image at the same depth

• WHEN active Image Empty 与另一参与对象在同一深度产生重叠样本
• THEN active Image Empty 的样本合成在另一对象之上

Scenario: Frame extends beyond the projected source

• WHEN Frame 同时覆盖参与源投射内部和外部区域
• THEN 系统重采样并合成内部的源 RGBA
• AND 系统为外部区域写入透明 RGBA

Scenario: Frame has no active projection overlap

• WHEN 完成的 Frame 与 active Image Empty 的屏幕投射没有几何重叠
• THEN 系统以 warning 提醒用户
• AND 系统取消操作并保留所有选中对象不变

Requirement: Viewport defines output resolution

Frame SHALL 使用所画矩形在当前 Region 中的屏幕像素宽高作为结果尺寸依据，并 SHALL 保持 Frame 的屏幕宽高比。结果宽高 SHALL NOT 超过当前 Region 对应维度，最长边 SHALL NOT 超过 Preferences 中可配置的 Frame 最大长边。active 或其他参与图片的原始分辨率、对象距离和透视缩放 SHALL NOT 直接放大结果尺寸。

Scenario: Other selected image has a higher resolution

• WHEN 非 active 参与图片的分辨率高于 active 图片
• THEN 结果尺寸仍只由当前 Viewport 中的 Frame 像素尺寸决定
• AND 非 active 图片重采样到该结果 Canvas

Scenario: Frame is drawn around a distant image

• WHEN active Image Empty 距离视角很远或投射尺度很小
• THEN 结果尺寸仍对应 Frame 的当前屏幕像素尺寸
• AND 对象距离不会产生超出 Viewport 分辨率的图片

Scenario: Frame exceeds the configured maximum

• WHEN Frame 屏幕像素最长边超过 Preferences 配置上限
• THEN 系统等比限制结果尺寸
• AND 结果宽高比继续对应 Frame

Requirement: Transparent output edges avoid black interpolation

Frame SHALL 保持未覆盖区域的 Alpha 为 0，并 SHALL 使用相邻可见颜色扩展紧邻可见内容的透明像素 RGB。颜色扩展 SHALL NOT 改变任何像素的 Alpha 或 Frame Canvas 范围。

Scenario: Projected image ends inside the frame

• WHEN 不透明或半透明图片边缘外侧是 Frame 的透明区域
• THEN 外侧像素 Alpha 保持为 0
• AND 线性纹理插值不会因外侧 RGB 0 形成明显黑边

Requirement: Frame creates a view-facing Image Empty

Frame SHALL 使用 active Image Empty 的原 Blender Object 承载结果 Image，并更新其世界变换和 Image Empty 显示范围，使本地 XY 图片平面平行于操作完成时的 Viewport 视平面、本地正面朝向该视角，且结果矩形在该视角中覆盖用户所画 Frame。结果平面 SHALL 位于穿过 active Image Empty 世界原点、并与视平面平行的深度平面上。

Scenario: User finishes a frame in perspective view

• WHEN 用户在透视 Viewport 中完成 Frame
• THEN 结果 Image Empty 朝向操作时的视角
• AND 结果四边在该视角中对应 Frame 的四边
• AND 结果使用 active Image Empty 世界原点所在的视图深度

Scenario: User finishes a frame in orthographic view

• WHEN 用户在正交 Viewport 中完成 Frame
• THEN 结果 Image Empty 平行于该正交视平面并覆盖 Frame
• AND 烘焙后的图案保持操作时的屏幕外观

Requirement: Frame operates on selected still Image Empties

Frame SHALL 以当前 Selection 内的 active still Image Empty 为基准对象，并将所有选中的 still Image Empty 作为参与源；选中的非 Image Empty 对象 SHALL 被忽略。Frame SHALL 允许矩形手势从 Viewport 任意位置开始。active object 未被选中、不是 still Image Empty、任一选中 Image Empty 不是 still image、Frame 尺寸无效或任一参与投影无法稳定求解时，系统 SHALL 取消整个操作并保持所有对象不变。

Scenario: User starts outside the source projection

• WHEN active object 是 still Image Empty，且用户从源投射范围外开始拖出一个与源投射相交的 Frame
• THEN 系统使用 active Image Empty 及其他选中的 still Image Empty 完成 Frame 操作

Scenario: Active object is unsupported

• WHEN active object 不是 still Image Empty
• THEN Frame 不开始图片重采样、合成或对象替换
• AND 系统以 warning 提醒用户选择一个 active Image Empty

Scenario: Active image is not selected

• WHEN active object 是 still Image Empty，但它不属于当前 Selection
• THEN Frame 不进入矩形操作
• AND 系统以 warning 提醒用户选择 active Image Empty

Scenario: Selection contains images but active object is not an image

• WHEN Selection 含有 still Image Empty，但 active object 是非图片对象
• THEN Frame 不使用 Selection 中的其他图片作为隐式基准
• AND 系统以 warning 取消操作

Scenario: Selection contains a non-image object

• WHEN active object 是 still Image Empty，且 Selection 还包含非 Image Empty 对象
• THEN Frame 忽略非 Image Empty 对象
• AND 非 Image Empty 对象不参与合成或删除

Scenario: A selected Image Empty is animated

• WHEN 任一选中的 Image Empty 使用视频或图片序列
• THEN 系统取消整个 Frame 操作
• AND 所有选中对象保持不变

Requirement: Frame has no edit options

Frame SHALL 始终让 active Image Empty 承载结果，并在结果完整创建和放置后删除其他参与合并的选中 Image Empty。整个替换与删除 SHALL 属于同一个 Undo 操作；失败时 SHALL 保留全部输入对象。Frame SHALL NOT 提供 Refine Selection、Invert 或 Keep Original。系统 SHALL 删除 Crop Box 对应的 crop_box_refine_selection、crop_box_invert 和 crop_box_keep_original Scene Properties；Crop Lasso、Crop Polyline 和 Crop Perspective 的独立选项 SHALL 保持不变。

Scenario: User opens Frame settings

• WHEN 用户激活 Frame
• THEN 工具设置不显示 Refine Selection、Invert 或 Keep Original

Scenario: User completes a frame

• WHEN Frame 成功生成结果
• THEN active Blender Object 改为承载合成结果 Image 和新的视平面对齐变换
• AND 其他参与合并的 Image Empty 被删除
• AND 被忽略的非 Image Empty 对象保持不变

Scenario: Multi-image merge is undone

• WHEN 用户撤销一次成功的多图 Frame
• THEN active Image Empty 恢复操作前的 Image 与变换
• AND 其他被删除的参与 Image Empty 恢复

Scenario: Existing file contains removed Crop Box properties

• WHEN 扩展加载曾保存 Crop Box 选项的 .blend 文件
• THEN 运行时不注册或读取这些已删除属性
• AND 其他 Crop 子工具的设置仍按各自属性工作

Requirement: Image tools preserve ordinary click selection

Frame、Crop Lasso 与 Cutout Lasso SHALL 只在鼠标发生拖动后启动图片手势，普通点击 SHALL 使用 Viewport 对象选择行为。Polyline 与 Perspective 首次点击另一对象时 SHALL 只切换 active selection，不开始图片编辑。图片工具 SHALL NOT 启用或显示 Blender fallback selection 的 Drag 设置。

所有图片编辑手势 SHALL 只在 active object 是当前 Selection 内的 Image Empty 时启动；否则系统 SHALL 以 warning 取消该次手势。

Scenario: User clicks another Image Empty while Frame is active

• WHEN 已有一个 active Image Empty，用户普通点击另一 Image Empty
• THEN Blender 按原生规则选择该对象并使其 active
• AND Frame 不开始、不显示矩形 Overlay，也不生成图片

Scenario: User shift-clicks another object

• WHEN 任一图片工具处于 active，用户 Shift 单击另一对象
• THEN Blender 保留原生追加或切换选择行为

Scenario: User drags while Frame is active

• WHEN 用户按住左键并移动到 Blender 的 drag threshold 之外
• THEN Frame 才收集当前 Selection 并进入矩形操作

Scenario: User opens image tool settings

• WHEN 用户激活 Frame、Crop Lasso、Crop Polyline、Crop Perspective 或 Cutout Lasso
• THEN Tool Settings 不显示 Drag: Select Box/Lasso 等 fallback selection 设置