CanvasLens

A powerful HTML5 Canvas-based image viewing and annotation library built with TypeScript. CanvasLens provides a unified Web Component for image viewing, zooming, panning, annotation, and before/after image comparison.

Features

• 🖼️ Image Viewer - Load images with automatic aspect ratio preservation
• 🔍 Zoom & Pan - Mouse wheel zoom with cursor-centered zooming, smooth drag to pan
• ✏️ Annotations - Rectangle, arrow, text, circle, and line annotation tools
• 🎨 Custom Styles - Fully customizable annotation styles (colors, line styles, shadows, fonts)
• 🔄 Image Comparison - Interactive slider-based before/after comparison
• 🖼️ Overlay Mode - Full-screen professional editing interface
• 🎯 Web Component - Standard HTML element that works with any framework
• 🎨 TypeScript Support - Full type safety and IntelliSense
• ⚡ Performance - Optimized rendering and memory management

Installation

npm install @koniz-dev/canvaslens

CDN

<script type="module">
  import { CanvasLens } from 'https://unpkg.com/@koniz-dev/canvaslens@latest/dist/index.js';
</script>

Quick Start

<canvas-lens 
  src="https://picsum.photos/800/600"
  width="800px" 
  height="600px"
  tools='{"zoom": true, "pan": true, "annotation": {"rect": true, "arrow": true}}'>
</canvas-lens>

<script type="module">
  import { CanvasLens } from '@koniz-dev/canvaslens';
</script>

API Reference

Attributes

Attribute	Type	Default	Description
src	string	-	Image source URL or data URI
width	string | number	"800"	Width in px, %, or number
height	string | number	"600"	Height in px, %, or number
background-color	string	"#f0f0f0"	Background color (CSS color value)
tools	string (JSON)	"{}"	Tool configuration as JSON string
max-zoom	number	10	Maximum zoom level
min-zoom	number	0.1	Minimum zoom level
image-type	string	-	Image MIME type (e.g., "image/jpeg")
file-name	string	-	File name for display purposes

Methods

Method	Parameters	Returns	Description
loadImage(src, type?, fileName?)	string, string?, string?	Promise<void>	Load image from URL
loadImageFromFile(file)	File	void	Load image from File object
resize(width, height)	number, number	void	Resize the canvas
zoomIn(factor?)	number?	void	Zoom in by factor (default: 1.2)
zoomOut(factor?)	number?	void	Zoom out by factor (default: 1.2)
zoomTo(scale)	number	void	Set zoom level to specific scale
fitToView()	-	void	Fit image to view
resetView()	-	void	Reset view to original state
activateTool(toolType)	string	boolean	Activate annotation tool ('rect', 'arrow', 'text', 'circle', 'line')
deactivateTool()	-	boolean	Deactivate current tool
updateTools(toolConfig)	ToolConfig	void	Update tools configuration
getActiveTool()	-	string | null	Get currently active tool
addAnnotation(annotation)	Annotation	void	Add annotation to canvas
removeAnnotation(id)	string	void	Remove annotation by ID
clearAnnotations()	-	void	Clear all annotations
getAnnotations()	-	Annotation[]	Get all annotations
toggleComparisonMode()	-	void	Toggle comparison mode
setComparisonMode(enabled)	boolean	void	Set comparison mode state
isComparisonMode()	-	boolean	Check if comparison mode is enabled
openOverlay()	-	void	Open full-screen overlay editor
closeOverlay()	-	void	Close overlay editor
isOverlayOpen()	-	boolean	Check if overlay is open
isImageLoaded()	-	boolean	Check if image is loaded
getImageData()	-	CustomImageData | null	Get current image data
getZoomLevel()	-	number	Get current zoom level
getPanOffset()	-	{x: number, y: number}	Get current pan offset
hasChanges()	-	boolean	Check if there are unsaved changes

Tool Configuration

Property	Type	Default	Description
zoom	boolean	false	Enable zoom functionality
pan	boolean	false	Enable pan functionality
annotation	object	undefined	Annotation tools configuration
annotation.rect	boolean	false	Enable rectangle annotation tool
annotation.arrow	boolean	false	Enable arrow annotation tool
annotation.text	boolean	false	Enable text annotation tool
annotation.circle	boolean	false	Enable circle annotation tool
annotation.line	boolean	false	Enable line annotation tool
annotation.style	AnnotationStyle	undefined	Default annotation style
comparison	boolean	false	Enable image comparison functionality

Annotation Style Configuration

Property	Type	Required	Description
strokeColor	string	Yes	Border color (hex, rgb, or named color)
strokeWidth	number	Yes	Border width in pixels
lineStyle	'solid' | 'dashed' | 'dotted'	No	Line style (default: 'solid')
fillColor	string	No	Fill color with transparency (use rgba)
shadowColor	string	No	Shadow color (use rgba for transparency)
shadowBlur	number	No	Shadow blur radius in pixels
shadowOffsetX	number	No	Shadow horizontal offset in pixels
shadowOffsetY	number	No	Shadow vertical offset in pixels
fontSize	number	No	Font size for text annotations
fontFamily	string	No	Font family for text annotations

Events

Event	Detail	Description
imageload	CustomImageData	Image loaded successfully
imageloaderror	Error	Image loading failed
zoomchange	number	Zoom level changed
panchange	{x, y}	Pan position changed
annotationadd	Annotation	Annotation added
annotationremove	string	Annotation removed (ID)
toolchange	string | null	Active tool changed
comparisonchange	number	Comparison slider position changed
error	CanvasLensError	Error occurred

Examples

Basic Usage

<canvas-lens 
  src="https://example.com/image.jpg"
  width="800px" 
  height="600px"
  tools='{"zoom": true, "pan": true}'>
</canvas-lens>

With Annotation Tools

<canvas-lens 
  src="https://example.com/image.jpg"
  width="800px" 
  height="600px"
  tools='{
    "zoom": true,
    "pan": true,
    "annotation": {
      "rect": true,
      "arrow": true,
      "text": true
    }
  }'>
</canvas-lens>

With Custom Annotation Styles

<canvas-lens 
  src="https://example.com/image.jpg"
  width="800px" 
  height="600px"
  tools='{
    "annotation": {
      "rect": true,
      "style": {
        "strokeColor": "#0096ff",
        "strokeWidth": 3,
        "lineStyle": "dashed",
        "fillColor": "rgba(0, 150, 255, 0.3)"
      }
    }
  }'>
</canvas-lens>

JavaScript API

import { CanvasLens } from '@koniz-dev/canvaslens';

const viewer = document.querySelector('canvas-lens');

// Load image
await viewer.loadImage('https://example.com/image.jpg');

// Zoom and pan
viewer.zoomTo(2.0);
viewer.fitToView();

// Annotations
viewer.activateTool('rect');
viewer.addAnnotation({
  id: 'rect-1',
  type: 'rect',
  points: [{ x: 100, y: 100 }, { x: 300, y: 250 }],
  style: {
    strokeColor: '#ff0000',
    strokeWidth: 2,
    fillColor: 'rgba(255, 0, 0, 0.2)'
  }
});

// Events
viewer.addEventListener('annotationadd', (e) => {
  console.log('Annotation added:', e.detail);
});

React Example

import { CanvasLens } from '@koniz-dev/canvaslens';

function ImageViewer({ src }) {
  const toolConfig = {
    zoom: true,
    pan: true,
    annotation: {
      rect: true,
      arrow: true,
      style: {
        strokeColor: '#0096ff',
        strokeWidth: 3,
        lineStyle: 'dashed'
      }
    }
  };

  return (
    <canvas-lens 
      src={src}
      width="800px" 
      height="600px"
      tools={JSON.stringify(toolConfig)}
    />
  );
}

Controls

• Mouse Wheel: Zoom in/out (cursor-centered)
• Left Click + Drag: Pan around the image
• Double Click: Reset view to initial state
• Alt + R/A/T/C/L: Toggle annotation tools
• Escape: Deactivate current tool
• Ctrl/Cmd + 0: Fit image to view

Browser Support

Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Documentation

• Complete API Reference
• Annotation Styles Guide
• Examples & Use Cases
• Framework Integration
• Security Documentation

Error Handling

CanvasLens provides comprehensive error handling:

// Listen for errors
viewer.addEventListener('error', (e) => {
  const error = e.detail;
  console.error(`[${error.type}] ${error.message}`, error.context);
  
  // Handle recoverable errors
  if (error.recoverable) {
    // Attempt recovery
  }
});

// Use try-catch for async operations
try {
  await viewer.loadImage('https://example.com/image.jpg');
} catch (error) {
  // Handle error
}

Error Types

• INITIALIZATION: Component initialization failed
• IMAGE_LOAD: Image loading failed
• RENDERING: Canvas rendering error
• ANNOTATION: Annotation operation error
• TOOL_ACTIVATION: Tool activation failed
• OVERLAY: Overlay mode error
• ATTRIBUTE_PARSING: Configuration parsing error

License

MIT License - see LICENSE file for details.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

• Issues: GitHub Issues
• NPM Package: @koniz-dev/canvaslens