@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.

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

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

Rendering Pipeline

1. Draw original image to canvas
2. Scale detected regions to full resolution
3. Render connections (background layer)
4. Render bounding boxes with technical styling
5. Render keypoints with crosshairs
6. Render HUD overlay elements
7. 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.