Regira.Media 6.1.2

Regira Drawing

Regira Drawing is a .NET image processing library that provides a consistent abstraction over image manipulation, format conversion, and multi-layer composition. All operations are available through a single IImageService interface, implemented by both backends.

Projects

Installation

<PackageReference Include="Regira.Drawing.SkiaSharp" Version="6.*" />


<PackageReference Include="Regira.Drawing.GDI" Version="6.*" />

Quick Start

// Register
services.AddSingleton<IImageService, Regira.Drawing.SkiaSharp.Services.ImageService>();

// Use
using var image   = (await imageService.Parse(inputBytes))!;
using var resized = await imageService.Resize(image, new ImageSize(200, 200));
using var webp    = await imageService.ChangeFormat(resized, ImageFormat.Webp);
return webp.GetBytes()!;

Core Models

IImageFile / ImageFile

Represents an image held in memory. Implements IDisposable.

ImageSize

var size   = new ImageSize(800, 600);
var half   = size / 2;          // (400, 300)
var square = (ImageSize)128;    // (128, 128) — implicit from int

Color

RGBA struct with hex string support.

Color c = "#FF000080";   // implicit from string
string rgb  = c.Hex;    // "#FF0000"
string rgba = c.HexA;   // "#FF000080"

ImageFormat

Png  Jpeg  Webp  Gif  Bmp  Tiff  Ico  Heif  Tga  Wbmp  …

ImageEdgeOffset

CSS-style distance from each edge.

new ImageEdgeOffset(top: 10, left: 20, bottom: 10, right: 20)
new ImageEdgeOffset(10, 20)   // top + left; Bottom and Right stay null

ImagePosition

Flags enum for layer alignment. Combine with |.

ImageLayerOptions

Controls how a layer is positioned and rendered when composited.

IImageService — Image Operations

IImageService is a composite of five focused sub-interfaces. Every method returns a Task and accepts an optional trailing CancellationToken (omitted below for brevity).

Parsing

Task<IImageFile?> Parse(Stream? stream)
Task<IImageFile?> Parse(byte[]? bytes)
Task<IImageFile?> Parse(byte[] rawBytes, ImageSize size, ImageFormat? format = null)
Task<IImageFile?> Parse(IMemoryFile file)

The third overload accepts unencoded pixel data together with explicit dimensions and format.

Format

Task<ImageFormat> GetFormat(IImageFile input)
Task<IImageFile>  ChangeFormat(IImageFile input, ImageFormat targetFormat)

Transform

Task<ImageSize>  GetDimensions(IImageFile input)
Task<IImageFile> Resize(IImageFile input, ImageSize wantedSize, int quality = 100)     // preserves aspect ratio
Task<IImageFile> ResizeFixed(IImageFile input, ImageSize size, int quality = 100)      // ignores aspect ratio
Task<IImageFile> CropRectangle(IImageFile input, ImageEdgeOffset rect)
Task<IImageFile> Rotate(IImageFile input, int degrees, Color? background = null)
Task<IImageFile> FlipHorizontal(IImageFile input)
Task<IImageFile> FlipVertical(IImageFile input)

SkiaSharp default quality: 80. GDI default quality: 100.

Color

Task<Color>      GetPixelColor(IImageFile input, int x, int y)
Task<IImageFile> MakeTransparent(IImageFile input, Color? color = null)  // null = light gray (245, 245, 245)
Task<IImageFile> MakeOpaque(IImageFile input)

Draw / Create

Task<IImageFile> Create(ImageSize size, Color? backgroundColor = null, ImageFormat? format = null)
Task<IImageFile> CreateTextImage(LabelImageOptions? options = null)
Task<IImageFile> Draw(IEnumerable<ImageLayer> items, IImageFile? target = null)

Layer Composition — ImageBuilder

ImageBuilder composes multiple layers onto a single canvas using a fluent API.

Registration

services.AddSingleton<IImageService, Regira.Drawing.SkiaSharp.Services.ImageService>();
services.AddSingleton<IImageCreator, CanvasImageCreator>();
services.AddSingleton<IImageCreator, LabelImageCreator>();
services.AddSingleton<IImageCreator>(provider =>
    AggregateImageCreator.Create(
        provider.GetRequiredService<IImageService>(),
        provider.GetServices<IImageCreator>()
    )
);

Fluent API

var result = await new ImageBuilder(imageService, imageCreators)
    .SetBaseLayer(new CanvasImageOptions { Size = new ImageSize(800, 600), BackgroundColor = Color.White })
    .Add(layer1, layer2, layer3)
    .Build();

SetBaseLayer overloads

If no base layer is set, Build() auto-calculates a canvas that fits all added layers.

Layer types

Three generic types let you add image files, canvases, or labels as layers:

// Existing image — pin to bottom-right
new ImageLayer { Source = imageFile,
                 Options = new() { Position = ImagePosition.Right | ImagePosition.Bottom, Margin = 10 } }

// Blank colored rectangle — absolute position
new ImageLayer<CanvasImageOptions> { Source = new() { Size = new ImageSize(100, 30), BackgroundColor = "#0000FF80" },
                                     Options = new() { Offset = new ImageEdgeOffset(top: 20, left: 15) } }

// Text label — centered with rotation and opacity
new ImageLayer<LabelImageOptions>  { Source = new() { Text = "DRAFT", FontSize = 32, TextColor = "#FF0000",
                                                       BackgroundColor = Color.Transparent },
                                     Options = new() { Position = ImagePosition.HCenter | ImagePosition.VCenter,
                                                       Rotation = -30, Opacity = 0.4f } }

Custom IImageCreator

Implement IImageCreator<T> to make ImageBuilder understand any source type:

public class QrCodeCreator(IQrService qr) : ImageCreatorBase<QrCodeOptions>
{
    public override async Task<IImageFile?> Create(QrCodeOptions input, CancellationToken cancellationToken = default) =>
        new ImageFile { Bytes = await qr.Generate(input.Content, input.Size), Format = ImageFormat.Png };
}

services.AddSingleton<IImageCreator, QrCodeCreator>();

Text Images

IImageService imageService = new Regira.Drawing.SkiaSharp.Services.ImageService();

using var img = await imageService.CreateTextImage("Hello World");   // implicit string shorthand

Use Color.Transparent as background when compositing the label over another image.

SkiaSharp vs GDI

Both implement IImageService and are interchangeable in consuming code.

DTOs & API Integration

Common.Media ships DTO types for JSON API contracts. DtoExtensions converts them to domain objects.

All measurement properties (Width, Height, Top, Left, …) are float and interpreted according to the DTO's DimensionUnit property, of type LengthUnit:

A live demo is available at services.regira.com/office — endpoint /drawing/create, samples at /drawing/samples/**.

Overview

1. Index — Overview, models, and API reference
2. Examples — Thumbnail, watermark, badge builder, and API service pattern
3. Video processing — Video compression and snapshot extraction via FFMpeg

License

Apache License 2.0 — this package contains no license validation and no runtime limits. See LICENSE. A few companion packages are commercially licensed with a free tier; see the licensing overview.