Skip to content

CLAUDE.md

Latest commit

 

History

History
69 lines (52 loc) · 2.82 KB

CLAUDE.md

File metadata and controls

69 lines (52 loc) · 2.82 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

KernelScope is an educational web application for visualizing convolution operations in image processing. Users watch kernels slide across images pixel-by-pixel, inspect individual calculations, and understand how filters like Sobel edge detection work.

Current Status: Specification phase only (see SPEC.md for full requirements)

Tech Stack (from SPEC.md)

  • Framework: React
  • Rendering: Three.js (for efficient pixel rendering and future 3D visualizations)
  • Processing: Client-side only, Web Workers for convolution computation
  • State: Stateless (no backend, no persistence)

Key Architectural Decisions

Rendering Approach

Use Three.js for the image canvas to enable:

  • Efficient rendering of images up to 1024×1024 pixels
  • Smooth 60fps zoom/pan with pixelated view at high zoom levels
  • Foundation for future 3D surface plot visualization

Computation

Convolution runs in Web Workers to keep UI responsive during processing.

View Modes

Two visualization modes to implement:

  1. Side-by-side: Original and processed images, synced zoom/pan
  2. Single view (in-place): Wavefront showing processed/original split advancing with raster scan

Core Features to Implement

  • Image input (samples + upload, max 1024×1024, auto-convert to grayscale)
  • Preset kernels: Sobel (Gx, Gy, magnitude), Gaussian blur, Sharpen
  • Custom 3×3 kernel editor
  • Edge handling: zero padding, mirror, clamp
  • Playback controls: play/pause, speed slider, step buttons, timeline scrubber
  • Pixel inspection: click any pixel for detailed calculation breakdown
  • Continuous zoom with preset levels, pixelated view when zoomed in
  • Color-coded feedback mode (green/red flash for value changes)
  • PNG export of processed image

Development Guidelines

Code Organization

  • Use TypeScript for type safety
  • One component per file, co-locate related hooks
  • Extract reusable logic into custom hooks
  • Keep core algorithms (convolution, image processing) separate from UI components

Performance

  • Offload heavy computation to Web Workers
  • Use useMemo/useCallback for expensive calculations
  • Profile and optimize Three.js render loops
  • Avoid re-renders: lift state appropriately, memoize components when needed

Testing

  • Write unit tests for core algorithms (convolution, edge handling)
  • Component tests for interactive behavior
  • Test edge cases: small images, large images, extreme kernel values

Code Quality

  • Prefer functional components with hooks over class components
  • Use descriptive variable names; self-documenting code over excessive comments
  • Keep functions small and focused on a single responsibility
  • Handle errors gracefully at system boundaries (file upload, image decoding)