CanvasImage Widget

The CanvasImage widget loads and displays image files in the console by converting them to colored character blocks.

When to Use

Use CanvasImage when you need to display visual content from image files in your console application. Common scenarios:

• Application branding: Show logos or banners at startup
• Data visualization: Display charts, graphs, or diagrams generated as images
• Preview functionality: Show thumbnails or previews of image files
• Visual feedback: Display icons or status images during operations

For drawing custom graphics programmatically (shapes, lines, patterns), use Canvas instead. For ASCII art from text, use the FigletText widget.

Basic Usage

CanvasImage is not shipped with the default Spectre.Console package. It will need to be installed seperately.

dotnet add package Spectre.Console.ImageSharp

Load an image from a file path. The widget automatically handles color conversion and scaling.

var image = new CanvasImage("path/to/image.png");
AnsiConsole.Write(image);

Loading Images

From File Path

The simplest approach loads an image directly from the filesystem.

var image = new CanvasImage("path/to/image.png");
AnsiConsole.Write(image);

From Byte Array

Use byte arrays when working with images from memory, databases, or network sources.

byte[] imageData = File.ReadAllBytes("path/to/image.png");
var image = new CanvasImage(imageData);
AnsiConsole.Write(image);

From Stream

Use streams for efficient processing of large images or when reading from network resources.

using var stream = File.OpenRead("path/to/image.png");
var image = new CanvasImage(stream);
AnsiConsole.Write(image);

Sizing the Image

Setting Maximum Width

Use MaxWidth() to constrain images to fit within your console layout while maintaining aspect ratio.

var image = new CanvasImage("path/to/image.png")
    .MaxWidth(80);
  
AnsiConsole.Write(image);

Removing Width Constraints

Use NoMaxWidth() to remove size constraints and display the image at full resolution (limited by console dimensions).

var image = new CanvasImage("path/to/image.png")
    .MaxWidth(80)
    .NoMaxWidth(); // Remove constraint
  
AnsiConsole.Write(image);

Resampling Methods

When images are scaled, different resampling algorithms affect quality and performance.

Bicubic Resampling (Default)

Use BicubicResampler() for the highest quality when scaling images. This is the default and works well for most scenarios.

var image = new CanvasImage("path/to/image.png")
    .MaxWidth(60)
    .BicubicResampler();
  
AnsiConsole.Write(image);

Bilinear Resampling

Use BilinearResampler() for a balance between quality and performance when rendering many images.

var image = new CanvasImage("path/to/image.png")
    .MaxWidth(60)
    .BilinearResampler();
  
AnsiConsole.Write(image);

Nearest Neighbor Resampling

Use NearestNeighborResampler() for the fastest scaling, which creates a pixelated effect. Good for retro aesthetics or pixel art.

var image = new CanvasImage("path/to/image.png")
    .MaxWidth(60)
    .NearestNeighborResampler();
  
AnsiConsole.Write(image);

Comparing Resampling Methods

Compare the visual differences between resampling methods to choose the right one for your needs.

AnsiConsole.MarkupLine("[yellow]Bicubic (highest quality):[/]");
var bicubic = new CanvasImage("path/to/image.png")
    .MaxWidth(40)
    .BicubicResampler();
AnsiConsole.Write(bicubic);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]Bilinear (balanced):[/]");
var bilinear = new CanvasImage("path/to/image.png")
    .MaxWidth(40)
    .BilinearResampler();
AnsiConsole.Write(bilinear);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]Nearest neighbor (fastest):[/]");
var nearestNeighbor = new CanvasImage("path/to/image.png")
    .MaxWidth(40)
    .NearestNeighborResampler();
AnsiConsole.Write(nearestNeighbor);

Advanced Image Processing

Basic Mutations

Use Mutate() to apply ImageSharp transformations like rotation, flipping, or cropping before rendering.

var image = new CanvasImage("path/to/image.png")
    .MaxWidth(60)
    .Mutate(ctx => ctx.Rotate(90));
  
AnsiConsole.Write(image);

Combining Multiple Transformations

Chain multiple mutations together for complex image processing effects.

var image = new CanvasImage("path/to/image.png")
    .MaxWidth(80)
    .Mutate(ctx => ctx
        .Rotate(45)
        .Flip(FlipMode.Horizontal));
  
AnsiConsole.Write(image);

Complete Configuration

Combine sizing, resampling, and mutations for complete control over image appearance.

var image = new CanvasImage("path/to/image.png")
    .MaxWidth(80)
    .BicubicResampler()
    .Mutate(ctx => ctx.Crop(new Rectangle(10, 10, 200, 200)));
  
AnsiConsole.Write(image);

See Also

• Canvas Widget - Draw custom graphics programmatically
• FigletText Widget - ASCII art text banners

API Reference

public CanvasImage(string filename)

public CanvasImage(ReadOnlySpan<byte> data)

public CanvasImage(Stream data)