如何编写GIMP Script-Fu的.scm函数实现两个图层合并

GIMP 原生提供了图层合并的内置接口，你无需自行实现像素级合并逻辑，直接调用内置API即可完成需求，以下是符合.scm文件规范的可直接运行的完整代码：

(define (merge-two-layers input-image top-layer bottom-layer merge-type)
  ; 校验图层归属，避免跨图像操作报错
  (if (and (= (car (gimp-item-get-image top-layer)) input-image)
           (= (car (gimp-item-get-image bottom-layer)) input-image))
    (begin
      ; 调整图层顺序，确保上层图层位于下层图层正上方
      (gimp-image-raise-layer input-image top-layer bottom-layer)
      ; 执行合并操作，返回合并后的新图层ID
      (let ((merged-layer (car (gimp-image-merge-layers 
                                 input-image
                                 (vector top-layer bottom-layer) ; 待合并图层向量，顺序从上到下
                                 merge-type 
                                 FALSE)))) ; 固定传FALSE即可，由merge-type控制裁剪逻辑
        ; 刷新GIMP界面显示
        (gimp-displays-flush)
        ; 返回合并完成的图层供后续操作调用
        merged-layer)
      )
    ; 图层归属不匹配时抛出明确错误
    (error "传入的图层不属于目标图像，无法执行合并操作")
    )
  )

; 脚本注册逻辑，注册后可在「滤镜/自定义工具」下找到可视化入口
(script-fu-register
  "merge-two-layers"
  "合并两个指定图层"
  "将传入的两个上下图层合并为单个图层"
  "Bethel Kingsley"
  "MIT License"
  "2024"
  "*"
  SF-IMAGE    "目标图像"    0
  SF-DRAWABLE "上层待合并图层" 0
  SF-DRAWABLE "下层待合并图层" 0
  SF-ENUM     "合并模式" '("MergeType" "merge-type")
  )

(script-fu-menu-register "merge-two-layers" "<Image>/Filters/Custom")

关键参数与使用说明 #

• 合并模式（merge-type）是合并操作的核心配置，常用可选值如下：
  • CLIP-TO-IMAGE：合并后的图层边界对齐当前画布大小，超出画布的像素会被裁剪
  • CLIP-TO-BOTTOM-LAYER：合并后的图层边界对齐下层待合并图层的范围
  • EXPAND-AS-NECESSARY：自动扩展图层边界，完整保留两个图层的所有像素内容
• 调用注意事项：
  • 传入的两个待合并图层必须属于同一个目标图像，否则脚本会抛出错误
  • gimp-image-merge-layers执行后会删除原有的两个独立图层，返回值是合并生成的新图层ID，后续对合并结果的操作需要使用这个返回的ID
  • 所有修改图像的Script-Fu操作执行完成后，都需要调用gimp-displays-flush刷新界面，否则GIMP窗口不会实时显示修改结果
  • 如果不需要在GIMP菜单里显示可视化入口，可以删掉代码末尾的script-fu-register和script-fu-menu-register部分，直接把merge-two-layers函数作为工具函数嵌入到你自己的其他脚本里调用

内容的提问来源于stack exchange，提问作者Bethel kingsley