Image Editor Tools
Designimage-editor-toolsImage Editor Tools is an Agent Skill for design published in the mcmonkeyprojects/SwarmUI repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Architecture and patterns for developing image editor tools and UI in the SwarmUI image editor.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/mcmonkeyprojects/SwarmUI/blob/HEAD/.agents/skills/image-editor-tools/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/image-editor-tools, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Image Editor Tools
Guide to the image editor tool system in src/wwwroot/js/genpage/helpers/image_editor.js.
When to Use
- Use this skill when adding or modifying image editor tools
- Use this skill when working with layers, color controls, or the image editor toolbar
- Use this skill when adding new helper JS files that interact with the image editor
Architecture
Class Hierarchy
ImageEditorTool- Base class. Createsthis.div(toolbar button) andthis.configDiv(bottom bar config area) viamakeDivs(). Has lifecycle methods:setActive(),setInactive(),draw(), mouse handlers,onLayerChanged().ImageEditorTempTool- Extends base. OverridesmakeDivs()with a no-op, sothis.divis undefined. Used for hidden sub-tools (e.g., the eyedropper color picker tool). Any code accessing.divon a tool must null-check for this case.ImageEditorToolWithColor- Extends base. Adds color control support:getColorControlsHTML(),wireColorControls(),setColor(col), and color-awareonLayerChanged()with dual mask/image color memory. Tools that need a color picker (Brush, Bucket, Shape) extend this.ImageEditorToolSam2Base- Extends base. Shared SAM2 warmup/clear-mask/request-tracking logic. Subclasses overrideaddWarmupGenData(genData, cx, cy)and optionallyonClearMask(). SAM2Points and SAM2BBox extend this.- Concrete tools extend the appropriate base:
ImageEditorToolBrush/ImageEditorToolBucket/ImageEditorToolShapeextendImageEditorToolWithColor;ImageEditorToolSam2Points/ImageEditorToolSam2BBoxextendImageEditorToolSam2Base; others extendImageEditorTool.
Tool Registration
Tools are registered in the ImageEditor constructor via this.addTool(new ToolClass(...)). Order matters for toolbar display. The tool ID string (e.g., 'brush', 'paintbucket') is used with this.editor.activateTool(id).
Layer System
- Layers have a boolean
isMaskproperty. onLayerChanged(oldLayer, newLayer)is called on every tool when the active layer changes (viasetActiveLayer()). The old layer is passed directly so tools can compare previous vs new state.- The base
onLayerChangedhandlesisMaskOnlytools (hides them when not on a mask). - Tools with color can override
onLayerChangedto adapt (e.g., compress color to grayscale for masks, swap stored color based onoldLayer.isMaskvsnewLayer.isMask).
Color Controls Pattern
Tools that use color extend ImageEditorToolWithColor, which provides:
getColorControlsHTML(): Returns HTML for a.image-editor-tool-blockdiv with hex text input (.id-col1), color swatch (.id-col2), and eyedrop button (.id-col3). Usesthis.colorfor the default value.wireColorControls(): Call after settingconfigDiv.innerHTMLto wire up the color picker, swatch click, and eyedropper button. Opens the picker via the singletoncolorPickerHelper(fromcolor_picker.js).setColor(col): Updatesthis.color, the text input, and the swatch background.- Dual color memory:
imageColorandmaskColorfields store separate colors for image vs mask layers. The inheritedonLayerChangedswaps between them (guarded bythis.colorTextexisting, so tools like the eraser that skipwireColorControls()are unaffected). - Grayscale enforcement: When on a mask layer, colors are compressed to grayscale via
colorPickerHelper.hexToGrayscale(), and the picker opens in grayscale mode.
Bottom Bar Config
Each tool's config UI is in this.configDiv, a flex row at the bottom of the editor. Common sub-blocks use .image-editor-tool-block with align-items: center. Sliders use enableSliderForBox() from site.js.
Instructions
- When adding a new tool, extend
ImageEditorTool(orImageEditorTempToolif it should be hidden). - Register it in the
ImageEditorconstructor withthis.addTool(new YourTool(this)). - If the tool needs a new helper JS file, add it to
src/Pages/Text2Image.cshtmlin the@section Scriptsblock beforeimage_editor.js. - Use
createDiv()fromutil.jsfor DOM creation. - Use theme CSS variables (
--popup-back,--light-border, etc.) for styling. - Always null-check
.divwhen working with tools that might be TempTools. - If adding color controls, extend
ImageEditorToolWithColor, pass the default color tosuper(), callthis.getColorControlsHTML()when building config HTML, and callthis.wireColorControls()after settingconfigDiv.innerHTML. The base class handlessetColor(),onLayerChanged()color swapping, and grayscale enforcement automatically.