map-hotspot-annotator

Platformneta-skills/map-hotspot-annotator
Use it in Cohub

Paste this into your agent's chat — it fetches the skill and follows it.

Use the skill: map-hotspot-annotator. Run `npx -y @neta-art/neta-search-cli@latest skills use neta-skills/map-hotspot-annotator --via site` and follow what it prints. Read its complete output, redirecting it to a temporary file first if necessary, and resolve relative paths from the skill directory it prints.
Use in Neta Studio Open it in Neta Studio and see what people made with it.
Install from a terminal
npx -y @neta-art/neta-search-cli@latest skills use neta-skills/map-hotspot-annotator
Summary

Turn a map image into clickable regions with coordinates you can edit and export.

  • Works on world maps, level select screens, illustrated rooms, or diagrams with objects you want to click.
  • Creates an interactive preview page where you can see and test each clickable spot on your map.
  • Best with clear objects: islands on a sea map, buildings in a town, rooms in a dungeon layout.
  • You get stable coordinate data you can adjust, reuse in a game engine, or publish as an interactive page.
SKILL.md
# Map Hotspot Annotator

## Purpose

Turn a static map image into stable interaction data and an HTML overlay. The skill captures this pipeline:

```text
map image
→ agent visual recognition of objects
→ percentage hotspot JSON
→ HTML/SVG overlay
→ optional manual calibration
→ production-ready interaction data
```

Use this for world maps, level-select maps, illustrated rooms, town maps, tactical screens, product diagrams, or any static visual where users need clickable regions.

## Core Principle

Do not treat image recognition as the final product. The final product is a stable data contract:

```json
{
  "id": "cloud_academy",
  "type": "island",
  "x": 27.8,
  "y": 19.7,
  "radius": 7.2,
  "action": { "type": "open_panel", "target": "cloud_academy" }
}
```

Agent vision is used to create the first pass. Humans or a calibration UI can correct it. JSON stores the durable interaction layer.

## When starting a task

1. Identify the input image.
   - If the image is attached, save or use it as the reference.
   - If the image is already in the workspace, verify path and dimensions.
   - If the user asks for a new map first, generate or locate the map before annotating.
2. Decide object granularity.
   - `coarse`: major islands / rooms / zones only.
   - `medium`: major objects + path nodes / entrances.
   - `fine`: buildings, props, rewards, exits, sub-interactions.
3. Choose hotspot shape.
   - `circle`: fastest and best for prototypes.
   - `rect`: good for UI panels and rectangular buildings.
   - `polygon`: best for precise island/room boundaries.
4. Produce `hotspots.json` using percentage coordinates.
5. If asked for a page, build an HTML overlay that reads or embeds the JSON.
6. Publish a public review link when working in Cohub and the user needs review.

## Coordinate Contract

Always store coordinates as percentages unless the target engine requires pixels.

```text
x = center_x / image_width * 100
y = center_y / image_height * 100
radius = clickable_radius / image_width * 100
```

For `circle` objects:

```json
{
  "id": "stable_id",
  "name": "Display name",
  "type": "island",
  "shape": "circle",
  "x": 50,
  "y": 50,
  "radius": 5,
  "confidence": 0.85,
  "description": "Visual basis for this point."
}
```

For `rect` objects:

```json
{
  "id": "settings_panel",
  "shape": "rect",
  "x": 76,
  "y": 8,
  "w": 18,
  "h": 12
}
```

For `polygon` objects:

```json
{
  "id": "main_island_boundary",
  "shape": "polygon",
  "points": [
    [44, 42],
    [56, 40],
    [62, 51],
    [52, 60],
    [42, 55]
  ]
}
```

## Agent Visual Recognition Method

Use visual reasoning first:

1. List the main visible objects.
2. Group decorative elements separately from interactive objects.
3. For each interactive object, estimate:
   - semantic identity
   - center point
   - approximate clickable radius or boundary
   - confidence
   - why it should be interactive
4. Prefer interaction centers over geometric centers.
5. Use stable ids in English snake_case; display names can be Chinese or localized.
6. Mark uncertain items with lower `confidence` and a note.

## Recommended object types

- `island` — main world / zone / landmass
- `hub` — central or primary navigation point
- `path_node` — bridge, road junction, route star, transition point
- `building` — visible building or landmark
- `entry` — doorway, portal, gate, exit
- `reward` — chest, star, collectible, prize
- `ui` — baked UI element in the image
- `custom` — fallback for unknown user-defined object

## HTML Overlay Requirements

When building a page:

- Put the image and hotspot layer in the same positioned container.
- Match the container aspect ratio to the image dimensions.
- Use absolute positioning with `%` for hotspots.
- Use semantic buttons for clickable hotspots.
- Add visible focus states and keyboard access.
- Keep text in HTML, not baked into generated map images.
- Provide a JSON export path when the page is an editor.

Minimal CSS pattern:

```css
.map-stage {
  position: relative;
  aspect-ratio: 1824 / 1024;
}
.map-stage img {
  width: 100%;
  height: 100%;
  display: block;
  object-fit: contain;
}
.hotspot-layer {
  position: absolute;
  inset: 0;
}
.hotspot {
  position: absolute;
  transform: translate(-50%, -50%);
}
```

Minimal render pattern:

```js
hotspot.style.left = `${object.x}%`;
hotspot.style.top = `${object.y}%`;
hotspot.style.width = `${object.radius * 2}%`;
hotspot.style.height = `${object.radius * 2}%`;
```

## Deliverables

For a prototype:

```text
index.html
assets/map.png
data/hotspots.json
```

For a reusable package:

```text
map-name/
├── index.html
├── assets/
│   └── map.png
├── data/
│   └── hotspots.json
└── README.md
```

For an analysis-only request, return:

```markdown
## Recognized objects

n. id — name — type — x/y/radius — confidence — note

## JSON

...

## Calibration notes

...
```

## Reference case

Read `references/map-hotspot-reference-case.md` when you need a concrete example. It includes the Creator Era toy world map case and points to the bundled image:

- `assets/creator-era-world-map-reference.png`
- `references/creator-era-world-map-hotspots.json`

## Quality Checks

Before delivery:

- Verify the source image dimensions.
- Confirm coordinates are percentages, not pixels.
- Check that every object has `id`, `type`, `shape`, `x`, `y`, and a confidence note.
- Check that major objects are not duplicated.
- Check that decorative elements are not over-marked unless requested.
- If HTML is built, verify public link or local file opens and the image path is correct.
- State clearly whether the output is agent-visual first pass, calibrated, or model-detected.

## Boundaries

- Do not promise pixel-perfect automatic segmentation from agent visual estimation alone.
- Do not run OCR or create text-dependent interactions unless the user asks for text recognition.
- Do not store private or sensitive images in a public skill package unless the user explicitly confirms. For reference cases, use only approved public/demo assets.
Related skills
create-avgPlatformTurn a story idea into a playable visual novel with branching choices and character art.game-makerPlatformTurns your characters and world into a real playable browser game, not a mockup.pov-life-slicePlatformDrop viewers into a believable 15-second moment inside your world, seen through someone's eyes.production-spritesheet-builderPlatformBuild pixel-perfect sprite sheets and game animations with fixed grids and safe backgroundsreferenced-4x4-asset-sheetPlatformGenerate 16 game assets in one organized sheet, then crop them into ready-to-use images.production-tile-collision-mapPlatformTurn your map art into playable collision grids with roads, open areas, and interactive path testing.