Spectre.Console Documentation - 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

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

public static void BasicCanvasImageExample()
{
    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.

public static void BasicCanvasImageExample()
{
    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.

public static void CanvasImageFromBytesExample()
{
    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.

public static void CanvasImageFromStreamExample()
{
    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.

public static void CanvasImageMaxWidthExample()
{
    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).

public static void CanvasImageNoMaxWidthExample()
{
    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.

public static void CanvasImagePixelWidthExample()
{
    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.

public static void CanvasImageBicubicResamplerExample()
{
    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.

public static void CanvasImageBilinearResamplerExample()
{
    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.

public static void CanvasImageNearestNeighborResamplerExample()
{
    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.

public static void CanvasImageResamplerComparisonExample()
{
    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.

public static void CanvasImageMutateExample()
{
    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.

public static void CanvasImageAdvancedMutateExample()
{
    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.

public static void CanvasImageCompleteExample()
{
    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);
}

API Reference

Type 'Spectre.Console.CanvasImage' not found in Spectre.Console assembly