mostlylucid.consoleimage 1.0.0

mostlylucid.consoleimage

High-quality ASCII art renderer for .NET 10 using shape-matching algorithm.

Based on Alex Harri's excellent article on ASCII rendering techniques.

Features

• Shape-matching algorithm: Characters selected by visual shape similarity, not just brightness
• 3×2 staggered sampling grid: 6 sampling circles arranged per Alex Harri's article for accurate shape matching
• K-D tree optimization: Fast nearest-neighbor search in 6D vector space
• Contrast enhancement: Global power function + directional contrast with 10 external sampling circles
• Animated GIF support: Smooth playback with diff rendering (only updates changed pixels)
• Color modes:
  • ANSI colored ASCII characters
  • High-fidelity color blocks using Unicode half-blocks (▀▄)
• Auto background detection: Automatically detects dark/light backgrounds
• Floyd-Steinberg dithering: Error diffusion for smoother gradient rendering
• Edge-direction characters: Uses directional chars (/ \ | -) based on detected edges
• AOT compatible: Works with Native AOT compilation
• Cross-platform: Windows, Linux, macOS (x64 and ARM64)

Installation

NuGet Package (Library)

dotnet add package mostlylucid.consoleimage

CLI Tool (Standalone Binaries)

Download from GitHub Releases:

Quick Start

using ConsoleImage.Core;

// One line - just works with sensible defaults!
// (color ON, invert ON for dark terminals, auto background detection)
Console.WriteLine(AsciiArt.Render("photo.jpg"));

CLI Usage

# Basic - color and animation ON by default
ascii-image photo.jpg

# Specify width
ascii-image photo.jpg -w 80

# Disable color (monochrome)
ascii-image photo.jpg --no-color

# High-fidelity color blocks (requires 24-bit color terminal)
ascii-image photo.jpg --blocks

# Play animated GIF (animates by default)
ascii-image animation.gif

# Don't animate, just show first frame
ascii-image animation.gif --no-animate

# Control animation loops (0 = infinite, default)
ascii-image animation.gif --loop 3

# Speed up animation
ascii-image animation.gif --speed 2.0

# For light terminal backgrounds
ascii-image photo.jpg --no-invert

# Edge detection for enhanced foreground
ascii-image photo.jpg --edge

# Manual background suppression
ascii-image photo.jpg --bg-threshold 0.85      # Suppress light backgrounds
ascii-image photo.jpg --dark-bg-threshold 0.15 # Suppress dark backgrounds

# Save to file
ascii-image photo.jpg -o output.txt

# Disable dithering (ON by default for smoother gradients)
ascii-image photo.jpg --no-dither

# Disable edge-direction characters (ON by default)
ascii-image photo.jpg --no-edge-chars

# Custom aspect ratio (default: 0.5, meaning chars are 2x taller than wide)
ascii-image photo.jpg --aspect-ratio 0.6

CLI Options

Library API

Simple API

using ConsoleImage.Core;

// Basic - just works
Console.WriteLine(AsciiArt.Render("photo.jpg"));

// With width
Console.WriteLine(AsciiArt.Render("photo.jpg", 80));

// Colored output
Console.WriteLine(AsciiArt.RenderColored("photo.jpg"));

// For light terminal backgrounds
Console.WriteLine(AsciiArt.RenderForLightBackground("photo.jpg"));

// Play animated GIF
await AsciiArt.PlayGif("animation.gif");

Full Options API

using ConsoleImage.Core;

// Use presets
var options = RenderOptions.Default;           // Sensible defaults
var options = RenderOptions.HighDetail;        // Maximum detail
var options = RenderOptions.Monochrome;        // No color
var options = RenderOptions.ForLightBackground; // For light terminals
var options = RenderOptions.ForDarkBackground; // Enhanced for dark images
var options = RenderOptions.ForAnimation(loopCount: 3);

// Or customize everything
var options = new RenderOptions
{
    MaxWidth = 100,
    MaxHeight = 50,
    UseColor = true,
    Invert = true,                    // Dark terminals (default)
    ContrastPower = 3.0f,
    DirectionalContrastStrength = 0.3f,
    CharacterSetPreset = "extended",
    AutoBackgroundSuppression = true,
    UseParallelProcessing = true
};

using var renderer = new AsciiRenderer(options);
var frame = renderer.RenderFile("photo.jpg");
Console.WriteLine(frame.ToAnsiString()); // Colored
Console.WriteLine(frame.ToString());      // Plain

High-Fidelity Color Blocks

using ConsoleImage.Core;

// Enable ANSI support on Windows (call once at startup)
ConsoleHelper.EnableAnsiSupport();

// Uses Unicode half-blocks (▀▄) for 2x vertical resolution
using var renderer = new ColorBlockRenderer(options);
string output = renderer.RenderFile("photo.jpg");
Console.WriteLine(output);

// For animated GIFs
var frames = renderer.RenderGif("animation.gif");
foreach (var frame in frames)
{
    Console.WriteLine(frame.Content);
    Thread.Sleep(frame.DelayMs);
}

ANSI Support on Windows

For colored output and animations to work correctly on Windows, you may need to enable virtual terminal processing:

using ConsoleImage.Core;

// Call once at application startup
ConsoleHelper.EnableAnsiSupport();

// Now ANSI colors and cursor control will work
Console.WriteLine(AsciiArt.RenderColored("photo.jpg"));

Modern terminals like Windows Terminal have this enabled by default, but older consoles (cmd.exe, older PowerShell) may need this call.

Spectre.Console Integration

The library output is compatible with Spectre.Console. You can embed ASCII art in Spectre panels:

using Spectre.Console;
using ConsoleImage.Core;

var ascii = AsciiArt.Render("photo.jpg", 60);
var panel = new Panel(new Markup(ascii))
{
    Header = new PanelHeader("My Image"),
    Border = BoxBorder.Rounded
};
AnsiConsole.Write(panel);

For colored output with Spectre.Console, use the raw ANSI string:

// Spectre.Console handles ANSI escape codes automatically
AnsiConsole.Write(new Text(AsciiArt.RenderColored("photo.jpg")));

Animated GIFs

using ConsoleImage.Core;

// Simple playback (infinite loop by default)
await AsciiArt.PlayGif("animation.gif");

// With options
var options = new RenderOptions
{
    LoopCount = 3,
    AnimationSpeedMultiplier = 1.5f,
    UseColor = true
};
await AsciiArt.PlayGif("animation.gif", options);

// Manual frame control
using var renderer = new AsciiRenderer(options);
var frames = renderer.RenderGif("animation.gif");

using var player = new AsciiAnimationPlayer(frames, useColor: true, loopCount: 0);
await player.PlayAsync(cancellationToken);

Configuration from appsettings.json

{
  "AsciiRenderer": {
    "MaxWidth": 120,
    "MaxHeight": 60,
    "ContrastPower": 2.5,
    "DirectionalContrastStrength": 0.3,
    "UseColor": true,
    "Invert": true,
    "AutoBackgroundSuppression": true,
    "CharacterSetPreset": "default"
  }
}

var config = builder.Configuration.GetSection("AsciiRenderer").Get<RenderOptions>();
Console.WriteLine(AsciiArt.FromFile("photo.jpg", config));

Character Set Presets

How It Works

This library implements Alex Harri's shape-matching approach:

1. Character Analysis

Each ASCII character is rendered and analyzed using 6 sampling circles in a 3×2 staggered grid:

[0]  [1]  [2]   ← Top row (staggered vertically)
[3]  [4]  [5]   ← Bottom row

Left circles are lowered, right circles are raised to minimize gaps while avoiding overlap. Each circle samples "ink coverage" to create a 6D shape vector.

2. Normalization

All character vectors are normalized by dividing by the maximum component value across ALL characters, ensuring comparable magnitudes.

3. Image Sampling

Input images are sampled the same way, creating shape vectors for each output cell.

4. Contrast Enhancement

Global contrast (power function):

value = (value / max)^power × max

This "crunches" lower values toward zero while preserving lighter areas.

Directional contrast (10 external circles): External sampling circles reach outside each cell. For each internal component:

maxValue = max(internal, external)
result = applyContrast(maxValue)

This enhances edges where content meets empty space.

5. K-D Tree Matching

Fast nearest-neighbor search in 6D space finds the character whose shape vector best matches each image cell. Results are cached for repeated lookups.

6. Animation Optimization

For GIFs, frame differencing computes only changed pixels between frames, using ANSI cursor positioning to update efficiently.

Performance

• SIMD optimized: Uses Vector128/Vector256 for distance calculations
• Parallel processing: Multi-threaded rendering for large images
• Caching: Quantized vector lookups cached with 5-bit precision

Animation Smoothness

Multiple techniques ensure flicker-free animation:

• DECSET 2026 Synchronized Output: Batches frame output for atomic rendering (supported by Windows Terminal, WezTerm, Ghostty, Alacritty, iTerm2)
• Diff rendering: Only updates changed pixels between frames using ANSI cursor positioning
• Cursor hiding: \x1b[?25l hides cursor during playback
• Cursor save/restore: \x1b[s / \x1b[u for consistent frame positioning
• Pre-buffering: All frames converted to strings before playback
• Immediate flush: Console.Out.Flush() after each frame

Building from Source

git clone https://github.com/scottgal/ConsoleImage.git
cd ConsoleImage
dotnet build
dotnet run --project ConsoleImage -- path/to/image.jpg

Publishing AOT Binary

dotnet publish ConsoleImage/ConsoleImage.csproj \
  -c Release \
  -r win-x64 \
  --self-contained true \
  -p:PublishAot=true

Credits

• Algorithm: Alex Harri's ASCII Rendering article
• Image processing: SixLabors.ImageSharp

License

This is free and unencumbered software released into the public domain. See UNLICENSE for details.