Add canvas and image support

Adds support for drawing "pixels" and displaying
images in the terminal.

src/Spectre.Console.ImageSharp/CanvasImage.cs

@@ -0,0 +1,125 @@
+using System;
+using System.Collections.Generic;
+using SixLabors.ImageSharp.PixelFormats;
+using SixLabors.ImageSharp.Processing;
+using SixLabors.ImageSharp.Processing.Processors.Transforms;
+using Spectre.Console.Rendering;
+
+namespace Spectre.Console
+{
+    /// <summary>
+    /// Represents a renderable image.
+    /// </summary>
+    public sealed class CanvasImage : Renderable
+    {
+        private static readonly IResampler _defaultResampler = KnownResamplers.Bicubic;
+
+        /// <summary>
+        /// Gets the image width.
+        /// </summary>
+        public int Width => Image.Width;
+
+        /// <summary>
+        /// Gets the image height.
+        /// </summary>
+        public int Height => Image.Height;
+
+        /// <summary>
+        /// Gets or sets the render width of the canvas.
+        /// </summary>
+        public int? MaxWidth { get; set; }
+
+        /// <summary>
+        /// Gets or sets the render width of the canvas.
+        /// </summary>
+        public int PixelWidth { get; set; } = 2;
+
+        /// <summary>
+        /// Gets or sets the <see cref="IResampler"/> that should
+        /// be used when scaling the image. Defaults to bicubic sampling.
+        /// </summary>
+        public IResampler? Resampler { get; set; }
+
+        internal SixLabors.ImageSharp.Image<Rgba32> Image { get; }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CanvasImage"/> class.
+        /// </summary>
+        /// <param name="filename">The image filename.</param>
+        public CanvasImage(string filename)
+        {
+            Image = SixLabors.ImageSharp.Image.Load<Rgba32>(filename);
+        }
+
+        /// <inheritdoc/>
+        protected override Measurement Measure(RenderContext context, int maxWidth)
+        {
+            if (PixelWidth < 0)
+            {
+                throw new InvalidOperationException("Pixel width must be greater than zero.");
+            }
+
+            var width = MaxWidth ?? Width;
+            if (maxWidth < width * PixelWidth)
+            {
+                return new Measurement(maxWidth, maxWidth);
+            }
+
+            return new Measurement(width * PixelWidth, width * PixelWidth);
+        }
+
+        /// <inheritdoc/>
+        protected override IEnumerable<Segment> Render(RenderContext context, int maxWidth)
+        {
+            var image = Image;
+
+            var width = Width;
+            var height = Height;
+
+            // Got a max width?
+            if (MaxWidth != null)
+            {
+                height = (int)(height * ((float)MaxWidth.Value) / Width);
+                width = MaxWidth.Value;
+            }
+
+            // Exceed the max width when we take pixel width into account?
+            if (width * PixelWidth > maxWidth)
+            {
+                height = (int)(height * (maxWidth / (float)(width * PixelWidth)));
+                width = maxWidth / PixelWidth;
+            }
+
+            // Need to rescale the pixel buffer?
+            if (width != Width || height != Height)
+            {
+                var resampler = Resampler ?? _defaultResampler;
+                image = image.Clone(); // Clone the original image
+                image.Mutate(i => i.Resize(width, height, resampler));
+            }
+
+            var canvas = new Canvas(width, height)
+            {
+                MaxWidth = MaxWidth,
+                PixelWidth = PixelWidth,
+                Scale = false,
+            };
+
+            for (var y = 0; y < image.Height; y++)
+            {
+                for (var x = 0; x < image.Width; x++)
+                {
+                    if (image[x, y].A == 0)
+                    {
+                        continue;
+                    }
+
+                    canvas.SetPixel(x, y, new Color(
+                        image[x, y].R, image[x, y].G, image[x, y].B));
+                }
+            }
+
+            return ((IRenderable)canvas).Render(context, maxWidth);
+        }
+    }
+}

src/Spectre.Console.ImageSharp/CanvasImageExtensions.cs

@@ -0,0 +1,135 @@
+using System;
+using SixLabors.ImageSharp.Processing;
+
+namespace Spectre.Console
+{
+    /// <summary>
+    /// Contains extension methods for <see cref="CanvasImage"/>.
+    /// </summary>
+    public static class CanvasImageExtensions
+    {
+        /// <summary>
+        /// Sets the maximum width of the rendered image.
+        /// </summary>
+        /// <param name="image">The canvas image.</param>
+        /// <param name="maxWidth">The maximum width.</param>
+        /// <returns>The same instance so that multiple calls can be chained.</returns>
+        public static CanvasImage MaxWidth(this CanvasImage image, int? maxWidth)
+        {
+            if (image is null)
+            {
+                throw new ArgumentNullException(nameof(image));
+            }
+
+            image.MaxWidth = maxWidth;
+            return image;
+        }
+
+        /// <summary>
+        /// Disables the maximum width of the rendered image.
+        /// </summary>
+        /// <param name="image">The canvas image.</param>
+        /// <returns>The same instance so that multiple calls can be chained.</returns>
+        public static CanvasImage NoMaxWidth(this CanvasImage image)
+        {
+            if (image is null)
+            {
+                throw new ArgumentNullException(nameof(image));
+            }
+
+            image.MaxWidth = null;
+            return image;
+        }
+
+        /// <summary>
+        /// Sets the pixel width.
+        /// </summary>
+        /// <param name="image">The canvas image.</param>
+        /// <param name="width">The pixel width.</param>
+        /// <returns>The same instance so that multiple calls can be chained.</returns>
+        public static CanvasImage PixelWidth(this CanvasImage image, int width)
+        {
+            if (image is null)
+            {
+                throw new ArgumentNullException(nameof(image));
+            }
+
+            image.PixelWidth = width;
+            return image;
+        }
+
+        /// <summary>
+        /// Mutates the underlying image.
+        /// </summary>
+        /// <param name="image">The canvas image.</param>
+        /// <param name="action">The action that mutates the underlying image.</param>
+        /// <returns>The same instance so that multiple calls can be chained.</returns>
+        public static CanvasImage Mutate(this CanvasImage image, Action<IImageProcessingContext> action)
+        {
+            if (image is null)
+            {
+                throw new ArgumentNullException(nameof(image));
+            }
+
+            if (action is null)
+            {
+                throw new ArgumentNullException(nameof(action));
+            }
+
+            image.Image.Mutate(action);
+            return image;
+        }
+
+        /// <summary>
+        /// Uses a bicubic sampler that implements the bicubic kernel algorithm W(x).
+        /// </summary>
+        /// <param name="image">The canvas image.</param>
+        /// <returns>The same instance so that multiple calls can be chained.</returns>
+        public static CanvasImage BicubicResampler(this CanvasImage image)
+        {
+            if (image is null)
+            {
+                throw new ArgumentNullException(nameof(image));
+            }
+
+            image.Resampler = KnownResamplers.Bicubic;
+            return image;
+        }
+
+        /// <summary>
+        /// 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.
+        /// </summary>
+        /// <param name="image">The canvas image.</param>
+        /// <returns>The same instance so that multiple calls can be chained.</returns>
+        public static CanvasImage BilinearResampler(this CanvasImage image)
+        {
+            if (image is null)
+            {
+                throw new ArgumentNullException(nameof(image));
+            }
+
+            image.Resampler = KnownResamplers.Triangle;
+            return image;
+        }
+
+        /// <summary>
+        /// 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.
+        /// </summary>
+        /// <param name="image">The canvas image.</param>
+        /// <returns>The same instance so that multiple calls can be chained.</returns>
+        public static CanvasImage NearestNeighborResampler(this CanvasImage image)
+        {
+            if (image is null)
+            {
+                throw new ArgumentNullException(nameof(image));
+            }
+
+            image.Resampler = KnownResamplers.NearestNeighbor;
+            return image;
+        }
+    }
+}

src/Spectre.Console.ImageSharp/Spectre.Console.ImageSharp.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>netstandard2.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <Description>A library that extends Spectre.Console with ImageSharp super powers.</Description>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <AdditionalFiles Include="..\stylecop.json" Link="Properties/stylecop.json" />
+    <None Include="../../resources/gfx/small-logo.png" Pack="true" PackagePath="\" Link="Properties/small-logo.png" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="SixLabors.ImageSharp" Version="1.0.2" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Spectre.Console\Spectre.Console.csproj" />
+  </ItemGroup>
+
+</Project>