PhotoMeasure

A Vue 3 + TypeScript image annotation library using Konva.js for rendering high-resolution images with interactive polygon shapes, measurements, and regions.

Features

• 🖼️ High-resolution image support with tile-based rendering (useTileRenderer)
• 📄 PDF Support with high-performance rendering (usePdf)
• 🔍 Smooth zoom & pan with mouse wheel, pinch gestures, and programmatic control
• 📐 Interactive polygons with vertex editing, edge labels, and undo/redo history
• 🎯 Multi-polygon support with chaining mode and auto-alignment
• 📱 Mobile-friendly touch interactions
• 🎨 Customizable styling for strokes, fills, and labels
• 💾 Advanced Exporting: Export stage or pure canvas as base64 PNG
• 📦 Full TypeScript support with exported types

Installation

npm install photomeasure

Dependencies

npm install konva vue-konva pdfjs-dist uuid

Quick Start

<template>
  <InspectorViewer
    ref="viewerRef"
    :image-url="imageUrl"
    @image:loaded="onImageLoaded"
    @stage:click="onStageClick"
  >
    <template #default="{ scaleFactor, stageScale }">
      <PolygonRenderer
        v-for="shape in shapes"
        :key="shape.id"
        :shape="shape"
        :scale-factor="scaleFactor"
        :stage-scale="stageScale"
        :is-selected="selectedId === shape.id"
        @toggle="onToggleShape"
        @update:points="onUpdatePoints"
      />
    </template>
  </InspectorViewer>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { 
  InspectorViewer, 
  PolygonRenderer,
  type ShapeModel 
} from 'photomeasure'

const viewerRef = ref()
const imageUrl = ref('https://example.com/image.jpg')
const selectedId = ref<string | null>(null)

const shapes = ref<ShapeModel[]>([])

const onImageLoaded = (dimensions: { width: number; height: number }) => {
  console.log('Image loaded:', dimensions)
}

const onStageClick = (event: any) => {
  if (event.target === event.target.getStage()) {
    selectedId.value = null
  }
}

const onToggleShape = (shape: ShapeModel) => {
  selectedId.value = selectedId.value === shape.id ? null : shape.id
}

const onUpdatePoints = (points: number[][]) => {
  // Handle point updates
}
</script>

PDF Support

Use the usePdf composable to load and render PDF documents as images for the InspectorViewer.

import { usePdf } from 'photomeasure'

const { setSource, getPageImage, pageCount } = usePdf()

// Load a PDF
await setSource('path/to/document.pdf')

// Get a specific page as a WebP data URL
const imageUrl = await getPageImage(1, 2.0) // page 1, 2x scale

Composables

useImagePolygonLoader

Manages polygon state with undo/redo history and provides stage exporting.

import { useImagePolygonLoader } from 'photomeasure'

const {
  polygons,
  loadImage,
  undo,
  redo,
  canUndo,
  canRedo,
  exportStageAsBase64
} = useImagePolygonLoader()

// Load image and polygons
await loadImage('image.jpg')
loadPolygons(initialShapes)

// Export current view
const dataUrl = await exportStageAsBase64(viewerRef.value)

useTileRenderer

Optimizes rendering for extremely large images by splitting them into tiles.

import { useTileRenderer } from 'photomeasure'

const { updateView, updateVisibleTiles } = useTileRenderer({
  tileContainer: containerRef,
  stageRef: viewerRef,
  stageScale: currentScale,
  // ... other options
})

useOffscreenInspectorExporter

Exports a high-quality image of the annotation view without rendering it to the visible DOM.

import { useOffscreenInspectorExporter } from 'photomeasure'

const { exportFromInspector } = useOffscreenInspectorExporter()
const dataUrl = await exportFromInspector(imageUrl, polygons)

Components

InspectorViewer

The main stage component for displaying images and annotations.

| Prop | Type | Default | Description | |------|------|---------|-------------| | imageUrl | string | '' | URL of the image to display | | initialScale | number | 1 | Initial zoom scale | | isDraggable | boolean | true | Enable stage panning | | backgroundColor | string | '#f0f0f0' | Background color |

PolygonRenderer

A versatile component that renders either a single Polygon or a MultiPolygon based on the shape type.

Development

# Install dependencies
npm install

# Start dev server
npm run dev

# Build library
npm run build:lib

License

MIT