Spectre.Console

CanvasImage Widget

Display image files in the console using pixel-based rendering

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

Important

SixLabors.ImageSharp, a library which Spectre.Console relies upon, is licensed under Apache 2.0 when distributed as part of Spectre.Console. The Six Labors Split License covers all other usage.

Screenshot

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);

Adjusting Pixel Width

Use PixelWidth() to control the character-to-pixel ratio. Lower values create taller, narrower images; higher values create shorter, wider ones.

AnsiConsole.MarkupLine("[yellow]Pixel width 1 (narrow):[/]");
var narrow = new CanvasImage("path/to/image.png")
    .PixelWidth(1);
AnsiConsole.Write(narrow);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]Pixel width 2 (default):[/]");
var normal = new CanvasImage("path/to/image.png")
    .PixelWidth(2);
AnsiConsole.Write(normal);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]Pixel width 4 (wide):[/]");
var wide = new CanvasImage("path/to/image.png")
    .PixelWidth(4);
AnsiConsole.Write(wide);

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)
    .PixelWidth(2)
    .BicubicResampler()
    .Mutate(ctx => ctx.Crop(new Rectangle(10, 10, 200, 200)));
  
AnsiConsole.Write(image);

See Also

API Reference

Represents a renderable image.

Constructors

CanvasImage(string filename)

Initializes a new instance of the class.

Parameters:

filename (string)
The image filename.
CanvasImage(ReadOnlySpan<byte> data)

Initializes a new instance of the class.

Parameters:

data (ReadOnlySpan<byte>)
Buffer containing an image.
CanvasImage(Stream data)

Initializes a new instance of the class.

Parameters:

data (Stream)
Stream containing an image.

Properties

Height : int

Gets the image height.

MaxWidth : Nullable<int>

Gets or sets the render width of the canvas.

PixelWidth : int

Gets or sets the render width of the canvas.

Resampler : IResampler

Gets or sets the that should be used when scaling the image. Defaults to bicubic sampling.

Width : int

Gets the image width.

Extension Methods

CanvasImage BicubicResampler()

Uses a bicubic sampler that implements the bicubic kernel algorithm W(x).

Returns:

The same instance so that multiple calls can be chained.

CanvasImage BilinearResampler()

Uses a bilinear sampler. This interpolation algorithm can be used where perfect image transformation with pixel matching is impossible, so that one can calculate and assign appropriate intensity values to pixels.

Returns:

The same instance so that multiple calls can be chained.

IEnumerable<Segment> GetSegments(IAnsiConsole console)

Gets the segments for a renderable using the specified console.

Parameters:

console (IAnsiConsole)
The console.

Returns:

An enumerable containing segments representing the specified .

CanvasImage MaxWidth(Nullable<int> maxWidth)

Sets the maximum width of the rendered image.

Parameters:

maxWidth (Nullable<int>)
The maximum width.

Returns:

The same instance so that multiple calls can be chained.

CanvasImage Mutate(Action<IImageProcessingContext> action)

Mutates the underlying image.

Parameters:

action (Action<IImageProcessingContext>)
The action that mutates the underlying image.

Returns:

The same instance so that multiple calls can be chained.

CanvasImage NearestNeighborResampler()

Uses a Nearest-Neighbour sampler that implements the nearest neighbor algorithm. This uses a very fast, unscaled filter which will select the closest pixel to the new pixels position.

Returns:

The same instance so that multiple calls can be chained.

CanvasImage NoMaxWidth()

Disables the maximum width of the rendered image.

Returns:

The same instance so that multiple calls can be chained.

CanvasImage PixelWidth(int width)

Sets the pixel width.

Parameters:

width (int)
The pixel width.

Returns:

The same instance so that multiple calls can be chained.