Timelapse Brush Simulator (v)

Project Overview

This application serves as an exploration of fundamental raster graphics manipulation techniques commonly implemented in professional digital illustration applications. The demo showcases practical implementations of brush dynamics, compositing operations, frame-based animation systems, and real-time pixel manipulation using the HTML5 Canvas 2D API. The architecture emphasises performant ImageData operations, efficient rendering pipelines, and modular brush system design patterns applicable to production-grade creative software.

Core Brush System

Brush Types & Rendering Algorithms

• Round (r): Implements a radial gradient falloff stamp with configurable hardness using createRadialGradient(). Core algorithm for soft-edged brushes.
• Square (s): Hard-edged rectangular stamp using direct fillRect() operations for pixel-perfect geometric shapes.
• Texture (x): Professional stamp-based texture rendering system with PNG alpha channel preservation. Implements off-canvas compositing pipeline with rotation matrices (stroke-direction + stochastic variance), source-atop colour tinting, and automatic black-to-transparent preprocessing. Supports custom texture loading (256×256 or 512×512 recommended) with automatic ImageData manipulation for black pixel removal (RGB threshold < 10). Defaults to grunge-06.png. See dedicated Texture Brush section below for implementation details.
• Oil (o): Advanced rectangular brush (2:1 aspect ratio) with adaptive colour mixing via ImageData sampling, directional lighting simulation, and edge contamination effects. Implements real-time colour blending with underlying canvas pixels (30% contamination factor).
• Daub (d): Implements colour averaging within brush radius and applies directional smudging with opacity-weighted blending. Simulates paint mixing through multi-sample ImageData read operations and weighted averaging algorithms.
• Render (e): Selective blur algorithm using luminance-based edge detection (contrast threshold: 80). Implements distance-weighted averaging within circular kernels while preserving high-contrast edges. Uses getLuminance() helper (ITU-R BT.601 coefficients: 0.299R + 0.587G + 0.114B).
• Pixel (p): Snaps to down-sized, quantized grid coordinates with nearest-neighbor scaling. Directly manipulates frame ImageData at native resolution with immediate upscaling for display.
• Fill (f): Stack-based flood fill implementation avoiding recursion limits. Uses visited set for cycle detection and 4-directional neighbor propagation.

Brush Dynamics & Parameters

• Size: Base brush diameter (1-100px). Directly affects kernel size for sampling operations.
• Opacity: Global alpha compositing with automatic scale switching. Standard mode: 0.1-1.0 range (0.1 increments). Fine-tune mode: 0-0.1 range (0.01 increments) activated when slider reaches minimum position, enabling precise low-opacity control for glazing and subtle layering. Slider thumb changes to pink gradient in fine-tune mode for visual feedback.
• Hardness: Controls radial gradient falloff curve. Higher values create sharper edges by adjusting colour stop positions.
• Spacing: Dual-mode interpolation system with toggle-able behavior (click label to switch modes). Lower values in either mode increase sample points at performance cost.
  • Smooth mode (default): Speed-based adaptive spacing where faster strokes automatically increase stamp density for gap-free rendering - lower values increase base density.
  • Absolute mode: Fixed-distance spacing regardless of stroke velocity, providing precise control over stamp placement for texturing and stippling effects.
• Flow: Per-stamp opacity multiplier enabling build-up effects through repeated application.
• Scatter: Stochastic offset applied to stamp positions. Uses uniform random distribution within defined radius to displaced from its intended position.
• Taper: Speed-based size modulation. Brush size decreases when moving slowly and increases when moving quickly, creating dynamic pressure simulation.
• Jitter: Per-stamp randomisation of size and opacity (50% size variance, 30% opacity variance) for highly organic variation.

Brush Preset System (.jbrush Format)

• File Format: JSON-based .jbrush files for human-readable brush configurations. Structure includes metadata (name, version, author, created date), brush parameters object (all 11 dynamics parameters: size, opacity, hardness, spacing, flow, scatter, taper, jitter, rotationMode, spinAngle, colour), and application metadata (tags, app identifier, version).
• Export Pipeline: JSON.stringify() serialisation with 2-space indentation for readability. Creates Blob with application/json MIME type and triggers download via dynamically created anchor element with Object URL.
• Import Pipeline: FileReader API with readAsText() for asynchronous file loading. JSON.parse() deserialisation with try-catch error handling. Validates brush object existence before applying parameters to prevent corrupted file errors.
• Parameter Mapping: Direct property assignment to primaryBrush object with fallback defaults for missing properties (defensive programming). Synchronizes all UI sliders and dropdowns via value assignment and dispatches change events to trigger preset application logic.
• State Synchronisation: Automatically updates cursor visualisation (updateCursor()), active brush display (updateActiveBrushDisplay()), and applies brush-specific presets through an event dispatch mechanism.
• Use Cases: Artist brush library creation, cross-session workflow persistence, community brush sharing, tutorial preset distribution, and backup/restoration of custom configurations.

Texture Brush System

The Texture brush implements a production-grade stamp-based rendering pipeline comparable to texture brush systems in professional illustration software. Unlike procedural brushes, texture brushes apply pre-rendered bitmap data with full alpha channel support, enabling complex organic patterns impossible to synthesize algorithmically in real-time.

Rendering Architecture

• Off-Canvas Compositing: Each stamp is rendered to a temporary HTMLCanvasElement for multi-stage processing before final composition. This prevents taint issues and enables complex blend mode stacking without affecting the main canvas state.
• Transform Pipeline: Applies 2D affine transformation matrix (translate → rotate → translate inverse) for stroke-direction-aligned rotation. Additional stochastic rotation variance (±0.25 radians) prevents repetitive patterns in continuous strokes.
• Alpha Preservation: Uses source-atop compositing mode for colour tinting, which preserves the original texture's alpha channel. This is critical for maintaining brush shape fidelity as standard multiply mode would destroy transparency gradients.
• Opacity Control: Secondary destination-in pass applies user-defined opacity via globalAlpha, creating a gradient mask that modulates the entire stamp uniformly. Maintains fine transparency control (0-0.1 fine mode with 0.01 steps).
• Square Stamp Geometry: Unlike circular gradient brushes, texture brushes maintain square aspect ratio to prevent distortion of directional grain patterns (essential for materials like charcoal, wood grain, fabric weave).

Texture Processing Pipeline

• Black-to-Transparent Conversion: Preprocessing step converts dark pixels (RGB < 10 threshold) to full transparency (alpha = 0) via ImageData manipulation. This enables "black and white texture" workflow where artists draw texture shapes in black on white backgrounds, with black defining the brush silhouette.
• Async Loading: Image.onload callback chain ensures texture processing completes before brush availability. Uses data URL intermediary (canvas.toDataURL()) for processed image storage, creating clean Image objects from manipulated pixel data.
• CORS Handling: Sets crossOrigin = 'anonymous' attribute with try-catch fallback for getImageData() operations. Gracefully degrades to unprocessed texture if security restrictions prevent pixel access (file:// protocol).
• Format Support: Accepts PNG and JPEG via FileReader API with client-side validation. PNG recommended for alpha channel support; JPEG usable for opaque textures.
• Size Validation: Warns users when loading textures > 1024×1024 due to memory overhead and potential frame rate degradation during real-time drawing. Optimal range: 256×256 to 512×512 for balance between detail and performance.

Default Texture & Custom Loading

• Default Texture: grunge-06.png loaded on initialization via loadDefaultTexture() with automatic black-to-transparent preprocessing. Provides immediate texture brush functionality without user action.
• Load Texture Button: Context-sensitive UI element (visible only when Texture brush active) triggers file picker with pre-selection tips dialog. Confirms texture format requirements (black/white, size recommendations) before opening native file chooser.
• Texture State Management: Global brushTexture reference updated on successful load with textureLoaded flag preventing race conditions. Fallback to solid square stamp if texture unavailable (async loading incomplete or error state).
• Auto-Preset Application: Switching to Texture brush automatically sets Size=100, Opacity=0.06 (fine mode), Flow=1.0 for optimal texture application parameters. Larger size necessary for texture detail visibility; low opacity enables gradual buildup.

Performance Considerations

• Canvas Reuse: Temporary canvas created per stamp rather than cached to avoid state pollution. V8 optimization recognises allocation pattern and JIT-compiles efficient object pool.
• Transform Overhead: 2D rotation matrix calculation (Math.atan2, translate, rotate) adds ~0.1ms per stamp on modern hardware - negligible for typical stroke densities (spacing ≥ 1.0).
• ImageData Manipulation: Black-to-transparent conversion is O(n) where n = width × height × 4 (RGBA). For 512×512 texture: ~1M operations, completes in <5ms on desktop CPUs. Performed once per texture load, not per stamp.
• Memory Profile: Each texture stored as Image object (~width × height × 4 bytes). 512×512 RGBA ≈ 1MB. Temporary canvases garbage collected after composition, preventing memory leaks during extended drawing sessions.

Comparison to Industry Implementations

• Procreate Valkyrie: Uses Metal compute shaders for GPU-accelerated texture stamping with real-time grain rotation and dual-texture layering. This Canvas 2D implementation shares core concepts (stamp compositing, rotation, alpha preservation) using CPU rasterization - suitable for web context where GPU access is limited.
• Photoshop ABR: Supports multiple texture layers per brush tip with blend mode stacking and scatter matrices. This implementation only focuses on single-texture workflow with manual layering via opacity buildup - appropriate for educational/demonstration context.
• Krita Texture Brushes: Implements pattern offset and scale randomization for non-repetitive application. This demo includes rotation randomization; pattern offset could be added via random texture sampling coordinates (partial implementation ready in commented code).

Pixel Art Mode Implementation

• Resolution System: Canvas operates at 100×56 native resolution (16:9 aspect ratio) with 8× upscaling to 800×450 display resolution.
• Scaling Algorithm: Nearest-neighbour interpolation (imageSmoothingEnabled = false) preserves hard pixel edges during upscaling operations.
• Grid Overlay: Conditionally rendered when pixelScale ≥ 4 using semi-transparent stroke operations for visual grid alignment.
• Coordinate Transformation: Mouse coordinates mapped to pixel grid via Math.floor(x / pixelScale) for precise pixel targeting.
• Frame Management: All frames stored at native pixel art resolution. Upscaling applied per-frame during rendering pipeline.
• Export Pipeline: Exports at native 100×56 resolution preserving original pixel art without interpolation artifacts.
• Mode Isolation: Mutually exclusive with Timelapse Challenge to prevent conflicting render pipelines.

Animation Framework

• Frame Storage: Array of ImageData objects enabling efficient frame manipulation without canvas redraws.
• Onion Skinning: Composites previous frame at 30% opacity using temporary canvas and drawImage() with globalAlpha modulation.
• Playback System: setInterval-based animation loop at 10 FPS (100ms intervals) with frame cycling via modulo arithmetic.
• GIF Export: Integration with gifshot library for client-side GIF encoding. Converts ImageData to data URLs for processing.
• Frame Interpolation: Smooth slider-based navigation with real-time frame switching and display updates.

Timelapse Challenge System

• Snapshot Capture: Automatic frame capture after each stroke completion, storing as data URLs for memory efficiency.
• Stroke Limitation: 30-stroke constraint enforced through state management and drawing block flags.
• GIF Generation: Sequential snapshot compilation into timelapse animation with 150ms frame duration (3 frameDuration units).
• State Management: Modal drawing restriction preventing further input after stroke limit reached.
• Proof of Work: The timelapse recording serves as cryptographic-style proof of human creative process, providing verifiable evidence of manual creation to distinguish authentic human-generated artwork from AI-synthesized images. Each incremental snapshot forms an immutable chain of artistic decision-making.

Colour Palette System

• Palette Architecture: Object array structure containing name metadata and 20-colour hex arrays for easy extensibility.
• Dynamic Switching: Modulo-based cycling through a number of curated palettes with automatic DOM regeneration and state preservation.
• Eyedropper Tool: Direct pixel sampling via getImageData() with hex conversion for colour picking from canvas content.
• Palettes Included: FARMLAND-20 (Eclipse89), ARTBOUND (Doph), DUNGEON-20 (Meaghan), MIXEDBAG[20] (SoundsDotZip), SOGGY 20 (green guy), ELEMENTAL (Space Sandwich), 20P DX (GrafxKid), MOJAVE20 (magodellepercussioni), GRAY WEATHER (Cactus Celery).

Rendering Optimisations

• Stroke Interpolation: Bresenham-inspired spacing calculations prevent gaps in fast strokes while maintaining performance.
• Click-to-Paint: Immediate drawPixel() invocation on mousedown event ensures single-click responsiveness.
• Cursor Generation: Dynamic canvas-based cursor creation with type-specific shapes.
• Render Button: Scanline-based progressive rendering with requestAnimationFrame for non-blocking full-canvas blur operations with visual feedback.
• Bounds Checking: Consistent boundary validation prevents ImageData access violations during edge cases.
• Context State Management: ctx.save()/restore() pairs ensure clean state isolation for compositing operations.

Quality of Life (QoL) Features

• Undo/Redo System: Full stroke history with Ctrl+Z (undo) and Ctrl+Y/Ctrl+Shift+Z (redo) keyboard shortcuts. Maintains last 20 states with efficient ImageData cloning for memory management. Automatically saves state after strokes, fill operations, clear canvas, and render effects.
• Eyedropper Auto-Revert: Automatically restores the previously selected brush type after color picking, eliminating manual reselection and maintaining workflow continuity.
• Keyboard Shortcuts: Single-letter shortcuts displayed in dropdown for all 8 brush types (r=round, s=square, t=texture, o=oil, d=daub, e=render, p=pixel, f=fill) enabling rapid brush switching without mouse interaction. Number keys 1-9 instantly switch between colour palettes. Bracket keys [ and ] decrease/increase brush size by 2px increments (clamped to 1-50px range) with real-time cursor feedback.
• Click-to-Paint: Single clicks immediately register strokes rather than requiring drag motion, essential for precise dot placement and stippling techniques.
• Dynamic Cursor Visualisation: Real-time cursor updates reflect current brush type and size with custom canvas-rendered shapes (circular, rectangular, square) providing accurate visual feedback before stroke application.
• Onion Skinning: Toggle-based previous frame overlay at 30% opacity enables precise frame-to-frame animation refinement without external reference layers.
• Global Mouse Release Detection: Listens for mouseup events on document rather than canvas only, preventing "stuck drawing" when cursor leaves canvas bounds during stroke - critical for edge-case handling.
• Boundary-Safe Drawing: Automatic coordinate clamping prevents strokes when cursor exits canvas area, avoiding unintended marks and state corruption.
• Auto-Preset Application: Brush-specific defaults automatically applied on selection (Pixel: all parameters optimized for pixel art; Oil: scatter=25 for organic texture) reducing manual slider adjustment.
• Mode Conflict Prevention: Mutual exclusion alerts between Pixel Art mode and Timelapse Challenge prevent incompatible state combinations with clear user messaging.
• Touch Device Support: Full touch event handling with preventDefault() for gesture conflicts enables iPad/tablet usage with identical functionality to desktop mouse control.
• Frame Slider Navigation: Scrub through animation frames via slider with real-time preview and onion skin persistence, avoiding repetitive button clicks for frame review.
• Progressive Render Feedback: Scanline animation during Render button operation provides visual progress indication preventing perceived application freeze during heavy processing.
• One-Click Export: Direct PNG/GIF download without intermediate dialogs or confirmations streamlines asset extraction workflow.
• Palette Hot-Swapping: Single-click palette name cycling with automatic colour grid regeneration and state preservation enables rapid colour scheme exploration.
• Brush Presets (.jbrush): Export and import custom brush configurations as JSON-based .jbrush files containing all 11 parameters (size, opacity, hardness, spacing, flow, scatter, taper, jitter, rotationMode, spinAngle, colour). Enables brush library creation, sharing between artists, and persistent workflow customisation across sessions.
• Stroke Stabilisation: Optional line stabilisation system with adjustable strength (0-100%) that reduces hand tremor and jitter using weighted point averaging. Particularly beneficial for mouse users or drawing on trackpads without graphics tablets. Uses rolling buffer of last 5 points with exponential weighting favouring recent positions. Toggle on/off via button without affecting existing workflow.
• Detachable Colour Palette: Floating palette system with drag-and-drop repositioning. Click pin icon (📌) to detach palette into floating mode, enabling placement anywhere over canvas or surrounding UI. Drag palette by any empty area while floating. Auto-docks when dragged near original position (50px threshold). Maintains state and selections during detach/dock operations.
• Opacity Fine-Tuning Mode: Automatic scale switching for precise low-opacity control. When opacity slider reaches 0.1 (leftmost position), scale automatically changes to 0-0.1 range with 0.01 increments for detailed transparency work. Moving slider back to 0.1 (now rightmost position) reverts to standard 0.1-1.0 scale. Enables precise control for subtle glazing and layering techniques without separate fine adjustment controls.

Technical Architecture Highlights

• Event System: Touch and mouse event normalisation for cross-device compatibility with preventDefault() for gesture handling.
• State Management: Centralised brush state objects with reactive UI synchronisation via event listeners.
• Mode Switching: Automatic brush preset application (pixel art: hardness=1, spacing=0.1; oil: scatter=25).
• Memory Management: ImageData caching for frames with efficient data URL conversion for export operations.
• Colour Space Handling: RGB/hex conversion utilities with proper colour parsing for cross-format compatibility.

Debugging

• Extensive Debugging: Something I take great satisfaction in mastering, as comprehensive debugging methodologies are critical to the reliability, performance, and reputation of any project.
• Onion Skinning: Debugging still in progress for frame-accurate animation visualization.