DemaConsulting.CanvasNet 0.1.0-beta.2

CanvasNet

.NET canvas library for loading, saving, and cropping images

Overview

CanvasNet is a .NET library providing a mutable, span-based 32-bit RGBA pixel buffer along with codecs for loading and saving images in common file formats. It's designed for fast, allocation-conscious image operations using Span<T>, and supports independent-copy cropping for load/crop/save workflows.

Features

• 🖼️ Pixel Buffer - Mutable 32-bit RGBA Surface with span-based row access
• ✂️ Cropping - Independent-copy cropping for load/crop/save workflows
• 🌈 Compositing - Vectorized alpha premultiply/unpremultiply and Porter-Duff "over" compositing (surface-over-surface and surface-over-constant-color)
• 📀 BMP Codec - Load and save 24-bit and 32-bit uncompressed Windows BMP files
• 🎨 PNG Codec - Load any non-interlaced, spec-valid PNG color type/bit depth combination (Grayscale, Palette, Truecolor, and their alpha variants, at bit depths 1-16, with tRNS transparency); save 8-bit Truecolor (RGB) and Truecolor-with-alpha (RGBA) PNG files
• 🖨️ TIFF Codec - Load and save 8-bit RGB/RGBA/Grayscale TIFF files with PackBits/LZW/Deflate
• 🗜️ JPEG Codec - Load baseline/progressive JPEG and save baseline 4:2:0 JPEG with quality control
• 📐 SVG Codec - Decode/rasterize a common real-world subset of SVG documents (shapes, paths, transforms, gradients, <use>, text) into a Surface of caller-chosen dimensions
• 🔍 Header-Only Probing - GetInfo reads only image headers (dimensions/channels/alpha) without decoding pixel data, letting callers triage untrusted files before calling Load
• 🖌️ Path Filling - Antialiased nonzero/even-odd fill of closed vector paths onto a Surface
• 🖊️ Stroke-to-Fill - Convert stroked vector paths (caps, joins, dashes, miter limits) into fillable outline geometry and render them through the same antialiased fill pipeline
• 🌅 Gradient Paint - Fill a path with a linear or two-circle radial gradient color ramp, with pad/reflect/repeat spread and premultiplied-alpha color interpolation
• 🔤 TrueType Fonts - Load glyph-based TrueType SFNT fonts, map Unicode codepoints to glyph indices, extract glyph outlines as Geometry.Path, and query advance widths and basic kerning
• 🎬 Rendering - Transform-aware Canvas (Save/Restore/Translate/RotateDegrees), text rendering with alignment (DrawText, MeasureText), shape helpers (FillRect, FillRoundRect, FillCircle, and their strokes), corner rounding (CornerRoundEffect.Apply), and Rgba32.Parse/TryParse for #RRGGBB / #AARRGGBB color literals
• ⚡ Span-Based - Fast, allocation-conscious row and pixel access
• 🔄 Multi-Target - Supports .NET 8, 9, and 10
• 📦 NuGet Ready - Easy integration via NuGet package

Installation

dotnet add package DemaConsulting.CanvasNet

Or via Package Manager Console:

Install-Package DemaConsulting.CanvasNet

Usage

using DemaConsulting.CanvasNet.Canvas;
using DemaConsulting.CanvasNet.Codecs;
using System.IO;

var surface = new Surface(4, 4);
surface[1, 1] = new Rgba32(255, 0, 0, 255); // set a red, opaque pixel
var cropped = surface.Crop(0, 0, 2, 2);     // independent 2x2 copy

BmpCodec.Save(surface, "surface.bmp");        // save as a 32-bit BMP file
var reloaded = BmpCodec.Load("surface.bmp"); // load it back

PngCodec.Save(surface, "surface.png");        // save as an RGBA PNG file
var reloadedPng = PngCodec.Load("surface.png"); // load it back

TiffCodec.Save(surface, "surface.tiff");        // save as an RGBA TIFF file
var reloadedTiff = TiffCodec.Load("surface.tiff"); // load it back

JpegCodec.Save(surface, "surface.jpg", 90);        // save as a baseline JPEG file
var reloadedJpeg = JpegCodec.Load("surface.jpg"); // load it back

var rasterized = SvgCodec.Load("icon.svg", 256, 256); // decode/rasterize an SVG into a 256x256 surface

// Triage an untrusted file's header before decoding pixel data:
var info = PngCodec.GetInfo("untrusted.png"); // reads only the header, never decodes IDAT
if (info.Width > Surface.MaxDimension
    || info.Height > Surface.MaxDimension
    || (long)info.Width * info.Height > (long)Surface.MaxDimension * Surface.MaxDimension)
{
    throw new InvalidDataException("Image dimensions exceed the supported maximum.");
}

var safeSurface = PngCodec.Load("untrusted.png"); // safe to decode fully

Filling a vector path onto a surface:

using DemaConsulting.CanvasNet.Canvas;
using DemaConsulting.CanvasNet.Drawing;
using DemaConsulting.CanvasNet.Geometry;
using System.Numerics;

var canvas = new Surface(64, 64);
var triangle = new PathBuilder()
    .MoveTo(new Vector2(8, 56))
    .LineTo(new Vector2(56, 56))
    .LineTo(new Vector2(32, 8))
    .Close()
    .Build();

PathFiller.Fill(canvas, triangle, new Rgba32(0, 128, 255, 255)); // antialiased solid fill

Stroking a vector path onto a surface:

using DemaConsulting.CanvasNet.Canvas;
using DemaConsulting.CanvasNet.Drawing;
using DemaConsulting.CanvasNet.Geometry;
using System.Numerics;

var canvas = new Surface(64, 64);
var polyline = new PathBuilder()
    .MoveTo(new Vector2(8, 48))
    .LineTo(new Vector2(32, 16))
    .LineTo(new Vector2(56, 48))
    .Build();

var style = new StrokeStyle(
    width: 6f,
    cap: LineCap.Round,
    join: LineJoin.Round,
    dashArray: [10f, 6f]);

var strokedOutline = PathStroker.Stroke(polyline, style);
PathFiller.Fill(canvas, strokedOutline, new Rgba32(255, 128, 0, 255));

Filling a vector path with a linear gradient:

using DemaConsulting.CanvasNet.Canvas;
using DemaConsulting.CanvasNet.Drawing;
using DemaConsulting.CanvasNet.Geometry;
using System.Numerics;

var canvas = new Surface(64, 64);
var rectangle = new PathBuilder()
    .MoveTo(new Vector2(4, 4))
    .LineTo(new Vector2(60, 4))
    .LineTo(new Vector2(60, 60))
    .LineTo(new Vector2(4, 60))
    .Close()
    .Build();

var gradient = new LinearGradient(
    start: new Vector2(4, 0),
    end: new Vector2(60, 0),
    stops:
    [
        new GradientStop(0f, new Rgba32(255, 0, 0, 255)),
        new GradientStop(1f, new Rgba32(0, 0, 255, 255))
    ]);

PathFiller.Fill(canvas, rectangle, gradient, FillRule.NonZero, 1f); // red-to-blue ramp

Loading a TrueType font and filling a glyph outline:

using DemaConsulting.CanvasNet.Canvas;
using DemaConsulting.CanvasNet.Drawing;
using DemaConsulting.CanvasNet.Fonts;
using DemaConsulting.CanvasNet.Geometry;
using System.Numerics;

static Path TransformGlyph(Path glyph, float scale, float baselineY)
{
    var builder = new PathBuilder();

    Vector2 ToCanvas(Vector2 point) => new(point.X * scale, baselineY - point.Y * scale);

    foreach (var subpath in glyph.Subpaths)
    {
        builder.MoveTo(ToCanvas(subpath.Start));
        foreach (var command in subpath.Commands)
        {
            switch (command.Type)
            {
                case PathCommandType.LineTo:
                    builder.LineTo(ToCanvas(command.EndPoint));
                    break;
                case PathCommandType.QuadraticBezierTo:
                    builder.QuadraticBezierTo(
                        ToCanvas(command.Control1),
                        ToCanvas(command.EndPoint));
                    break;
                case PathCommandType.Close:
                    builder.Close();
                    break;
            }
        }
    }

    return builder.Build();
}

var font = TrueTypeFont.Load("font.ttf");
var glyphIndex = font.GetGlyphIndex('A');
var glyphOutline = font.GetGlyphOutline(glyphIndex); // raw font-design-unit coordinates (Y up)
var scale = 48f / font.UnitsPerEm;
var canvasOutline = TransformGlyph(glyphOutline, scale, baselineY: 56f);

var surface = new Surface(64, 64);
PathFiller.Fill(surface, canvasOutline, new Rgba32(20, 120, 255, 255));

Building

pwsh ./build.ps1

API Documentation

Detailed API documentation for all public types and members is distributed in the api/ folder of the NuGet package.

User Guide

The CanvasNet User Guide is available on the CanvasNet releases page.

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, coding standards, and the pull request process.

License

Copyright (c) DEMA Consulting. Licensed under the MIT License. See LICENSE for details.

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

Support

• Report a bug or request a feature
• Ask a question or start a discussion