Flash Mask

English | 简体中文 | 繁體中文 | 日本語 | Deutsch | Français | Español

Quick image masks that show AI exactly where to edit.

"Not that—the one next to it." How many times have you had to say that to AI?
You want to tweak a single detail, and the model regenerates the entire image. Until now, fixing that meant firing up a heavyweight image editor for tedious selections and exports.
Flash Mask turns that whole process into seconds: drop in an image, outline the area you want changed, and copy structured JSON coordinates straight to your AI or agent so it knows the exact edit location. When you need pixel-level precision, export a 1:1 black-and-white mask with one click.

---

Overview

Flash Mask is a lightweight, native macOS companion app built for AI image editing and visual workflows. When collaborating with AI models or coding agents, text prompts alone often fail to specify exact boundaries, resulting in unintended changes across the entire image or edits in the wrong spot.

On macOS, Flash Mask outputs JSON 1.1 with an instruction for the whole image and optional notes for individual regions. The website's web app remains on JSON 1.0.

Mac App

• Paste a screenshot directly from the clipboard.
• Add one instruction for the whole image and optional notes for individual regions.
• Use the interface in seven languages: English, Simplified Chinese, Traditional Chinese, Japanese, German, French, and Spanish.
• Use a dedicated settings window to switch language, check for updates, and open the website, help, GitHub source, or support page.

Instead of wrestling with lasso tools, fill layers, and manual exports in complex image editors, Flash Mask converts your selections into agent-ready coordinates in seconds:

• Structured JSON coordinates by default: Copy standardized JSON containing pixel coordinates, normalized coordinates, source image dimensions, local absolute file paths, and optional edit instructions (prompts) with one click. Paste directly into your AI chat or agent workflow.
• 1:1 black-and-white PNG mask on demand: For inpainting models and traditional pipelines that require pixel-level masks, export a crisp PNG mask matching original image dimensions (pure white selection, pure black background, no feathering or anti-aliasing).
• 100% local, offline, and private: Image decoding, coordinate calculations, and mask rendering run entirely on your Mac. No images, file paths, coordinates, or prompts are ever uploaded. No accounts, no sign-ins, no ads, and no tracking SDKs.
• Focused on spatial targeting—no built-in AI lock-in: Flash Mask focuses on clearly communicating where to edit and what to change. The actual image generation and editing are handled by your preferred AI tool or agent—no vendor lock-in or cloud dependencies.

Use Cases

• Character art & AI generation touch-ups: Outline hands, facial features, clothing, or accessories to guide targeted inpainting while keeping the rest of the image stable.
• Photo cleanup & object removal: Quickly box out background bystanders, clutter, watermarks, or blemishes for image-editing agents to remove and inpaint cleanly.
• Poster & marketing asset edits: Mark specific text layouts, product subjects, or graphic elements that need replacement in posters, banners, and e-commerce assets.
• UI bug callouts for coding agents: Pinpoint visual bugs in UI screenshots—such as clipped text, overlapping controls, or layout misalignments in iOS Simulator, macOS apps, Canvas, WebGL, maps, charts, or game UIs—and hand both exact coordinates and fix instructions directly to your coding agent.

Quick Start

1. Open an image: Drag and drop a PNG, JPEG/JPG, or WebP image into the window, click Open Image, or paste a screenshot from the clipboard. Pan, zoom, and toggle between Fit and Actual Size (1:1 pixel) views.
2. Outline and refine regions:
   • Click and drag on the image to outline a freehand area; release the mouse button to add it. Draw multiple separate regions as needed (automatically merged as a union).
   • Click any existing region to fine-tune it: drag the entire selection to reposition it, or drag, add, and delete individual polygon vertices.
   • Optional: Enter an instruction for the whole image in the "What should your agent do?" field, then select a region to add a note for that region.
3. Copy JSON or export mask:
   • Click Copy JSON: Copies structured data—including the local file path, image dimensions, polygon coordinates, and edit prompt—to your clipboard to paste directly into your AI or agent.
   • Click Export Mask PNG: Opens the macOS save sheet to export a crisp black-and-white PNG mask matching the source image dimensions. The mask marks the selected areas; notes are included in JSON.

JSON Coordinate Data Format

Flash Mask outputs versioned, self-describing JSON with dual coordinate systems—absolute pixel coordinates and normalized [0.0, 1.0] coordinates (origin at top-left, X increasing rightward, Y increasing downward). The Mac app uses JSON 1.1; the website's web app uses JSON 1.0:

{
  "mask_spec_version": "1.1",
  "instruction": "This JSON identifies areas the user selected in the source image. Each polygon marks one selected area; multiple polygons form a combined selection; the first and last points are connected automatically. The top-level `prompt`, if present, applies to the whole image. Each region's `prompt`, if present, applies only to that region. Interpret these texts in the context of the current conversation. The combined geometry marks range only; it does not assign a processing order among regions.",
  "source_image": {
    "file_name": "example.jpg",
    "width": 1920,
    "height": 1080,
    "file_path": "/Users/username/Pictures/example.jpg"
  },
  "coordinate_system": {
    "origin": "top-left",
    "x_direction": "right",
    "y_direction": "down"
  },
  "prompt": "Keep the building",
  "regions": [
    {
      "id": 1,
      "shape": "polygon",
      "points_px": [[96, 108], [480, 108], [480, 432], [96, 432]],
      "points_normalized": [[0.05, 0.1], [0.25, 0.1], [0.25, 0.4], [0.05, 0.4]],
      "prompt": "Remove stray lines"
    },
    {
      "id": 3,
      "shape": "polygon",
      "points_px": [[600, 108], [900, 108], [900, 432], [600, 432]],
      "points_normalized": [[0.3125, 0.1], [0.46875, 0.1], [0.46875, 0.4], [0.3125, 0.4]],
      "prompt": "Use a light gray background"
    }
  ]
}

Field Reference

• mask_spec_version: Specification version. The Mac app currently emits "1.1"; the website's web app remains on "1.0".
• instruction: Embedded self-describing guidance that instructs downstream AI models or agents on how to interpret polygons and user intent.
• source_image: Source file name, pixel dimensions (width, height), and the absolute local Mac file path (file_path is specific to the macOS app so local agents can directly access the file).
• coordinate_system: Coordinate system definition (fixed at top-left origin, X increasing rightward, Y increasing downward).
• prompt: Optional. In Mac JSON 1.1, this instruction applies to the whole image.
• regions: List of marked regions. Each region includes integer pixel coordinates (points_px as [x, y]) and dimensionless normalized coordinates (points_normalized as [x/width, y/height]). Mac JSON 1.1 may include an optional prompt for a specific region; region IDs remain stable when another region is deleted. Start and end vertices close automatically, and multiple regions form a combined union.

Strict JSON 1.0 consumers must upgrade their validator before accepting JSON 1.1. Flash Mask does not silently drop region notes.

Features

• Broad Format Support: Import PNG, JPEG/JPG, and WebP images.
• Multi-Region Selection: Draw multiple irregular selections on a single image; selections automatically combine into a unified mask upon export.
• Interactive Vertex Editing: Drag entire selections to reposition them, or precisely add, move, and remove polygon vertices.
• Smooth Canvas Navigation: Pan and zoom smoothly, with quick toggles for Fit and Actual Size (1:1 pixel) views.
• Image and Region Notes: Attach an optional instruction to the whole image and add notes to individual regions in the Mac app.
• Dual Coordinate Systems: Generates both absolute pixel coordinates and resolution-independent normalized coordinates to support varied agent and model schemas.
• Original Resolution Fidelity: Black-and-white PNG masks match source image dimensions 1:1, rendered with pure white selections, pure black backgrounds, and crisp, unfeathered edges.
• Direct Local File Paths: The macOS app outputs verified absolute file paths in JSON so local automation scripts and agents can locate files instantly.
• Seven Interface Languages: English, Simplified Chinese, Traditional Chinese, Japanese, German, French, and Spanish. The app follows your system language by default; switch anytime from the language menu in the top bar or in Settings without losing your current image, regions, or notes.
• Privacy & Offline First: Runs 100% locally with no sign-in required, zero ads, and no tracking or analytics SDKs.

Getting Flash Mask

• Mac App Store: Get the official pre-built app on the Mac App Store. A one-time purchase with lifetime access—no subscriptions and no in-app purchases.
• Official Website: Visit flashmask.net for product updates and details.
• Source Releases: Download source code archives from GitHub Releases. (Note: Official binary builds are distributed exclusively through the Mac App Store; GitHub Releases does not attach pre-built binaries).

Open Source Scope

This repository provides the complete open-source code for the Flash Mask macOS client, including:

• Native macOS AppKit / WKWebView host wrapper and Xcode project (macos/)
• Embedded HTML / JavaScript editor core (index.html)
• Coordinate contract protocol parsing, selection vertex cleaning, and mask generation logic (src/)
• Flash Mask 1.0 and 1.1 JSON Coordinate Contract validation schemas (schemas/)
• Core automated contract and unit test suite (tests/)

Note: This repository contains the standalone macOS application and its editing core. It does not include standalone web deployment scripts or commercial backend services (such as marketing landing pages, quota/ad systems, analytics, or hosted infrastructure). Under the Apache-2.0 license, the core editing module and shared data contracts may be freely ported and adapted.

Contributing

See the contribution guide for local checks, CI coverage, and pull request details.

Building the Mac App from Source

Prerequisites

• A Mac with a full Xcode installation; the host macOS version must be supported by that Xcode release
• The app targets macOS 13.0 or later and builds as a universal binary (arm64 + x86_64)
• Pure Swift, AppKit, and WebKit build—zero external Swift package dependencies

Build Command

Run the following command from the repository root:

xcodebuild \
  -project 'macos/Flash Mask.xcodeproj' \
  -scheme 'Flash Mask' \
  -configuration Release \
  -derivedDataPath '.derivedData/local' \
  ONLY_ACTIVE_ARCH=NO \
  CODE_SIGNING_ALLOWED=NO \
  build

Build output location: .derivedData/local/Build/Products/Release/Flash Mask.app

This command creates an unsigned local build, compiling the native wrapper and bundling index.html and application resources into a standalone app. The Release configuration targets macOS 13.0 and builds both arm64 and x86_64 slices. The official App Store build is produced through the separate Xcode Archive and distribution workflow, not this local build command.

One-Command Build Script

Alternatively, use the included build.sh script (run ./build.sh --help for details):

./build.sh
./build.sh --version 1.3.1 --build-number 9 --dmg

The script defaults to version 1.3 and build 8; --version and --build-number override those values. It checks the built app's version, minimum macOS version, and both architecture slices. --dmg packages that unsigned app for local testing; the resulting DMG is not suitable for Gatekeeper distribution.

For distribution outside the Mac App Store, sign the app with your own Developer ID Application identity and a secure timestamp, verify its code signature, submit it for notarization, and staple and validate the accepted ticket. Then package that exact app with:

./build.sh --package-app "/path/to/stapled/Flash Mask.app"

--package-app verifies the Developer ID signature, secure timestamp, notarization ticket, macOS 13.0 minimum, and both architecture slices, then creates a versioned DMG without running xcodebuild or signing again. The DMG itself remains unsigned; signing, notarizing, and stapling that outer container are separate steps for direct distribution. The helper does not sign, notarize, archive, or produce an official App Store build. Derivative builds must use their own Bundle ID, app name, and brand assets.

Running Core Tests

Running the core protocol and logic test suite requires Node.js 22 or later. (Node.js is used exclusively for testing contracts and algorithms; building the macOS app itself does not require Node.js).

npm ci --ignore-scripts
npm test

The test suite covers:

• JSON Coordinate Contract schema validation for macOS and Web targets
• Platform-specific field constraints and omission rules
• Polygon geometry calculations and lasso vertex simplification (smoothing and redundancy removal)
• 1:1 black-and-white PNG mask pixel rasterization accuracy
• Performance boundaries and vertex count limit safeguards
• Localization resources: identical keys, placeholders, and paired bundle resources across all seven languages

On macOS, npm test also compiles and runs the native Swift tests (localization resources and Settings window placement), which briefly open test windows. Run the native interface tests separately with node --test tests/mac-localization-ui.js. CI runs the core tests on Linux and the native and interface tests on Apple Silicon macOS 15, Intel, and macOS 14; see the contribution guide.

Directory Structure

Path	Description
index.html	Embedded editor interface, canvas interactions, and UI state machine
src/	Coordinate contract parsing, mask rasterization, and selection vertex cleaning algorithms
src/localizations/	Interface text for all seven languages, one JSON file per language
scripts/	Build-time script that validates and packages the paired localization resources
schemas/	Official JSON Schema definitions for the Flash Mask 1.0 and 1.1 Coordinate Contracts
macos/	Native AppKit / WKWebView host wrapper, security-scoped file access, and Xcode project
tests/	Unit tests, contract validation suites, and test fixtures

License & Notices

Flash Mask original source code is licensed under the Apache License 2.0. Subject to the terms of the license, you may freely use, modify, and distribute this software, including in commercial and proprietary derivative works.

• Copyright and attribution notices are documented in NOTICE.
• Third-party components and dependencies are listed in THIRD_PARTY_NOTICES.md.
• Brand assets—including the name "Flash Mask", logos, and application icons—are protected under separate Brand Asset Terms and are excluded from the Apache-2.0 license grant.
• User Data Ownership: All JSON coordinate data, images, and PNG masks generated with Flash Mask belong entirely to the user and are not subject to the Apache-2.0 license.