ASCII Art Generator Developer Reference

• tool/ascii/index.html: page shell, metadata, structured data, cursor layer, loader, tabs, input controls, output containers, charts, action buttons, fullscreen overlays, related tools, and script order.
• js/tool/ascii/ascii_art.js: core ASCIIArtGenerator, SummedAreaTable, ASCIIFilterChain, density calibration, raster conversion, render adapters, download helpers, and benchmark helper.
• js/tool/ascii/ascii-engine.js: active research controller used by the page: state, option collection, mode switching, render orchestration, charts, research actions, export buttons, webcam management, dropdown glue, fullscreen handling, and initialization.
• js/tool/ascii/ascii.js: earlier controller implementation with similar binding, export, fullscreen, and benchmark responsibilities. It is not the final script loaded by the current page, but it remains useful reference material.
• js/ascii/index.js: console ASCII loader that fetches and logs /images/brand/ascii.txt.
• js/ascii/core/fetch-ascii.js: safe text fetch helper for console ASCII assets.
• js/ascii/core/ascii-logger.js: chunked console output and ASCII header logging.

ASCIIArtGenerator is a zero-dependency class that works in browsers and can be used in Node-like environments when image data is pre-rasterized. It owns the actual conversion from pixels to characters.

• constructor(options): merges caller options with defaults and prepares canvas, performance stats, character set library, density cache, Floyd-Steinberg buffers, and deterministic RNG state.
• setSeed(seed): resets deterministic xorshift32 state.
• generate(imageData, width, height, options): synchronous conversion path for pre-extracted ImageData. Returns text, HTML element, canvas element, or SVG string based on renderMode.
• imageToASCII(image, options): async path for URL strings, image elements, canvases, offscreen canvases, and ImageData sources.
• warmDensityCache(sets): precomputes density maps for selected character sets.
• getPerformanceStats(): returns last render time, average render time, and render count.
• runBenchmark(...): helper used to measure repeated render performance.

ascii-engine.js collects UI state in getOptions(), then mirrors those values into generator.defaults and generator.options. This keeps live settings and future generator creations aligned.

• Mapping: charSet, inverted, brightnessAlgorithm, and colorMode.
• Geometry: width, optional fixed height, and aspectRatio.
• Sampling: sampler values are area, bilinear, or point.
• Dithering: none, floyd-steinberg, or ordered with bayer4 or bayer8.
• Edge guidance: edgeAware and edgeStrength.
• Tone: contrast, saturation, and gamma pre-processing.
• Output: renderMode, filters, compression level, font options, background color, text color, temporal dithering, seed, and noise intensity.

1. Collect UI state: read controls, custom charset, filters, color values, and render mode.
2. Prepare source: image mode draws the loaded image to a canvas; text mode rasterizes the entered text; webcam mode draws the current video frame.
3. Extract ImageData: the source canvas becomes pixel data for ASCIIArtGenerator.generate().
4. Pre-process: optional contrast, saturation, gamma, and background-aware alpha composition are applied.
5. Sample: the engine uses point, bilinear, or area sampling. Area sampling uses a summed-area-table approach for downscaled cells.
6. Map brightness: sampled luminance maps to density-calibrated glyphs.
7. Dither: Floyd-Steinberg diffuses quantization error; ordered mode uses Bayer thresholds.
8. Steer edges: Sobel magnitude and direction can choose directional glyphs for strong edges without violating target density.
9. Post-process: filters and lossy glyph thinning run after ASCII text creation.
10. Render adapter: text, HTML, canvas, or SVG output is returned and stored in lastASCIIText, lastASCIIHTML, lastASCIICanvas, or lastASCIISVG.

The active controller is an IIFE in ascii-engine.js. It resolves elements by ID, preserves module-private state, and binds every tab, control, chart, export, and webcam action during init().

• Tabs: buttons with data-asc-tab switch Lab, Actions, Standards, Formulas, References, and Research panels.
• Mode buttons: Image, Text, and Webcam update currentMode and toggle the matching input panel.
• Sliders and dropdowns: update labels, refresh generator options, and trigger debounced rendering when Live mode is enabled.
• Status surfaces: showStatus, showError, toast, metrics labels, and performance badges communicate state.
• Fullscreen overlays: output fullscreen and chart fullscreen are separate overlays with close buttons and copied canvas content.
• Memory cleanup: object URLs and webcam tracks are released when inputs are cleared or modes change.

• Density calibration: measures glyph ink coverage using canvas and stores sorted density records for charting and JSON export.
• Histogram: summarizes output tonal distribution.
• Character frequency: counts glyph usage and renders bar/donut views.
• Sobel preview: draws source view and edge magnitude preview for any mode.
• Sampling comparison: visualizes how sampling choices affect output.
• Performance timeline: stores recent render history and plots render time over control changes.
• Batch rendering: renders each input line with current settings and reports timing, rows, and character count.
• Charset comparison: measures count, min density, max density, range, and monotonicity across built-in character sets.

Export functions use the latest stored output values. Always render at least once before exporting. Downloads are created through browser Blob URLs and temporary anchor clicks.

• exportTXT: writes lastASCIIText as text/plain.
• exportPNG: exports visible canvas directly, rasterizes HTML, rasterizes SVG, or creates a canvas from text fallback.
• exportSVG: prefers generator SVG, wraps colored HTML in SVG foreignObject, or builds a text-based SVG.
• exportHTML: writes a self-contained HTML document from the HTML output or escaped text fallback.
• exportJSON: writes output text, options, metrics, density calibration, and render history.
• exportCSV: writes character frequency rows for the latest text output.
• exportAll: runs multiple export functions on staggered timers to avoid overlapping downloads.

• startWebcam: calls navigator.mediaDevices.getUserMedia, attaches the stream to the video element, enables capture controls, and reports permission errors.
• renderWebcamFrame: draws the current video frame to canvas and converts it through the same ImageData path as images.
• Live mode: runs repeated renders on a timer with a 150 ms live debounce to preserve responsiveness.
• stopWebcam: stops tracks, clears timers, disables capture controls, and releases the stream reference.
• Security note: camera permission is controlled by the browser. Production use should be served over HTTPS or localhost for MediaDevices access.

• Add a character set: add it to CHARSETS in ascii-engine.js, add a dropdown item in the page, and ensure density calibration remains monotonic enough for useful mapping.
• Add a filter: extend ASCIIFilterChain.applyFilters, add a checkbox with class ascii-filter-check, and document how it transforms rows.
• Add a render mode: update ASCIIArtGenerator.generate, preserve a lastASCII... state variable, add an output container, and add export behavior.
• Add analytics: create a chart canvas, render function, fullscreen label, and hook into updateGraphs().
• Add an export: keep it browser-only, use Blob URLs, and include a fallback when the current render mode is not native to the target format.
• Add an input mode: rasterize the input to canvas first, then reuse the ImageData conversion path.

• Keep the 20 MB file limit unless the memory model is redesigned.
• Keep large image downscale/warning behavior to avoid canvas memory failures.
• Revoke object URLs after replacing or clearing source images.
• Stop webcam tracks when leaving webcam mode or unloading the page.
• Use debounced rendering for sliders, dropdowns, and live webcam frames.
• Do not store raw image files in local storage; the current design keeps processing local and transient.
• Prefer area sampling for quality, but keep point and bilinear available for comparison and speed.
• Be careful with color HTML output because it can create large DOM trees.

• Open /tool/ascii/ and confirm the Lab tab renders with controls and placeholder output.
• Render text input with Text, HTML, Canvas, and SVG render modes.
• Upload a small PNG and test Standard, Detailed, Blocks, Lines, and Braille character sets.
• Toggle Floyd-Steinberg, ordered Bayer 4x4, ordered Bayer 8x8, and no dithering.
• Toggle edge-aware mode and verify the Sobel preview chart updates.
• Test copy, TXT, PNG, SVG, HTML, JSON, CSV, and Export All after a render.
• Open output fullscreen and chart fullscreen, then close both by button and keyboard flow.
• Run charset comparison, benchmark, and batch rendering in the Actions/Research tabs.
• Start webcam on HTTPS or localhost, capture a frame, enable Live, then stop the stream.
• Run project validation after doc or script changes.