README.nuget.md

mostlylucid.consoleimage.spectre

Spectre.Console integration for ConsoleImage - display ASCII art within Spectre layouts.

Full documentation on GitHub

Render Modes

ASCII	ColorBlocks	Braille	Matrix

Features

• IRenderable implementations for all render modes
• Animated GIF support with Spectre's Live display
• Matrix digital rain effect with animations
• Composable with Spectre panels, tables, and layouts

Quick Start

using ConsoleImage.Spectre;
using Spectre.Console;

// Static images
AnsiConsole.Write(new AsciiImage("photo.jpg"));
AnsiConsole.Write(new ColorBlockImage("photo.jpg"));
AnsiConsole.Write(new BrailleImage("photo.jpg"));
AnsiConsole.Write(new MatrixImage("photo.jpg"));

Renderable Classes

AsciiImage

Shape-matched ASCII characters with optional color.

using ConsoleImage.Core;
using ConsoleImage.Spectre;

var options = new RenderOptions { MaxWidth = 80, UseColor = true };
var image = new AsciiImage("photo.jpg", options);
AnsiConsole.Write(image);

// Or from pre-rendered frame
using var renderer = new AsciiRenderer(options);
var frame = renderer.RenderFile("photo.jpg");
AnsiConsole.Write(new AsciiImage(frame));

ColorBlockImage

Unicode half-blocks for 2x vertical resolution.

var image = new ColorBlockImage("photo.jpg", new RenderOptions { MaxWidth = 80 });
AnsiConsole.Write(image);

BrailleImage

2x4 dot patterns for highest resolution.

var image = new BrailleImage("photo.jpg", new RenderOptions { MaxWidth = 80 });
AnsiConsole.Write(image);

MatrixImage

Digital rain effect overlay.

var matrixOpts = new MatrixOptions
{
    BaseColor = new Rgba32(0, 255, 0, 255),  // Classic green
    Density = 0.5f
};
var image = new MatrixImage("photo.jpg", matrixOptions: matrixOpts);
AnsiConsole.Write(image);

Animated GIFs

AnimatedImage

Plays GIFs with Spectre's Live display.

using ConsoleImage.Spectre;

// Play animated GIF (any mode)
var animation = new AnimatedImage("cat.gif", AnimationMode.Braille);
await animation.PlayAsync(cancellationToken);

// With loop control
await animation.PlayAsync(loopCount: 3);

// Manual frame control
await AnsiConsole.Live(animation)
    .StartAsync(async ctx =>
    {
        while (!token.IsCancellationRequested)
        {
            animation.TryAdvanceFrame();
            ctx.Refresh();
            await Task.Delay(16);
        }
    });

AnimatedMatrixImage

Continuous Matrix rain animation.

var animation = new AnimatedMatrixImage("photo.jpg", frameCount: 200);
await animation.PlayAsync(cancellationToken);

Animation Modes

public enum AnimationMode
{
    Ascii,       // Shape-matched characters
    ColorBlock,  // Unicode half-blocks
    Braille,     // 2x4 dot patterns
    Matrix       // Digital rain effect
}

Composing with Spectre Layouts

// In a panel
var panel = new Panel(new AsciiImage("photo.jpg"))
{
    Header = new PanelHeader("My Image"),
    Border = BoxBorder.Rounded
};
AnsiConsole.Write(panel);

// In a table
var table = new Table();
table.AddColumn("ASCII");
table.AddColumn("Blocks");
table.AddRow(
    new AsciiImage("photo.jpg", new RenderOptions { MaxWidth = 40 }),
    new ColorBlockImage("photo.jpg", new RenderOptions { MaxWidth = 40 })
);
AnsiConsole.Write(table);

// In columns
AnsiConsole.Write(new Columns(
    new AsciiImage("a.jpg"),
    new BrailleImage("b.jpg")
));

RenderOptions

var options = new RenderOptions
{
    MaxWidth = 80,           // Maximum width
    MaxHeight = 40,          // Maximum height
    UseColor = true,         // Enable ANSI colors
    CharacterAspectRatio = 0.5f,  // Terminal char width/height
    ContrastPower = 2.5f,    // Contrast enhancement
    Gamma = 0.65f            // Gamma correction
};

Related Packages

• mostlylucid.consoleimage - Core rendering (dependency)
• mostlylucid.consoleimage.video - Video playback

License

Public domain - UNLICENSE