Kaleidoscope Class Specification & Developer Learning Guide

1. Introduction

The Kaleidoscope class transforms static images into living visual symmetry. It supports GPU and software fallback rendering, double-buffered transitions, and modular state control. This engine is crafted to be ethical, inclusive, performant, and enlightening — serving as both a powerful tool and a teaching aid.

2. Core API & Object Reference

class Kaleidoscope {
  constructor({ canvas, resolution, debug, defaultImage })
}

🔐 Constructor Parameters

• canvas — HTMLCanvasElement to draw to
• resolution — { width, height } object
• debug — enables detailed trace output
• defaultImage — optional fallback image

🧠 Internal Buffers & Data

• imageA imageB — user-supplied original images
• sourceSquareA sourceSquareB — square-resampled inputs
• targetBufferA targetBufferB — rendered symmetrical buffers
• finalOutputA finalOutputB — final display images cropped to screen resolution
• activeBuffer nextBuffer — for double-buffered animation ping-pong

⚙️ Public Properties

• angleA angleB — rotation in degrees for intuitive UI
• alphaA alphaB — crossfade blend weights (0.0–1.0)
• rev — seconds per revolution
• spherize — radial lens distortion amount (applied to both outputs)
• refractionIndex — controls bend factor of spherize
• radius — radius for spherize transformation
• animate — true for continuous updates

🧩 Methods

• loadImage(target, file) — assign an image to A or B
• draw() — render current frame (GPU or software)
• capture(filename) — export high-res screenshot
• fadeTo(nextImage, duration) — crossfade between images
• update(deltaTime) — update rotation + alpha blends
• toggleDebug(state) — enable/disable tracing

3. Rendering Pipeline

1. Load image → imageA / imageB
2. Resize to square → sourceSquareA
3. Mirror & radialize → targetBufferA
4. Spherize both buffers → outputA / outputB
5. Crop final frame → finalOutputA
6. Crossfade with alpha
7. Draw to canvas

4. Angle in Degrees

All public-facing angles are in degrees. Internally, radians are used. You can manipulate:

kaleido.angleA = 45;
kaleido.angleB = 270;
kaleido.rev = 12; // one full turn every 12 seconds

This keeps the API intuitive for artists and educators.

5. Debug Logging

Debug mode traces each function's entry, key state variables, and failures. Debug log can be downloaded or cleared. UI visibility is automatically toggled by debug.

6. Accessibility & Sacred Geometry

Designed for universal creative access. High-end output, low-end compatibility:

• GPU fallback to software-only on old phones
• Sliders optimized for touch
• Frame captures up to 8K regardless of live playback

This is not a proprietary trick — it’s a tool for light-based exploration. Everyone’s welcome here.

7. Learning Philosophy

• Only compute what you show
• Optimize for awe and clarity, not frame rate
• Build transparency into the system
• Use language and variables anyone can grasp

This engine teaches students how geometry, rotation, and pixels converge to make something beautiful. All logic is shared in plain text — as it should be.