textmode.contour.js

textmode.contour.js is an add-on library for textmode.js that registers a cell-space contour conversion mode. It converts image, video, texture, and overlay sources into directional line characters while preserving the usual textmode.js source controls for color, inversion, flips, rotation, and character selection.

Features

• Add a contour conversion mode through the standard textmode.js plugin system
• Map cell-space contour orientation to directional characters
• Preserve characters(), charColorMode(), cellColorMode(), invert(), flipX(), flipY(), and charRotation()
• Support ESM and UMD consumers with the same ContourConversionPlugin export

Installation

Prerequisites

• textmode.js 0.16.0 or newer
• A modern browser with WebGL2 support
• Node.js 20.8.1+ and npm for ESM installation

UMD

<script src="https://cdn.jsdelivr.net/npm/textmode.js@latest/dist/textmode.umd.js"></script>
<script src="https://cdn.jsdelivr.net/npm/textmode.contour.js@latest/dist/textmode.contour.umd.js"></script>

const t = textmode.create({
	width: window.innerWidth,
	height: window.innerHeight,
	fontSize: 8,
	plugins: [ContourConversionPlugin],
});

t.setup(async () => {
	const image = await t.loadImage('photo.jpg');
	image.characters('-/|\\-/|\\');
	image.conversionMode('contour');
	image.charColorMode('fixed');
	image.charColor('#ffffff');
	image.cellColorMode('fixed');
	image.cellColor('#000000');
});

The UMD bundle exposes ContourConversionPlugin globally.

ESM

npm install textmode.js textmode.contour.js

import { textmode } from 'textmode.js';
import { ContourConversionPlugin } from 'textmode.contour.js';

const t = textmode.create({
	width: 800,
	height: 600,
	fontSize: 8,
	plugins: [ContourConversionPlugin],
});

Source API

Use the core conversionMode() API after installing the plugin:

source.characters('-/|\\-/|\\');
source.conversionMode('contour');

Use contour-specific setters when a source needs different detection parameters:

source.contourThreshold(0.12);
source.contourColorSensitivity(0.75);

These setters update per-source shader uniforms and invalidate the source conversion cache. They do not replace characters() or the core conversionMode('contour') call.

The mode uses cell-space marching squares over an adaptive scalar field. Each text cell picks the strongest local luminance, RGB, or alpha transition, extracts a single contour segment from the cell corners, and maps that segment to a directional glyph. This keeps filled-shape boundaries close to one cell thick without a separate thinning pass.

The mode detects color and luminance transitions. Thick stroked source artwork contains two real transitions, one on each side of the stroke, so use filled shapes or thinner source strokes when you want a single object contour.

The default character order is -/|\\-/|\\. It is interpreted as eight edge-tangent bins: horizontal, / diagonal, vertical, \ diagonal, then the opposite four directions. The shader derives this tangent from the adaptive scalar-field normal in screen coordinates before choosing a character.

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.contour.js is licensed under the MIT License.