textmode.accurate.js
v1.0.1
Published
Accurate media conversion plugin for textmode.js
Maintainers
humanbydefinitionReadme
textmode.accurate.js
textmode.accurate.js is an add-on library for textmode.js that restores an accurate, multi-sample glyph matching conversion mode. It registers a new accurate conversion strategy next to the built-in brightness mode, making image, video, and texture sources choose glyphs from sampled cell shape instead of average brightness alone.
[!WARNING]
Theaccurateconversion mode is more computationally expensive than the defaultbrightnessmode. It may not be suitable for all use cases, especially on lower-end devices.
Features
- Add an
accurateconversion mode through the standardtextmode.jsplugin system - Match glyph silhouettes against a sampled source-cell mask for higher fidelity conversion
- Preserve sampled foreground and background color behavior from the core conversion pipeline
- Support ESM and UMD consumers with the same
AccurateConversionPluginexport - Integrate with existing
TextmodeSource.conversionMode()calls
Installation
Prerequisites
To get started with textmode.accurate.js, you'll need:
textmode.js0.13.0or newer- A modern browser with WebGL2 support
- Node.js
20.8.1+andnpmfor ESM installation
UMD
To use textmode.accurate.js in a browser without a bundler, load the UMD builds for both textmode.js and this add-on. textmode.js must be loaded first so the accurate conversion add-on can attach to the expected global runtime.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>textmode.accurate.js sketch</title>
<script src="https://cdn.jsdelivr.net/npm/textmode.js@latest/dist/textmode.umd.js"></script>
<script src="https://cdn.jsdelivr.net/npm/textmode.accurate.js@latest/dist/textmode.accurate.umd.js"></script>
</head>
<body>
<script src="./sketch.js"></script>
</body>
</html>const t = textmode.create({
width: window.innerWidth,
height: window.innerHeight,
fontSize: 8,
plugins: [AccurateConversionPlugin],
});
t.setup(async () => {
const image = await t.loadImage('photo.jpg');
image.conversionMode('accurate');
});The UMD bundle exposes AccurateConversionPlugin globally.
ESM
Install the core library and the accurate conversion add-on together:
npm install textmode.js textmode.accurate.jsThen import both packages in your sketch or application code:
import { textmode } from 'textmode.js';
import { AccurateConversionPlugin } from 'textmode.accurate.js';Plugin setup
import { textmode } from 'textmode.js';
import { AccurateConversionPlugin } from 'textmode.accurate.js';
const t = textmode.create({
width: 800,
height: 600,
fontSize: 8,
plugins: [AccurateConversionPlugin],
});The plugin registers the accurate conversion strategy during setup and unregisters it again if the plugin is uninstalled.
Accurate conversion mode
Use conversionMode('accurate') on any compatible source after the plugin is installed:
t.setup(async () => {
const video = await t.loadVideo('clip.mp4');
video.play();
video.loop();
video.conversionMode('accurate');
video.charColorMode('sampled');
video.cellColorMode('sampled');
});
t.draw(() => {
t.background(0);
t.image(video);
});The built-in brightness mode chooses glyphs from average luminance. The accurate mode samples each cell in a grid, compares candidate glyph masks against the source-cell shape, and keeps the closest glyph match.
Documentation
- textmode.js documentation for ecosystem guides and API reference
- Local API reference after running
npm run build:docs - Examples for ESM and UMD setup
License
textmode.accurate.js is licensed under the MIT License.