# Image Annotation guide

## Regions are notes

A region is a part of an image, and each region is one note.
The note's name is the region's title. Its properties hold the image, the source note, and the shape.
Its body starts with the crop block, then holds what you write.

Rename the note, and the region is renamed. Delete the note, and the region is deleted.
Obsidian updates links in both cases, as it does for any note.

## Put a region into your writing

Embed the region note: `![[Eyes]]`. The embed shows the crop and your text.
A plain link, `[[Eyes]]`, shows the crop when you hover over it.

There are five ways to add the embed:

- In the editor, select the region, then select **Insert in <note>**. The embed goes on a new line at the cursor of the note you last wrote in.
- Select **Insert in…**, or right-click the region and select **Insert in note…**, then choose any note. The embed goes at the end of that note.
- Drag the region's name from the editor's list into a note.
- Run **Image Annotation: Insert image region** in a note and choose the region.
- Type `![[` and the region's name.

To see every note that uses a region, look at the region note's backlinks, or at **Used in** in the editor.

## Say something different about the same part

A region has one text. To write something different about the same part of an image, duplicate the region.
Right-click it and select **Duplicate**. The copy has the same image and shape, and no text.

## The source note

The `source` property links to the note the image came from. The plugin fills it in when it can:

1. From the note you right-clicked the image in.
2. From another region of the same image.
3. From a web image's local copy, whose name starts with its source note.
4. From the one note that embeds the image in its text.

When several notes embed the image, the plugin asks which one it came from, once per editor tab.
When it cannot tell, `source` stays empty. Fill it in yourself; the property field suggests notes.

Local copies saved before version 0.2 are named with a hash, so rule 3 cannot read them.

## Edit a region

Run **Image Annotation: Browse image regions** and choose a region, or select the button on its crop.
The editor opens in a tab with the region selected.

- To change the shape, drag the region or one of its handles. The change saves when you release the pointer.
- To rename the region, double-click its name in the list, or press F2. Press Enter to save.
- To draw the shape again, right-click the region and select **Redraw shape**.

To delete a region, select it and press Delete, or right-click it and select **Delete region**.
A dialog tells you how many notes link to it. The region note goes to the trash, following Obsidian's trash setting.
Links to it stay, and show as unresolved.

## Editor keys

| Key | Action |
| --- | --- |
| V | Select and change regions |
| R | Draw a rectangle |
| P | Draw a polygon |
| Enter | Finish a polygon |
| Esc | Discard the drawing |
| Delete | Delete the selected region |
| F2 | Rename the selected region |
| + / − / 0 | Zoom in, zoom out, fit the image |

Ctrl + scroll also zooms.

## Clean up snapshots

Run **Image Annotation: Clean up unused image snapshots** to review unused downloads and move them to trash.
The command checks again before removal. It keeps snapshots used by regions, notes, or canvases.
Open Markdown editor text also protects images that have not yet been saved.
Close the editor tabs before cleanup. Local images outside the snapshot folder are not candidates.

## Storage and sync

Region notes go in the folder set in **Settings → Image Annotation → Region folder**, `Regions` by default.
You can move a region note to any folder later.

The plugin also uses this folder:

```text
Image Annotation/
  index.json   a copy of the regions, for Image Graph
  Media/       local copies of web images, named "<source note> - image - b2df.jpg"
```

The region notes are the record. The plugin rewrites `index.json` from them, so you do not need to keep it.
Each region is its own file, so sync merges changes to different regions without conflict.

A web image saved from two notes is one local copy: the plugin compares the image's content, not its name.

A copy of a region note made with **Make a copy** becomes a separate region with its own `region_id`.

Rename images inside Obsidian while the plugin is enabled, so the `image` property follows.
Changes to an image's content can invalidate a region's shape.

## Web images and privacy

The plugin downloads a web image only when you choose it for annotation.
The image website receives that request. The plugin does not upload notes or annotation data.
There are no accounts, telemetry, or remote processing services.

Web images must have a direct image URL. Supported formats are PNG, JPEG, WebP, GIF, BMP, and AVIF.
The plugin first asks the server for the image size and rejects declared sizes above 40 MB.
If the server omits or rejects that request, the plugin checks the downloaded bytes instead.
This fallback does not cap network transfer or peak memory use.
Local SVG images also work. Video and audio annotation are not supported.

## Upgrading from 0.1

Version 0.2 replaces captions and attachments with region notes. Old data is not converted.
Before its first write, the plugin copies the old index to `Image Annotation/index-0.1.json`.
Old caption files stay in the vault as ordinary notes. Old previews show as plain code blocks.