Mask Background Processor

Overview

The Mask Background processor (mask_background) uses an AI model (e.g., Replicate) to produce a grayscale mask or a transparent cutout from an input image. The processor can cache the generated mask to avoid repeated AI calls and can invert the mask if needed. This is ideal for “cutout” tasks or background removal workflows.

---

Example Usage

- processor:
    processor: "mask_background"
    inputs:
      source: "input/input.png"
    params:
      mask_cache: "cache/mask.png"
      invert: "False"
    outputs:
      mask: "cache/mask.png" # At least one of 'mask' or 'rgba' must be specified
      rgba: "temp/subject.png"

Explanation

• mask_cache: If the file (or its override) exists, the AI call is skipped. Otherwise, after generating a new mask, it is stored here.
• invert: "False": If set to "True", the final mask is inverted (white ↔ black).
• mask: "cache/mask.png": The final grayscale mask.
• rgba: "temp/subject.png": An optional RGBA image where the subject is preserved, and the background is transparent (derived from the mask).

---

Inputs

Key	Required	Description
source	Yes	A file path referencing the input image to process, typically read from your storage system ("input").

---

Params

Key	Type	Required	Default	Description
mask_cache	file path		(none)	If specified and found, skip calling the AI. Otherwise, after generating a new mask, store it here. Also checks for *-or.png override for manual edits.
invert	boolean		false	If "true", invert the final mask (white ↔ black). Has no effect on the underlying cached file (i.e., the cached data is stored un-inverted).

(You can add more, such as a replicate model param if your AI service demands it.)

---

Outputs

Key	Required	Description
mask		Grayscale mask output (white = foreground, black = background). If omitted but rgba is present, that might suffice.
rgba		An RGBA PNG where the background is removed, subject only. Derived from mask + source.

At least one of mask or rgba must be provided. If neither is specified, the processor cannot write a result.

---

Mask Editor and Caching

• Mask Editor:
  • The editor reads the cached mask from a file like "cache/mask.png".
  • On user edits, it writes the override file (e.g., "cache/mask-or.png").
• Cache Skipping:
  • If mask_cache is provided and "cache/mask-or.png" (override) exists, that override is used.
  • Otherwise, if the normal mask_cache exists, we skip the AI call.
• Result:
  • If the AI is needed, it calls the external model, extracts a grayscale channel, and saves that to mask_cache.
  • The final file is also placed in mask output (and optionally rgba).