REF 010 — DOCS

Using Regionly

Regionly turns labeled areas you draw on an image into exact coordinates an AI can act on. Everything runs in your browser — the image is never uploaded. This page covers the workflow, the export formats, and every shortcut.

Quick start

1. Open an image. Drop it into the editor, paste with Ctrl+V, or click New to browse. PNG, JPG, WebP, and GIF work — as do saved .regionly.json projects.
2. Draw regions. Pick a tool, drag or click on the image, and give each region a label. Add an optional note where the AI needs context ("blocks movement", "click target").
3. Hit Done. The export view shows two tabs: versioned JSON and prompt-ready plain text.
4. Copy or download. Paste the text into a ChatGPT or Claude prompt, or feed the JSON to code and agents.

The seven tools

The JSON export, field by field

Exports are versioned (regionly v1.x) and additive-only within a major version. The machine-readable contract lives at regionly-v1.schema.json; the full geometry reference is on the format page.

{
  "format": "regionly",
  "version": "1.0",
  "generator": "https://regionly.dimsylaisolutions.com",
  "exportedAt": "2026-07-20T14:00:00.000Z",
  "image": { "name": "room.png", "width": 1536, "height": 1024 },
  "coordinateSystem": {
    "pixels": "origin top-left of the image, x right, y down, units = image pixels",
    "normalized": "same origin/axes, each value divided by image width (x) or height (y), range 0-1"
  },
  "labels": [
    {
      "label": "bed",
      "color": "#3e7bfa",
      "regions": [
        {
          "id": "r1a2b3",
          "type": "rect",
          "note": "blocks movement",
          "pixels":     { "x": 90, "y": 90, "width": 170, "height": 230 },
          "normalized": { "x": 0.05859, "y": 0.08789, "width": 0.11068, "height": 0.22461 },
          "boundingBox": {
            "pixels":     { "x": 90, "y": 90, "width": 170, "height": 230 },
            "normalized": { "x": 0.05859, "y": 0.08789, "width": 0.11068, "height": 0.22461 }
          }
        }
      ]
    }
  ],
  "stats": { "labelCount": 1, "regionCount": 1 }
}

The prompt-text export

The second tab renders the same data as plain language — built to paste straight into a prompt, no JSON parsing required of the model:

Labeled regions for image "room.png" (1536x1024 pixels).
Coordinate system: origin at the top-left corner of the image; x increases
rightward, y increases downward; all values are image pixels.
1 region across 1 label:

## bed (1 region)
- rectangle at x=90, y=90, width=170, height=230 (top-left corner at 90,90;
  bottom-right at 260,320)
   note: blocks movement

Feeding exports to ChatGPT, Claude & agents

Attach the image to your chat, then paste the export below your instructions. The model stops guessing where things are — it reads the answer. A concrete example with a trimmed JSON snippet:

Here is an app screenshot (attached) and its labeled regions:

{
  "format": "regionly",
  "image": { "name": "app.png", "width": 1280, "height": 800 },
  "labels": [
    { "label": "signup button", "regions": [
      { "type": "rect",
        "pixels": { "x": 1032, "y": 24, "width": 180, "height": 44 } }
    ] },
    { "label": "pricing table", "regions": [
      { "type": "rect",
        "pixels": { "x": 96, "y": 310, "width": 1088, "height": 380 } }
    ] }
  ]
}

Task: write a Playwright script that clicks the center of the signup
button, and suggest a clearer headline for the pricing table.

Tips that hold across models: keep labels short and literal, put "why it matters" in the note, and prefer normalized coordinates when your pipeline resizes images. For automation, the JSON is stable and versioned — parse it instead of the text.

Project files

Save (Ctrl+S) downloads a single .regionly.json project file with the image and your regions embedded. Drop it back into the editor any time to resume. Project files (format: "regionly-project") are a save format — use the export for anything downstream.

Keyboard shortcuts

API & MCP access (Premium)

Premium subscribers can annotate images programmatically — from a script, a backend, or an AI agent — using the same engine as the in-app Auto button. API calls share your account's daily AI limit.

Get a key

Sign in, open Account (top right), and under API keys choose New API key. The key (rk_…) is shown once — copy it then. Revoke a key any time from the same panel; anything using it stops immediately.

REST endpoint

POST https://regionly.dimsylaisolutions.com/api/v1/annotate

curl https://regionly.dimsylaisolutions.com/api/v1/annotate \
  -H "Authorization: Bearer rk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "image": "data:image/png;base64,iVBORw0K...", "hint": "mark the walkable floor and obstacles" }'

The response is the same region shape as the JSON export — pixel-free normalized 0–1 coordinates, ready to scale to any image size:

{
  "imageType": "top-down game room",
  "regionCount": 9,
  "regions": [
    { "type": "polygon", "label": "floor", "note": "walkable area", "points": [[0.05,0.4],[0.95,0.4],[0.95,0.98],[0.05,0.98]] },
    { "type": "rect", "label": "bed", "note": "blocks movement", "x": 0.14, "y": 0.23, "w": 0.4, "h": 0.45 },
    { "type": "point", "label": "door", "note": "entrance", "x": 0.5, "y": 0.99 }
  ]
}

image must be a data: URL (PNG, JPEG, or WebP), up to ~2.5 MB. hint is optional. Errors return { "error": "..." } with a matching status (401 bad/expired key, 402 subscription inactive, 429 daily limit, 413 image too large).

MCP server (for agents)

A zero-dependency MCP server (mcp/regionly-mcp.mjs in the repo) exposes annotation as an annotate_image tool for Claude Desktop, Claude Code, or any MCP client. Point it at a local file or a data URL:

{
  "mcpServers": {
    "regionly": {
      "command": "node",
      "args": ["/path/to/regionly-mcp.mjs"],
      "env": { "REGIONLY_API_KEY": "rk_your_key" }
    }
  }
}

Then ask your agent to “annotate this screenshot” — it calls Regionly and gets back exact region coordinates it can reason about or feed into a game/map/UI workflow.