Package Exports

@thomasdavis/spectre-ui

Readme

@thomasdavis/spectre-ui

A React component for automatic image region detection with technical overlay visualization. Analyzes images using edge detection algorithms and overlays them with customizable bounding boxes, keypoints, connection graphs, and HUD-style interfaces.

npm version license bundle size

Features

Automatic Region Detection: Edge-based detection using luminance gradients
Keypoint Generation: Automatically generates tracking points within detected regions
Connection Graphs: Visual links showing spatial relationships between regions
Real-time Canvas Rendering: Efficient HTML5 Canvas with customizable overlays
Multiple Image Formats: Supports URL, File, HTMLImageElement, and Base64 data URIs
Framework-Agnostic: Zero CSS dependencies, works with any React framework
TypeScript First: Full type definitions included
Advanced Callbacks: Expose region detection and rendering events
Highly Customizable: Control every aspect of the visualization

Installation

npm install @thomasdavis/spectre-ui
# or
pnpm add @thomasdavis/spectre-ui
# or
yarn add @thomasdavis/spectre-ui

Quick Start

import { Spectre } from '@thomasdavis/spectre-ui';

function App() {
  return <Spectre image="/path/to/image.jpg" />;
}

Usage

Basic Usage

import { Spectre } from '@thomasdavis/spectre-ui';

function ImageAnalyzer() {
  return (
    <div style={{ width: '800px', height: '600px' }}>
      <Spectre
        image="/path/to/image.jpg"
        color="#00ffff"
        opacity={0.8}
      />
    </div>
  );
}

Multiple Image Input Formats

import { Spectre } from '@thomasdavis/spectre-ui';
import { useState } from 'react';

function ImageUploadExample() {
  const [image, setImage] = useState(null);

  const handleFileUpload = (event) => {
    const file = event.target.files[0];
    setImage(file); // Pass File object directly
  };

  return (
    <>
      <input type="file" onChange={handleFileUpload} accept="image/*" />
      <Spectre image={image} />
    </>
  );
}

// Or with URL
<Spectre image="https://example.com/image.jpg" />

// Or with HTMLImageElement
const img = new Image();
img.src = '/image.jpg';
<Spectre image={img} />

// Or with Base64 data URI
<Spectre image="data:image/png;base64,iVBORw0KG..." />

With Event Callbacks

import { Spectre } from '@thomasdavis/spectre-ui';
import type { ProcessingStats, DetectedRegion } from '@thomasdavis/spectre-ui';

function InteractiveExample() {
  const handleRegionDetect = (regions: DetectedRegion[]) => {
    console.log(`Detected ${regions.length} regions:`, regions);
  };

  const handleProcessingComplete = (stats: ProcessingStats) => {
    console.log(`Processing completed in ${stats.processingTime}ms`);
    console.log(`Found ${stats.regionCount} regions with ${stats.pointCount} keypoints`);
  };

  const handleError = (error: Error) => {
    console.error('Failed to process image:', error);
  };

  return (
    <Spectre
      image="/image.jpg"
      onRegionDetect={handleRegionDetect}
      onProcessingComplete={handleProcessingComplete}
      onError={handleError}
    />
  );
}

Custom Styling & Configuration

import { Spectre } from '@thomasdavis/spectre-ui';

function CustomizedExample() {
  return (
    <Spectre
      image="/image.jpg"
      // Visual configuration
      enabled={true}
      opacity={0.7}
      color="#ff00ff"
      strokeWidth={2}

      // Feature toggles
      showBoxes={true}
      showConnections={true}
      showKeypoints={true}
      showHud={false}

      // Advanced controls
      connectionDensity={400}
      maxRegions={8}
      edgeThreshold={20}

      // Canvas styling
      style={{
        border: '2px solid cyan',
        borderRadius: '8px'
      }}
      className="my-custom-class"
    />
  );
}

Canvas Access via Ref

import { Spectre } from '@thomasdavis/spectre-ui';
import { useRef } from 'react';

function ExportExample() {
  const canvasRef = useRef<HTMLCanvasElement>(null);

  const exportImage = () => {
    if (canvasRef.current) {
      const dataUrl = canvasRef.current.toDataURL('image/png');
      const link = document.createElement('a');
      link.download = 'analysis.png';
      link.href = dataUrl;
      link.click();
    }
  };

  return (
    <>
      <Spectre
        image="/image.jpg"
        canvasRef={canvasRef}
      />
      <button onClick={exportImage}>Export Image</button>
    </>
  );
}

API Reference

SpectreProps

Prop	Type	Default	Description
`image`	`string \| HTMLImageElement \| File \| null`	Required	Image input (URL, File, HTMLImageElement, or Base64)
`enabled`	`boolean`	`true`	Enable/disable overlay rendering
`opacity`	`number`	`0.65`	Overlay opacity (0-1)
`color`	`string`	`"#ffffff"`	Overlay color (hex format)
`strokeWidth`	`number`	`1.5`	Line thickness (0.5-5)
`showBoxes`	`boolean`	`true`	Show bounding boxes around regions
`showConnections`	`boolean`	`true`	Show connection lines between regions
`showKeypoints`	`boolean`	`true`	Show keypoint markers
`showHud`	`boolean`	`true`	Show HUD overlay elements
`connectionDensity`	`number`	`300`	Connection density (100-600)
`maxRegions`	`number`	`6`	Maximum number of regions to detect (1-10)
`edgeThreshold`	`number`	`15`	Edge detection threshold (0-100)
`regionDetectionScale`	`number`	Auto	Image scale for detection (0-1)
`width`	`number \| "auto"`	`"auto"`	Canvas width
`height`	`number \| "auto"`	`"auto"`	Canvas height
`className`	`string`	`undefined`	CSS class for canvas element
`style`	`CSSProperties`	`undefined`	Inline styles for canvas
`onLoad`	`(stats: ProcessingStats) => void`	`undefined`	Callback when image loads
`onError`	`(error: Error) => void`	`undefined`	Callback on error
`onRegionDetect`	`(regions: DetectedRegion[]) => void`	`undefined`	Callback when regions detected
`onRender`	`(canvas: HTMLCanvasElement) => void`	`undefined`	Callback after rendering
`onProcessingStart`	`() => void`	`undefined`	Callback when processing starts
`onProcessingComplete`	`(stats: ProcessingStats) => void`	`undefined`	Callback when processing completes
`canvasRef`	`RefObject<HTMLCanvasElement>`	`undefined`	External canvas ref

ProcessingStats

interface ProcessingStats {
  pointCount: number;        // Total keypoints detected
  regionCount: number;        // Number of regions detected
  connectionCount: number;    // Number of connections generated
  processingTime: number;     // Processing time in milliseconds
  imageWidth: number;         // Image width in pixels
  imageHeight: number;        // Image height in pixels
  triangleCount: number;      // Reserved for future use
}

DetectedRegion

interface DetectedRegion {
  id: string;                 // Region identifier (e.g., "R00")
  x: number;                  // X coordinate
  y: number;                  // Y coordinate
  width: number;              // Region width
  height: number;             // Region height
  keypoints: Point[];         // Array of keypoints
  label: string;              // Region label (e.g., "OBJ_A")
  confidence: number;         // Detection confidence (0-1)
}

Point

interface Point {
  x: number;
  y: number;
}

Connection

interface Connection {
  from: Point;                // Start point
  to: Point;                  // End point
  fromRegion: string;         // Source region ID
  toRegion: string;           // Target region ID
}

Advanced Usage

Custom Region Detection

For advanced use cases, you can use the low-level APIs:

import {
  loadImage,
  detectRegions,
  generateConnections
} from '@thomasdavis/spectre-ui';

async function customAnalysis() {
  // Load image
  const img = await loadImage('/image.jpg');

  // Detect regions with custom options
  const regions = detectRegions(img, {
    scale: 0.5,
    maxRegions: 10,
    edgeThreshold: 20,
  });

  // Generate connections
  const connections = generateConnections(regions, 400);

  console.log('Analysis complete:', { regions, connections });
}

How It Works

Region Detection Algorithm

Image Preprocessing: Images are scaled for optimal processing speed
Luminance Calculation: Converts RGB to luminance (0.299R + 0.587G + 0.114B)
Edge Detection: Calculates horizontal and vertical gradients
Grid Analysis: Divides image into cells and calculates edge density
Region Selection: Identifies top non-overlapping regions with highest edge density
Keypoint Generation: Creates tracking points within each region
Connection Graph: Links keypoints between regions based on density

Rendering Pipeline

Draw original image to canvas
Scale detected regions to full resolution
Render connections (background layer)
Render bounding boxes with technical styling
Render keypoints with crosshairs
Render HUD overlay elements
Calculate and report processing statistics

Browser Support

Requires modern browsers with support for:

HTML5 Canvas API
ES2020 JavaScript features
CSS Grid and Flexbox (for demo)
File API (for File input support)

Performance Considerations

Images are downscaled for region detection (max 1500px dimension)
Processing is synchronous but typically completes in <100ms
Canvas rendering uses efficient 2D context operations
Grid size adapts to image dimensions for optimal performance

TypeScript Support

This package includes full TypeScript type definitions. All props and return types are fully typed.

import type {
  SpectreProps,
  ProcessingStats,
  DetectedRegion,
  Point,
  Connection,
  ImageInput,
} from '@thomasdavis/spectre-ui';

License

MIT

Contributing

Contributions are welcome! Please check the repository for contribution guidelines.

Repository

https://github.com/thomasdavis/spectre-ui

Support

For issues and questions, please use the GitHub issue tracker.