motion-vector-analyzer

Motion Vector Analyzer

A comprehensive TypeScript library that analyzes motion vectors in JPEG and PNG images using gradient analysis, Sobel filters, and optical flow algorithms with advanced visualization capabilities.

Features

Core Analysis

• Image Loading: Supports JPEG and PNG image formats using Sharp
• Gradient Analysis: Calculates image gradients using Sobel operators
• Optical Flow: Advanced optical flow algorithms (sparse and dense)
• Vector Field Calculation: Converts gradients to motion vectors representing visual flow

Enhanced Visualization 🎨

• Advanced Arrow Rendering: Simple, filled, and outlined arrow styles with anti-aliasing
• Multiple Visualization Modes: Arrows, heat maps, streamlines, particle animation, and contour lines
• Interactive Features: Zoom, pan, tooltips, and real-time parameter adjustment
• Color Schemes: Magnitude-based, direction-based, custom gradients, and color blind friendly options
• Export Formats: PNG, SVG, interactive HTML, and animated GIF
• Performance Optimizations: Render caching, level-of-detail rendering, and GPU acceleration

Output Options

• Multiple Formats: Standalone vector visualizations, overlays on original images, and color map data
• Publication Quality: High-resolution, anti-aliased output suitable for academic papers
• Interactive Web: Self-contained HTML visualizations with no external dependencies

Quick Start

# Install the library
npm install motion-vector-analyzer

# Or for development
git clone https://github.com/yourusername/motion-vector-analyzer.git
cd motion-vector-analyzer
npm install

Basic Usage

import { MotionVectorAnalyzer } from 'motion-vector-analyzer';

const analyzer = new MotionVectorAnalyzer();

// Load and analyze an image
await analyzer.loadImage('path/to/your/image.jpg');
await analyzer.analyzeMotionVectors();

// Save visualization
await analyzer.saveVisualization('output/vectors.png');

Usage

As a Library

The Motion Vector Analyzer is designed to be used as a TypeScript/JavaScript library in your applications.

Programmatic Usage

Basic Analysis

import { MotionVectorAnalyzer } from './src/MotionVectorAnalyzer';

const analyzer = new MotionVectorAnalyzer();

// Load and analyze an image
await analyzer.loadImage('path/to/image.jpg');
analyzer.analyzeMotionVectors(smoothingWindow = 3, downsampleFactor = 4);

// Save basic visualization
await analyzer.saveVisualization('output/vectors.png', {
  scale: 15,
  color: '#FF0000',
  showMagnitude: true,
  vectorDensity: 4
});

Enhanced Visualization

// Enhanced arrow rendering
await analyzer.saveVisualization('output/enhanced.png', {
  arrowStyle: 'filled',
  thickness: 2,
  antiAliasing: true,
  colorScheme: 'direction',
  scale: 15
});

// Interactive HTML visualization
await analyzer.createInteractiveVisualization('output/interactive.html', {
  mode: 'arrows',
  interactive: true,
  showTooltips: true,
  enableSelection: true,
  realTimeAdjustment: true,
  scale: 15,
  colorScheme: 'direction'
});

// Multiple visualization modes
const modes = ['arrows', 'heatmap', 'streamlines', 'particles', 'contours'];
for (const mode of modes) {
  await analyzer.createInteractiveVisualization(`output/${mode}.png`, {
    mode,
    interactive: false,
    scale: 10,
    vectorDensity: 2
  });
}

// Export in different formats
await analyzer.exportVisualization('output/publication.svg', {
  format: 'svg',
  width: 1200,
  height: 900
});

Optical Flow Analysis

// Load two images for optical flow
await analyzer.loadImagesForOpticalFlow('previous.jpg', 'current.jpg');

// Analyze with optical flow
analyzer.analyzeMotionVectorsWithOptions({
  algorithm: 'optical_flow',
  flowType: 'dense',
  forwardBackward: true
});

// Save results
await analyzer.saveVisualization('output/optical_flow.png', {
  scale: 20,
  arrowStyle: 'filled',
  antiAliasing: true
});
});

await analyzer.saveVisualizationWithBackground(
  'path/to/image.jpg',
  'output/overlay.png'
);

How It Works

• Image Loading: Images are loaded and converted to grayscale for processing
• Gradient Calculation: Sobel filters (3x3 kernels) calculate horizontal and vertical gradients:
  • Sobel X: Detects vertical edges
  • Sobel Y: Detects horizontal edges
• Vector Field Generation: Gradients are converted to motion vectors:
  • Vector direction is perpendicular to gradient direction
  • Vector magnitude represents edge strength
• Smoothing: Optional smoothing window reduces noise in the vector field
• Visualization: Vectors are drawn as arrows with optional magnitude-based opacity

Output Files

Basic Output

• *_vectors.png: Vector field visualization on white background
• *_overlay.png: Vectors overlaid on the original image
• *_colormap.json: Color map data for further analysis

Enhanced Output

• *_interactive.html: Interactive web visualization with zoom, pan, and tooltips
• *_export.svg: Scalable vector graphics for publications
• *_heatmap.png: Magnitude heat map visualization
• *_streamlines.png: Flow streamline visualization
• *_particles.gif: Animated particle flow
• *_contours.png: Magnitude contour lines

Configuration Options

Enhanced VisualizationOptions

• scale: Scale factor for vector display (default: 10)
• color: Arrow color in hex format (default: '#FF0000')
• backgroundColor: Background color (default: '#FFFFFF')
• showMagnitude: Vary opacity based on vector magnitude (default: true)
• vectorDensity: Skip factor for vector display (default: 1)
• arrowStyle: Arrow style - 'simple', 'filled', or 'outlined' (default: 'simple')
• thickness: Line thickness (scales with magnitude)
• antiAliasing: Enable smooth line rendering (default: true)
• colorScheme: Color mapping - 'magnitude', 'direction', or 'custom' (default: 'magnitude')
• customColorMap: Custom color gradient array
• colorBlindFriendly: Use accessible color palettes (default: false)

InteractiveVisualizationOptions

Extends VisualizationOptions with:

• mode: Visualization mode - 'arrows', 'heatmap', 'streamlines', 'particles', 'contours'
• interactive: Enable interactive features (default: true)
• zoom: Initial zoom level (default: 1)
• pan: Initial pan offset {x, y}
• showTooltips: Show vector information on hover (default: true)
• enableSelection: Allow vector selection (default: true)
• realTimeAdjustment: Enable parameter controls (default: true)
• animationSpeed: Speed for particle animations
• animationFrames: Number of frames for GIF export
• particleCount: Number of particles for flow visualization
• contourLevels: Number of contour lines
• streamlineDensity: Density of streamline seeding

ExportOptions

• format: Export format - 'png', 'svg', 'html', 'gif'
• width: Output width (for SVG/HTML)
• height: Output height (for SVG/HTML)
• quality: Output quality (0-100)
• animationFrames: Number of animation frames
• interactive: Generate interactive HTML (for HTML format)

Processing Options

• smoothingWindow: Size of smoothing kernel (default: 3)
• downsampleFactor: Factor to reduce vector field resolution (default: 1)
• opticalFlowOptions: Advanced optical flow configuration

Examples

Place your JPEG or PNG images in the examples/ directory and run:

npm run dev

The program will process all valid images and save results to the output/ directory.

Project Structure

├── src/
│   ├── modules/
│   │   ├── ImageLoader.ts         # Image loading and preprocessing
│   │   ├── GradientAnalyzer.ts    # Sobel filter implementation
│   │   ├── VectorFieldCalculator.ts # Vector field math
│   │   ├── Visualizer.ts          # Basic image generation
│   │   ├── EnhancedVisualizer.ts  # Enhanced visualization features
│   │   └── OpticalFlowAnalyzer.ts # Optical flow algorithms
│   ├── types.ts                   # TypeScript interfaces
│   ├── MotionVectorAnalyzer.ts    # Main analyzer class
│   ├── test-enhanced-visualization.ts # Enhanced feature tests
│   └── index.ts                   # CLI entry point
├── examples/
│   ├── enhanced-visualization-demo.js # Complete feature demo
│   └── [sample images]             # Test images
├── output/                         # Generated results
├── ENHANCED_VISUALIZATION_GUIDE.md # Detailed feature guide
└── package.json

Dependencies

• sharp: High-performance image processing
• jimp: Image manipulation and visualization
• typescript: Type-safe development

Development

Building from Source

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Run linter
npm run lint

CLI Usage (Development)

For development and testing, you can use the included CLI:

# Development mode (processes examples/)
npm run dev

# Build and run
npm run build && npm start

Deployment

Publishing to npm

# Build the project
npm run build

# Login to npm (if not already logged in)
npm login

# Publish the package
npm publish

Requirements

• Node.js >= 16.0.0
• npm >= 7.0.0

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests for new functionality
• Run the test suite: npm test
• Submit a pull request

License

MIT