Sharp Annotator Plugin

Professional image annotation and markup tool for Node.js using the Sharp library. Add markers, arrows, callouts, highlights, and various annotations to images with themes and colors. Perfect for documentation, tutorials, and bug reports.

Features

Annotation Types

• marker - Numbered circles (1, 2, 3...) with gradient and shadow
• arrow - Straight arrows with customizable heads
• curved-arrow - Smooth curved arrows with quadratic curves
• callout - Text boxes with pointers (speech bubbles)
• rect - Rectangle highlights with dashed borders
• circle - Circle highlights with dashed borders
• label - Text labels with optional background boxes
• highlight - Semi-transparent overlays for emphasis
• blur - Blur sensitive content (configurable strength)
• connector - Dashed lines between elements
• icon - Icon badges (check, x, warning, info, question)

Themes

• documentation - Professional blue/gray scheme
• tutorial - Educational green/blue colors
• bugReport - Attention-grabbing red/orange theme
• highlight - Emphasis-focused yellow/cyan palette

Colors

red, orange, yellow, green, blue, purple, pink, cyan, teal, white, black, gray, lightGray, darkGray, success, warning, error, info, primary, secondary, accent

Quick Start

1. Installation

cd pets/sharp-annotator
bun install

2. Test Connection

opencode run "test sharp annotator connection" --print-logs

3. Get Image Dimensions

opencode run "get image dimensions for image.png" --print-logs

4. Basic Annotation

opencode run "annotate image image.png with numbered marker at 100,100" --print-logs

Usage Examples

Simple Markers

{
  "imagePath": "screenshot.png",
  "annotationsJson": "[{\"type\":\"marker\",\"x\":150,\"y\":200,\"text\":\"1\"},{\"type\":\"marker\",\"x\":300,\"y\":250,\"text\":\"2\"}]"
}

Bug Report Annotations

{
  "imagePath": "bug.png",
  "theme": "bugReport",
  "annotationsJson": "[{\"type\":\"rect\",\"x\":100,\"y\":150,\"width\":200,\"height\":100},{\"type\":\"icon\",\"x\":200,\"y\":200,\"iconName\":\"error\"},{\"type\":\"callout\",\"x\":320,\"y\":200,\"text\":\"Critical bug here!\"}]"
}

Tutorial Step Annotations

{
  "imagePath": "tutorial.png",
  "theme": "tutorial",
  "annotationsJson": "[{\"type\":\"marker\",\"x\":50,\"y\":100,\"text\":\"1\"},{\"type\":\"label\",\"x\":80,\"y\":100,\"text\":\"Click here\"},{\"type\":\"arrow\",\"x\":50,\"y\":120,\"endX\":150,\"endY\":180}]"
}

Complex Workflow

{
  "imagePath": "workflow.png",
  "theme": "documentation",
  "annotationsJson": "[{\"type\":\"marker\",\"x\":100,\"y\":100,\"text\":\"1\"},{\"type\":\"curved-arrow\",\"x\":120,\"y\":120,\"endX\":250,\"y\":200},{\"type\":\"highlight\",\"x\":230,\"y\":180,\"width\":80,\"height\":40},{\"type\":\"label\",\"x\":270,\"y\":200,\"text\":\"Important step\"},{\"type\":\"connector\",\"x\":270,\"y\":220,\"endX\":350,\"y\":250}]"
}

Tools

sharp-annotator-test-connection

Tests the plugin connection and verifies Sharp library availability.

Returns:

• Sharp library version information
• Supported formats (JPEG, PNG, WebP, GIF, AVIF, TIFF)
• Available annotation types
• Supported themes and colors

sharp-annotator-get-image-dimensions

Retrieves image metadata including dimensions, format, and properties.

Parameters:

• imagePath (string, required): Path to the image file

Returns:

• Width, height, format
• Channel information
• File size
• Alpha channel presence

sharp-annotator-annotate-image

Adds multiple annotations to an image with various types, themes, and colors.

Parameters:

• imagePath (string, required): Path to input image
• outputPath (string, optional): Output path (defaults to adding _annotated suffix)
• annotationsJson (string, required): JSON array of annotation objects
• theme (string, optional): Default theme for all annotations
• quality (number, optional): Output quality 1-100 (default: 90)

Annotation Object Structure:

{
  "type": "annotation-type",
  "x": 100,
  "y": 100,
  "width": 200,        // For rect, highlight, callout
  "height": 50,       // For rect, highlight, callout
  "endX": 200,        // For arrow, curved-arrow, connector
  "endY": 150,        // For arrow, curved-arrow, connector
  "text": "Label",     // For marker, label, callout
  "color": "red",      // Override theme color
  "theme": "bugReport", // Per-annotation theme
  "strokeWidth": 3,    // Line thickness
  "fontSize": 18,      // Text size
  "radius": 30,        // For circle
  "blurStrength": 15,  // For blur
  "dashLength": 8,     // For connector
  "iconName": "check"  // For icon
}

Annotation Types Reference

Marker

{
  "type": "marker",
  "x": 100,
  "y": 100,
  "text": "1"  // Optional: defaults to "1"
}

Creates a numbered circle with gradient fill and shadow.

Arrow

{
  "type": "arrow",
  "x": 50,
  "y": 50,
  "endX": 150,
  "endY": 100,
  "strokeWidth": 3
}

Draws a straight arrow with customizable arrow head.

Curved Arrow

{
  "type": "curved-arrow",
  "x": 50,
  "y": 50,
  "endX": 200,
  "endY": 100
}

Creates a smooth curved arrow using quadratic Bezier curves.

Callout

{
  "type": "callout",
  "x": 200,
  "y": 100,
  "width": 150,
  "height": 60,
  "text": "Note: This is important"
}

Creates a speech bubble with text and pointer.

Rectangle Highlight

{
  "type": "rect",
  "x": 100,
  "y": 150,
  "width": 200,
  "height": 80,
  "strokeWidth": 2
}

Dashed rectangle border for highlighting areas.

Circle Highlight

{
  "type": "circle",
  "x": 200,
  "y": 200,
  "radius": 40
}

Dashed circle for circular highlights.

Label

{
  "type": "label",
  "x": 150,
  "y": 100,
  "text": "Step 1",
  "fontSize": 16
}

Text label with optional background box.

Highlight Overlay

{
  "type": "highlight",
  "x": 100,
  "y": 100,
  "width": 150,
  "height": 50
}

Semi-transparent colored overlay.

Blur

{
  "type": "blur",
  "x": 200,
  "y": 200,
  "width": 100,
  "height": 30,
  "blurStrength": 15
}

Applies Gaussian blur to sensitive content.

Connector

{
  "type": "connector",
  "x": 100,
  "y": 100,
  "endX": 200,
  "endY": 150,
  "dashLength": 5
}

Dashed line connecting two points.

Icon

{
  "type": "icon",
  "x": 150,
  "y": 150,
  "iconName": "warning"  // check, x, warning, info, question
}

Predefined icon badges with circles.

Environment Variables

Optional

• SHARP_ANNOTATOR_OUTPUT_DIR - Default output directory for annotated images (default: ./output)

File Support

Input Formats

• JPEG, PNG, WebP, GIF, AVIF, TIFF

Output Format

• PNG (always, to preserve transparency and quality)

Error Handling

The plugin provides comprehensive error handling for:

• Missing or invalid image files
• Invalid JSON in annotations
• Out-of-bounds coordinates
• Unsupported file formats
• File system permissions

Performance Tips

1. Batch Annotations: Add multiple annotations in a single call rather than multiple calls
2. Image Size: Large images may take longer to process
3. Output Directory: Use a fast local drive for best performance
4. Memory Usage: Very high-resolution images may require more memory

Common Workflows

Bug Report Creation

1. Take screenshot of the issue
2. Use get-image-dimensions to understand layout
3. Add red highlights and error icons to problem areas
4. Add callout annotations with descriptions
5. Save annotated image for bug report

Tutorial Creation

1. Use tutorial theme for consistent colors
2. Add numbered markers for steps
3. Use arrows and curved arrows to guide flow
4. Add labels for UI elements
5. Connect related elements with connectors

Documentation

1. Use documentation theme for professional look
2. Highlight important areas with rectangles
3. Add numbered markers for reference
4. Use callouts for detailed explanations

Testing

# Test plugin connection
opencode run "test sharp annotator connection"

# Test with a sample image
opencode run "get image dimensions for test.png"

# Test basic annotation
opencode run "annotate image test.png with marker at 100,100"

Examples and Templates

Check the test/ directory for:

• Sample images
• Annotation templates
• Example JSON configurations
• Test scripts for common workflows

Troubleshooting

Sharp Library Issues

If Sharp fails to load:

# Reinstall sharp
bun remove sharp
bun add sharp

# Clear any cached versions
rm -rf node_modules/.cache/sharp

Memory Issues with Large Images

• Reduce image size before annotation
• Use smaller annotation sets
• Increase available system memory

File Path Issues

• Use absolute paths for reliability
• Ensure input directory exists
• Check write permissions for output directory

Dependencies

• sharp: High-performance image processing library
• openpets-sdk: OpenPets plugin framework
• dotenv: Environment variable management

License

This plugin is part of the OpenPets ecosystem and follows the same license terms.