# oneimage docs, all pages (OneImage 1.10.1)

Every page of https://recursiveai.org/oneimage/docs/ as markdown, getting started first. Index: https://recursiveai.org/oneimage/llms.txt


<!-- https://recursiveai.org/oneimage/docs/getting-started/ -->

# Getting started

OneImage is an image library for .NET written in pure C#, with no dependency beyond .NET itself. This page goes from install to a first thumbnail, format conversion, editing, and serving resized images from ASP.NET Core. Every sample on it was compiled and run against the 1.10.1 packages from NuGet.

## Install

OneImage targets .NET 10 (`net10.0`).

```sh
dotnet add package RecursiveAI.OneImage
```

The package is `RecursiveAI.OneImage` and the namespace is `OneImage`. The package has no dependencies: no native binaries, no other NuGet packages. NativeAOT and trimming are supported.

## Your first thumbnail

```csharp
using OneImage;

// 400 px wide, upright, in sRGB, EXIF and GPS removed, written as WebP.
Image.Thumbnail("in.jpg", 400).Save("thumb.webp");
```

`Image.Thumbnail` does what a web-ready copy needs, in this order: it applies the EXIF orientation, resizes (a JPEG is decoded at 1/2, 1/4 or 1/8 scale when that is enough), converts to sRGB and strips EXIF, XMP and IPTC. It never makes an image larger than the original unless you pass `upscale: true`. It also takes a `Stream`, a `ReadOnlyMemory<byte>` or an existing `Image`.

## Convert format and quality

```csharp
// The output format follows the file extension.
Image.Load("in.jpg").Save("out.png");

// Quality and other codec settings go in SaveOptions.
Image.Load("in.png").Save("out.jpg",
    new SaveOptions { EncoderOptions = new JpegEncoderOptions { Quality = 85 } });
Image.Load("in.png").Save("out.webp",
    new SaveOptions { EncoderOptions = new WebPEncoderOptions { Quality = 80 } });

// A stream has no extension, so name the format.
using var stream = File.Create("out-stream.png");
Image.Load("in.jpg").Save(stream, PngFormat.Instance);
```

JPEG and WebP default to quality 75. Every format's options (PNG compression level, WebP lossless, GIF palette size, TIFF compression) are in the [guide](https://recursiveai.org/oneimage/docs/guide/#saving). The core package reads and writes PNG, JPEG, WebP, GIF, TIFF, BMP and ICO, and detects the format from the content, not the extension.

## Load, edit, save

```csharp
Image photo = Image.Load("in.jpg");     // reads the headers only
Console.WriteLine($"{photo.Width} x {photo.Height}");

// Fill a 200 x 200 box, cropping around the busiest part.
photo.Resize(width: 200, height: 200, fit: Fit.Cover, anchor: Anchor.Smart)
     .Save("square.jpg");

// Each call returns a new Image; photo itself never changes.
photo.Crop(0, 0, 1200, 800)
     .Rotate(90)
     .Flip(FlipAxis.Horizontal)
     .Save("edited.png");
```

`Resize` takes a `Fit` (`Contain`, `Cover`, `Stretch`, `Pad`, `BoxPad`, `Min`) and an `Anchor`; leave out `width` or `height` to keep the aspect ratio. Crops, rotations, padding, color adjustments, blurs and filters, compositing and pixel access through a `Canvas` are in the [guide](https://recursiveai.org/oneimage/docs/guide/#operations).

## The lazy model

An `Image` is a description of work, not a decoded bitmap: `Load` reads only the headers, each operation returns a new immutable `Image`, and pixels are computed tile by tile when you `Save`. So a file whose header is fine but whose data is damaged loads without error and throws at `Save`: put the `Save` inside your `try`, or load with `Validate = true`.

```csharp
try
{
    Image.Load("upload.jpg").Resize(width: 800).Save("upload.webp");
}
catch (ImageException ex)    // damaged data, a size limit, an unsupported operation
{
    Console.WriteLine(ex.Message);
}

// To fail at Load instead, decode once up front.
Image upload = Image.Load("upload.jpg", new LoadOptions { Validate = true });
```

All of OneImage's own exceptions derive from `ImageException`. Because an image loaded from a path reopens the file when its pixels are needed, keep the file in place until you are done, or load from a `Stream` or `byte[]` instead ([sources and lifetime](https://recursiveai.org/oneimage/docs/guide/#sources-and-lifetime)).

## Serve images from ASP.NET Core

`RecursiveAI.OneImage.Web` resizes, crops and converts images on request, driven by the query string, and caches the results on disk. It is a separate package, so the core package stays free of ASP.NET Core.

```sh
dotnet add package RecursiveAI.OneImage.Web
```

```csharp
using OneImage.Web;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOneImage();

var app = builder.Build();
app.UseOneImage();      // before UseStaticFiles
app.UseStaticFiles();
app.Run();
```

Every image under `wwwroot` can now be asked for in another size or format:

```text
/photos/cat.jpg?width=400                    400 px wide, same format, aspect ratio kept
/photos/cat.jpg?w=300&h=300&fit=cover        300 x 300, cropped around the center
/photos/cat.jpg?width=800&format=webp&q=80   WebP at quality 80
```

A request without commands falls through to the static file middleware untouched, and an invalid value such as `width=abc` is a 400, never silently clamped. Requests for the same result are processed once and then served from the cache, with `ETag`, `Last-Modified` and 304 responses.

On a public site, sign your URLs or allow only presets, because every distinct valid set of commands creates a cache entry. With a key set, a request without a valid `hmac` gets a 403. Here the key is at least 32 random bytes, base64, from configuration (for example the environment variable `Images__Key`):

```csharp
using OneImage.Web;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOneImage(o =>
{
    o.MaxWidth = 2000;
    o.Presets["thumb"] = "width=200&height=200&fit=cover&format=webp";
    o.HmacSecretKey = Convert.FromBase64String(builder.Configuration["Images:Key"]!);
})
.ConfigureCache(c => c.CacheRootPath = "/var/cache/images");

var app = builder.Build();
app.UseOneImage();
app.UseStaticFiles();

var signer = app.Services.GetRequiredService<ImageUrlSigner>();
string src = signer.Sign("/photos/cat.jpg?preset=thumb");   // adds &hmac=...
app.MapGet("/", () => Results.Text($"<img src=\"{src}\">", "text/html"));
app.Run();
```

The defaults assume a public, unauthenticated endpoint: output is at most 4096 px a side and 16,777,216 pixels, sources at most 64 MiB, queries at most 1024 characters, at most one image per processor (at least two) is processed at a time, EXIF, XMP and IPTC are removed, and the cache folder sits outside `wwwroot`. The ImageSharp.Web query spellings (`rmode`, `ranchor`, `rsampler`, `bgcolor` and the rest) are accepted too. Commands, providers, hooks and the cache layout are in [OneImage.Web](https://recursiveai.org/oneimage/docs/web/).

## Add-on packages

Drawing (paths, fills, strokes, brushes, clipping, boolean operations) and layered documents are in the core package. The rest comes as separate packages, so you only ship what you use:

| Package | What it does | Install |
|---|---|---|
| [OneImage.Web](https://recursiveai.org/oneimage/docs/web/) | ASP.NET Core middleware: URL-driven resizing, cropping and conversion, a disk cache, signed URLs and request limits. | `dotnet add package RecursiveAI.OneImage.Web` |
| [OneImage.Text](https://recursiveai.org/oneimage/docs/text/) | Fonts and text: OpenType shaping, right-to-left and complex scripts, line breaking, rich text and color glyphs. Depends on RecursiveAI.OneFont. | `dotnet add package RecursiveAI.OneImage.Text` |
| [OneImage.Svg](https://recursiveai.org/oneimage/docs/svg/) | SVG and SVGZ as an image format, drawn at the size you ask for. Depends on OneImage.Text. | `dotnet add package RecursiveAI.OneImage.Svg` |
| [OneImage.Psd](https://recursiveai.org/oneimage/docs/psd/) | PSD and PSB: the merged image as an image format, and the layers as a document you can edit and write back. | `dotnet add package RecursiveAI.OneImage.Psd` |
| [OneImage.Pdf](https://recursiveai.org/oneimage/docs/pdf/) | PDF pages as an image format, each page a frame, drawn at the size you ask for. Depends on RecursiveAI.OnePdf. | `dotnet add package RecursiveAI.OneImage.Pdf` |

SVG, PSD and PDF are not in the default configuration. Register the ones you use, then load them like any other file:

```csharp
using OneImage;
using OneImage.Pdf;
using OneImage.Psd;
using OneImage.Svg;

var config = new ImageConfiguration()
    .Add(SvgFormat.Instance)
    .Add(PsdFormat.Instance)
    .Add(new PdfFormat(new PdfRenderOptions { Dpi = 150 }));
var load = new LoadOptions { Configuration = config };

// SVG is drawn at the size you ask for, not scaled up.
Image.Load("logo.svg", load).Resize(width: 400).Save("logo.png");

// PSD loads as its merged image.
Image.Load("poster.psd", load).Resize(width: 800).Save("poster.webp");

// Each PDF page is a frame.
Image.Load("report.pdf", load).Frames[0].ToImage().Save("page1.png");
```

Text is drawn through the same vector drawing as shapes:

```csharp
using OneImage;
using OneImage.Drawing;
using OneImage.Text;
using Path = OneImage.Drawing.Path;

var fonts = new FontCollection();
Font font = fonts.Add("DejaVuSans.ttf").CreateFont(48);

Image.Load("in.jpg")
    .Fill(new Rgba32(255, 255, 255, 180), Path.RoundedRectangle(40, 40, 520, 120, 16))
    .DrawText("Hello from OneImage", new TextOptions(font) { Origin = new(70, 115) },
              Brush.Solid(new Rgba32(20, 20, 20, 255)))
    .Save("captioned.jpg");
```

## Where next

- [Guide](https://recursiveai.org/oneimage/docs/guide/): the lazy model, errors, operations, `Canvas`, metadata, color, animation, limits, threading, AOT and trimming.
- [OneImage.Web](https://recursiveai.org/oneimage/docs/web/): every command, the security defaults, signed URLs, caching and providers.
- [Drawing](https://recursiveai.org/oneimage/docs/drawing/), [Text](https://recursiveai.org/oneimage/docs/text/) and [Layers](https://recursiveai.org/oneimage/docs/layers/).
- [Migrating from ImageSharp and System.Drawing](https://recursiveai.org/oneimage/docs/migrating/), with code side by side, and [migrating from SkiaSharp](https://recursiveai.org/oneimage/articles/migrate-from-skiasharp/).
- [Comparison](https://recursiveai.org/oneimage/docs/comparison/) with ImageSharp, SkiaSharp, Magick.NET and NetVips, and the [benchmarks](https://recursiveai.org/oneimage/docs/performance/).
- [All docs](https://recursiveai.org/oneimage/docs/), or all of them as one Markdown file for an LLM: [llms-full.txt](https://recursiveai.org/oneimage/llms-full.txt).

Guides: [compress images](https://recursiveai.org/oneimage/articles/compress-image-csharp/), [grayscale](https://recursiveai.org/oneimage/articles/convert-image-to-grayscale-csharp/), [watermarks](https://recursiveai.org/oneimage/articles/add-watermark-to-image-csharp/), [animated GIFs](https://recursiveai.org/oneimage/articles/resize-animated-gif-csharp/), [multipage TIFF](https://recursiveai.org/oneimage/articles/split-multipage-tiff-csharp/), [PDF to TIFF](https://recursiveai.org/oneimage/articles/pdf-to-tiff-csharp/), [PSD to PNG](https://recursiveai.org/oneimage/articles/psd-to-png-csharp/) and [resizing on the fly in ASP.NET Core](https://recursiveai.org/oneimage/articles/resize-images-on-the-fly-aspnet-core/).


<!-- https://recursiveai.org/oneimage/docs/guide/ -->

# OneImage guide

Every snippet here is compiled and run by `tests/OneImage.Tests/Docs/DocsExamples.cs`. All types are in the `OneImage` namespace.

Contents: [the lazy model](#the-lazy-model) · [errors](#errors) · [sources and lifetime](#sources-and-lifetime) · [saving](#saving) · [operations](#operations) · [pixel access and Canvas](#pixel-access-and-canvas) · [metadata](#metadata) · [color](#color) · [animation](#animation-and-multi-page-files) · [limits](#limits) · [threading and memory](#threading-and-memory) · [AOT and trimming](#aot-and-trimming) · [formats](#formats)

## The lazy model

An `Image` is a description of a computation. `Image.Load` reads only the headers (size, format, metadata). Each operation returns a new `Image` that remembers what to do. Work happens when you pull pixels: `Save`, `ToArray<T>()`, `CopyPixelsTo<T>()`, or `ToCanvas()` followed by access.

```csharp
Image img = Image.Load("photo.jpg");          // headers only
Image small = img.Resize(width: 300);         // nothing decoded yet
small.Save("small.png");                      // decode, resize and encode, streaming over tiles
```

What follows from this:

- **Cheap pipelines.** Only what the output needs is computed. A crop never decodes the tiles outside it, and a JPEG thumbnail is decoded at 1/2, 1/4 or 1/8 scale when that is enough. Large images stream through bounded memory rather than being held whole.
- **Images are immutable and safe to share between threads.** An operation never changes the image it is called on.
- **Errors can appear late.** Corrupt pixel data is found when the pixels are pulled, which may be the `Save` at the end of the chain. See [Errors](#errors).
- **Order of operations is yours.** `Resize` then `Crop` is a different image from `Crop` then `Resize`; the engine only reorders what cannot change the result (for example pushing a crop down to the decoder).
- **Argument mistakes are eager.** A bad parameter (no width and no height, a negative size, an undefined enum) throws at the call that got it, not later.

`Image` is not `IDisposable`: it holds no unmanaged resources.

## Errors

Only these leave a public method: the library's own exceptions, `ArgumentException` and friends, I/O exceptions passed through unchanged, and `OperationCanceledException`.

| Exception | Meaning |
|---|---|
| `ImageFormatException` | The data is not a recognized image or is damaged. |
| `ImageLimitException` | The data is valid but exceeds an `ImageLimits` bound (see [Limits](#limits)). Raised from header values, before anything large is allocated. |
| `ImageOperationException` | The request cannot be done: no encoder for the format, an unknown output extension, an op on a pixel format it does not support (for example `Composite` on a CMYK image). |
| `ImageSourceChangedException` | A file loaded by path changed before its pixels were read (derives from `ImageOperationException`). |

All four derive from `ImageException`. A missing or unreadable file throws the ordinary `FileNotFoundException`/`IOException`.

```csharp
try
{
    Image.Load("upload.png").Resize(width: 800).Save("out.jpg");
}
catch (ImageException ex)    // format, limit, operation, source-changed
{
    Console.WriteLine(ex.Message);
}
```

### Errors can surface at `Save`

`Load` validates the container (signature, header, limits) but does not decode pixels. A file whose header is fine and whose compressed data is damaged loads successfully, and throws `ImageFormatException` at the first pixel pull, typically in `Save`. A failed `Save(path)` deletes the partial output file.

To find out up front, ask for validation:

```csharp
// Decodes every frame once; throws ImageFormatException here if anything is wrong.
Image img = Image.Load("upload.png", new LoadOptions { Validate = true });
```

`Validate` costs a full decode. Frames that decode sequentially are kept, so the work is not repeated by the later `Save`.

### Probing without exceptions

```csharp
if (Image.TryLoad("maybe.png", out Image? image))
{
    // use image
}

if (Image.TryIdentify(bytes, out ImageInfo? info))
{
    Console.WriteLine($"{info.Format.Name} {info.Width}x{info.Height}, {info.Frames.Count} frame(s)");
}
```

`TryLoad` and `TryIdentify` return `false` for `ImageFormatException` and `ImageLimitException`. I/O errors still throw. `Image.Identify` reads only the headers; it reports the *stored* size, before auto-orientation.

## Sources and lifetime

| Source | What `Load` does | What you may do afterwards |
|---|---|---|
| Path | Reads the headers and records the file's size and modification time. The file is **reopened** whenever pixels are pulled. | Don't change or delete the file while the image is in use. If its size or modification time differ at pull time, `ImageSourceChangedException` is thrown. |
| `Stream` | Copies the remaining bytes into pooled memory. | The stream is yours: close or dispose it right away. |
| `ReadOnlyMemory<byte>` | References the memory, no copy. | Don't modify the memory while the image, or anything derived from it, is in use. |

```csharp
Image fromPath   = Image.Load("a.jpg");
Image fromStream = Image.Load(File.OpenRead("a.jpg"));      // copied now
Image fromMemory = Image.Load(File.ReadAllBytes("a.jpg"));  // referenced
```

Async variants exist for I/O: `LoadAsync`, `IdentifyAsync`, `SaveAsync`. Everything that computes takes a `CancellationToken`.

`Canvas` is `IDisposable`: dispose it to return pooled tile memory. Forgetting is safe, because the garbage collector reclaims the buffers, but slower.

## Saving

`Save(path)` picks the format from the extension. A stream or `IBufferWriter<byte>` needs the format: `PngFormat.Instance`, `JpegFormat.Instance`, `GifFormat.Instance`, `BmpFormat.Instance`, `IcoFormat.Instance`, `TiffFormat.Instance`, or `WebPFormat.Instance`.

Codec settings go in `SaveOptions.EncoderOptions`:

```csharp
img.Save("q.jpg",  new SaveOptions { EncoderOptions = new JpegEncoderOptions { Quality = 85, Subsampling = JpegSubsampling.Yuv444 } });
img.Save("q.webp", new SaveOptions { EncoderOptions = new WebPEncoderOptions { Quality = 80 } });
img.Save("l.webp", new SaveOptions { EncoderOptions = new WebPEncoderOptions { Lossless = true } });
img.Save("q.png",  new SaveOptions { EncoderOptions = new PngEncoderOptions { CompressionLevel = 9 } });
img.Save("q.tif",  new SaveOptions { EncoderOptions = new TiffEncoderOptions { Compression = TiffCompression.Deflate } });
img.Save("p.gif",  new SaveOptions { EncoderOptions = new GifEncoderOptions { MaxColors = 64, Dither = Dither.Ordered } });
```

Defaults: JPEG quality 75 (the libjpeg scale), 4:2:0, optimized Huffman tables on, sequential. WebP lossy quality 75, effort 4. Each options class documents the rest.

Rules worth knowing:

- Formats that cannot hold animation (JPEG, BMP) write the first frame only. PNG (APNG), WebP, GIF and TIFF (pages) write all frames.
- JPEG has no alpha. An image with alpha is written with its stored color values; use `Flatten` to put it on a background first:

  ```csharp
  logo.Flatten(new Rgba32(255, 255, 255, 255)).Save("logo.jpg");
  ```
- The encoder converts the pixel format when the format cannot hold it (for example 16-bit to 8-bit for JPEG).
- Encoders produce identical bytes for identical input on a given platform, regardless of thread count.

## Operations

All are lazy and return a new `Image`; all apply to every frame of an animation. XML docs on each method state the defaults and edge behavior.

**Resize and thumbnails**

```csharp
img.Resize(width: 300);                                   // height follows the aspect ratio
img.Resize(width: 200, height: 200, fit: Fit.Cover, anchor: Anchor.Smart);   // fill the box, crop the overflow
img.Resize(width: 200, height: 200, fit: Fit.Pad, background: new Rgba32(255, 255, 255, 255));
img.Resize(width: 100, filter: ResamplingFilter.Mitchell);
```

- `Fit`: `Contain` (default; fits inside the box), `Cover` (fills the box, crops), `Stretch`, `Pad`, `BoxPad` (like `Pad`, but never enlarges) and `Min` (covers the box without cropping, never enlarges). `ResizeInto(canvasWidth, canvasHeight, target)` scales the image into a given rectangle of a canvas. `Anchor`: nine positions plus `Smart`, an entropy/edge heuristic that picks the crop window.
- Default filter `Auto`: Lanczos3 on an axis that shrinks, Catmull-Rom on one that grows. Others: `Nearest`, `Box`, `Bilinear`, `CatmullRom`, `Mitchell`, `Lanczos2`, `Lanczos3`, `Lanczos5`, `Lanczos8`, `Hermite`, `Robidoux`, `RobidouxSharp`, `Spline`, `Welch`.
- Resampling runs in linear light on premultiplied alpha and treats untagged RGB as sRGB. Pass `linear: false` to filter the stored values.
- **Upscale defaults differ on purpose.** `Resize` enlarges by default (`upscale: true`): you asked for that size. `Image.Thumbnail` never enlarges unless you pass `upscale: true`: a thumbnail is not bigger than the original. With `Resize(..., upscale: false)` Contain, Cover and Pad stop at scale 1.

**Many small resizes: `PixelResizer`**

`Image.Resize` builds a graph, which is the right tool for one image. A program that resizes thousands of small ones in a loop (text-line crops for OCR, sprites, tiles) pays for that graph and for the tap tables of every new size on each call. `PixelResizer` does the same resize straight from a span to a span and keeps its working memory between calls:

```csharp
using var resizer = new PixelResizer();                       // one per thread; reuse it for every call
var buffer = new Gray8[4000 * 32];
foreach ((Gray8[] pixels, int width, int height) in crops)
{
    (int w, int h) = PixelResizer.GetSize(width, height, height: 32);   // the size Image.Resize(height: 32) gives
    resizer.Resize<Gray8>(pixels, width, height, buffer.AsSpan(0, w * h), w, h);
}
```

- **Same bytes as `Image.Resize`.** The output is identical to `image.Resize(w, h, Fit.Stretch, filter: ..., linear: ...)` for every filter, with the same linear-light and alpha handling, box pre-reduce and rounding, on every hardware path and at any degree. `GetSize` returns the size `Resize` scales to before any crop or padding (for `Fit.Cover` and `Fit.Pad`, crop or pad the result yourself).
- **No allocation after warm-up.** Buffers grow to the largest size seen and are reused; calls with a different source or target size each time allocate nothing either. `ScratchBytes` reports what is held, `maxScratchBytes` (default 256 MiB) bounds it (an over-large call throws `ImageLimitException` before allocating), and `Trim()`/`Dispose()` give it back to the array pool.
- **Typed and raw.** `Resize<TPixel>` takes `Gray8`, `Gray16`, `Rgb24`, `Rgba32` and the other pixel structs (straight alpha), with optional strides in pixels. `ResizeRaw` takes bytes and a `PixelFormat`, which also covers premultiplied alpha, CMYK and Lab.
- **Threads.** An instance is not thread-safe (an overlapping call throws `InvalidOperationException`); use one per thread. Large enough calls split their output rows over up to `maxDegree` threads (default `ImageEngine.DefaultCallDegree`); small ones, and `maxDegree: 1`, stay on the calling thread. The bytes never depend on it.

`Image.Thumbnail(path, width, height?, fit, anchor, upscale, filter, keepMetadata, ...)` is `Resize` plus the right defaults for a web-ready copy, in this order: apply EXIF orientation; resize (shrink-on-load for JPEG, never larger than the original unless `upscale: true`); convert RGB to sRGB and embed the compact sRGB profile; strip EXIF/XMP/IPTC. It also accepts a `Stream`, `ReadOnlyMemory<byte>` or an existing `Image`.

**Geometry**

```csharp
img.Crop(10, 10, 100, 100);                   // x, y, width, height; must lie inside the image
img.Rotate(90);                               // clockwise; multiples of 90 are exact pixel moves
img.Rotate(15, background: new Rgba32(255, 255, 255, 255));   // expands to the bounding box by default
img.Flip(FlipAxis.Horizontal);
img.Pad(left: 10, top: 10, right: 10, bottom: 10, mode: EdgeMode.Mirror);
img.Trim();                                   // remove a uniform border (eager: it looks at the pixels)
```

`Orient(1..8)`, `AutoOrient()` and `Affine(...)` are also there. `Perspective(...)` applies a 3×3 projective transform, given as a `ProjectiveMatrix`, a `ProjectiveTransformBuilder` (tapers, rotation, scale, skew, translation) or four corner points:

```csharp
img.Perspective(new ProjectiveTransformBuilder().AppendTaper(TaperSide.Top, TaperCorner.Both, 0.7));
img.Perspective([(30, 10), (150, 40), (120, 130), (10, 100)]);   // corners: top-left, top-right, bottom-right, bottom-left
```

Like `Rotate` and `Affine` it grows the canvas to the transformed bounding box by default. `Trim` is the one geometry op that computes immediately, because it must scan for the border.

**Color and tone**: `Grayscale`, `BrightnessContrast`, `Exposure`, `Gamma`, `Levels`, `Curves`, `HueSaturationLightness`, `Invert`, `Threshold`, `Posterize`, `ChannelMixer`, `CombineChannels`, `AddAlpha`, `RemoveAlpha`, `Flatten`, `ConvertTo(PixelFormat)`. Adjacent tone ops fuse into one pass. Identity parameters return the input unchanged. Tone ops act on straight (not premultiplied) color and leave alpha alone; most work on encoded values, while `Grayscale` and `Exposure` default to linear light.

**Color matrix and presets**: `ApplyColorMatrix(ColorMatrix)` multiplies straight RGBA by a 5×4 matrix (ImageSharp's layout; `ColorMatrix` documents it), and the looks built on it are `Sepia(amount)`, `BlackWhite()`, `Kodachrome()`, `Lomograph()`, `Polaroid()`, `ColorBlindness(mode)` (the eight simulations) and `Opacity(amount)`. They work on stored values, fuse with the other color ops, and the identity (`Sepia(0)`, `Opacity(1)`) returns the input.

```csharp
Image warm = photo.Sepia(0.6f).BrightnessContrast(contrast: 0.1).Opacity(0.9f);
Image seen = photo.ColorBlindness(ColorBlindnessMode.Protanopia);
```

```csharp
img.Grayscale().BrightnessContrast(brightness: 0.1, contrast: 0.2).Gamma(1.1);
```

**Palettes**: `Quantize(colors, dither, alpha)` limits an image to a palette of at most 256 colors but keeps an ordinary RGB(A) format, so you can still process it or save it anywhere.

```csharp
img.Quantize(colors: 16, dither: Dither.FloydSteinberg);
```

**Compositing**: `Composite(overlay, x, y, opacity, linear)` lays one image over another (source-over, color-managed, premultiplied). It is the building block for watermarks:

```csharp
Image marked = photo.Composite(mark, x: photo.Width - 90, y: photo.Height - 40, opacity: 0.8f);
```

The overlay is converted to the base image's profile. The blend happens on stored (encoded) values unless `linear: true`.

`blend:` picks how colors combine (`BlendMode`: Normal, Multiply, Screen, Overlay, Darken, Lighten, ColorDodge, ColorBurn, HardLight, SoftLight, Difference, Exclusion, Add, Subtract, LinearBurn, LinearDodge, VividLight, LinearLight, PinLight, HardMix, Divide, Hue, Saturation, Color, Luminosity), following the W3C Compositing and Blending formulas. `alpha:` picks the Porter-Duff operator for coverage (`AlphaComposition`: SrcOver by default, then Clear, Src, Dest, DestOver, SrcIn, DestIn, SrcOut, DestOut, SrcAtop, DestAtop, Xor, Plus). Only pixels under the overlay change.

```csharp
Image shaded = photo.Composite(texture, opacity: 0.6f, blend: BlendMode.Multiply);
Image cutout = photo.AddAlpha().Composite(mask, alpha: AlphaComposition.DestIn); // the base needs an alpha channel for DestIn
```

**Filters**

```csharp
img.GaussianBlur(sigma: 2);                       // sigmaY: for a different vertical sigma
img.BoxBlur(radius: 3);
img.Sharpen(amount: 1.5, radius: 1.2, threshold: 0.02, linear: false);   // unsharp mask
img.Median(radius: 1);                            // 3x3 median, removes speckle noise
img.Sobel();                                      // edge strength as a gray image
img.Convolve(new float[,] { { 0, -1, 0 }, { -1, 5, -1 }, { 0, -1, 0 } });   // your own kernel
```

All are lazy, read only their tile plus a margin of the kernel radius (so they stream), and apply to every frame.

- **Working space.** `GaussianBlur`, `BoxBlur`, `Sharpen` and `Convolve` work in linear light on premultiplied alpha by default (`linear: true`), so blurring on transparency leaves no dark halos. `Sharpen` in linear light gives stronger halos on the dark side of edges; pass `linear: false` for the conventional look. `Median` and `Sobel` use the stored values and have no `linear` parameter.
- **Edges.** `edge:` is `EdgeMode.Clamp` (default, repeat the edge pixel), `Mirror`, or `Constant` (transparent black, so edges darken on opaque images). `Wrap` is not supported by filters.
- **Parameters.** `GaussianBlur(sigma)` has kernel radius `ceil(3 sigma)`; sigma 0 on an axis leaves it unchanged. `BoxBlur` radius is 1 to 4096 (window `2r+1`). `Sharpen`: `out = in + amount * (in - blur)`; `radius` is the Gaussian sigma; differences below `threshold` (0 to 1, fraction of full scale) are left alone; alpha is not sharpened. `Median` radius is 1 to 127. `Sobel(scale)` returns a gray image without alpha (luminance by Rec. 709 weights, divided so a black-to-white step gives full scale at `scale: 1`); it refuses CMYK and Lab.
- **`Convolve`** applies the kernel as written (correlation, not flipped), needs odd width and height, divides by the sum of the weights unless you pass `divisor:` (1 when the sum is 0), then adds `offset:` as a fraction of full scale. A rank-one kernel runs as two 1-D passes, with the same result.
- **Large blurs are approximated.** Gaussian sigma above 16 and box radius above 48 are computed on a reduced-resolution copy and enlarged, to keep streaming memory bounded. The result stays within a few 8-bit levels of the exact blur on photographs; see the XML docs for the measured difference. Below those limits the result is exact.
- Results do not depend on the thread count.

**Effects**

```csharp
img.Pixelate(size: 8);                                   // mosaic; each block takes its center pixel
img.OilPaint(levels: 10, brushSize: 15);                 // painterly flattening
img.Vignette(new Rgba32(0, 0, 0, 255));                  // darken towards the corners; radiusX:, radiusY:, area: are optional
img.Glow(new Rgba32(255, 255, 255, 255), radius: 200);   // a radial tint, full color at the center
img.BokehBlur(radius: 32, components: 2, gamma: 3);      // lens blur; bright points bloom into discs
img.GaussianSharpen(sigma: 3);
img.DetectEdges(EdgeDetector.Kirsch);                    // also Prewitt, Scharr, RobertsCross, Kayyali, Laplacian3x3/5x5, LaplacianOfGaussian, Robinson, Sobel
img.DetectEdges(EdgeDetector.Scharr, grayscale: false);  // per color channel, keeps format and alpha
img.EntropyCrop(threshold: 0.5f);                        // crop to the area with detail (eager, like Trim)
```

They are lazy (except `EntropyCrop`), read only their tile plus a margin (the radius, brush half-width or kernel size; none for `Pixelate`, `Vignette` and `Glow`), and apply to every frame.

- **Working space.** These work on stored values (not linear light), as ImageSharp does; `GaussianSharpen(linear: true)` is the one that can switch. `OilPaint`, `Vignette`, `Glow` and `DetectEdges` accept gray and RGB images and refuse CMYK and Lab; `Pixelate` takes any format.
- **Edges.** `BokehBlur`, `GaussianSharpen` and `DetectEdges` take `edge:` as the other filters do (clamp by default).
- **Limits.** `BokehBlur` radius is 1 to 255 with 1 to 6 components (cost grows with the radius, not its square); `GaussianSharpen` sigma up to 42; `OilPaint` brush up to 255 and up to 1024 levels.
- **`Vignette` and `Glow`** blend the color over the pixel (source-over, its alpha times the falloff). The vignette falloff is `0.9 * distance / sqrt(rx^2 + ry^2)`; the glow's is `1 - 0.95 * distance / radius`. Pass `area:` to confine the effect to a rectangle and center it there. The default glow color is black, as in ImageSharp.
- Results do not depend on the thread count.

**Histograms, thresholds and dithering**

```csharp
img.AutoLevel();                                                      // stretch the luminance histogram; syncChannels: false curves each channel
img.AdaptiveThreshold();                                              // black and white against the mean of the surrounding window
img.BinaryDither(Dither.Bayer8x8);                                    // two colors, any of the dithers; upper:, lower: set the colors
img.Dither(KnownPalettes.WebSafe, Dither.FloydSteinberg);             // your own palette; scale: weakens it; fastMatch: false matches every pixel exactly
img.Quantize(64, Dither.Atkinson, quantizer: Quantizer.Octree);       // Wu (default), Octree, WebSafe or Werner
```

They are lazy and apply to every frame. `AutoLevel` counts the 8-bit luminance (Rec. 709) histogram exactly, so results do not depend on the thread count. `AdaptiveThreshold` reads a margin of `width / 16` pixels around each tile. Ordered dithers run per tile; error diffusion runs once, in row order, when the first tile is requested, and gives the same pixels whatever the thread count.

**Histogram equalization**

```csharp
img.HistogramEqualization();                                                    // global; 256 levels, no clipping
img.HistogramEqualization(HistogramEqualizationMethod.AdaptiveTileInterpolation, clipHistogram: true);   // local contrast on an 8 x 8 grid, clipped at 350
img.HistogramEqualization(HistogramEqualizationMethod.AdaptiveSlidingWindow, tiles: 16);                 // a window around every pixel; slower
img.HistogramEqualization(luminanceLevels: 65536);                              // 16-bit images at full precision
```

It works on gray and RGB images, is lazy, and applies to every frame. The luminance (Rec. 709 weights) of each pixel is mapped through the cumulative histogram; **an RGB pixel becomes gray**, since the new luminance is written to all three channels (this is what ImageSharp does too, and the output agrees with it within 1 level at 8 bits). Alpha is carried over. The global and tile methods count the whole image once before the first tile comes out; the sliding window needs only the neighborhood of each tile, but its cost per pixel grows with the window size (`width / tiles`). Clipping (`clipHistogram`, `clipLimit`) cuts bins above the limit and spreads the excess evenly in whole counts; the limit is an absolute count per bin, so it should scale with tile size. The XML docs describe the tile geometry, window edges and rounding in full. Results do not depend on the thread count.

**Analysis**

```csharp
ImageHistogram hist = img.Histogram();                    // 256 bins per channel
long darkRed = hist[0, 0];                                // channel 0 (R), bin 0
ReadOnlySpan<long> green = hist.Channel(1);

ImageStatistics stats = img.Statistics();
ChannelStatistics red = stats.Channels[0];                // Count, Min, Max, Mean, StdDev
```

Both compute the whole frame immediately, in parallel, and only read pixels (the image is not changed). They look at **frame 0**; use `img.Frames[i].Histogram()` / `.Statistics()` for another frame. Channels are in stored order with alpha last (gray; R, G, B; C, M, Y, K). Samples are the stored values: no color conversion, no un-premultiplying. `bins` is 1 to 65,536; 8-bit value `v` goes to bin `floor(v * bins / 256)`. `Statistics` values are in the channel's stored units (0..255, 0..65,535 or 0..1: see `FullScale`); `StdDev` is the population standard deviation. `skipTransparent: true` ignores pixels with alpha 0. Lab images are refused. Corrupt data throws `ImageFormatException` here, like any pixel pull.

## Pixel access and Canvas

Read pixels out of any `Image` as the struct you want. Formats are converted if they differ.

```csharp
Rgba32[] all = img.ToArray<Rgba32>();                           // frame 0
var block = new Gray8[16 * 16];
img.CopyPixelsTo(block, new ImageRect(100, 100, 16, 16));       // a rectangle
Image fromMemory = Image.FromPixels<Rgba32>(pixels, width, height);   // the other direction
```

Pixel structs: `Gray8`, `Gray16`, `GrayFloat`, `GrayAlpha8`, `Rgb24`, `Rgba32`, `Rgb48`, `Rgba64`, `RgbaHalf`, `RgbFloat`, `RgbaFloat`, `Cmyk32`, `LabFloat`. `Image.Format` is a runtime `PixelFormat` (`Rgb8`, `Rgba8`, `Gray8`, ...).

For editing, use a `Canvas`: a mutable image stored in 128×128 tiles created on first write.

```csharp
using Canvas canvas = img.ToCanvas();                 // tiles are computed on first touch
canvas[0, 0] = new Rgba32(255, 0, 0, 255);            // single pixel, converted to/from the canvas format

// Row access. T must match the canvas format exactly: a JPEG decodes to Rgb8, so T is Rgb24.
using (PixelLock<Rgb24> l = canvas.Lock<Rgb24>(new ImageRect(10, 10, 50, 50), LockAccess.ReadWrite))
{
    for (int y = 0; y < l.Height; y++)
    {
        l.GetRow(y).Fill(new Rgb24(0, 0, 0));
    }
}

Image before = canvas.Snapshot();                     // O(1), immutable
canvas[0, 0] = new Rgba32(0, 255, 0, 255);            // the snapshot does not change
```

- `Lock<T>` never converts. With a mismatched `T` it throws an `ArgumentException` that names the canvas format and the matching struct; to read in another pixel type use `canvas.CopyTo<T>(...)` or `canvas.Snapshot().ToArray<T>()`.
- `Lock` access modes: `Read`, `Write` (you overwrite every pixel in the rectangle) and `ReadWrite`. Dispose the lock to commit.
- `new Canvas(width, height, PixelFormat.Rgba8)` makes an empty (transparent black) canvas.
- A canvas has one writer. Hand `Snapshot()` images to other threads. Snapshots share tiles and a tile is copied only when the canvas next writes it, so keeping many snapshots for undo is cheap.
- A canvas holds a single frame. `ToCanvas()` uses frame 0.

## Metadata

`Image.Metadata` carries `IccProfile`, `Exif`, `Xmp` and `Iptc` as raw blobs, plus `Orientation` (1–8).

- **Preserved by default.** `Load` → ops → `Save` keeps the ICC profile and the EXIF/XMP/IPTC blobs for formats that can carry them. On save, the EXIF block's pixel-dimension and orientation tags are corrected to the saved image. A malformed EXIF block is dropped instead of written with stale values.
- **Typed EXIF.** `image.Metadata.ReadExif()` (or `TryReadExif`) parses the common tags: `Orientation`, `Make`, `Model`, `CaptureTime`, `Gps`.

  ```csharp
  ExifData? exif = img.Metadata.ReadExif();
  string? make = exif?.Make;
  ```
- **Auto-orient at load.** By default `Load` applies the stored EXIF orientation lazily: `Width`/`Height` are the upright size and `Metadata.Orientation` reads 1, so saving writes upright pixels and an orientation tag of 1. Opt out for the stored layout and the original tag:

  ```csharp
  Image stored = Image.Load("photo.jpg", new LoadOptions { AutoOrient = false });
  ```
- **Strip it.** `StripMetadata()` removes EXIF, XMP and IPTC and the ICC profile; `StripMetadata(keepIcc: true)` keeps the profile. It leaves the orientation value alone, since that describes how to display the pixels.
- **`Thumbnail` strips for privacy.** EXIF can contain GPS position and device details, so `Image.Thumbnail` removes EXIF/XMP/IPTC and keeps only the ICC profile (converted to sRGB) and the corrected orientation. `keepMetadata: true` carries the blobs over, GPS included; use it knowingly.

## Color

- **Default: source space kept.** Decoding does not change color values. The embedded ICC profile travels with the image and is written back on save. `ConvertColor` and `AssignProfile` are explicit.
- **`Thumbnail` converts to sRGB** (relative colorimetric, black point compensation), so wide-gamut and CMYK sources look right everywhere.
- **Explicit conversion.**

  ```csharp
  Image p3   = img.AssignProfile(ColorProfile.DisplayP3);      // label only: values are unchanged
  Image srgb = p3.ConvertColor(ColorProfile.Srgb);             // converts values and embeds the profile
  Image perceptual = p3.ConvertColor(ColorProfile.Srgb, RenderingIntent.Perceptual, blackPointCompensation: false);
  ```

  `ConvertColor` defaults to relative colorimetric with black point compensation on. Built-in profiles: `Srgb`, `DisplayP3`, `WideGamutRgb` (Adobe RGB (1998)-compatible), `ProPhoto`, `Rec2020`, linear variants, gray, `LabD50` and `GenericCmyk`; `ColorProfile.FromIcc(bytes)` reads any ICC v2/v4 matrix or LUT profile. DeviceLink, named-color and iccMAX profiles are not supported.
- **Untagged CMYK** (a CMYK JPEG or TIFF with no profile) is interpreted with the built-in generic CMYK profile, derived from published FOGRA39 characterization data, when converting to RGB. See `THIRD-PARTY-NOTICES.md`.
- **Linear light.** Resizing, rotation and compositing with `linear: true` convert to linear light first, treating untagged RGB and gray as sRGB; tone ops and blends use encoded values unless told otherwise. Each op documents its `linear` parameter.
- HDR transfer functions (PQ/HLG) are not interpreted; `cICP` and similar tags are not applied.

## Animation and multi-page files

An `Image` has `FrameCount`, `Frames`, `LoopCount` (0 = forever) and a `Delay` per frame. GIF, APNG, animated WebP and multi-page TIFF load as multiple frames. Operations apply to every frame, so animation survives a pipeline:

```csharp
Image anim = Image.Load("spin.gif");
Console.WriteLine($"{anim.FrameCount} frames, loop {anim.LoopCount}, first delay {anim.Frames[0].Delay}");

anim.Resize(width: 60).Save("spin.webp");                 // all frames, delays and loop count are kept
Image still = anim.Frames[1].ToImage();                   // one frame as its own image
anim.Save("first.jpg");                                   // JPEG cannot animate: frame 0 only
```

Animations are exposed as fully composited frames of the canvas size (disposal and blending already applied). Members of `Image` that read pixels (`ToArray`, `CopyPixelsTo`, `ToCanvas`, `Histogram`, `Statistics`) use frame 0 only and ignore the rest, without warning; use `Frames[i]` (an `ImageFrame` has `ToArray`, `CopyPixelsTo`, `Histogram`, `Statistics` and `ToImage()`) for the others. Each TIFF page is a frame with its own size.

## Limits

Everything read from untrusted bytes is checked against `ImageLimits` using header values, before the allocation they guard.

| Limit | Default |
|---|---|
| `MaxPixelsPerFrame` | 2²⁸ |
| `MaxDimension` | 65,535 |
| `MaxFrames` | 1,000 |
| `MaxTotalPixels` | 2³⁰ |
| `MaxMetadataBytes` | 16 MB |
| `MaxExpansionRatio` (inflate/LZW output vs. input) | 1,100 |

```csharp
// Per call.
Image.Load("a.jpg", new LoadOptions { Limits = new ImageLimits { MaxPixelsPerFrame = 1_000_000, MaxDimension = 4096 } });
Image.Load("a.jpg", new LoadOptions { Limits = ImageLimits.Unrestricted });   // trusted input only

// Global default, set once at startup.
ImageConfiguration.Default.Limits = new ImageLimits { MaxPixelsPerFrame = 50_000_000 };
```

`ImageLimits.Unrestricted` removes the configurable bounds. Two engine caps remain: 2²⁴ pixels per dimension and 2²² tiles per frame. Exceeding a limit throws `ImageLimitException`. `Canvas` and `Save` take limits too.

## Threading and memory

- Rendering uses the .NET thread pool with 128×128 tiles as the unit of work. A single call uses at most `ImageEngine.DefaultCallDegree` threads (default `min(4, cores)`), so one request does not take a whole server. Override per call with `SaveOptions.MaxDegree` / `LoadOptions.MaxDegree` / the `maxDegree` parameter; `ImageEngine.MaxDegree` (default: core count) caps everything. Results never depend on the degree.
- Computed tiles are cached under a global byte budget, 256 MiB by default (`ImageEngine.CacheBudgetBytes`), least recently used first; an evicted tile is recomputed on demand. Canvas tiles are owned by the canvas and are not counted or evicted.

  ```csharp
  ImageEngine.DefaultCallDegree = 2;
  ImageEngine.CacheBudgetBytes = 64L * 1024 * 1024;
  ```
- Large images from sequential decoders (16 MiB of pixel data and up) stream through a window of tile rows instead of being held whole. An operation that needs rows out of order (rotate by 90° or 270°, a vertical flip) makes the engine decode the whole frame once.
- **Region reads of large JPEG and PNG files.** Such a frame streams through a window of rows, so `CopyPixelsTo` of a rectangle behind the window would have to decode again. The first region read keeps only the window. From the second on, the rows read are kept in a plane in the pixel format you ask for (`Gray8`, `Rgb24`, ...), filled from the top down only as far as needed, so reading 44 bands or 20 random rectangles costs about one decode plus the copies, even when the image is rotated by its EXIF orientation. The plane is capped by `ImageEngine.RegionCacheBytes` (default 64 MiB per frame, 0 turns it off); a frame whose plane does not fit behaves as before. The trade-off is memory held while the `Image` lives: about 8.7 MB for a Gray8 plane of an A4 page at 300 dpi and 26 MB for Rgb24 (one plane per format used, least recently used dropped). Call `image.ReleaseDecodedPixels()` when you are done reading regions; later reads decode again. Pixels read never depend on the cache. To read bands without keeping the plane, pass `useRegionCache: false` (`image.CopyPixelsTo(buffer, rect, useRegionCache: false)`): the read is served from the decoder's sliding window, so top-down bands decode the page once and hold a few tile rows, while a rect that goes back above the window, or a rotated image, decodes again for that call (more time, no retained memory). It does not touch the process-wide `RegionCacheBytes`, and a plane another caller already built is still used. `ReleaseDecodedPixels()` (on `Image`, `ImageFrame` and any image made from the frame, `frame.ToImage()` included) gives back all of it: the plane, the window and decoder thread, a decode kept as tiles, decoder block caches and the cached tiles of every operation above the decode; the image keeps working and recomputes the same pixels. Small frames (under 16 MiB in their own format) are not streamed: the second read of one keeps the decoded frame as tiles, a full copy of the frame, until you release it. Buffers the library returned to its pools (the 48 MiB tile pool, and the shared byte-array pool the TIFF decoder uses) stay resident for reuse and are not held by the image.
- `Image.Load(Stream)` copies the compressed file into pooled memory, once per image; `Image.Load(path)` and `Load(ReadOnlyMemory<byte>)` do not.
- `Image` instances are safe for concurrent reads. A `Canvas` is not.

## AOT and trimming

The library has no reflection, no dynamic code and no dependencies, and is annotated trimmable and AOT-compatible. Codecs are registered explicitly, so an app that only handles two formats can leave the others out of the published binary: build your own `ImageConfiguration` instead of touching `ImageConfiguration.Default` (which references every codec).

```csharp
var config = new ImageConfiguration().Add(JpegFormat.Instance).Add(PngFormat.Instance);

Image img = Image.Load("a.jpg", new LoadOptions { Configuration = config });
img.Save("a.png", new SaveOptions { Configuration = config });   // extension lookup uses this configuration
// Image.Load("a.webp", new LoadOptions { Configuration = config }) throws ImageFormatException: WebP is not registered.
```

Format-less entry points (`Thumbnail`, `Load` without options) use `ImageConfiguration.Default`; pass `LoadOptions` with your configuration when trimming matters. You can add your own `IImageFormat` the same way.

## Formats

| Format | Read | Write |
|---|---|---|
| PNG | all color types, depths 1–16, Adam7, tRNS, APNG | 8/16-bit gray, gray+alpha, RGB, RGBA; automatic or required palette (`PngColorMode`); APNG; levels 0–9; filter choice |
| JPEG | baseline, extended and progressive, Huffman or arithmetic, 8- and 12-bit, gray/YCbCr/RGB/CMYK/YCCK, restart markers; DCT scaling 1/2, 1/4, 1/8. Not lossless or hierarchical | baseline or progressive; quality 1–100; 4:2:0/4:2:2/4:4:0/4:4:4; optimized tables; gray, RGB and CMYK |
| WebP | lossy (VP8), lossless (VP8L), alpha, animation | lossy, lossless, alpha, animation |
| GIF | GIF87a/89a, animation, transparency, disposal, loop count | global/local palettes, ≤256 colors, dithering (none, Floyd–Steinberg, ordered), frame differencing |
| TIFF | strips and tiles, BigTIFF, none/LZW/Deflate/PackBits/JPEG/CCITT G3 and G4, predictors, planar, 1–16-bit and 32-bit float; gray/RGB/palette/CMYK; multi-page. Signed and 64-bit samples, plain YCbCr and CIELab are rejected with an error | none/LZW/Deflate/PackBits, 8/16/32f, multi-page, BigTIFF |
| BMP | 1–32 bpp, RLE, V4/V5 headers | 24/32 bpp |
| ICO | yes (BMP and PNG entries; each size is a frame) | yes |

Detection is by content, not extension. `Image.Identify` and `Image.TryIdentify` report format, size, frame count and metadata without decoding pixels.


<!-- https://recursiveai.org/oneimage/docs/web/ -->

# OneImage.Web: image processing for ASP.NET Core

`RecursiveAI.OneImage.Web` resizes, crops, converts and recompresses images on request, driven by URL commands, and caches the results on disk. It is built on the OneImage library, so a thumbnail of a 24 MP JPEG is decoded at reduced size rather than in full. It is a separate package: the core `RecursiveAI.OneImage` package stays free of ASP.NET Core. Target framework `net10.0`; no reflection, trimmable and NativeAOT-compatible (Razor tag helpers aside, which Razor itself does not support under AOT).

Contents: [quick start](#quick-start) · [commands](#commands) · [ImageSharp.Web compatibility](#imagesharpweb-compatibility) · [security defaults](#security-defaults) · [signed URLs](#signed-urls) · [caching](#caching-and-conditional-requests) · [providers](#providers) · [hooks](#hooks) · [how it works](#how-it-works) · [errors](#status-codes)

## Quick start

```sh
dotnet add package RecursiveAI.OneImage.Web
```

```csharp
using OneImage.Web;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOneImage();

var app = builder.Build();
app.UseOneImage();      // before UseStaticFiles
app.UseStaticFiles();
app.Run();
```

Now every image under `wwwroot` can be asked for in another size or format:

```text
/photos/cat.jpg?width=400                    400 px wide, same format, aspect ratio kept
/photos/cat.jpg?w=300&h=300&fit=cover        300 x 300, cropped around the center
/photos/cat.jpg?width=800&format=webp&q=80   WebP at quality 80
```

A request without commands is not touched and falls through to the static file middleware. `AddOneImage` takes the settings and returns a builder:

```csharp
builder.Services.AddOneImage(o =>
{
    o.MaxWidth = 2000;
    o.Presets["thumb"] = "width=200&height=200&fit=cover&format=webp";
    o.HmacSecretKey = Convert.FromBase64String(builder.Configuration["Images:Key"]!);
})
.ConfigureCache(c => c.CacheRootPath = "/var/cache/images");
```

In Razor, `@addTagHelper *, OneImage.Web` enables `<img src="~/photos/cat.jpg" oi-width="400" oi-format="webp" />`, which writes the URL with the commands and, when a key is configured, the signature. In code, `ImageUrlSigner.Sign("/photos/cat.jpg?width=400")` does the same.

## Commands

Names are case-insensitive. Each command may appear once; two spellings of the same command with different values fail with 400.

| Command (aliases) | Values | Default | Meaning |
|---|---|---|---|
| `width` (`w`), `height` (`h`) | 1 to `MaxWidth` / `MaxHeight` | none | Target size. With one of them the other follows the aspect ratio. With none the size is kept. |
| `fit` | `contain`, `cover` (`crop`), `stretch`, `pad` | `OneImageOptions.DefaultFit` (`contain`) | How the image fills a width-and-height box. |
| `anchor` (`ranchor`) | `center`, `top`, `bottom`, `left`, `right`, `topleft`, `topright`, `bottomleft`, `bottomright`, `smart` | `center` | Which part a crop keeps or where padding goes. `smart` picks the busiest part. |
| `focus` (`xy`) | `x,y`, each 0 to 1 | none | A focal point for `cover` with both sizes; the crop is centered on it as far as the edges allow. Replaces `anchor`. |
| `upscale` | `1`/`0`, `true`/`false` | `DefaultUpscale` (`false`) | Allow enlarging past the source size. |
| `filter` (`rsampler`) | `auto`, `nearest`, `box`, `bilinear` (`triangle`), `catmullrom` (`bicubic`), `mitchell`, `lanczos2`, `lanczos3` | `auto` | Resampling filter. Lanczos3 when shrinking, Catmull-Rom when enlarging. Resampling always happens in linear light. |
| `bg` | color | none | Padding color and the color transparency is flattened onto. |
| `format` (`fm`) | `jpeg`/`jpg`, `png`, `webp`, `gif`, `bmp` (those in `AllowedFormats`) | the source format if allowed, else PNG | Output format. |
| `quality` (`q`) | 1 to 100 | encoder default (75) | JPEG and WebP quality. Ignored for other formats. |
| `orient` (`autoorient`) | `1`/`0` | `1` | Apply the EXIF orientation. |
| `preset` | a name from `Presets` | none | A stored command string. Explicit commands override its values. |

Colors are `rgb`, `rgba`, `rrggbb` or `rrggbbaa` hex (with or without `#`, which must be sent as `%23`), `r,g,b[,a]` numbers, or `white`, `black`, `transparent`, `red`, `green`, `blue`, `yellow`, `gray`.

**Unknown parameters** are ignored by default and take no part in the cache key, so `?width=100&utm_source=x` and `?width=100` are one cache entry. `UnknownCommands = Reject` makes them 400 errors (list the ones that belong to other middleware in `IgnoredParameters`). A request with no recognized command is not processed.

**Invalid values** (`width=abc`, `quality=0`, an unknown format or preset) are 400 errors; nothing is silently clamped.

**Presets only.** `PresetsOnly = true` honors `preset` and nothing else; all other parameters are ignored. The set of possible results is then the presets times your files, which is the right setting for a public site that does not sign its URLs.

## ImageSharp.Web compatibility

The ImageSharp.Web 3.2.0 spellings are accepted alongside ours, so existing URLs keep working:

| ImageSharp.Web | Here |
|---|---|
| `width`, `height` | same |
| `rmode=crop` / `pad` / `boxpad` / `max` / `min` / `stretch` | `crop` is `fit=cover` with enlarging, `pad` is `fit=pad`, `boxpad` is `fit=pad` without enlarging, `max` is `fit=contain` without enlarging, `min` scales to cover the box without cropping, `stretch` is `fit=stretch`. `manual` is not supported and fails with 400. |
| `ranchor` / `anchor`, `xy` | same (`anchor` also accepts `smart`) |
| `rsampler` | `nearest`, `box`, `triangle`, `bicubic`, `mitchell`, `lanczos2`, `lanczos3`. `welch`, `hermite`, `spline`, `robidoux`, `lanczos5` and `lanczos8` are not available and fail with 400. |
| `color` | padding color |
| `bgcolor` | the color transparency is flattened onto |
| `orient` / `autoorient`, `format`, `quality` | same |
| `compand` | accepted and ignored: resampling is always in linear light |
| `preset` (preset-only parser) | `PresetsOnly` |

Defaults differ in one place: ImageSharp.Web crops when a width and a height are given without a mode, and enlarges. Call `options.UseImageSharpDefaults()` (it sets `DefaultFit = Cover` and `DefaultUpscale = true`) for the same behavior. HMAC tokens are not interchangeable with ImageSharp.Web's (see below); regenerate signed URLs.

Setting mapping: `BrowserMaxAge`, `CacheMaxAge`, `CacheHashLength`, `OnParseCommandsAsync`, `OnBeforeSaveAsync`, `OnProcessedAsync` and `OnPrepareResponseAsync` keep their names; `HMACSecretKey` is `HmacSecretKey`. ImageSharp.Web's custom `IImageWebProcessor` classes have no equivalent: do the extra work in `OnBeforeSaveAsync`, which receives the lazy `Image`.

## Security defaults

The defaults assume the endpoint is public and unauthenticated.

- **Output size is bounded.** `MaxWidth` and `MaxHeight` default to 4096 and `MaxOutputPixels` to 16,777,216. They apply to requested values (400 at parse) and to the resulting image, including when no size is requested, so re-encoding a 24 MP photo needs a higher `MaxOutputPixels`.
- **Source size is bounded.** `MaxSourceBytes` (64 MiB, 413) and `SourceLimits`, the library's decoding limits with 2^27 pixels per frame, 2^28 in total and 500 frames (413). A decompression-bomb file fails before its pixels are allocated.
- **Query length** is capped at 1024 characters.
- **Work is bounded.** At most `MaxConcurrentProcessing` images (the processor count, at least 2) are processed at once; others wait.
- **Cache growth.** Without a signing key, every distinct valid combination of commands creates a cache entry, and nothing deletes entries. On a public site use `HmacSecretKey` or `PresetsOnly`, or restrict values in an `OnParseCommandsAsync` hook (for example snapping widths to a list). Stale and unwanted entries can be removed by deleting files in the cache folder at any time.
- **No path escapes.** Providers never serve a path outside their root; the physical provider also hides dot-files. Only paths with a known image extension are looked at.
- **Metadata.** EXIF, XMP and IPTC are removed (they can contain GPS positions); the ICC profile stays and the pixels are converted to sRGB as `Image.Thumbnail` does. `KeepMetadata = true` keeps them.
- **Cache folder** defaults to `oneimage-cache` in the content root, not under `wwwroot`, so cached files are only reachable through the middleware.
- Error responses are fixed short texts; they never echo input or file paths.

## Signed URLs

Set `HmacSecretKey` (at least 32 random bytes) and every request that carries commands must carry a valid `hmac` parameter, or it fails with **403**. Choose `HmacAlgorithm.Sha256` (default), `Sha384` or `Sha512`.

The token is the lower-case hex HMAC of the request path (decoded, with the path base) followed by `?` and the raw query string without the `hmac` parameter, exactly as sent. Any change to the path or the query, including the order of parameters, invalidates it. The token is compared in constant time. There is no expiry in this version; rotate the key to revoke.

```csharp
var signer = app.Services.GetRequiredService<ImageUrlSigner>();
string url = signer.Sign("/photos/cat.jpg?width=400&format=webp");
// /photos/cat.jpg?width=400&format=webp&hmac=3f8a...
```

`HmacUtilities.ComputeToken(value, key, algorithm)` and `HmacUtilities.SignedText(path, query)` are available for signing from other code. Requests without recognized commands need no token (they are not processed), and presets need one too when a key is set.

## Caching and conditional requests

**Cache key.** `PathCacheKey` builds `request path + newline + canonical commands`. The canonical text is the *normalized* command set with every default applied (`ProcessingCommands.ToCanonicalString()`, for example `v1;w=400;fit=Contain;anchor=Center;filter=Auto;up=0;fmt=webp;q=80;orient=1;meta=0`), plus `CacheSalt` if set. Aliases, parameter order, case and unknown parameters therefore do not create separate entries. `HostPathCacheKey` also includes the host. Replace the key with `SetCacheKey<T>()`.

**Cache hash and layout.** `Sha256CacheHash` hashes the key; the first `CacheHashLength` hex characters (default 32, 12 to 64) name the files, spread over `CacheFolderDepth` folders (default 2) of `CacheFolderNameLength` characters (default 2): `cache/ab/cd/abcd....img` and a `.meta` text record. The record holds the full hash, so a collision on the shortened name causes a reprocess, never a wrong image.

**Invalidation on source change.** The record stores the source's modification time and length. On each request the provider's current values are compared; any difference reprocesses the image and replaces the entry. Entries older than `CacheMaxAge` (365 days) are replaced too. `CacheSalt` invalidates everything at once.

**Writing.** Files are written under a temporary name and renamed, the record last, so readers never see partial entries and several processes can share a folder. If a cache file was deleted, the next request rebuilds it. A failing cache write is logged and the response is still served.

**Response headers.** `ETag` (derived from the key hash and the source version, so it is known without reading the cache), `Last-Modified` (the source's), `Cache-Control: public, max-age=<BrowserMaxAge>` (7 days; zero sends `no-cache`), `Content-Type`, `Content-Length` and `X-Content-Type-Options: nosniff`. `If-None-Match` (weak comparison, `*`) and `If-Modified-Since` produce **304** without reading or processing anything. `HEAD` is answered with the headers only.

**Concurrent identical requests** are processed once: the first request starts the work, the others wait for it (and may give up if their client disconnects, without cancelling the work). The source version is part of that wait key, so a request for a newer source never receives the older result.

## Providers

A provider finds the source file for a request. Providers are asked in registration order until one returns a source; a provider can restrict itself to a path prefix.

| Provider | Source |
|---|---|
| `WebRootImageProvider` | `wwwroot` (registered by default) |
| `PhysicalFileImageProvider(root, behavior, prefix)` | any folder, under a URL prefix |
| `FileProviderImageProvider(IFileProvider, behavior, prefix)` | any `IFileProvider` |
| your own `IImageProvider` | databases, blob storage, anything with a modified time and a length |

`ProcessingBehavior.CommandOnly` (default) processes only requests with commands; `All` also re-encodes plain requests.

```csharp
builder.Services.AddOneImage()
    .ClearProviders()
    .AddProvider(_ => new PhysicalFileImageProvider("/srv/photos", requestPathPrefix: "/photos"))
    .AddProvider<MyBlobProvider>();
```

`SetCache<T>()`, `SetCacheKey<T>()` and `SetCacheHash<T>()` replace the other parts. An `IImageCache` needs two methods (get and set by hash).

## Hooks

| Hook | When | Typical use |
|---|---|---|
| `OnParseCommandsAsync` | after the query was read and the signature checked | add `format=webp` when the browser accepts it (add a `Vary: Accept` header in `OnPrepareResponseAsync`), snap sizes |
| `OnBeforeSaveAsync` | on the lazy result image, before encoding | watermark, extra filters (change `CacheSalt` when it changes) |
| `OnProcessedAsync` | after an image was actually processed, not on cache hits | metrics |
| `OnPrepareResponseAsync` | before any response of the middleware, 304 included | headers |

## How it works

For an image request the middleware, in order: ignores non-GET/HEAD requests and paths without an image extension; reads the commands (expanding a preset); verifies the signature; runs `OnParseCommandsAsync`; asks the providers for the source; validates and normalizes the commands against the limits; computes the cache key, hash and ETag; answers 304 if the client's validators match; looks in the cache and checks the source version; otherwise processes once (see above) and stores the result.

Processing is the library's thumbnail pipeline: the source bytes are read once (bounded by `MaxSourceBytes`), decoded lazily with the configured limits, resized (JPEG sources are decoded at 1/2, 1/4 or 1/8 size when the target allows), converted to sRGB, stripped of EXIF/XMP/IPTC, flattened for formats without alpha, and encoded.

## Status codes

| Code | When |
|---|---|
| 200, 304 | served; not modified |
| 400 | invalid, unknown (when rejecting), conflicting or over-limit command; long query; result over the output limits |
| 403 | missing or wrong `hmac` while a key is configured |
| 413 | source file over `MaxSourceBytes`, or over the decoding limits |
| 415 | the source is not a readable image |
| 422 | the image could not be processed |
| (next middleware) | no recognized command, no such file, other method or extension |

## Not included yet

Cloud storage providers and caches, per-URL expiry for signed links, a fluent URL builder, an in-memory result cache in front of the disk cache, and automatic cache cleanup.


<!-- https://recursiveai.org/oneimage/docs/text/ -->

# Text

Fonts and text for `Image` and `Canvas`, in the separate package `RecursiveAI.OneImage.Text` (namespace `OneImage.Text`, one dependency besides OneImage, the font library [`RecursiveAI.OneFont`](https://www.nuget.org/packages/RecursiveAI.OneFont) 1.2 or later, which has none of its own). Text is drawn through the vector drawing layer: the laid-out text becomes one `Path` of glyph outlines, filled with a `Brush` and/or stroked with a `Pen` like any other path. See [drawing.md](https://recursiveai.org/oneimage/docs/drawing/) for brushes, pens, blend modes and anti-aliasing.

```csharp
using OneImage;
using OneImage.Drawing;
using OneImage.Text;

var fonts = new FontCollection();
FontFamily family = fonts.Add("NotoSans-Regular.ttf");
Font font = family.CreateFont(32);                       // 32 points = 32 px at the default 72 dpi

var options = new TextOptions(font)
{
    Origin = new(40, 60),
    WrappingLength = 400,
    HorizontalAlignment = HorizontalAlignment.Left,
};

Image img = Image.Load("photo.jpg")
    .DrawText("Hello, world. Wrapped at 400 px.", options, Brush.Solid(new Rgba32(255, 255, 255, 255)));

TextMetrics m = TextMeasurer.Measure("Hello", options);   // advance size, ink bounds, lines
Path outline = TextBuilder.GeneratePath("Hello", options);  // fill, stroke, transform or clip it yourself
```

## Built on OneFont

Font parsing and text shaping come from `RecursiveAI.OneFont`; this package adds what is specific to drawing text on images. From OneFont:

- TrueType, OpenType (CFF) and TrueType Collection parsing, the character map, metrics, kerning and unhinted glyph outlines;
- the GSUB/GPOS engine and the Arabic, Indic, Universal Shaping Engine, Thai and Lao shapers, through `ShapeCodePoints` (code points in, glyphs with their code points and clusters out, with the script carried from run to run) and `ShapedRun` (flat arrays, no allocation per call once warm);
- the Unicode bidirectional algorithm (levels, rule L1, display order), line break opportunities, grapheme clusters, East Asian width, joining types.

Here: WOFF 1.0 and WOFF 2.0 (with the library's own inflate and Brotli), which are unpacked and handed to OneFont as a plain font; TrueType hinting; vertical metrics; COLR/CPAL color glyphs; the Vertical_Orientation data (UAX #50); word breaking modes and justification; the layout of paragraphs, runs, fallback, decorations and paths; measuring; and turning outlines into paths and pixels. A glyph id the shaper returns that the font does not have (a damaged character map) is drawn and measured as the missing glyph. Damage in a font is reported as this package's `FontFormatException`, not OneFont's.

## Fonts

`FontCollection` loads TrueType (glyf, quadratic) and OpenType with CFF outlines (CFF1: name-keyed and CID-keyed, local and global subroutines, flex), TrueType Collections (`AddCollection` adds every face) WOFF 1.0 (decompressed with the library's own inflate) and WOFF 2.0 (see [WOFF2](#woff2)). CFF2 is not read, and Type 1 hinting is ignored; TrueType instructions run only when asked for (see [Hinting](#hinting)). A variable font draws its default instance. Add from a path, a `Stream` or memory; faces with the same family name join one `FontFamily`, one face per `FontStyle`. `FontFamily.CreateFont(size, style)` picks the closest face when the style is missing and never synthesizes bold or slant.

Tables read: `cmap` (formats 0, 4, 6, 12, 13; the best Unicode subtable), `head`, `hhea`, `hmtx`, `maxp`, `OS/2`, `name`, `post`, `loca`/`glyf`, `CFF `, `kern` (format 0, Microsoft and Apple headers), `GDEF`, `GSUB` and `GPOS` (see [Shaping](#shaping)), and `COLR` and `CPAL` (see [Color fonts](#color-fonts)). Fonts are untrusted input: parsing is bounds-checked safe code, counts are checked against table lengths before anything is allocated, composite glyphs are flattened with an explicit stack (depth 8, 512 components), and the charstring interpreter bounds its operand stack, subroutine depth and operator count. A malformed font throws `FontFormatException` (an `ImageFormatException`), at load for the header tables and lazily, when the glyph data is first used, for the rest. Damaged `GDEF`, `GSUB`, `GPOS`, `COLR` and `CPAL` tables never throw: what cannot be read is ignored (see [Shaping](#shaping)). `fuzz/run.sh font` covers all of it, and `fuzz/run.sh brotli` the decompressor under WOFF2.

`FontMetrics` reports design units: `Ascender`, `Descender` (negative), `LineGap`, `LineHeight`, underline and strikeout, x-height and cap height. The vertical metrics are the OS/2 typographic ones when the font sets the `USE_TYPO_METRICS` flag, else `hhea`.

## WOFF2

`FontCollection.Add` and `AddCollection` read WOFF 2.0 files (W3C WOFF 2.0, 2018) from a path, a stream or memory, whether they hold one font or a collection (`AddCollection` adds every face; shared tables are decoded once). Everything the format defines is read: the table directory with known and custom tags, the Brotli-compressed table block, the transformed `glyf`/`loca` pair (the streams of contour counts, points, flags, coordinates, composites, boxes and instructions, with the overlap flags) and the transformed `hmtx` (side bearings rebuilt from the glyph boxes). The metadata and private blocks are skipped. A transformed `glyf` gets a plain `loca` back in the format the header names, and `head.indexToLocFormat` is corrected if the file disagrees with itself. Reconstructed glyphs are written with plain 16-bit coordinates, so the table can be larger than the original; the outlines are the same.

The decompressor is the library's own Brotli (RFC 7932, decode only, safe managed code, with the static dictionary embedded as a resource); the BCL's `BrotliDecoder` wraps a native library and is not used. The Brotli stream is untrusted like everything else in the file: the output buffer grows with the data actually produced and never to a size read from the file, and it stops at the sum of the table sizes the directory declares (each at most 128 MiB, all at most 256 MiB) and at 2048 bytes of output per input byte (plus 64 KiB), so a tiny file that declares a huge table fails with a `FontFormatException` after allocating a few kilobytes. The window is the output itself, so there is no separate history buffer. Unknown table transforms, a missing composite box, a mismatched `glyf`/`loca` pair and extra or missing table bytes are rejected, as the specification says.

Measured on the 45 KB WOFF2 of the Noto Sans shaping subset (shared workstation, load 6 to 12, .NET 10.0.11, BenchmarkDotNet, local smoke numbers): loading it takes 1.0 ms and 557 KB against SixLabors.Fonts 2.1.3's 1.35 ms and 2.5 MB. The Brotli decoder alone runs at roughly 330 MB/s on text and 0.9 GB/s on font-like binary data, about half the speed of the native decoder behind `System.IO.Compression`.

## Units and layout

`Font.Size` is in points. Pixels = points × `TextOptions.Dpi` / 72, and the default dpi is 72, so a size is the pixel height of the em square. Everything else (origin, wrapping length, results) is pixels, y down. By default there is no hinting and no rounding ([Hinting](#hinting) is opt-in and changes drawn outlines only): advances, positions and bounds are unrounded floats, so a string's advance is the exact sum of its glyph advances in font units times the scale.

- **Lines.** Line breaks (LF, CR, CRLF, VT, FF, NEL, U+2028, U+2029) always start a line, except one at the very end of the text, which does not open an empty line. The line pitch is `Size × Dpi/72 × LineSpacing`; that is one em at the default spacing, not the font's own line height. The font's ascent and descent are centered in the line box: baseline = ascender − (natural line height − pitch) / 2.
- **Wrapping.** `WrappingLength` ≤ 0 means none. Lines end at the break opportunities of the Unicode line breaking algorithm (see [Line breaking and segmentation](#line-breaking-and-segmentation)). Spaces at the end of a line may hang past the limit and are left out of its width. By default a word longer than the limit keeps its own line and overflows (`WordBreaking.BreakWord` breaks it). Tabs advance `TabWidth` space widths (default 4).
- **Kerning** is on by default (`KerningMode.Normal`): the `kern` feature of the font (GPOS pair adjustment), or the legacy `kern` table when the font has no GPOS kerning. `KerningMode.None` switches the `kern` feature off; see [Shaping](#shaping).
- **Alignment.** `HorizontalAlignment` puts a box on the origin (left edge, center or right edge); the box is as wide as the widest line. `TextAlignment` Start keeps lines at the box's left edge. Center and End move each line by its slack against the wrapping length (the widest line when there is none), placing it in a box of that width positioned by the horizontal alignment. This reproduces ImageSharp's behavior, including that a centered block does not center its lines unless asked to. `VerticalAlignment` puts the block (lines × pitch tall) on the origin.
- **Measuring.** `TextMeasurer.Measure` gives `TextMetrics`: `Advance` (widest line without trailing spaces × lines × pitch; independent of origin and alignment), `Bounds` (the ink, exact curve extents, positioned), `LineCount` and per-line `LineMetrics`. `GetCharacterBounds` gives each character's (grapheme cluster's) advance box and ink box. Zero-width format characters (U+200B–U+200F, U+2060, U+FEFF, soft hyphen, bidi controls) are dropped from the layout.
- **Missing glyphs** draw the font's `.notdef` glyph, unless a fallback family has the character (see [Font fallback](#font-fallback)).

## Shaping

Text is shaped before it is laid out: code points go through the font's character map, then GSUB substitutions, then GPOS positioning, and the result is a run of glyphs with advances and offsets. Layout (wrapping, alignment, measuring, drawing) works on those glyphs only. The engine follows the OpenType specification and works for every script that needs no reordering, plus Arabic-style joining and Hebrew (see [Arabic and Hebrew](#arabic-and-hebrew)) and the Indic, Southeast Asian and USE scripts (see [Complex scripts](#complex-scripts-indic-southeast-asian-and-the-universal-shaping-engine)).

- **Tables.** `GDEF` glyph classes, mark attachment classes and mark glyph sets. `GSUB` lookup types 1 single, 2 multiple, 3 alternate, 4 ligature, 5 context, 6 chained context (all three formats of each context), 7 extension and 8 reverse chaining single. `GPOS` types 1 single, 2 pair (formats 1 and 2), 3 cursive, 4 mark-to-base, 5 mark-to-ligature, 6 mark-to-mark, 7 context, 8 chained context and 9 extension. All lookup flags apply: ignore base glyphs, ligatures and marks, mark attachment type, and mark filtering sets (a filtering set wins over an attachment type). Device and variation-index tables inside value records and anchors are skipped, since text is unhinted and a variable font draws its default instance.
- **Lookup order.** Lookups of the enabled features run in lookup-list order, as the specification says, in two stages: `ccmp` and `locl` first, then everything else. So `smcp` on `fi` changes the letters to small capitals before `liga` looks for a ligature, and the ligature does not form; ImageSharp ligates first.
- **Script and language.** Each stretch of one script (Latin, Greek, Cyrillic; spaces, digits and punctuation join the stretch they are in; combining marks follow their base; nothing substitutes or kerns across a change of script) is shaped with that script's feature set, falling back to `DFLT`, `dflt`, then `latn` when the font lacks the script. `TextOptions.Language` (a BCP 47 tag such as `"sr"`, `"ro"`, `"tr"`, `"ca"`, or an OpenType language tag in capitals such as `"SRB"`) picks the font's language system for the script; a language the font does not have uses the script's default. The default is no language.
- **Features.** The defaults for horizontal text are `ccmp`, `locl`, `rlig`, `liga`, `clig`, `calt`, `rclt`, `kern`, `mark`, `mkmk` and `curs`. `TextOptions.Features` takes `FontFeature` settings in order, later ones replacing earlier ones: `FontFeature.On("smcp")`, `FontFeature.Off("liga")`, or a value (`new FontFeature("salt", 2)` picks the second alternate; a value past the font's alternates leaves the glyph alone). `Kerning = KerningMode.None` is the same as `Off("kern")`, and an explicit `kern` setting wins over it. A tag the font does not have does nothing. A feature outside the default stages (`smcp`, `onum`, `dlig`, `ss01`...) runs in the second stage with the defaults.
- **Marks.** A mark is placed from the anchors of the font's `mark` and `mkmk` lookups: on the base, on a ligature's component (a mark that sat between components in the text belongs to the component it followed), or on the mark before it. A combining sequence the font composes through `ccmp` (a base and a mark becoming one glyph, or several marks becoming one) is substituted before positioning. The offsets move the glyph's outline only: advances, wrapping and `GetCharacterBounds` boxes still follow the pen.
- **Clusters.** A glyph stands for the characters from its `Index` on; a ligature is one glyph for several characters, so `GetCharacterBounds` returns one box for `fi`, starting at the `f`. A zero width non-joiner (U+200C), a zero width space (U+200B) and a soft hyphen (U+00AD) end a shaping run, so nothing ligates or kerns across them (the last two are line break opportunities, which a ligature would otherwise swallow); the other zero width format characters are dropped. A base and its combining marks, and the glyphs of one character the font splits into several, share one box, so wrapping and `GetCharacterBounds` work on grapheme clusters whatever the glyph run looks like; a line never ends inside a ligature.
- **Limits.** Fonts are untrusted. Every read is bounds-checked and a subtable that cannot be read is skipped. Contexts nest lookups at most 6 deep. A run may grow to eight glyphs per character plus 256, and may attempt at most 65,536 + 1,024 per character subtable applications (and 2^26 overall; a subtable that fails to read counts as 2,048, and a subtable the engine skips because it has a type it cannot use counts as 1, so a lookup of tens of thousands of such subtables cannot cost that many steps at every glyph); a run that exhausts the budget keeps what it has and applies no further lookups. A damaged GSUB/GPOS/GDEF header means the table is ignored, as if the font had none. Nothing here throws.

What the engine does not do yet: canonical reordering and composition of combining marks (a mark sequence is shaped as typed; the font's own `ccmp` handles the compositions it has), contour-point anchors, feature ranges inside a string, Apple `morx`/`kerx` layout, and the `GSUB`/`GPOS` FeatureVariations table. A script-specific shaper plugs in as a `ScriptShaper` (its feature stages and a hook on the glyph run) without touching the lookup engine.

## Direction and right-to-left text

Text is split into paragraphs at line feeds, and each paragraph runs the Unicode Bidirectional Algorithm (UAX #9, Unicode 17 data, from OneFont, which passes the official `BidiTest.txt` and `BidiCharacterTest.txt` in full). `TextOptions.TextDirection` sets the base direction: `Auto` (the default) takes each paragraph's direction from its first strong character and falls back to left to right; `LeftToRight` and `RightToLeft` force the paragraph level, and the algorithm still reorders embedded runs of the other direction. Plain left-to-right text, with no right-to-left capable character, skips the algorithm entirely.

- **Reordering.** Runs are reordered per wrapped line (rules L1 and L2), on the characters of the line, so a line break in the middle of a mixed paragraph reorders each line on its own. Trailing white space of a line takes the paragraph level and hangs past the line's visible end. Brackets are mirrored (rule L4 and bracket pairs, rule N0), by code point, or through the font's `rtlm` feature when it has one. Explicit embeddings, overrides and isolates (up to depth 125) are honored; their control characters have no advance and no glyph.
- **Alignment.** `TextAlignment.Start` and `End` follow the paragraph direction: `Start` is the right edge of a right-to-left paragraph. `HorizontalAlignment` is the physical left, center or right of the block and ignores direction. Justification stretches every line but the last and counts hanging spaces out.
- **Metrics.** `Lines` report characters in logical order: `Start` and `Length` are always a range of the string. `GetCharacterBounds` boxes are placed where the characters are drawn. A line never breaks inside a grapheme cluster.
- **Limits.** Embedding depth is bounded at 125 and the bracket stack at 63, as the algorithm says; run counts are bounded by the text length. Hostile text (160,000 characters of nested controls, brackets or alternating directions) lays out in time linear in its length (45 to 255 ms in the tests), and the `bidi` fuzz target covers it.

## Arabic and Hebrew

Arabic, Syriac and N'Ko go through a joining shaper. Each letter's form comes from the Joining_Type of its neighbours (transparent marks and ZWJ/ZWNJ are looked through or break the join as Unicode says), and the form features run in this order: `ccmp`, `locl`, `rtlm`; then `isol`, `fina`, `fin2`, `fin3`, `medi`, `med2`, `init` (each only on the letters of its form); then `rlig`; then `calt`; then `liga`, `clig`, `rclt`, `mset`; and `kern`, `mark`, `mkmk`, `curs` for positioning. Lam-alef and other ligatures come from the font's lookups, so a font without them gets plain joined forms. Digits after Arabic text pick up the Arabic script's lookups. Syriac Alaph forms (`fin2`, `fin3`, `med2` selection) are not implemented. Cursive attachment in right-to-left runs is implemented but no test font has `curs`, so it is untested.

Hebrew needs no joining: the generic shaper and the bidirectional algorithm place the letters, and points and cantillation marks attach through the font's `mark` and `mkmk` lookups. A mark keeps its offset from its base when a run is reversed, so marks stay on their letters.

Kerning does not cross a change of direction. The script of digits, spaces and punctuation is taken from the paragraph's neighbouring letters, so they use the lookups of the text around them.

### Agreement with SixLabors.Fonts

Checked against SixLabors.Fonts 2.1.3 through its public API, on one merged Noto Sans / Noto Sans Arabic / Noto Sans Hebrew subset (`tests/testdata/fonts/NotoSans-Bidi-Subset.ttf`, SIL Open Font License) covering Arabic joining forms, lam-alef, marks, tatweel, Arabic-Indic digits, Hebrew with points, and mixed English, Arabic and Hebrew paragraphs with numbers and brackets, in `Auto` and `RightToLeft`. Glyph ids are equal; glyph origins agree to 0.01 px except in the cases below. Line counts, line widths and the glyph order of each line are equal for four mixed paragraphs at four wrapping lengths.

Deliberate differences:

- **(a) Kerning across Hebrew points.** The font's kern lookup ignores marks, so we kern the letters on either side of a point; SixLabors.Fonts does not. Up to 2 px at 40 px; identical with kerning off.
- **(b) The space after a Hebrew letter** across a change of direction is 10 font units (0.4 px at 40 px) wider in SixLabors.Fonts; we use the font's advance.
- **(c) Direction controls.** SixLabors.Fonts gives embedding, isolate and override controls a 0.6 em advance each; we give them none. Glyph ids still agree.
- **(d) Forced direction.** With `TextDirection.LeftToRight` SixLabors.Fonts does no reordering at all, and with `RightToLeft` it reverses the whole line, even Latin words and digits. We apply UAX #9 with the paragraph level forced, so Latin words and numbers in a right-to-left paragraph stay readable.
- **(e) One direction per text or per paragraph.** SixLabors.Fonts takes one direction for the whole string; we take it per paragraph (UAX #9 rule P1), so a string with an English line and an Arabic line lays out each in its own direction.
- **(f) Alignment of wrapped right-to-left paragraphs** that mix Latin words or numbers: SixLabors.Fonts left-aligns some lines of such a paragraph; every line of ours starts at the paragraph's start edge, the right.
- **(g) Font fallback.** With a fallback face SixLabors.Fonts applies the primary font's GDEF and GPOS to fallback glyph ids, and digits after Hebrew in a Hebrew-primary font come out with zero advance. We shape each face with its own tables.

## Complex scripts: Indic, Southeast Asian and the Universal Shaping Engine

Three shapers, in OneFont, are chosen by the script of a run (the tags, Indic_Syllabic_Category, Indic_Positional_Category and the canonical two-part decompositions come from the Unicode Character Database 17.0.0).

- **Indic shaper:** Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada and Malayalam, following Microsoft's Indic script-development documents (the v2 tags `dev2`, `bng2`... first, then the v1 tags). Text is cut into syllables (consonant clusters with halants, ZWJ/ZWNJ, matras, nukta, modifiers, standalone vowels), split vowels are decomposed, the base consonant is found, a reph is moved, pre-base matras go to the front, and features run in the documented order: `locl`, `ccmp`, then `nukt`, `akhn`, `rphf`, `rkrf`, `pref`, `blwf`, `abvf`, `half`, `pstf`, `vatu`, `cjct`, then `init`, `pres`, `abvs`, `blws`, `psts`, `haln`, `dist`, `abvm`, `blwm` with the default positioning features. A mark with no base gets a dotted circle (U+25CC) as its base.
- **Universal Shaping Engine shaper:** Khmer, Myanmar, Sinhala, Tibetan, Balinese, Javanese and the other scripts of the USE list, from the USE specification (syllable categories from the Indic_Syllabic_Category and Indic_Positional_Category properties) with Khmer and Myanmar specifics: coeng + ro, pre-base vowels and medials, the Khmer split vowels (U+17BE, 17BF, 17C0, 17C4, 17C5 become U+17C1 plus a sign), kinzi and stacked consonants.
- **Thai and Lao:** SARA AM (U+0E33, U+0EB3) is split into NIKHAHIT and SARA AA, and the nikhahit moves in front of the tone mark that precedes it, as the Thai script document says. Marks are placed by the font's `mark`/`mkmk` lookups and contextual substitutions.
- **Line breaking** for Thai, Lao, Khmer and Myanmar stays UAX #14 without dictionaries: their letters are class SA and are treated as letters, so there is a break opportunity only at spaces, punctuation and explicit zero width spaces, not inside a word. Text without spaces therefore wraps only where the author put a ZWSP. Grapheme clusters (UAX #29) keep a syllable's marks with their base.
- **Limits.** A syllable is cut after 48 glyphs; runs over 4,096 glyphs are shaped in pieces of 2,048 glyphs cut at syllable boundaries, so the cost is linear (400,000 hostile characters shape in under 2 s). Reordering and dotted circle insertion are bounded by the syllable cut. Fonts with damaged tables behave as for any script (see Shaping).
- **Choices that follow the documents, not the reference.** ZWJ and ZWNJ are never skipped by lookup flags; their glyphs are removed before positioning. ZWJ after a consonant and halant asks for the half form, ZWNJ denies it. A reph forms only when the font's `rphf` changes Ra + halant. Malayalam needs a ZWJ for a reph. The base consonant is found with probes of the font's `pref`, `blwf` and `pstf` lookups. A syllable's characters share one cluster value.

### Agreement with SixLabors.Fonts

Checked against SixLabors.Fonts 2.1.3 through its public API with 17 Noto subsets (`tests/testdata/fonts/Noto*-Subset-Regular.ttf`, SIL Open Font License, made by `tools/TextFonts/make-complex-fonts.py`) on 1,042 cases (`tests/testdata/complex/*.txt`: matras, reph, half forms, conjuncts, nukta, joiners, broken clusters, Tamil/Malayalam split vowels, Khmer coeng and pre-base vowels, Myanmar medials, Sinhala and Tibetan stacks, SARA AM). Glyph ids must be equal and glyph origins within 0.01 font units. The reference throws on 26 of the cases (NullReferenceException or IndexOutOfRangeException inside SixLabors.Fonts); those are not compared.

| script | cases | exact match | reference throws | deliberate differences |
|---|---|---|---|---|
| Devanagari | 157 | 149 | 0 | 8 |
| Bengali | 83 | 75 | 0 | 8 |
| Gurmukhi | 57 | 43 | 11 | 3 |
| Gujarati | 75 | 65 | 1 | 9 |
| Oriya | 67 | 63 | 0 | 4 |
| Tamil | 76 | 73 | 0 | 3 |
| Telugu | 75 | 61 | 4 | 10 |
| Kannada | 71 | 58 | 0 | 13 |
| Malayalam | 89 | 76 | 5 | 8 |
| Khmer | 54 | 43 | 5 | 6 |
| Myanmar | 39 | 16 | 0 | 23 |
| Sinhala | 32 | 26 | 0 | 6 |
| Tibetan | 31 | 25 | 0 | 6 |
| Thai | 45 | 41 | 0 | 4 |
| Lao | 27 | 25 | 0 | 2 |
| Balinese | 35 | 31 | 0 | 4 |
| Javanese | 29 | 27 | 0 | 2 |
| total | 1,042 | 897 | 26 | 119 |

Every difference is listed in `tests/testdata/complex/known-differences.txt` with a reason; the test fails if a listed case starts to match or an unlisted one differs. The reasons, and the rule each follows:

- **broken-cluster (61).** A mark without a base: we insert the dotted circle first, in logical order, and the mark follows it (a pre-base matra moves in front of the circle as it would in front of a consonant), as the Indic and USE documents describe. The reference puts the circle after the mark.
- **myanmar-reorder (21).** The reference does no reordering for Myanmar. We follow USE: the pre-base vowel E (U+1031) and medial Ra (U+103C) move before the consonant, a virama joins two consonants into the font's stacked form, and a consonant + asat + virama before a consonant becomes the font's kinzi. Checked on the glyph runs: for U+1000 U+1039 U+1000 we draw the stacked glyph where the reference draws the base, a visible virama and the base again; for U+1000 U+1031 the vowel comes first; for U+1004 U+103A U+1039 U+1000 we draw the font's kinzi glyph where the reference draws raw letters. Medial ya + wa (U+103B U+103D) uses the font's own ligature for the pair.
- **tibetan-extra-glyph (4).** For U+0F40 followed by U+0F73 or U+0F81 (and the sequence with U+0F71 U+0F72) we output the consonant with aa, then the vowel sign; the reference appends an extra dotted circle glyph (U+25CC), treating a valid stack as a broken one. We do not.
- **joiner-kerning (4).** ZWJ/ZWNJ glyphs are removed after substitution, so pair adjustment sees the neighbours next to each other. The reference positions with the joiner in between.
- **ignore-marks-pair (4), below-mark-offset (3).** Malayalam i/ii: a pair lookup with IgnoreMarks does not apply to a second glyph the GDEF table calls a mark (OpenType lookup flags); the reference applies it (5 font units). Gujarati u/uu/vocalic r: the font's contextual `dist`/`blwm` single positioning applies in ours and not in the reference.
- **sara-am (5).** The nikhahit goes in front of the tone mark (Thai script document); the reference leaves the tone mark and nikhahit overlapping.
- **kannada-conjunct (3).** We form the font's conjunct and conjunct + matra ligatures; the reference places the matra before the below-base consonant and breaks the ligature.
- **bengali-form (4), contextual-form (8), prebase-reorder (2).** The font's contextual variants or the ordering follow the font's tables and the documents in ours; the reference skips them. Checked on the glyph runs for Bengali ka + hasant + ka (we form the font's conjunct, the reference draws ka, a visible hasant and ka), Sinhala ka + al-lakuna + ZWJ + ra + e (the left vowel comes first in ours) and Khmer coeng + ka. The remaining members (Balinese, Javanese, Thai tone-mark variants, Sinhala ra + al-lakuna + ZWJ alone) differ because ours applies the font's substitution; we did not derive each one from a rule in the documents, so treat those as unproven and not as known errors of the reference.

Tolerances are exact for glyph ids and 0.01 font units for origins (lossless layout arithmetic). A font with the older v1 script tags only is shaped through the v1 tags; the v1-specific behaviors of the older engines (for example the pre-v2 reph handling) are not reproduced.

## Line breaking and segmentation

Where a wrapped line may end is decided by the Unicode line breaking algorithm, UAX #14, with the data of Unicode 17.0 (in OneFont). The default rules are used as written, with the small kana of class CJ treated as NS (the annex's strict reading). All of `LineBreakTest.txt` (19,338 cases) and `GraphemeBreakTest.txt` (766 cases) pass; the tests read the unmodified files from `tests/testdata/unicode`.

- **What breaks.** After spaces, hyphens (HY, HH) and en/em dashes, around the soft hyphen (U+00AD, a break after it, nothing drawn), after the zero width space, between ideographs and kana but not before closing punctuation or small kana, after a solidus before a letter ("a/b" in a URL or path), between emoji sequences and flag pairs but never inside one, and after hard breaks. It does not break in "$1,234.56", "-5.25", "12.5%", "(s)he", inside a word, after an opening bracket or quote even across spaces, before a closing bracket or quote, around the no-break space (U+00A0, U+202F), the word joiner (U+2060) or the zero width joiner, or inside a Korean syllable block. A line break character in the text always starts a new line first; the algorithm runs on each paragraph.
- **Grapheme clusters.** UAX #29 extended grapheme clusters (combining marks, emoji ZWJ sequences and modifiers, flags, Hangul jamo and syllables, Indic conjuncts) are never split: a line never starts inside one in any `WordBreaking` mode, and `GetCharacterBounds` returns one box per cluster (`Index` and `CodePoint` are the cluster's first code point; the box and ink cover the whole cluster).
- **`TextOptions.WordBreaking`** (needs a `WrappingLength`; names as in ImageSharp):
  - `Standard` (default): lines end only at the opportunities above.
  - `BreakAll`: any cluster boundary is an opportunity (not in front of white space), so lines are filled to the length. CJK text fills exactly too.
  - `KeepAll`: `Standard`, but no opportunity right after an East Asian wide or fullwidth character, so CJK text breaks only at spaces. Other text is unchanged.
  - `BreakWord`: `Standard`, except a word that does not fit even on a line of its own is moved to a fresh line and then broken between clusters so it fills lines instead of overflowing (the CSS `overflow-wrap: break-word` behavior).
- **`TextOptions.TextJustification`** (needs a `WrappingLength`): `InterWord` adds the same width to every space inside a line (U+0020 and U+00A0, not tabs) and `InterCharacter` adds the same width after every cluster but the last, in both cases until the line is exactly the wrapping length. Like ImageSharp, every line is stretched, the last one and lines before a line break included; a line with nothing to widen, or one that is already too long, is left alone. Positions agree with SixLabors.Fonts 2.1.3 to 0.0001 px for both modes and all three text alignments.
- **Cost.** Segmentation is linear, runs once per paragraph over pooled arrays and allocates nothing in steady state (tested). Table lookups are two-stage over 64-code-point blocks.

## Color fonts

Color glyphs are on by default, as in SixLabors.Fonts (whose `TextOptions.ColorFontSupport` defaults to its COLR format): `TextOptions.ColorFontSupport` is `ColorFontSupport.MicrosoftColrFormat`, so `DrawText` on `Image` and `Canvas` paints the layers of COLR glyphs when the font has them. Set `ColorFontSupport.None` to draw every glyph as a plain outline filled with the brush. Fonts without COLR are not affected:

```csharp
var options = new TextOptions(font) { ColorPaletteIndex = 1 };            // color on by default; palette 1 of the font
img.DrawText("\u2600 sunny", options, Brush.Solid(new Rgba32(0, 0, 0, 255)));
```

- **What is read.** `COLR` version 0 (a base glyph is a stack of layer glyphs, painted bottom to top) with `CPAL` palettes (versions 0 and 1; the palette labels and types are ignored). `COLR` version 1 paint graphs are painted too, see [COLR version 1](#colr-version-1).
- **Palette.** `ColorPaletteIndex` (default 0) selects the `CPAL` palette; an index past the last palette selects palette 0, and `Font.ColorPaletteCount` tells how many there are. A layer whose entry does not exist is left out.
- **Foreground layers.** Palette index 0xFFFF means the text color: those layers are filled with the brush you pass, and nothing is drawn for them when there is none. Layers with a palette color are painted with it whatever the brush is (also when you pass only a pen). `opacity`, `blend`, `composition`, `antialias` and `linear` apply to every layer.
- **Pen.** The pen outlines the plain glyphs and the foreground layers, over all fills, as SixLabors.Fonts does; layers with their own color get no outline.
- **Order.** Plain glyphs first, then layer 0 of every color glyph, then layer 1, and so on, with layers of equal index and color merged into one fill. Colors of glyphs that overlap each other can therefore stack differently from glyph-by-glyph painting.
- **Layout is unchanged:** advances, wrapping and measuring use the base glyph. `TextBuilder.GeneratePath` and measuring never depend on `ColorFontSupport`; text as a path is the monochrome outline. `Font.HasColorGlyph(codePoint)` tells whether a code point has layers.
- **Damaged tables** are ignored and the font then has no color glyphs. With `ColorFontSupport.None`, or in a font or a text without color glyphs, the output is byte for byte the monochrome path.
- **In runs and fallback faces.** Color glyphs work wherever a glyph comes from: a run's own font, a font of a different size, or a fallback face. The foreground entry (0xFFFF) takes the brush of the run that owns the character (the brush you pass when the run has none), layers with a palette color keep that color, and the run's pen (or the one you pass) outlines the plain and foreground parts after all fills. The palette is `ColorPaletteIndex` of the options, applied to every face (an index past a face's last palette selects its palette 0).

## COLR version 1

Fonts with a `COLR` version 1 table (`BaseGlyphList`, `LayerList`, optional `ClipList`) paint their paint graphs when `ColorFontSupport` is on (the default). Glyphs that have only version 0 records still go through the layer path above; a version 1 glyph takes precedence when a font has both.

- **What is painted.** Solid fills; linear, radial and sweep gradients (with extend modes); glyph clips; layers; `PaintTransform`/`Translate`/`Scale`/`Rotate`/`Skew` (with their around-center forms); `PaintComposite` with all Porter-Duff and blend modes (`PLUS` is mapped to additive blending); `PaintColrGlyph` reuse. The glyph is drawn into a group the size of its ink and the group is filled onto the target, so opacity, `blend` and clipping apply to the whole glyph. The foreground color (palette index 0xFFFF) takes the run's brush; for a non-solid brush the color is sampled at the glyph's top-left pixel, and with no brush the foreground stops are transparent.
- **Budgets.** A paint graph is flattened with an explicit stack to at most 4096 nodes and depth 64; exponential sharing, very deep graphs, truncated tables and cycles cannot exhaust time or memory. A graph over budget, or a cycle, draws the plain glyph outline instead (Skia draws nothing for a cycle).
- **Differences.** Variable (`Var`) paint formats use their default values (no variation instance). Gradients interpolate non-premultiplied (straight) color, as Skia does; stops are rescaled to the first-to-last span. Edges of clip boxes are anti-aliased. Layout, measuring and `TextBuilder.GeneratePath` ignore paint graphs, as for version 0.
- **Agreement.** SixLabors.Fonts 2.1.3 has no version 1 support, so the reference is SkiaSharp (Skia's COLRv1 painter) on the googlefonts/color-fonts test font (`ColrV1-TestGlyphs.ttf`, Apache-2.0): 211 glyphs at 64 px, mean difference 0.36 levels (205 of 213 glyphs below 1.0; the worst non-cycle glyph 2.5, among the clip-box glyphs), excluding the two cyclic glyphs. The Skia comparison runs on Linux x64 only and is skipped where the native asset is missing.

## Vertical layout

`TextOptions.LayoutMode` takes the members of SixLabors.Fonts' `LayoutMode`: `HorizontalTopBottom` (default), `HorizontalBottomTop` (lines stack upward from the origin; each line still reads left to right), and the vertical modes `VerticalLeftRight`, `VerticalRightLeft`, `VerticalMixedLeftRight` and `VerticalMixedRightLeft`. In a vertical mode a line is a column: `WrappingLength` limits its height, `TextAlignment` works along it, and columns stack to the right (`LeftRight`) or left (`RightLeft`). `Measure(...).Advance` is (columns width, longest column).

- **Metrics.** Upright glyphs advance by `vmtx` (else the line height) and sit by `VORG` or the top side bearing (else one ascender below the cell top); the `vert` and `vrt2` features are on and `kern` is off for them, unless `TextOptions.Features` says otherwise. The plain vertical modes stand every character upright. The mixed modes follow UAX #50 Vertical_Orientation (Unicode 17): `U` and `Tu` stand, others lie rotated a quarter turn clockwise and advance by their horizontal advance. `Tr` and `Tu` are treated as `R` and `U` (no per-font test for a vertical form).
- **Placement.** Upright ideographs and kana (`U`, `Tu`) fill the em square, centered in the column; upright characters that would otherwise lie down (Latin in the plain modes) are centered by their ink. The rule was derived by probing SixLabors.Fonts 2.1.3.
- **Not applied in vertical modes:** bidirectional reordering, decorations and text on a path.
- **Agreement.** Against SixLabors.Fonts 2.1.3 on the CJK and Latin test fonts, all five non-default modes, wrapping off and at 100 px, at 40 and 24 px: 296 of 296 measurement and per-character ink cases within 0.02-0.03 px; 432 of 432 alignment cases (3 x 3 x 3 alignments, two wraps, two texts, four vertical modes).
- **Differences.** (1) In the mixed modes, when one column holds both upright and rotated characters, the reference widens the column by 0.282 em with the CJK test font (24 cases; cause not derived); ours keeps the column at the line pitch. (2) Wrapped CJK text: the reference ends a line one opportunity early after an ideograph, as in horizontal text (see above). (3) The behavior listed under "Not applied".

## Hinting

`TextOptions.HintingMode` is `None` by default. `HintingMode.Standard` grid-fits TrueType glyphs at the drawing size by running the font's own instructions (`fpgm`, `prep`, `cvt `, glyph programs), in safe code, with the rules of backward-compatible rendering as DirectWrite does for grayscale text: only y positions move, `GETINFO` reports interpreter version 40, and no point moves after both `IUP` instructions have run.

- **What changes.** Drawn outlines (`DrawText`, `TextBuilder.GeneratePath`) only. Measuring, advances, wrapping and x positions are exactly what `None` gives, so layout never depends on the hinting mode. Composite glyphs are hinted per component; the composite's own instructions are not run.
- **When it is skipped** (the unhinted outline is used): CFF fonts, fonts without instructions, `Path` text, vertical modes, super- and subscript runs, sizes below 4 or above 400 px per em, and any glyph or font program that fails.
- **Safety.** Font programs are untrusted. Budgets: 2^20 instructions for `fpgm`/`prep`, 2^18 per glyph program and 2^20 in total for all the programs of one top-level glyph (a composite's components share it, so a composite of any size costs at most 2^20 interpreter steps; when the total runs out the whole glyph is drawn unhinted, including components already fitted), call depth 32, stack, storage, CVT, twilight points and function counts clamped to `maxp` and fixed caps, `SLOOP` and `LOOPCALL` counts paid for in instructions, bounds-checked indexes, no function definitions in glyph programs. All arithmetic on font-controlled values is overflow-safe (no `Math.Abs` on the most negative integer, 128-bit intermediates in `ISECT`). The twilight zone is kept as `prep` leaves it, and each glyph program starts from its own copy, so points `prep` placed are visible to glyph programs and one glyph's changes never reach the next. Any violation aborts that program: the glyph (or the whole font at that size, for a failing setup program) is drawn unhinted, and nothing throws. Hinters and hinted outlines are cached per face and size (16 sizes, 8192 glyphs) and safe to use from many threads.
- **Agreement.** Black text on white at 9-16 px (24 cases: three strings, eight sizes) from a Latin subset of Noto Sans (ttfautohint instructions) against SixLabors.Fonts 2.1.3 with `HintingMode.Standard`: mean absolute level difference 0.45 (worst case 0.79), against 1.47 for our unhinted text and 1.49 between the reference's own hinted and unhinted output; hinting moves us closer in 24 of 24 cases. With a hand-hinted system font (DejaVu Sans or Liberation Sans, not committed) one exploratory run gave 0.70 against 1.40. Exact agreement is not expected for hand-hinted fonts.
- **Not supported:** other rendering modes (ClearType-style x hinting, the native ClearType mode of interpreter version 35) and hinting of rotated text.

## Rich text: runs, decorations and attributes

`TextOptions.TextRuns` gives parts of the text their own look. A `TextRun(start, end)` covers UTF-16 offsets `[start, end)` of the string passed to the call and can set:

| Property | Default | Effect |
|---|---|---|
| `Font` | null: `TextOptions.Font` | Face and size of the run. A run can use any family and style. |
| `TextAttributes` | `None` | `Superscript` or `Subscript` (below). |
| `TextDecorations` | `None` | Any of `Underline`, `Strikeout`, `Overline`. |
| `Brush`, `Pen` | null: the brush and pen of the `DrawText` call | Paint of the run's glyphs and of its filled decorations. |
| `UnderlinePen`, `StrikeoutPen`, `OverlinePen` | null | Strokes that decoration as a line with this pen (its width is the thickness) instead of filling a rectangle. |

```csharp
var options = new TextOptions(regular24) { Origin = new(20, 20), WrappingLength = 500 };
options.TextRuns.Add(new TextRun(0, 5) { Font = bold40, Brush = Brush.Solid(red), TextDecorations = TextDecorations.Underline });
options.TextRuns.Add(new TextRun(12, 13) { TextAttributes = TextAttributes.Superscript });
image.DrawText("Hello, rich world", options, Brush.Solid(black));
```

- **Resolution.** A character belongs to the last run in the list that covers it, otherwise to no run (the options' font, no decoration, the call's paint). Ranges are clamped to the text and empty ones ignored, so the work is linear in the text plus the number of runs however runs overlap. A run is read when the layout runs; `Clone()` copies runs.
- **Mixed sizes and faces.** Shaping, kerning and ligatures stay inside a stretch of one run and face. Each glyph carries its own scale, so widths, wrapping and alignment mix sizes freely. A line is as tall as the largest line pitch (`size × dpi/72 × LineSpacing`) of any glyph on it, and its baseline sits at the largest "ascent in the line box" (the font's ascent, with the leading split evenly above and below as described under *Units and layout*). Lines stack without gaps; an empty line takes the metrics of the run at its position. `LineMetrics` reports the line's own `Ascender`, `Descender` and `LineHeight`. A tab is `TabWidth` spaces of the space glyph of the run it sits in.
- **Decorations.** Positions come from the font of each glyph: the underline at `post` underline position and thickness, the strikeout at `OS/2` strikeout position and size, the overline one em plus the underline distance above the baseline with the underline's thickness (fonts with no such data get 1/20 em thick lines, an underline 1/10 em below and a strikeout 3/10 em above the baseline). The measures are the centers of the lines. A decoration runs from the pen position of the first decorated glyph to the end of the advance of the last one, as one rectangle across neighbouring glyphs of the same run, position and thickness, so it is continuous across glyphs, spaces and kerning; it restarts when the font or size changes, ends at the last visible glyph of each line (trailing spaces at a wrap are not underlined) and starts again on the next line. Decorations are painted like their run's glyphs, in the same path, and are left out of `Bounds` and ink boxes.
- **Super- and subscript.** The glyphs are scaled by the font's `OS/2` superscript or subscript size (x and y separately, by default 65 % by 60 % of the em), advances scale with them, and the baseline moves by the recommended y offset scaled by the vertical size (up for superscript, down for subscript). The line pitch of such a run is scaled by the vertical size too. Horizontal offsets are not applied. Decorations on such a run sit on the shifted baseline with scaled thickness.
- **Painting.** `DrawText` draws one path per distinct brush/pen pair (runs that share a brush and pen share a path), so a text with default paint is still one fill. `TextBuilder.GeneratePath` returns everything as one path, decorations as rectangles (a decoration stroked with its own pen has no outline and is left out). `DrawText` with every run painted accepts a null brush and pen.
- **Limits.** At most `TextOptions.MaxTextRuns` (16,384) runs; more throw `ImageLimitException`. Layout cost does not depend on how runs overlap; one style object is created per (run, face) actually used.

## Font fallback

`TextOptions.FallbackFontFamilies` lists families tried, in order, for characters the run's font cannot map. Up to `MaxFallbackFamilies` (32); more throw `ImageLimitException`.

- **Choosing.** For each grapheme cluster the first code point (zero-width and format characters and tabs never choose) is looked up in the run's face, then in the face of each fallback family that matches the run's style (or is closest to it), at the run's size. The first face with a glyph (a nonzero glyph id in its character map) shapes the whole cluster, so a base and its combining marks stay together. When no face has it, the primary face draws its missing-glyph box.
- **Shaping.** A stretch of one face is one shaping run, so ligatures and kerning never cross a change of face, and line breaking and wrapping work on the shaped glyphs as before.
- **Metrics.** A line takes its baseline from the largest ascent of the faces used on it, so a line with a fallback face of a taller ascent sits lower than the same line without it (the Noto Sans CJK subset, with an hhea ascent of 1.16 em against Noto Sans's 1.069 em, moves a line by 1.92 px at 40 px). Line height is the largest pitch (size-based), so it does not grow with a fallback face. Each face's own `OS/2`/`hhea` rule picks its ascender (typographic metrics when `USE_TYPO_METRICS` is set).
- **Cost.** One character-map lookup per cluster per face tried, only when fallback families are given.

## Text on a path

`TextOptions.Path` lays the text along a `Path`. The text is laid out exactly as straight text would be (wrapping, alignment, line spacing, origin, runs, fallback), treating the path as the top edge of the first line, and each glyph is then moved onto the path:

- A glyph's anchor is the middle of its advance. Its **distance** along the path is the layout x of the anchor (origin and alignment included), so `HorizontalAlignment.Center` centers about the *start* of the path, not its middle, and an origin x moves text along it.
- The glyph is **rotated about its anchor** to the direction of the path at that distance and is not bent: a rigid move per glyph. Its offset from the path is its layout y, to the right of the direction of travel in a y-down image (so text on a left-to-right line stands below it, and a clockwise circle carries text on the inside). Later lines are further to the right; `VerticalAlignment` and `Origin.Y` move the whole block off the path.
- **Past the ends.** An open path continues straight: before the start along its first segment, after the end along its last. A closed path wraps around: glyphs beyond the perimeter start over at the beginning, and the closing edge is a real edge.
- **Which path.** The path is flattened (0.1 px) and the first contour with a length is used; a path without length throws `ArgumentException`. Measuring (`TextMeasurer`) ignores the path.
- **Decorations** follow the path glyph by glyph (each piece is a rectangle rotated with its glyph), so on a curve neighbouring pieces overlap on the inside and open a thin wedge on the outside.
- **Cost.** One flatten, then a binary search over the cumulative segment lengths per glyph: linear in glyphs, logarithmic in path points. 100,000 glyphs on a path of 200,000 points take about 110 ms.

## System fonts

`SystemFonts` finds installed fonts without native calls: it scans the standard directories (Windows: the system Fonts folder and `%LOCALAPPDATA%\Microsoft\Windows\Fonts`; macOS: `/System/Library/Fonts`, `/Library/Fonts`, `/Network/Library/Fonts`, `~/Library/Fonts`; elsewhere: `/usr/share/fonts`, `/usr/local/share/fonts`, `$XDG_DATA_DIRS/*/fonts`, `~/.fonts` and `$XDG_DATA_HOME/fonts` or `~/.local/share/fonts`). `SystemFonts.Installed` is the process-wide `SystemFontSet`; `new SystemFontSet(directories)` scans directories of your choice.

```csharp
Font font = SystemFonts.CreateFont("DejaVu Sans", 24, FontStyle.Bold);
IReadOnlyList<string> names = SystemFonts.FamilyNames;   // sorted, nothing loaded
```

- **Lazy.** Nothing happens until the first lookup. The first call that needs names lists the files (`.ttf`, `.otf`, `.ttc`, `.otc`, to a depth of 8, at most 100,000 files) and reads just the table directory and `name` table of each, never glyph data: 10 ms for directories holding 1,413 files (277 families) on a warm cache on the Linux host this was built on. The result is kept for the life of the set; fonts installed afterwards are not noticed.
- **Loading.** `TryGet`/`Get`/`CreateFont` parse the files of that one family (all its styles) the first time and return the same `FontFamily` afterwards. A file that no longer parses is skipped; its family may then be missing or partial. WOFF files are not scanned (their tables are compressed).
- **Safe.** Header reads are bounds-checked against the file length and stop at 256 faces per collection, 256 tables and 1 MiB of names; unreadable directories and files are skipped without an error. Family names are the ones `FontFamily.Name` gives (the typographic family when the font has one).

## Drawing

`DrawText(text, options, brush, pen, ...)` exists for `Image` (lazy: layout happens at the call, pixels when the image is read) and `Canvas` (in place), plus overloads taking a color. The optional parameters are the fill ones: `antialias`, `opacity`, `blend`, `composition`, `linear`. With both a brush and a pen the outline is drawn over the fill. Glyph outlines are filled with the non-zero rule. `TextBuilder.GeneratePath` returns the same path as an ordinary `Path`, for filling, stroking or transforming yourself.

## Agreement with ImageSharp

Checked against SixLabors.Fonts 2.1.3 and ImageSharp.Drawing 2.1.7 through their public APIs (tests in `tests/OneImage.Text.Tests`).

- Glyph outlines: the same contours and points (TrueType, CFF-CID and composite glyphs) to within 0.01 font unit. The reference starts contours at a different point and inserts zero-length lines; the comparison normalizes both.
- Advances and kerning: equal to 0.01 px at one pixel per font unit, for GPOS kerning, the `kern` table and CFF with GPOS.
- Line counts, advance size and ink bounds: equal (0.01 and 0.05 px) across sizes, dpi, wrapping lengths, line spacing and all alignment combinations in the test matrix.
- Rendering: black text on white, mean level difference 0.03 to 0.28 over the whole image (3 to 5 over pixels where either draws ink), maximum 27 to 106 levels at single edge pixels. Positions are identical; the rest is coverage. We compute exact-area coverage; ImageSharp's scanline rasterizer over- and under-covers some thin or touching edges (see [drawing.md](https://recursiveai.org/oneimage/docs/drawing/)).

Differences you will meet, all deliberate or pending the later units:

- **Ligatures and wrapping.** We shape first and wrap on the shaped glyphs, so a line holding `fi`, `ffl` and the like is measured with the ligature glyph's own advance. ImageSharp substitutes the same ligatures but over-measures a line that holds one when it decides where to wrap (60 random 8-word texts with `fi`/`ff`/`fl` words: the line count differs in 33; the same texts without those letters: in none). A single line's advance is equal to 0.0001 px with and without ligatures.
- **Feature order and `numr`/`dnom`.** Lookups run in lookup-list order, so `smcp` before `liga` (above). ImageSharp leaves the digits alone when asked for `numr` or `dnom` on Noto Sans; we substitute the font's numerator and denominator forms, as the font defines them. Everything else we compared (ligatures, `ccmp` compositions, marks and stacked marks in Latin, Greek and Cyrillic, `smcp`, `c2sc`, `onum`, `lnum`, `tnum`, `pnum`, `zero`, `frac`, `sups`, `subs`, `ordn`, `case`, `ss03`, `ss04`, `salt`, `aalt`) gives the same glyph ids and origins to 0.002 font units.
- **Language** cannot be chosen in ImageSharp 2.1.3's `TextOptions`, so language forms (`locl`) are checked against the font's own tables, not against it.
- **Wrapping against ImageSharp.** Ordinary text (words separated by spaces, with the usual punctuation, quotation marks, brackets, numbers with separators, no-break spaces, Greek and Cyrillic) wraps at the same places in `Standard` and `KeepAll`: 1,590 combinations of five texts, three sizes and 53 wrapping lengths, none different; `BreakAll` and `BreakWord` agree in 95% and 91% of them. Where opportunities are not after spaces the two part, for these reasons (each pinned by a test in `tests/OneImage.Text.Tests/WrapReferenceTests.cs`):
  - ImageSharp fills a line exactly when it ends at a space, but after a hyphen, a soft hyphen, a zero width space or an ideograph it also wants room for the next character, so it ends the line one opportunity early: with "mm-mm-mm" it needs the width of one more "m" (18.75 px at 20 px) than the line occupies; CJK text holds one character fewer per line. We fill exactly: a line is accepted when its text fits. This explains most (83%, against 57% for an exact fill) of the differences on hyphenated, soft-hyphenated, zero-width-space and CJK text; the rest is how ImageSharp treats soft hyphens and some hyphen cases.
  - ImageSharp ends a line between a prefix or sign and its number ("$ | 1,234.56", "- | 5.25"); UAX #14 rule LB25 keeps them together, as do we.
  - ImageSharp implements an older revision of the line breaking rules (UAX #14 revision 37). Under rules LB15a-d, added since, an opening quotation mark stays with the word after it even across spaces: "word “ quoted" wraps as "word" then "“ quoted" here, and as "word “" then "quoted" there.
  - ImageSharp never breaks after a solidus, so a long URL stays on one line; we break after "/" before a letter as UAX #14 allows, which wraps URLs and paths.
  - `KeepAll` in ImageSharp stops wrapping after the first line that cannot be broken to fit, and its `BreakWord` starts a too-long word on the current line; ours moves it to a fresh line first.
- **Tabs** advance `TabWidth` spaces. ImageSharp's `TabWidth` had no effect on the font we probed, which has no tab glyph.
- **Empty lines.** Text that starts with a line break measures two lines of one pitch each; ImageSharp adds extra height for the leading empty line. A line of only spaces keeps its full width here; ImageSharp reported one space's width for two. Text with no ink has zero-size bounds, where ImageSharp reports a box.
- **Color glyph advances.** We use the base glyph's advance, as the OpenType specification and the layout of every other glyph do. With color enabled SixLabors.Fonts 2.1.3 advances by the advance of the glyph's first layer instead; the two agree in fonts whose layers are as wide as their base glyph (the test font), and differ in others.
- **Color rendering** on the test font (layered shapes, foreground color, a half-transparent layer, two palettes, a composite layer): brush only, mean 0.07 levels over the image and at most 28 at single edge pixels; with a pen, mean 1.9 to 2.7 levels, which is the half-pixel stroke placement difference described in [drawing.md](https://recursiveai.org/oneimage/docs/drawing/). COLR version 1 paint graphs are not painted by SixLabors.Fonts 2.1.3; see [COLR version 1](#colr-version-1) for the comparison used instead.
- **WOFF2** has no ImageSharp difference worth naming: faces, outlines (point for point), advances, side bearings, kerning and shaped text from the WOFF2 of each test font (TrueType, CFF, a collection, and a file using the `hmtx` transform) equal those of the source font.
- **Rich text** (probed through the public API of SixLabors.Fonts 2.1.3 and ImageSharp.Drawing 2.1.7; tolerances are what the tests assert):
  - *Runs with mixed sizes and faces*, with and without wrapping: glyph ink boxes agree to 0.0002 px, advance and line count exactly. In some run configurations (a run without a font next to plain text, or runs of different sizes) the reference applies an extra pair adjustment to `r` followed by some letters (-20 units) and, in one probed case, to `o` followed by `w` (-60 units; in mixed-size text it is scaled by the size of one of the runs) that it does not apply to the same text without runs; we apply the font's `GPOS` kerning only, and the tests use text without the pairs.
  - *Overlapping runs*: the reference drops the rest of an outer run after a nested one (an inner run in the middle of an outer run leaves the outer run's decorations off the text after it); we resolve every character to the last run covering it.
  - *Decorations*: segment ends and heights agree to 0.01 px, thickness to 0.01 px, in plain, wrapped, mixed-size and raised runs. The reference reports one segment per glyph; we report one per line and run, and the filled rectangle is the same area.
  - *Super- and subscript*: ink boxes agree to 0.0001 px.
  - *Fallback without wrapping*: ink boxes agree exactly. *With wrapping* the line count agrees but the reference declines some break opportunities where a fallback face is involved (for `ABあいCD` at 150 px it keeps two kana on a line where the text fits three); we wrap by the same rule as without fallback.
  - *Text on a path*: glyph vertices agree to 0.0003 px on lines (horizontal, diagonal, reversed, steep), alignments, origin, wrapping and multi-line text, and past the end of an open path. On a 120-segment circle ten of twelve glyphs agree to 0.001 px; two sit one segment step (up to 1.9 px at their far corners) away from the reference's. The reference does not place glyphs on the closing edge of a closed polygon (they continue straight past the last explicit vertex) while still wrapping at the full perimeter; we follow the closing edge. We also take the first contour of a multi-contour path.
  - *Rendering* (black on white, 420x200, mean absolute level difference over all pixels; `RichRenderTests`): runs with underline, strikeout and overline 0.62 (max 248), a wrapped paragraph with a larger run and superscript 0.39 (max 254), fallback text 0.13 (max 133), text along a polyline 0.07 (max 99). Glyph pixels agree like plain `DrawText` does. The large maxima are decoration lines: both libraries agree on where a decoration is (segment ends, center and thickness within 0.01 px) but the reference rasterizes the thin rectangle about 0.3 to 0.7 px higher or lower than that geometry, so a one or two pixel line differs in whole rows; we paint the reported geometry exactly.
  - *Layout and hinting modes*: the reference's `HorizontalBottomTop` mode places glyphs as top-to-bottom does; ours stacks lines upward. Vertical layout and hinting are compared in [Vertical layout](#vertical-layout) and [Hinting](#hinting).

## Shaping clusters for your own layout

`TextShaping` (in `OneImage.Text`) exposes what a caller needs to lay text out itself — SVG text, with a position for every character, is the user — without the library's own paragraph layout:

```csharp
byte[] levels = TextShaping.GetBidiLevels(text, TextDirection.LeftToRight, out int paragraphLevel);  // UAX #9 level per UTF-16 unit
int[] visual = TextShaping.GetVisualOrder(levels);                                                   // logical indexes in visual order
IReadOnlyList<ShapedCluster> clusters = TextShaping.ShapeRun(text, font, rightToLeft: false, new ShapingOptions { Language = "tr" });
foreach (ShapedCluster c in clusters)
{
    // c.Start and c.Length: UTF-16 units of the input; c.Advance: pixels at the font size, kerning included;
    // c.GetOutline(): the glyphs as a Path with the pen at (0, 0), y down, in pixels; c.HasMissingGlyph.
}
```

- `GetBidiLevels(string, TextDirection, out int paragraphLevel)` runs the algorithm on one paragraph (`Auto` picks the level from the first strong character) and returns one level per UTF-16 unit. `GetVisualOrder(ReadOnlySpan<byte> levels)` reverses runs per rule L2 and returns the logical index at each visual position; an empty input gives an empty array.
- `ShapeRun(ReadOnlySpan<char>, Font, bool rightToLeft = false, ShapingOptions? = null)` shapes one run in one font and returns its clusters in logical order. A cluster is what cannot be positioned apart (a letter with its marks, a ligature, a syllable), so each can be placed, rotated or stretched on its own. Runs longer than `TextShaping.MaxRunLength` (2^24) throw `ArgumentException`. The run is not split by script or direction: the caller does that, and passes `rightToLeft` for odd levels. A character the font lacks gives a cluster with `HasMissingGlyph` true and the font's missing-glyph outline.
- `ShapingOptions`: `Language` (BCP 47, default the font's default language system), `Kerning` (`KerningMode`, default `Normal`) and `Features` (`FontFeature` list, empty by default, applied on top of the script's defaults; value 0 switches a feature off).
- **Vertical columns.** `ShapingOptions.Vertical` shapes a run to stand upright in a column (kerning off, `vert` and `vrt2` on, like the vertical `LayoutMode`s; `Features` still win). `ShapedCluster.VerticalAdvance` is the cluster's height in a column (the sum of `vmtx` advances, or the line height without vertical metrics) and `GetUprightOutline()` its outline with the origin at the middle of the column at the top of the cell, placed by `VORG` or the top side bearing exactly as the vertical layout modes place upright glyphs. `TextShaping.IsUprightInVerticalText(codePoint)` is the UAX #50 test (U and Tu stand; the rest lie rotated a quarter turn clockwise, which a caller does with `GetOutline()` and `Advance`).
- `ShapedCluster.GetOutline()` builds the outline once and returns the same `Path` afterwards. Outlines are unhinted. Nothing is cached across runs.
- `FontFaceInfo.GetWeight(Font)`, `GetIsItalic(Font)`, `GetSuperscriptRaise(Font)` and `GetSubscriptDrop(Font)` read the face's OS/2 weight class, italic flag and the superscript and subscript offsets in pixels at the font's size (0 when the face has none).

## Where the next pieces plug in

`Layout/TextLayout.cs` is the whole layout in four steps with narrow seams between them.

- **Shaping** is `Shape` calling OneFont's `TextShaping.ShapeCodePoints`: code points and the clusters the layout chose in, glyphs (glyph id, cluster, code point, advance with kerning, offsets) out. Script-specific shapers live in OneFont.
- **Line breaking** is `PrepareBreaks` and `CanBreakBefore`: the break opportunities and cluster starts of a paragraph are computed from its text (OneFont's `TextSegmentation`) and reach the glyphs only through each glyph's text offset, so a shaper that merges or reorders glyphs needs no change here. Hyphenation, language-tagged tailoring and dictionary breaking for Thai, Lao, Khmer and Burmese (their characters are treated as letters, so there is no break inside a word) would be new work in OneFont.
- **Color fonts** beyond COLR (SVG and bitmap glyphs) extend the color branch of `BuildParts`, which already turns the layers of a version 0 color glyph into one fill per layer index and color, and hands a version 1 glyph to `ColrPainter`.
- **Runs, fallback, decorations and paths** live in `Layout/TextLayout.cs`: `ResolveRuns` maps every offset to a run, `Shape` splits shaping runs by (run, face) and every `ShapedGlyph` carries a `GlyphStyle` (face, scale, shift, line and decoration measures); `BuildParts` writes outlines and decoration rectangles per paint, with `GlyphMatrix` giving the straight or on-path placement (`Layout/PathRoute.cs`).

## ImageSharp names

| SixLabors.Fonts / ImageSharp.Drawing | OneImage.Text |
|---|---|
| `FontCollection.Add(path / stream)`, `AddCollection` | `FontCollection.Add(path / stream / memory)`, `AddCollection` |
| `FontFamily.CreateFont(size, style)` | `FontFamily.CreateFont(size, style)` |
| `RichTextOptions` / `TextOptions` | `TextOptions` (`Origin`, `WrappingLength`, `LineSpacing`, `TabWidth`, `Dpi`, alignments, `Kerning`, `WordBreaking`, `TextJustification`, `Language`, `Features`, `TextRuns`, `FallbackFontFamilies`, `Path`) |
| `RichTextRun` / `TextRun` (`Start`, `End`, `Font`, `TextAttributes`, `TextDecorations`, `Brush`, `Pen`, `UnderlinePen`, `StrikeoutPen`, `OverlinePen`) | `TextRun` with the same members (`Start`/`End` are UTF-16 offsets, End exclusive) |
| `SystemFonts.Get` / `CreateFont` / `Families` | `SystemFonts.Get` / `CreateFont` / `FamilyNames` (names only until a family is requested) |
| `TextBuilder.GenerateGlyphs(text, path, options)` | `TextOptions.Path` with `TextBuilder.GeneratePath` or `DrawText` |
| `TextOptions.FeatureTags` (`Tag`) | `TextOptions.Features` (`FontFeature`, with a value and off switches) |
| `TextMeasurer.MeasureAdvance` / `MeasureBounds` / `MeasureSize` / `CountLines` | `TextMeasurer.MeasureAdvance` / `MeasureBounds` / `Measure(...).Bounds.Size` / `CountLines` |
| `TextMeasurer.TryMeasureCharacterBounds` | `TextMeasurer.GetCharacterBounds` (`Ink`) |
| `ctx.DrawText(options, text, brush, pen)` | `img.DrawText(text, options, brush, pen)` / `canvas.DrawText(...)` |
| `TextOptions.ColorFontSupport` (`MicrosoftColrFormat`) | `TextOptions.ColorFontSupport` (`MicrosoftColrFormat` by default; also `ColorPaletteIndex`) |
| `TextOptions.LayoutMode` | `TextOptions.LayoutMode` (same members) |
| `TextOptions.HintingMode` (`None`, `Standard`) | `TextOptions.HintingMode` (`None` default, `Standard`) |
| `TextBuilder.GenerateGlyphs` | `TextBuilder.GeneratePath` |
| `TextRenderer` + `IGlyphRenderer` | `TextBuilder.GeneratePath`, then walk or transform the `Path` |


<!-- https://recursiveai.org/oneimage/docs/svg/ -->

# SVG

Design of `RecursiveAI.OneImage.Svg` (assembly and namespace `OneImage.Svg`): SVG as an image format that renders directly at the size you ask for. This page describes what the package is, how it is built, and where it stands. The package detects SVG, reads its natural size and draws shapes, paths, strokes, gradients, patterns, markers, groups with opacity and blend modes, transforms, viewports, `use` and `symbol`, clip paths, masks, style sheets, `switch`, `data:` images, filters and text at any size and one region at a time.

```csharp
using OneImage;
using OneImage.Svg;

var config = new ImageConfiguration().Add(SvgFormat.Instance);   // not part of ImageConfiguration.Default, so it trims away when unused
var load = new LoadOptions { Configuration = config };

ImageInfo info = Image.Identify("logo.svg", load);                // natural size, nothing rendered
Image.Load("logo.svg", load).Resize(width: 400).Save("logo-400.png");   // rasterized at 400 px, not scaled up from the natural size
```

## Scope

Static SVG 1.1 and the SVG Tiny-style content found in practice, plus the parts of SVG 2 and CSS that documents rely on:

| Area | Supported |
|---|---|
| Structure | `svg` (nested too), `g`, `defs`, `use`, `symbol`, `switch` (`systemLanguage`, `requiredFeatures`), `a`, `title`/`desc` ignored |
| Shapes | `rect` (with `rx`/`ry`), `circle`, `ellipse`, `line`, `polyline`, `polygon`, `path` |
| Painting | fill and stroke (width, caps, joins, miter limit, dashes), `fill-rule`, opacities, `paint-order`, `vector-effect: non-scaling-stroke`, `shape-rendering`, `visibility`, `display`, `color`/`currentColor`, `context-fill`/`context-stroke`, `mix-blend-mode`, `isolation`, `opacity` |
| Paint servers | `linearGradient`, `radialGradient` (with focal point and `fr`), `pattern`, href inheritance, `gradientTransform`/`patternTransform`, `spreadMethod`, both unit systems |
| Clipping and masking | `clipPath` (nested, per-child `clip-rule`), `mask` (luminance and alpha, nested), `overflow` clipping of nested viewports and markers |
| Markers | `marker-start`/`mid`/`end` and the `marker` shorthand, `orient`, `markerUnits`, `viewBox`, `refX`/`refY` |
| Images | `image` with a `data:` URI (PNG, JPEG, GIF, WebP, BMP, TIFF, ICO and nested SVG, decoded by OneImage's own codecs), `preserveAspectRatio`, `image-rendering` |
| Text | `text`, `tspan`, `textPath`, per-character `x`/`y`/`dx`/`dy`/`rotate`, `text-anchor`, baselines, decorations, spacing, `textLength`, writing modes; rendered through `OneImage.Text` |
| Filters | the `filter` element with the full SVG 1.1 primitive set, `feDropShadow`, and the CSS filter functions (`blur()`, `drop-shadow()`, `grayscale()`, ...) |
| CSS | presentation attributes, the `style` attribute, `<style>` with type, class, id, universal, attribute, descendant, child and sibling selectors, the structural pseudo-classes and `:not()`/`:is()`/`:where()`, specificity, source order, `!important`, `inherit`, `initial`, `unset`, `currentColor`, `transform` and `transform-origin` as properties |

Not supported, and never to be: SMIL animation, scripting and event attributes, `foreignObject`, `BackgroundImage`/`enable-background`, and any external fetch. Animation elements are ignored and the document renders as its first frame; `script` and `foreignObject` content is skipped.

**External references fail closed.** The package never opens a file, a URL or any other resource named by a document: `href`/`xlink:href` other than `#id` and `data:`, `@import`, `@font-face` sources, `url()` in CSS, the `xml-stylesheet` instruction. Such a reference is treated as dangling, which SVG already defines: an `image` or `use` renders nothing, a paint server reference falls back to its fallback color or `none`, a missing `filter` reference removes the element, a missing `clip-path`/`mask` is ignored. No error is raised and no I/O happens. A resolver hook can be added later as an explicit opt-in; there is none now.

## Architecture

```
bytes ─▶ source ─▶ XML parser ─▶ document ─▶ styles ─▶ render tree ─▶ renderer ─▶ pixels
         (gunzip,   (strict,      (typed     (CSS       (resolved,     (region at a
          caps)      bounded)      elements)  cascade)   size-free)     given scale)
```

1. **Source.** Reads the stream under a byte cap. Gzip data (`.svgz`) is detected by its signature and inflated with the library's own inflate, under the document cap and the expansion-ratio limit, then the stored CRC-32 and size are checked.
2. **XML parser** (`Xml/XmlParser.cs`). Our own, strict, XML 1.0 plus Namespaces, over UTF-8, UTF-16 (with BOM) and Latin-1/ASCII. It produces a plain tree of elements, attributes (namespace-resolved) and text.
3. **Document.** The tree is turned into typed SVG elements and attributes: lengths, colors, transforms, `viewBox`, `preserveAspectRatio`, paint, path data (parsed by the drawing layer's strict path parser). Unknown elements and attributes are kept as inert.
4. **Styles.** CSS is parsed, rules are matched and ordered, and every element gets computed property values with inheritance applied.
5. **Render tree.** The styled document is resolved into an immutable tree in user units, independent of the output size: groups (transform, opacity, clip, mask, filter, blend), paths (geometry, fill, stroke), images and text-as-outlines. `use`, `symbol`, nested `svg`, `switch`, markers and pattern contents are instantiated here, under budgets. References are resolved here too: a cycle or a dangling reference is turned into the defined fallback, never into a loop. The tree is built once per document and shared by every render of it.
6. **Renderer.** Draws a rectangle of the output at a given scale from the render tree, using the existing engine (see [Mapping to existing operations](#mapping-to-existing-operations)).

Everything up to and including the render tree is safe, bounds-checked code and runs under the [limits](#limits). There is no `unsafe` outside the core's kernel layer.

### XML parser: our own

The parser is written for this package rather than built on `System.Xml`. The deciding reasons, in order:

- **Policy is the point.** `XmlReader` can be made safe (`DtdProcessing.Prohibit`, no resolver), but then it is a safe configuration of a general parser. Ours cannot be configured unsafely: any `<!DOCTYPE` fails, and no entity reference except the five predefined ones and numeric character references is honored, so a document can never grow while it is read. There is nothing to forget to switch off.
- **Limits at the source.** Element count, depth, attributes per element, name length and namespace declarations in scope are enforced as the parser goes, before the memory they guard is allocated. `XmlReaderSettings` offers only character-count caps, so the rest would have to be counted in a wrapper anyway.
- **Iterative and allocation-aware.** The tree is built with an explicit stack (a 300,000-deep document is parsed without growing the call stack when the depth limit is raised) with interned names.
- **Trimming and AOT.** No dependency on `System.Xml`'s reader stack, which is large for trimmed or WASM apps.
- **Cost.** Measured on a 15 MiB document of 300,000 elements (local smoke, shared host at load ≈4.5, .NET 10.0.400): our parser builds the whole tree in 145–180 ms and 137 MiB allocated, including the 30 MiB UTF-16 copy of the text; `XmlReader` with DTDs prohibited only *reads* the same document, without building a tree, in 105–180 ms and 28 MiB. The two are the same speed class.

Deliberate deviations from a full XML processor: no DTDs of any kind (so documents with an internal subset, a handful of which exist in the wild, are rejected rather than partly honored), and encodings other than UTF-8, UTF-16 with BOM, ASCII and ISO-8859-1 are refused with a clear message instead of being guessed.

### Detection

`SvgFormat.Matches` sniffs the first 4 KiB: an optional BOM and white space, then any mix of XML declaration, comments, processing instructions and a DOCTYPE, then a start tag whose local name is `svg`. Gzip data is recognized by its signature and the first 2 KiB of its content is sniffed the same way, so a gzip file that is not an SVG is not claimed. The extensions are `.svg` and `.svgz`; the MIME type is `image/svg+xml`.

### Natural size

`Identify` reads only the root element's start tag (within the first 1 MiB), so it stays cheap on huge files. The natural size in CSS pixels (96 per inch) is:

- `width` and `height` when both are absolute lengths (`px`, `pt`, `pc`, `mm`, `cm`, `in`; `em` and `ex` at 16 and 8 px);
- percentages, zero and negative values count as absent; a missing side is derived from the other through the `viewBox` aspect ratio; with neither, the `viewBox` size is used;
- the pixel size is the size rounded **up**, at least 1; a malformed or non-finite value fails with `ImageFormatException`.

A side that nothing fixes takes the extent of the painted content: the far edge of the bounding box of all shapes, stroke width included (resvg measures it the same way). That needs the whole document, so `Identify` then reads and builds it (once; the render tree is kept for the pixels), and a document that has neither a size nor anything to draw fails with `ImageFormatException`. Zero and negative sizes follow the same rule where resvg's reference rendering is empty; this renders the content instead, which is the more useful answer.

## Rendering at the requested size

Rasterizing an SVG and then scaling the bitmap throws away exactly what makes SVG worth having. The core already treats this kind of thing like JPEG shrink-on-load: a decoder advertises what it can do and the graph pushes the request down. SVG gets the same treatment.

**Core changes** (small and additive; made):

- `DecoderCapabilities.RenderAtSize` (a new flag): the decoder can produce its frame at any pixel size, not only 1/2, 1/4, 1/8. It is meant to be combined with `RandomAccess`, which the SVG decoder also sets: a 128×128 region is cheap to render because only the render-tree nodes that touch it are drawn.
- `DecodeRequest` gains `TargetWidth` and `TargetHeight` (0 = the natural size; the existing two-argument constructor is kept). The `Region` of the request is then expressed in target pixels.
- A graph rewrite beside the existing shrink-on-load one (`DecodeSourceNode.TryPushRenderSize`, tried first in the resampling step): when `Resize`/`Thumbnail` sits directly on an undisturbed decode of a `RenderAtSize` decoder, the decode is re-created at the final size and no resample node is added. `Fit.Stretch` and `Contain` map to the target directly; `Cover` renders at the covering size and its crop is now pushed down as a region of the decode; `Pad` renders at the contained size and pads. Upscaling follows the fit rules: `Resize` enlarges by default, `Thumbnail` only with `upscale: true`, and an enlarged render is sharper, not blurrier. Rotation, `Affine` and other geometry ops keep working on the natural-size raster and are not rewritten. The rewrite does not look through an orientation node (SVG has no orientation, so none is added).

Without the rewrite, loading still works: the image has its natural size and downstream operations act on that raster. Output is always sRGB 8-bit straight RGBA, with a transparent background unless the caller flattens it.

**Region rendering.** One entry point draws "this rectangle of the output at this scale". The scale maps user space to pixels through the root `viewBox` and `preserveAspectRatio` into the target size (non-uniform if the caller asks for a stretched size). Per request the renderer:

1. looks up the render-tree nodes whose device bounds meet the region (a bounding-box grid built once per tree), in paint order;
2. paints into a `Canvas` the size of the region, with the region offset folded into the transform;
3. writes rows to the sink.

Each request is cut into bands of full region width and at most 128 rows (fewer for very wide regions, so a band stays under 4 megapixels), drawn one after another into a band-sized canvas; layers are band-sized too, and the frame itself is never held in layers. The core asks for one 128×128 tile at a time, so a tile is one band. Filter regions larger than a tile get their own bounded region (see [Limits](#limits)). Results do not depend on how the frame is cut: shapes are rasterized by exact area per pixel, and a 256² region of a 4096² render equals the same pixels of the whole render (tested; differences are at most 1 level, in practice zero). The bounding-box grid is a 64×64 grid over the natural area; a node covering more than 16 cells is kept in a short list every query checks.

## Mapping to existing operations

| SVG feature | Built from |
|---|---|
| Fill of a shape | `Fill(brush, path, rule, transform, opacity)`; `shape-rendering: crispEdges`/`optimizeSpeed` → `antialias: false` |
| Stroke | `Draw(pen, path, ...)`: width, `StrokeCap`, `StrokeJoin` (miter, round, bevel; SVG 2 `miter-clip`/`arcs` fall back to miter/bevel as SVG 2 allows), miter limit, dashes. Non-scaling stroke: stroke the transformed path |
| Solid, linear, radial paint | `Brush.Solid`, `Brush.LinearGradient`, `Brush.RadialGradient` with `GradientRepetition` for `spreadMethod`. **New:** an affine `transform` on gradient brushes (for `gradientTransform` and bounding-box units), and a focal/two-point-conical radial gradient |
| Pattern | The tile is rendered to an image at device resolution and painted with `Brush.FromImage` through the pattern transform. **New:** smooth (bilinear) sampling for non-axis-aligned pattern transforms |
| `opacity`, `mix-blend-mode`, `isolation` on a group | The group is drawn to an offscreen `Canvas` layer, then `Composite(layer, opacity, blend: BlendMode, alpha: AlphaComposition)`. Groups with none of these, no clip, mask or filter are drawn straight into the parent (no layer). A single shape with only `opacity` uses the fill/stroke opacity parameter |
| `clip-path` | Entirely geometric: each child shape (with its own `clip-rule`, transform and nested `clip-path`) is resolved with `PathBoolean`, the children are united (`UnionAll`), a nested clip is intersected, and the result becomes the clip path of the fills and strokes it covers (`Fill(..., clip:)`, whose coverage is multiplied into the fill coverage). A clip in `objectBoundingBox` units on a group needs the group's box, so the group is drawn to a layer and composited through the region |
| `mask` | The mask content is rendered to a layer; its luminance or its alpha (`mask-type: alpha`) times the mask region becomes the coverage of the masked layer, through the new `Image.ApplyMask` (alpha or luminance times alpha, with an offset; see the changelog). A mask on a mask narrows the first one the same way |
| Viewport clipping (`overflow`, nested `svg`, `symbol`, markers) | A rectangle path through `Clip` |
| `image` | `Image.Load` on the decoded `data:` bytes (limits apply), shrunk with `Resize` when drawn small, then painted through a brush derived from the public `Brush` (bilinear or nearest sampling, edges extended) over the fitted rectangle, so `preserveAspectRatio`, transforms and rotation are one placement matrix; a nested SVG document is drawn into a layer with its own render tree and composited through the same rectangle |
| Text | `OneImage.Text`: `TextBuilder.GeneratePath` gives outlines that are filled, stroked, clipped like any path; `TextOptions.Path` carries `textPath`; rich runs carry per-run font, decoration and fill. Per-character `x`/`y`/`dx`/`dy`/`rotate` needs the shaped glyphs placed individually: **new in `OneImage.Text`:** a public way to get each cluster's outline and advance after shaping |
| Markers | Instantiated into the render tree as groups with a transform per vertex |
| Filters | See below |

### Filters

A `filter` becomes a small graph of primitives evaluated on the element's rendered layer. Evaluation happens in linear-light premultiplied float:

| Primitive | Maps to |
|---|---|
| `feGaussianBlur` | `GaussianBlur(sigma, sigmaY, edge: Constant)`; the input outside the filter region is transparent |
| `feOffset` | whole-pixel offsets: `Pad`/`Crop`; fractional offsets: `Affine` translation |
| `feFlood` | a fill of the primitive subregion |
| `feBlend` | `Composite(..., blend: BlendMode)` (normal, multiply, screen, darken, lighten and the SVG 2 modes) |
| `feComposite` | `AlphaComposition` for over/in/out/atop/xor. **New:** `arithmetic` (k1..k4 on premultiplied channels, clamped) |
| `feColorMatrix` | `ColorMatrix` (matrix, saturate, hueRotate, luminanceToAlpha as a matrix) on straight color, as the SVG specification defines |
| `feMerge` | repeated source-over `Composite` |
| `feDropShadow` | blur + offset + flood + merge |
| `feImage` | a `data:` image, or an element reference rendered like `use` |
| `feComponentTransfer` | per-channel identity/table/discrete/linear/gamma on straight color, evaluated directly on float |
| `feConvolveMatrix` | direct evaluation with target offset, bias, `preserveAlpha`, `edgeMode` duplicate/wrap/none |
| `feMorphology` | erode/dilate: separable min/max over a rectangular window (van Herk), so the time does not grow with the radius |
| `feTile` | tiles the input's subregion over its own |
| `feTurbulence` | the Perlin turbulence of the specification (fractal noise and turbulence, seeds, octaves, stitch tiles) |
| `feDisplacementMap` | nearest-pixel displacement by a channel of the second input |
| `feDiffuseLighting`, `feSpecularLighting` and the three light sources | direct evaluation of the specification's Phong terms over the alpha channel as a height map |
| CSS filter functions | direct: `blur()` → `GaussianBlur`; `brightness`, `contrast`, `grayscale`, `hue-rotate`, `invert`, `opacity`, `saturate`, `sepia` → `ColorMatrix`/tone ops; `drop-shadow()` as `feDropShadow` |

The filter region (`x`, `y`, `width`, `height` in `objectBoundingBox` or `userSpaceOnUse`, default −10%, −10%, 120%, 120%) and primitive subregions are resolved in device pixels. The region needed for a tile is the tile grown by the filter's margin (blur radius, offset, morphology radius, convolution order), then clipped to the filter region. Filters on rotated or skewed content run on the pixel grid scaled by the transform's axis scales and the result is mapped back by the remaining rotation or skew.

### Filters, part one

Files: `Render/SceneBuilder.Filters.cs` (the `filter` property and filter elements into `RFilter` stages), `Render/Filters/` (`FilterRenderer` plans and runs a layer's filters, `FilterOps` and `FilterBlur` are the float kernels, `FilterBuffer` holds premultiplied float32 in sRGB or linear light). The blur and the color conversions between 8-bit, sRGB float and linear float run on AVX kernels (see [Filter speed](#filter-speed)); everything else is plain safe C#.

- **Evaluation.** The layer's content is drawn into a pixel grid, converted to premultiplied float once, run through the primitives (each converts its inputs to its own color space, from tables with interpolation) and rounded to 8 bits once at the end. Blur follows the specification's three-box approximation from a standard deviation of 2 pixels, and a true kernel below that; edges are transparent. Offsets move whole pixels (the scaled distance is cut toward zero, as the reference renderer does).
- **Regions.** The region the output needs, grown by the sum of the primitives' reach and cut to the filter region, is all that is computed, so a region render equals the same pixels of a whole render (tested: at most one level). A filter chain is planned from its last stage back, each stage producing what the next reads. A wrapping convolution reads the whole filter region.
- **Rotated and skewed content.** The filters run on the element's own axes scaled to the output; the result is drawn back through the remaining rotation or skew with bilinear sampling. Offsets and deviations are therefore along the element's axes (as in browsers), where the reference renderer applies them along the output's axes; the `complex-transform` tests differ from their references only in edge pixels.
- **Subregions.** Defaults are the filter region. With `primitiveUnits=objectBoundingBox`, `feFlood`, `feOffset` and `feImage` measure their fractions in the object's box and every other primitive in the filter region, which is what the reference images show.
- **`feImage`.** An element reference is drawn like a `use` with its origin at the subregion's; a picture is scaled with a Mitchell filter on encoded values into the subregion by `preserveAspectRatio`. Recursion through `feImage` (an element that carries the filter it is drawn by) drops the `filter` of that element wherever it appears.
- **CSS functions** run in sRGB; their region is the content's box grown by what the function adds around it. `drop-shadow()` with no offset and no blur draws nothing extra.
### Filters, part two

Files: `Render/SceneBuilder.FilterEffects.cs` (the primitives below into the `RFilter` model), `Render/Filters/FilterEffects.cs` (their float kernels), `Render/Filters/FilterBlockCache.cs` (shared output blocks).

- **`feComponentTransfer`.** Un-premultiply, apply the last `feFunc*` of each channel, clamp to 0..1, premultiply by the new alpha. An unknown `type`, a `table`/`discrete` without values, or values that do not parse leave the channel as it is. The alpha function sees transparent pixels too, so a table on alpha can fill them.
- **`feMorphology`.** The window is (2r+1) pixels wide on each axis, where r is the radius times the grid scale rounded to nearest. A radius of zero on one axis leaves that axis alone; a negative or missing radius, three numbers, or both zero leave the input as it is. Outside the region is transparent, so an erosion wider than the region is empty (and costs nothing); a huge dilation needs the whole region and fails typed when the region is over the pixel limit.
- **`feTile`.** The input's tile rectangle is its subregion when it sets one, otherwise the union of the tile rectangles of what it reads (the specification's default subregion), or the filter region for a standard input. That rectangle is only for tiling: a primitive that sets no subregion still fills the whole filter region, as in the reference renderings. Tiling reads the whole region, so such a filter is computed as a single block.
- **`feTurbulence`.** The reference algorithm of the specification, with one deliberate difference: the lattice vectors are all normalized, none is drawn again. The Filter Effects text adds a redraw of zero and over-long vectors that no renderer implements, and the reference images follow the original SVG 1.1 generator (verified: alpha matches to within 0.3 of a level). The point of a pixel is the user-space position of its top-left corner, in the element's own space. `stitchTiles` takes its tile from the subregion scaled to pixels (not user units), which is what the references show; the test is marked undefined behavior in the suite. `numOctaves` is capped at 10 (the next octave adds less than 2⁻¹⁰), negative or non-integer values, a negative or malformed `baseFrequency` give a transparent result. The values are in the primitive's color space.
- **`feDisplacementMap`.** `scale` is multiplied by the grid scale; each pixel takes the source pixel at its position plus `scale × (channel − ½)`, nearest, and transparent beyond the work rectangle. The map is read as straight color in the primitive's space. The reach is half the scale.
- **Lighting.** The surface is the alpha channel; the normal uses the specification's Sobel kernels in the interior and its edge and corner kernels on the filter region's border. Diffuse and specular follow the specification's formulas, with the light color in the primitive's color space; specular alpha is the largest color channel and the color stays as computed (it is ≤ alpha, so it reads as premultiplied). `surfaceScale` stays in pixel units of the grid while a light's position and height scale with it (heights by the mean scale), which is what the reference images show. A light's coordinates are user units even with `primitiveUnits=objectBoundingBox`. No light source, or a specular exponent outside 1..128, gives a transparent result; a negative constant gives opaque black; a spot light's non-positive `specularExponent` is read as 1; `limitingConeAngle` cuts hard (no smoothing). `kernelUnitLength`, when given, samples the surface at that distance (bilinear, border extended) instead of the pixel grid.
- **`feConvolveMatrix` completions.** A kernel sum that is zero within rounding (0.1 × 8 − 0.8) divides by 1, not by the rounding residue. The remaining differences from the references are the two undefined-behavior tests (`bias=0.5`, `edgeMode=wrap` with a kernel wider than the target).
- **Margins, blocks and cost.** Component transfer, tile, turbulence and the lighting kernels read at most their own pixel (lighting: one kernel unit); morphology reads its window, displacement half its scale. A filter whose margin is wide (32 pixels or more: a large blur, a large dilation) over a region of at least 128 K pixels would make every 128-pixel tile of the output refilter several times its own area, so its output is computed in blocks of 512 or 1024 pixels on a grid anchored to the element, kept as 8-bit RGBA under one byte budget (96 MiB, least recently used evicted, given back when the scene is collected) and shared by every request and thread that touches them. A block is computed once, by the first request, and the others wait for it. Blocks are equal to the same pixels computed alone to within one level (tested, with concurrent readers and evictions). Rendering the same loaded image again therefore reads blocks instead of filtering again. Measured: 4096-pixel render of 400 shapes under a blur of σ 8: 1316 → 578 ms; σ 30: 9.8 s → 0.85 s (shared development host, load 7).
- **Limits.** Pixels of the filter region × cells of a convolution kernel are limited to 2³³ (typed `ImageLimitException` before any buffer exists); the kernel itself to 4096 cells (a larger or malformed one makes the primitive transparent). Everything else is bounded by `MaxFilterPixels` on what a request needs, and by constant-time or capped algorithms: morphology costs the same for any radius, turbulence octaves are capped, displacement and lighting reads are clamped to the work rectangle.
- **Not matched.** `filter/subregion-and-primitiveUnits=objectBoundingBox-1` and `-2` (0.8%: with a `width` fraction on a blur the reference cuts at half of the region's far edge, not at half of its width; unexplained, not copied); the 6 `complex-transform` tests (edge pixels: the filters run on the element's axes, the references along the output's; `feTile` 9.7% because tiles resample); `feColorMatrix/type=matrix-with-non-normalized-values` (0.27%, borderline); two undefined-behavior convolution tests. That makes 395 of 406 `filters` files (the 7 `color-adjust` tests with text pass since the text step).

Benchmarks (`SvgFilterBenchmarks`; BenchmarkDotNet 0.15.8 short job, `[MemoryDiagnoser]`; worker: AMD Ryzen 9 7950X3D, 32 logical cores, .NET SDK 10.0.402 / runtime 10.0.13, load average 3.0 before, 3.6 to 4.2 during and 4.1 after from other jobs; load + render unless noted, so nothing is read from cached blocks):

| row | before blocks | now | allocated before | now |
|---|---:|---:|---:|---:|
| blur, sigma 30 units, 4096 px | 11.2 s | 762 ms | 388 MB | 74 MB |
| blur, sigma 8 units, 4096 px | 1.69 s | 579 ms (error 440 ms) | | 74 MB |
| icon with blur, 256 px | 1.43 ms | 1.24 ms (blocks on every filter: 2.7 ms) | | 318 KB |
| turbulence + lighting, 1024 px | not drawn | 52.8 ms | | 6.9 MB |
| Svg.Skia: blur 4096 px / turbulence + lighting 1024 px | | 218 ms / 55 ms | | |

A filtered group is read in place and its tiles go back to the pool right after it is composited, like the other layers.

### Filter speed

The blur and the pixel conversions are vector code with scalar references, and the result is bit for bit what the scalar code gives (rendered documents hash the same whole and in regions, and the resvg collection scores the same file by file).

- **Blur** (`Render/Filters/FilterBlur.cs`, kernels in core `Kernels/BlurKernel.cs`). The sums are doubles with the same operations in the same order as the scalar reference `FilterBlurReference`, and each box rounds to float, so nothing changes numerically. What changed is the layout and the instruction mix: a line (a row, or a column read in place with a stride) goes through all three boxes in line-sized scratch instead of three trips over the whole buffer; the four channels of a pixel are one 256-bit vector of doubles; four lines run together, because the add-then-subtract of one running sum is a latency chain; lines that are entirely zero are skipped (their blur is zero); and buffers of 128 K pixels or more are cut into row groups or column bands that run in parallel at the per-call degree. The blur is in place, so the second full-size float buffer is gone. Single-threaded, a 176 x 176 tile takes 0.6 ns per pixel per box horizontally and 0.8 vertically (scalar: 6.3 and 5.3). Without AVX the scalar reference runs.
- **Conversions** (`Kernels/FilterColorKernel.cs`, AVX2). Two pixels per step: 8-bit to premultiplied float, sRGB to linear and back with the 4096-step table (gathers) and the scalar code's clamps, and premultiplied float to 8-bit. A pair holding a NaN where the scalar `Math.Min`/`Math.Clamp` rules differ from the vector ones goes through the scalar code. A source layer stays 8-bit until a primitive reads it, so a linear-light primitive reads it straight into linear float (one rounding sequence, the same as expanding to sRGB float and converting). Only the part of the result that lands in the target is converted back to 8 bits. Measured on one thread: 8-bit to linear 3.9 ns per pixel (scalar 9.5), sRGB to linear 3.4 (7.1), linear to 8-bit 5.5 (12.2).
- **Not changed.** The 128-pixel tiles still refilter their margin when the margin is under 32 pixels (block output is quantized to 8 bits and equal only to within a level, so it cannot replace tile output byte for byte); drawing the layer's content into the work area is the largest remaining cost of the 1024 px rows.

Measured with `SvgFilterBenchmarks` (BenchmarkDotNet 0.15.8 short job, `[MemoryDiagnoser]`; worker: AMD Ryzen 9 7950X3D, 32 logical cores, .NET SDK 10.0.402 / runtime 10.0.13; load average 1.4 before and 2.8 after the final run; the "before" run was at 4.7 to 5.3, other jobs on the worker). Before and after use the same benchmark: the OneImage rows copy into a pixel buffer kept between iterations, because the earlier rows allocated and filled a fresh 4 MB `ToArray` result per iteration, which was the source of their full (Gen2) collections. No filter row has a Gen2 collection now. "Before" is the commit this section was written on top of.

| row (load + render unless noted) | before | now | Svg.Skia (render) |
|---|---:|---:|---:|
| blur, sigma 8 units, 1024 px (loaded document, render only) | 33.5 ms (error 45) | 10.7 ms | 11.9 ms |
| blur, sigma 8 units, 1024 px | 30.1 ms | 10.8 ms | |
| drop shadow, 1024 px | 44.1 ms | 17.8 ms | 58.4 ms |
| drop shadow, 1024 px (loaded document, render only) | 4.8 ms | 3.9 ms | |
| icon with blur, 256 px | 1.18 ms | 0.45 ms | 0.49 ms |
| blur, sigma 8 units, 4096 px | 491 ms | 156 ms | 210 ms |
| blur, sigma 30 units, 4096 px | 678 ms (error 98) | 206 ms (error 62) | 210 ms |
| turbulence + lighting, 1024 px | 51.5 ms | 50.1 ms | 53.2 ms |

Allocation per iteration: 1024 px blur 2.0 MB (was 2.1), 4096 px blur 7.1 MB (was 6.8), turbulence + lighting unchanged. The sigma 30 row's spread is wide (other jobs on the worker); it sits at Svg.Skia's figure, not clearly under it.

## Color

- The document and output are **sRGB**. Colors parse to sRGB (`icc-color()` fallbacks are ignored). Painting, compositing, blending, opacity and gradient interpolation happen on encoded sRGB values in premultiplied float — SVG's default `color-interpolation: sRGB` — and are rounded to 8 bits when a layer is stored.
- `color-interpolation: linearRGB` on gradients is honored through the `linear` option the brushes already have. On a `mask` it is ignored: the luminance is always computed on the stored sRGB values, as browsers and the reference renderer do (`Image.ApplyMask` has a `linear` option for other callers).
- **Filters** follow `color-interpolation-filters`, whose default is `linearRGB`. A filter's layer is converted to linear sRGB once through the color engine's built-in linear profile, held as premultiplied float32 for the whole primitive graph, and converted back once at the end, so a chain of primitives does not round to 8 bits between steps. A primitive that asks for `sRGB` converts its inputs and outputs at that boundary. Primitives that must see straight color (`feColorMatrix`, `feComponentTransfer`) un-premultiply for the operation, as specified.
- Raster images embedded as `data:` URIs keep their own color profile and are converted to sRGB when drawn. Output frames carry no profile.

## Limits

Every bound is checked before the allocation or work it guards; breaking one raises `ImageLimitException`. `SvgLimits` (set per registration: `new SvgFormat(new SvgLimits { ... })`) holds these, alongside the ordinary `ImageLimits` of the load call (pixels per frame, dimension, expansion ratio), which also bound the output size.

| Limit | Default | Where it applies |
|---|---:|---|
| Document bytes (file, and gzip output) | 32 MiB | source — implemented |
| Elements | 500,000 | XML parser — implemented |
| Element nesting depth | 256 | XML parser — implemented |
| Attributes per element | 512 | XML parser — implemented |
| Name length | 256 characters | XML parser — implemented |
| Namespace declarations in scope | 256 | XML parser — implemented |
| Root start-tag scan for `Identify` (`MaxRootTagScanBytes`) | 1 MiB | source — implemented: a root start tag that does not end inside the window fails with `ImageLimitException` |
| Gzip expansion ratio | `ImageLimits.MaxExpansionRatio` (1100) | source — implemented, checked while inflating (deflate cannot exceed about 1030:1 on its own, so the document cap is what stops a default-limit bomb) |
| CSS text (all `<style>` and `style` attributes; `MaxCssBytes`, in characters) | 2 MiB | styles — implemented |
| CSS rules (`MaxCssRules`, one per selector of a list) | 20,000 | styles — implemented |
| Selector matching work (`MaxCssMatchSteps`) | 100 million steps | styles — implemented: every simple-selector test and every ancestor or sibling move is a step; rules are indexed by id, class and type to keep honest documents far below this. A hostile sheet (a descendant chain that cannot match, against 200 nested groups and 100,000 shapes) is refused after about 0.4 s and 90 MiB allocated (local smoke, loaded host) |
| Path segments in a document (`MaxPathSegments`: moves, lines, curves and arcs of `path` data and the points of `polyline`/`polygon`, nested images included) | 4 million | document, while path data is read — implemented: a path of 5.7 million segments (30 MiB of data) is refused after about 0.5 s and 360 MiB allocated; 600,000 points draw in 0.3 s and 450 MiB. A path attribute is bounded by the document cap (32 MiB), whitespace and all |
| Instantiated render nodes (`use`, `symbol`, markers, pattern and mask contents, clip children, text glyphs) | 500,000 (`MaxInstances`) | render tree — implemented for elements reached through `use`, `symbol` and nested content: every instantiated element is counted as it is created, so a fan-out that multiplies stops at the budget (500,000 fan-out copies cost about 0.4 s and 75 MiB before the refusal, measured), and the refusal is remembered. Memoizing a `use`'s size is not done. A clip child counts as 16 instances because resolving it is a polygon boolean operation (a clip of 1,000 shapes in bounding-box units, used by 800 elements of different sizes, is refused after about 3.5 s); a clip resolved again for the same transform and box is reused from a cache of 4,096 entries |
| Reference depth (`use`→`use`, `clip-path`→`clip-path`, `mask`→`mask`, `pattern`/`marker`/`filter` chains) | 32 (`MaxReferenceDepth`) | render tree; `use` chains implemented; cycles are detected separately and draw nothing |
| Nested isolated layers (groups with `opacity`, `mask`, or a `clip-path` that needs its box), and masks chained through `mask` on a mask | 32 (`MaxLayerDepth`) | render tree and renderer — implemented; deeper nesting fails closed with `ImageLimitException` before anything is drawn |
| Nested image documents (`MaxImageDepth`) | 3 levels | `image` of an SVG data URI; they share the budgets above |
| `data:` payload per image / per document (`MaxImageBytes`, `MaxTotalImageBytes`) | 16 MiB / 64 MiB | render tree; decoded under `ImageLimits`; the encoded length is checked before the payload is decoded |
| Text characters (`MaxTextCharacters`) | 1 million | render tree — implemented: counted as text is read and again for every copy `use` instantiates; past it the load fails with `ImageLimitException` before any layout |
| Pattern tile size | 16 megapixels (`MaxPatternTilePixels`), 16,384 pixels per side | renderer, after scaling to device pixels — implemented: a larger tile is drawn at a coarser resolution, not refused; each level of pattern nesting gets half of its parent's share. The side cap exists because a pattern skewed by 90 degrees stretches one axis by 10^16: a 1 × 16-million-pixel tile fits the area budget but cost over a minute to draw |
| Offscreen layer | one band: region width × at most 128 rows, under 4 megapixels | renderer — implemented |
| Filter region | 64 megapixels (`MaxFilterPixels`) | renderer, in device pixels after clipping to what the output needs plus the margin the primitives read — implemented: a filter that needs more fails with `ImageLimitException` before any buffer exists |
| Filter primitives per filter / filter nesting | 256 / 4 (`MaxFilterPrimitives`, `MaxFilterDepth`) | render tree — implemented; nesting counts filters reached through `feImage` |
| Convolution kernel cells, convolution work, turbulence octaves | 4096; region pixels × cells ≤ 2³³; 10 | render tree and renderer — implemented: an invalid or oversized kernel makes the primitive transparent, too much work fails with `ImageLimitException`, octaves are clamped. Morphology costs the same for any radius |
| Filter output blocks kept | 96 MiB, process-wide | `FilterBlockCache` — implemented; least recently used blocks are dropped and recomputed |

Hardening runs (libFuzzer with SharpFuzz, seeded from every committed SVG under 16 KiB): `svg-xml` 7.2 million executions in 10 minutes, `svg-render` 1.1 million in 10 minutes, `svg` (path data) 3.7 million in 10 minutes, `font` 193,000 in 5 minutes, with peak resident memory of 52, 142, 29 and 204 MB. They found three problems, each fixed with a repro under `tests/testdata/svg`: a font size beyond float range escaped as `ArgumentOutOfRangeException` (two documents), and a pattern skewed by 90 degrees took 69 seconds because its tile was one pixel wide and 16 million tall (now capped at 16,384 pixels per side; 12 ms).

Every row above has a hostile-document test (`SvgLimitsTests`) that checks the typed refusal and bounds its time and allocation; the measured costs are in the test log (`ONEIMAGE_LIMIT_LOG=<file>` appends one line per case). Refusals are cheap, from well under a millisecond (nesting, names, attributes) to about half a second and a few hundred MiB for the limits that only trip after the work is read (path segments, CSS match steps, instances). Glyph outlines are the heaviest instances, about 2.4 KB each, so text fanned out through `use` costs the most: the refusal at 500,000 glyphs allocates about 1.2 GiB over 1.4 s (peak working set about 300 MiB above the baseline).

Cancellation is observed at least once per tile and per filter primitive. Rendering errors that are not limits (a malformed path, an unusable gradient) follow the SVG error-handling rules — the element is not rendered — and never raise.

Lazy behavior follows the rest of the library: `Identify` and `Load` read the root start tag (the whole document when the root gives no size); the rest of the document is read when pixels are first pulled, so a malformed body fails then with `ImageFormatException`. The render tree is built once per loaded image, under a lock, from the first request; a document that fails (a malformed body, a limit) fails the same way on every later request without redoing the work. `Load(..., validate: true)` decodes the frame once at its natural size, which parses and builds the document.

### What is drawn so far

- **Document and style.** A typed element tree of the SVG-namespace elements (non-SVG elements and their content are skipped); the cascade described below; `inherit`, `initial` and `unset`; inherited and non-inherited properties computed per element; `currentColor` kept as a keyword and resolved against the element's own `color`. An invalid value is ignored as if unwritten, except a negative `stroke-width`, which drops the stroke.
- **Style sheets.** Every `<style>` element whose `type` is empty or `text/css` (CDATA included, anywhere in the document, in document order) is parsed into rules. Supported selectors: type, `*`, `#id`, `.class`, attribute tests (`[a]`, `=`, `~=`, `|=`, `^=`, `$=`, `*=`, with the `i` flag), the descendant, `>`, `+` and `~` combinators, `:first-child`, `:last-child`, `:only-child`, `:nth-child()`, `:nth-last-child()`, the `-of-type` forms, `:empty`, `:root`, `:not()`, `:is()` and `:where()` over compound selectors; `:hover`, `:link` and the like never match in a static rendering. A selector this engine does not know (pseudo-elements, namespaces, other pseudo-classes) drops its rule, as CSS says. At-rules (`@import`, `@media`, `@font-face`, ...) are skipped without being read. Selectors see the document's own attributes, presentation attributes included, and count only SVG elements as siblings. Per element the declared properties are applied in this order, later over earlier: presentation attributes; matching rules by specificity (ids, then classes, attributes and pseudo-classes, then types) and source order; the `style` attribute; then the `!important` declarations in that same order. Rules apply to the document, so `use` instances copy the cascaded values of the element they reference and inherit from the `use`. Matching is right to left with backtracking on explicit arrays, no recursion, under a step budget (see [Limits](#limits)).
- **Conditional processing.** An element with `systemLanguage`, `requiredFeatures` or `requiredExtensions` renders only when all hold. A language tag in `systemLanguage` matches a configured language (`new SvgFormat(languages: ...)`, default `en`) when they are equal or the language is a prefix of the tag before a hyphen, ignoring case (`en` matches `en-GB`); an empty list is false. Extensions are not supported, so any `requiredExtensions` is false; `requiredFeatures` counts as true unless empty. `switch` renders the first child that can be rendered (a shape, `g`, `a`, `svg`, `use`, `image`, `text`, `switch`, `foreignObject`) whose conditions hold, even when `display: none` hides it; unknown elements and comments are skipped; the `switch` element itself takes part in styling and transforms like a group. The conditions also apply to the root `svg`. Conditions on `defs`, gradients and `clipPath` have no effect on how they are referenced.
- **Images.** `image` draws an `href`/`xlink:href` that is a `data:` URI (base64, white space allowed, or percent-encoded): any raster format the library reads, or an SVG document (plain or gzip), told apart by content, not by the media type. A missing or `auto` `width`/`height` comes from the picture (both from its size, one through its aspect ratio); `preserveAspectRatio` places it, `slice` cuts it to the viewport; `transform`, `opacity`, `visibility` and `display` apply; `image-rendering: optimizeSpeed`, `pixelated` and `crisp-edges` sample the nearest pixel. A raster is shrunk once per scale to the size it is drawn at (the library's default filter, on encoded values), then sampled bilinearly through the placement, with the border pixels extended so the fill's anti-aliasing gives the edge; a color profile is converted to sRGB. A picture is read once per `image` element however many times `use` instantiates it, and the shrunk pixels are kept for the life of the loaded image. A nested SVG is drawn as vectors, to its own bounds, through a layer. A picture that cannot be read is dangling and draws nothing; an external `href` is never fetched.
- **`transform-origin`.** One to three values (keywords, lengths, percentages); the reference box is the nearest `viewBox`. On the root, percentages refer to the viewport and the default stays the center. `transform-box` is not supported (the box is always the view box). The origin also applies to the `transform` of a `clipPath`, to `patternTransform` (reference box: the view box, as for drawn elements) and to `gradientTransform`: with `userSpaceOnUse` units the view box, with `objectBoundingBox` units the unit square, so `center` is 0.5 and a plain number is a fraction of the box.
- **Colors.** Keywords, `transparent`, `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`/`rgba()`, `hsl()`/`hsla()` and `hwb()` in the comma and the space syntax, with percentages, angle units and `/` alpha. Integers and percentages may not be mixed among the three channels of `rgb()`.
- **Geometry.** `rect` (with `rx`/`ry` and the auto rule), `circle`, `ellipse` (SVG 2 `auto` radii), `line`, `polyline`, `polygon`, and `path` with the whole grammar. Path data is read by the package's own parser, which draws what precedes the first error (the core's parser rejects the whole path) and reads arc flags without separators. A zero-length subpath draws a dot under round and square caps. Numbers beyond ±10¹⁵ are clamped, so hostile coordinates cannot reach the drawing code as infinities.
- **Paint.** `fill`, `stroke` with solid colors, `fill-rule`, `fill-opacity`, `stroke-opacity`, `opacity`; `shape-rendering` crisp values turn anti-aliasing off. `visibility` and `display`. `paint-order` orders fill, stroke and markers.
- **Paint servers.** `linearGradient` and `radialGradient` with `gradientUnits`, `gradientTransform`, `spreadMethod`, stops (offsets clamped and kept non-decreasing, `stop-color` with `currentColor` and `inherit`, `stop-opacity`), `href` inheritance (attributes only from a gradient of the same kind, stops from the first gradient in the chain that has some, loops end the chain) and the SVG 2 focal point and `fr` as a two-circle gradient (a focal circle outside the end circle is a cone, painted only inside it; equal concentric circles paint their disc in the first color). Stops interpolate as straight, non-premultiplied colors. A gradient with one stop is that color, with no usable geometry (both ends equal, no radius) the last stop, with no stops or a box without area (bounding-box units) it is unusable. `pattern` with `patternUnits`, `patternContentUnits`, `viewBox` and `preserveAspectRatio`, `patternTransform`, `href` inheritance of attributes and children, nested patterns. The pattern content is built once per pattern element, the tile is drawn at the resolution it is seen at (rounded up to whole pixels, then stretched to the exact period) and repeated through an image brush: nearest sampling when the pattern is not turned or skewed, bilinear otherwise. A tile past `SvgLimits.MaxPatternTilePixels` is drawn at a coarser resolution. An unusable server, or a reference that is dangling or points at another kind of element, uses its fallback (`url(#id) color`) or paints nothing; a pattern whose own content is painted by itself, directly or in a loop, paints nothing there. `context-fill` and `context-stroke` take the paints of the nearest `use` (gradients and patterns included, with the box of what the `use` drew), and nothing without one. `color-interpolation: linearRGB` on gradients is not supported.
- **Stroke.** Width, caps, joins (`miter-clip` and `arcs` fall back to miter), miter limit, dash array (an odd count is repeated) and offset, through the core stroker; the stroke outline is made once per scale and reused by every tile.
- **Structure.** Transforms (attribute and style property), `viewBox` and `preserveAspectRatio` on the root and nested `svg`, `g`, `a`, `defs` (not drawn), `use` (with `x`, `y`, `width`, `height`), `symbol` (viewBox, size from the `use`, its own `transform` ignored as in SVG 1.1), nested `svg` with the default clip (`overflow: visible` or `auto` removes it). The root's `transform` takes its origin at the center of the viewport, and the root's `background-color` paints the whole output.
- **Clipping.** `clip-path: url(#id)` on shapes, groups, `use`, nested `svg` and the root. `clipPath` children are shapes (`rect`, `circle`, `ellipse`, `line`, `polyline`, `polygon`, `path`) and `use` that points straight at one; `g`, `symbol`, `image`, `switch` and text (until text exists) contribute nothing, as do children with `display: none` or `visibility: hidden`. Each child has its own `transform`, `clip-rule` (also inherited from the `clipPath`) and nested `clip-path`; the `clipPath` has `clipPathUnits`, `transform` and its own `clip-path` (applied in the referencing element's space). A non-invertible transform, an empty `clipPath`, or `objectBoundingBox` units on an element with no area clip everything; a dangling reference, a reference to something that is not a `clipPath`, and a non-`url()` value such as `circle()` are ignored. A reference that leads back to a clip being resolved is ignored, which breaks cycles. A clip is resolved in scene space with the polygon boolean engine (flattened at 0.02 px), so a user-space clip costs nothing per group, its children inherit it, and shapes are culled against its bounds. `overflow` on nested `svg` and `symbol` clips the viewport (`visible` and `auto` do not; `inherit` takes the parent's); the legacy `clip` property is not used, as in the reference renderer.
- **Masking.** `mask: url(#id)` on shapes, groups, `use`, nested `svg` and the root: `maskUnits` (default `objectBoundingBox`, region -10%/-10%/120%/120%), `maskContentUnits`, `x`/`y`/`width`/`height` with percentages, `mask-type` (`luminance` or `alpha`, as an attribute or in `style`; an invalid value is luminance), a `mask` on the mask element, masks inside mask content, and masks on elements with a clip or opacity. The masked element is drawn to a layer as large as its bounds inside the band, the mask content to another, and the layer is composited through the mask by `Image.ApplyMask`. A mask whose content is empty, or whose units need the box of an element with no area, hides the element; a dangling or wrongly typed reference is ignored. Cycles of masks are broken the way the reference does it: masks are visited in document order and the `mask` link that closes a cycle is dropped everywhere. `color-interpolation` is ignored.
- **Markers.** `marker-start`, `marker-mid`, `marker-end` and the `marker` shorthand (a style declaration only, as the specification says) on `path`, `line`, `polyline`, `polygon` and, as SVG 2 has it, `rect`, `circle` and `ellipse`. `markerUnits` (an invalid value is `strokeWidth`), `markerWidth`/`markerHeight` (3 by default; zero or negative draws nothing), `refX`/`refY`, `viewBox` with `preserveAspectRatio`, `overflow` (hidden by default; `visible`, `auto` and an `inherit` that finds nothing leave the marker unclipped), and `orient` as `auto`, `auto-start-reverse` or an angle in `deg`, `grad`, `rad` or `turn`. A path's vertices are the start of each subpath and the end of each segment; a closepath is a straight segment back to the start, and a second closepath in a row adds nothing. The direction at a vertex is the average of the outgoing and incoming directions (the short way round; exactly opposite ones give their plain average), at the first vertex of a subpath only the outgoing one and at its last only the incoming one, even when the subpath is closed. A curve's direction at an end comes from its first or last control point that differs from the end, a zero-length segment takes its neighbor's direction, and an arc is split into pieces of at most a quarter turn whose joints are vertices too. The marker's content takes its style from the marker's own ancestors, not from the shape; `context-fill` and `context-stroke` are the shape's paints. A marker that is already being drawn draws nothing inside itself, and a `use` chain inside a marker starts afresh. The shape and its markers are one group when the shape has `opacity`, a blend mode, a clip or a mask; `paint-order` puts the markers before, between or after the fill and stroke. Every marker instance counts against `MaxInstances`.
- **Blending and isolation.** `mix-blend-mode` (every CSS blend mode; `plus-lighter` is the Porter-Duff plus operator, `AlphaComposition.Plus`: premultiplied colors and alpha add and clamp at 1) and `isolation: isolate` are style properties, not presentation attributes, so an attribute is ignored. An element with a blend mode, and an isolated group, is drawn to a layer and composited once: inside an isolated group blends only see the group. Layers cover only the part of the band their content can touch.
- **Layers.** A group with `opacity` below 1, and a shape with both fill and stroke and `opacity` below 1, is drawn to a band-sized layer and composited once, so overlaps inside it do not show through.
- **Units.** `px`, `pt`, `pc`, `mm`, `cm`, `in`, `em`, `ex` (half the font size), `rem` and `%` of the viewport (width, height, or the diagonal measure for lengths that follow neither). The default font size is 16.
- **Filters (parts one and two).** The `filter` property with `url(#id)` references and CSS filter functions in any mix and order. Filter elements: `filterUnits`, `primitiveUnits`, region defaults of -10% / 120%, `href` inheritance of attributes and primitives (loops and non-filter targets end the chain), primitive subregions, `in`/`in2`/`result` (an input that names nothing is the previous result, or the source graphic for the first primitive; `BackgroundImage`, `BackgroundAlpha`, `FillPaint` and `StrokePaint` are read as the source graphic), `color-interpolation-filters` per primitive. Primitives: `feGaussianBlur`, `feOffset`, `feFlood`, `feMerge`, `feBlend` (all 16 modes), `feComposite` (including `arithmetic` and `lighter`), `feColorMatrix`, `feConvolveMatrix`, `feImage` (a `data:` picture or an element drawn like `use`), `feDropShadow`; `feComponentTransfer`, `feMorphology`, `feTile`, `feTurbulence`, `feDisplacementMap`, `feDiffuseLighting` and `feSpecularLighting` with `feDistantLight`, `fePointLight` and `feSpotLight` (part two, under [Filters, part two](#filters-part-two)). Functions: `blur`, `drop-shadow`, `brightness`, `contrast`, `grayscale`, `hue-rotate`, `invert`, `opacity`, `saturate`, `sepia`; an invalid function drops the whole declaration, an unresolved `url()` among others is skipped, and a list of only unresolved references removes the element. A filter runs before clip, mask and opacity; a clip in force outside a filtered element applies to the filter's result. Details are under [Filters, part one](#filters-part-one).
- **References** (`use`) are instantiated under budgets (see [Limits](#limits)); a `use` of itself, of an ancestor, or around a cycle draws nothing; a dangling or external reference draws nothing. A `symbol` instantiated with a size gives percentage lengths inside it that size.

Seams for the following steps: style sheets add their declarations between the presentation attributes and the `style` attribute in `SvgDocument.Build`; paint servers are in; markers are in (`SceneBuilder.Markers.cs`: a shape with markers pushes one frame that instantiates them one at a time, so a marker inside itself is seen as active); text outlines resolve paints through `SceneBuilder.ResolvePaint` (it takes the geometry for the bounding box); filters wrap or add `RNode`s where `EmitShape` and `Open` create them (the frame already carries an inherited clip path in scene space and decides when a group needs a layer; `Decorate` adds an element's `clip-path` and `mask`, and `OverflowClip` is the viewport clip that markers and patterns reuse); text becomes `RPath`s from outlines. A node that is not a path (`RImage`) is drawn by `SceneRenderer.DrawNode` through `ImageRenderer`.

### What is drawn: text

Text is laid out by the SVG package and shaped and outlined by `OneImage.Text`; the glyph outlines go through the same fill, stroke, clip and paint-server code as any path.

- **Elements.** `text`, `tspan`, `a`, `tref` (it may point at any SVG element and takes its character data) and `textPath` (to a `path` or any basic shape; `startOffset` in user units or percent of the path length, `side=right`, subpaths followed in order, glyphs whose middle falls off the path are dropped). Glyphs on a path sit with their middle on the path and turn with the chord they span.
- **Positions.** Per-character `x`, `y`, `dx`, `dy` and `rotate` lists, each applying to the characters of its element in order and nearest-element-wins; an absolute position starts a new chunk. `text-anchor` anchors a chunk by its advance; `textLength` with `lengthAdjust` spacing or spacingAndGlyphs per chunk; `letter-spacing` and `word-spacing` (lengths, `em`, and percentages of the root viewport width, which is how the test-suite reference reads them).
- **Fonts.** `SvgFontOptions` (passed as `new SvgFormat(limits, languages, fonts)`) holds fonts added from files, bytes or streams, generic-family mappings, fallback families and whether installed fonts are scanned (default on). `font-family` lists, `font-weight`, `font-style`, `font-stretch`, the `font` shorthand and `font-variant: small-caps` (the font's `smcp` glyphs, or capitals at 0.8 of the size). Characters no listed font has fall back to the fallback families, then to the installed fonts. Without any usable font a text element draws nothing and the rest of the document renders. The initial and `medium` font size is `SvgFontOptions.DefaultFontSize`, 16 px by default as in browsers; the named sizes step by 1.2 around it (`xx-small` is medium / 1.2³, `xx-large` medium × 1.2³), and `em`, percentages and `rem` that reach the top of the document are relative to it.
- **Shaping.** Ligatures, kerning (`font-kerning`, and the SVG 1.1 `kerning="0"`), complex scripts and bidirectional text (`direction`, `unicode-bidi` embed and override) come from `OneImage.Text`. Kerning also applies across a `tspan` boundary between runs of one family that differ in size or weight, using the first run's font.
- **Baselines.** `dominant-baseline`, `alignment-baseline`, `baseline-shift` (including `super` and `sub` from the font's own metrics).
- **Painting.** Fill and stroke with paint servers (a gradient or pattern in `objectBoundingBox` units measures the line box: each glyph's advance wide and the font's ascent plus descent tall, not the ink), `context-fill`/`context-stroke`, `paint-order`, opacity, masks and filters on the text element. Underline, overline and line-through are drawn as bars with the font's metrics and share one bar across a run. `text-rendering: optimizeSpeed` on the `text` element draws its glyphs without anti-aliasing. Text inside a `clipPath` clips like geometry.
- **Whitespace.** `xml:space` and `white-space`; collapsing runs across `tspan` boundaries, and a preserved space ends a collapsing run.

- **Vertical text.** `writing-mode` `tb`, `tb-rl`, `vertical-rl`, `vertical-lr` (and `sideways-*`) on the `text` element (on a `tspan` it has no effect). The characters run down the column from `y`, with `x` the middle line of the column. As in the mixed vertical mode of `OneImage.Text`, characters with Vertical_Orientation U or Tu (ideographs, kana, Hangul) stand upright and are shaped with the font's `vert` forms; the rest (Latin, digits, Arabic) lie rotated a quarter turn clockwise, with the font's ascent-plus-descent box centered on the column line. `dx` moves across the column, `dy` along it, `text-anchor` anchors the extent along `y`, and right-to-left runs are reordered down the column. `glyph-orientation-vertical` and `text-orientation` are not used (the reference ignores them too), and all four vertical modes lay out the same way (each column starts at its own `x`). Underlines are bars on the rotated baseline, to its left. Text on a path ignores the writing mode.
- **Text style through `use`.** A `use` element's ancestors are the ancestors of the text it instantiates for everything that inherits (`font-family`, `text-anchor`, `writing-mode`, `direction`, `letter-spacing`, decorations); the surroundings of the referenced element itself no longer count.
- **Opacity on spans.** `opacity` on a `tspan`, `textPath` or `a` fades the characters of that element (and its descendants) as one group, with nested groups inside it. The reference renderer ignores it (`tspan/with-opacity`), so that one test differs on purpose.
- **Ligatures and positions.** A character with its own `dx` or `dy`, or a `rotate` that differs from the previous character's, ends the run the shaper sees, so it cannot be held inside a ligature; combining marks and joiners stay with their base.

Known gaps: variable-font axes, bitmap and COLRv1 glyphs, and vertical `text-orientation`.

## Testing against resvg's suite

Correctness is measured against the public test collection of the resvg project: its SVG files and reference PNGs, only. The committed subset lives in `tests/testdata/resvg` (MIT OR Apache-2.0, notice in `THIRD-PARTY-NOTICES.md`); `tools/fetch-resvg-tests.sh` downloads the full collection with its fonts at a pinned commit, and `ONEIMAGE_RESVG_TESTS` points the tests at it.

`ResvgConformance` loads every SVG, renders it at its reference PNG's size (300 px wide for the 200×200 test files) through the same `Resize` call a thumbnail request makes, and compares it to the reference with a stated tolerance: both images are composited over white, a pixel differs when any channel is off by more than 24 of 255, and a test passes when at most 0.25% of its pixels differ. The tolerance absorbs anti-aliasing differences between rasterizers, not wrong shapes or colors. It prints a pass-rate table per category (set `ONEIMAGE_SVG_REPORT` to also write it to a file), with the exclusions listed:

- DTD or entity declarations (refused by policy);
- external file references (refused by policy);
- scripts, animation, `foreignObject`, `@import` (not supported).

Behavior is specified from the SVG and CSS specifications and checked against the reference images; no renderer's source is consulted.

### Results

1,748 files (42 excluded), the full collection with the suite's fonts, run on the render-at-size path. "Before" is the skeleton, which could not draw.

| category | rendered | pass before | pass now | rate now |
|---|---:|---:|---:|---:|
| shapes | 133 | 0 | 128 | 96.2% |
| painting | 307 | 0 | 277 | 90.2% |
| structure | 230 | 0 | 197 | 85.7% |
| paint-servers | 154 | 0 | 146 | 94.8% |
| masking | 93 | 0 | 91 | 97.8% |
| filters | 406 | 0 | 395 | 97.3% |
| text | 383 | 0 | 279 | 72.8% |
| **all** | 1,706 | 0 | 1,513 | 88.7% |

Masking: 87 of 93. The 6 failures: `clip/simple-case` (an `image` under a clip, 2.6% of pixels) and 5 that clip with text. All 46 `clipPath` tests that do not use text, the `clip-rule` test and all 40 `mask` tests pass.

The filter and text passes are tests whose result happens not to need the feature (an empty result, or an element that is skipped). Subcategories in scope for this step:

| subcategory | pass |
|---|---:|
| shapes: rect, circle, ellipse, line, polyline, polygon | 75 / 76 |
| shapes: path | 53 / 57 |
| painting: stroke-width, stroke-linecap, stroke-linejoin, stroke-miterlimit, fill-rule | 25 / 26 |
| painting: stroke (solid paint) | 13 / 20 |
| painting: stroke-dasharray, stroke-dashoffset | 10 / 23 |
| painting: fill, fill-opacity, stroke-opacity, opacity, color | 74 / 91 |
| painting: display, visibility, shape-rendering, overflow | 10 / 29 |
| structure: svg (viewBox, preserveAspectRatio, nested svg, sizes) | 34 / 43 |
| structure: use, symbol, g, defs | 59 / 67 |
| structure: transform, style-attribute | 17 / 23 |

Of the 85 failures in these subcategories (and `fill`/`opacity`/`display` and so on), 27 are anti-aliasing borderlines: 0.25–1% of the pixels differ by more than the 24-level tolerance, all on thin strokes, dash ends and edges where two shapes share an edge. This renderer rasterizes by exact area; the reference comes from a supersampling rasterizer that treats strokes thinner than a pixel as hairlines, so edge pixels differ by 10–15% coverage. On a 1000×800 drawing of about 3,000 shapes (the benchmark document), 0.39% of the pixels differ by more than 24 levels from resvg 0.48.1 run as an external program (mean difference 1.4 levels). The rest, by reason:

- later steps: `fill`/`stroke` with gradients and patterns (painting fill, stroke, fill-opacity, stroke-opacity, defs, `funcIRI` tests), `context-fill`/`context-stroke`, markers, `paint-order`, `mix-blend-mode`, `isolation`, `use/complex-style-resolving-order`, `clipPath`/`mask`, filters and text (`display`/`visibility` on `tspan`, text in `defs`);
- deliberate differences: `shapes/rect/rem-values` (resvg does not support `rem`, so its reference shows nothing; this renders it as CSS defines), `painting/fill/rgba-0-127-0-50percent` (CSS Color 4 accepts a percentage alpha in the comma syntax; the reference rejects it), `structure/svg/zero-size` and `negative-size` (resvg's reference is empty; this renders the content at its measured size), `structure/svg/not-UTF-8-encoding` (Windows-1251 is not a supported encoding), `painting/shape-rendering/on-horizontal-line` (the pixel rows a non-anti-aliased line covers when its edge falls exactly on a pixel center), `structure/svg/preserveAspectRatio=none` (a 0.75 px frame stroke that the reference draws as a hairline).

### Text results

The text category, rendered with the suite's own fonts, generic families as the suite sets them, `DefaultFontSize = 12` (the suite's references were made with a 12 px `medium` font; our default is 16, the browsers') and no installed fonts (`ONEIMAGE_RESVG_TESTS` pointing at the full collection). Before the text unit text passed 16 of 383; the first text unit reached 269 (70.2%) and vertical writing and `use` inheritance bring it to 279 of 383 (72.8%). The whole table is 1416 of 1706 (83.0%; 1406 before this step). No category lost a test, and one test moved on purpose: `tspan/with-opacity` passed while the opacity of a `tspan` was ignored, as the reference ignores it, and differs now that it is applied as SVG 2 says.

| subdirectory | pass / rendered |
|---|---:|
| alignment-baseline | 16 / 19 |
| baseline-shift, dominant-baseline, font-size, font-size-adjust, font-stretch, font-style, font-variant, glyph-orientation-horizontal, glyph-orientation-vertical, word-spacing, kerning, font-kerning, text-rendering, tref | all |
| font-family, font-weight, tspan, text-anchor, text, textLength, letter-spacing | 12/13, 11/12, 28/32, 14/15, 38/44, 10/12, 9/12 |
| text-decoration | 11 / 22 |
| lengthAdjust | 1 / 4 |
| writing-mode | 17 / 24 |
| textPath | 7 / 43 |
| font-variation-settings, `font/` (variable-font and auto-axis tests), color-font | 0/14, 1/2, 1/10 |
| direction, unicode-bidi | 1/2, 0/1 |

Why the rest fails:

- **Variable fonts (about 28 tests: font-variation-settings, `font/`) and color fonts (9: bitmap, SVG-table and COLRv1 glyphs):** `OneImage.Text` reads neither variation axes nor those glyph tables. Out of scope for this unit.
- **Vertical writing (7 of the 24 writing-mode tests, plus lengthAdjust/vertical and alignment-baseline/hanging-on-vertical):** the layout agrees with the reference (columns, orientation per character, anchors, `dx`/`dy`; `tb-with-negative-dy-and-text-anchor`, `tb-with-rotate` and `mixed-languages-with-tb` are within 0.3-0.45%), but upright ideographs sit about 0.17 px (16-20 px text) to 1.2 px (64 px text) lower in the reference than the font's own vertical origin (`vmtx` top side bearing plus the glyph's top) puts them; no rule explains the amount, so `japanese-with-tb` (2.45%), `tb-and-punctuation` (0.96%) and the underline variants stay open. `tb-with-rotate` and `tb-with-rotate-and-underline` are marked undefined behavior in the suite. `lengthAdjust/vertical` stretches along the column, which this does not do, and `hanging-on-vertical` moves baselines across the column, which it does not either.
- **textPath (36):** every one is a small positional disagreement, 0.5-0.8% of pixels on the simple cases and more on curves and closed paths. A second look, on `m-L-Z-path` (a straight horizontal path, so flattening and tangent angle cannot matter): per glyph the reference sits from -0.4 to +0.3 user px from where the exact advances put it, in no pattern (not the sign of the advance's fraction, not rounding of advances or positions to whole pixels, and kerning is absent in that string), while plain text with the same font agrees to 0.01 px. Flattening tolerance, chord against tangent angle and arc length were already swept in the first pass. The reference's coverage is sampled on a 4 x 4 grid and could account for part of it. No rule was found, so it stays an unexplained difference.
- **Edge anti-aliasing (text-decoration 0.25–0.5%: all-types-*, style-resolving-*, underline, underline-with-y-list, tspan-decoration, indirect-with-multiple-colors; text/escaped-text-3, tspan/pseudo-multi-line, tspan/mixed-xml-space-2, lengthAdjust/with-underline and /text-on-path, textLength/on-a-single-tspan, complex-grapheme-split-by-tspan, xml-lang=ja):** the bars and outlines agree to a fraction of a pixel; the difference is the exact-area coverage against the reference's sampled coverage on stroked text edges.
- **Arabic and mixed-script (arabic, arabic-with-dx, arabic-with-dy, underline-with-dy-on-arabic, letter-spacing/on-Arabic and mixed-scripts, textLength/arabic, unicode-bidi/bidi-override, direction/rtl, zalgo, glyph-splitting):** shaping, mark placement or the reference's handling of spacing across joined letters differs from ours.
- **Deliberate:** `tspan/with-opacity` (the reference ignores `opacity` on a `tspan`; SVG 2 and browsers apply it) and `direction/rtl` — with `direction: rtl` we anchor `start` at the right edge, as the SVG specification says; the reference does not flip the anchor.
- **Filters on text (text/filter-bbox, letter-spacing/filter-bbox, textPath/with-filter):** the filter region of a text element's bounding box; another unit's area.
- **Font fallback and synthesis (font-family/fallback-1, font-weight/650, font/fallback-1):** which face the reference picks for an intermediate weight and for a missing-glyph fallback.

Text, a 800 x 1000 page of 40 lines of `tspan`s (bold, colored, sized, kerned, some with per-character `dx` and `rotate`) and a block of text on a curve, drawn at 800 px wide with the committed Noto Sans subsets (BenchmarkDotNet, default job, `[MemoryDiagnoser]`; worker: AMD Ryzen 9 7950X3D, 32 logical cores, .NET 10.0.402 / runtime 10.0.13, load average 3.9 before, 4.2 after from another job; no other library compared, because Svg.Skia takes its fonts from the system):

| row | before | now | allocated before | now |
|---|---:|---:|---:|---:|
| text page, OneImage load + render | 9.1 ms | 6.0 ms | 15.1 MB | 10.2 MB |
| text page, OneImage render (loaded) | 4.6 ms | 3.3 ms | 8.7 MB | 3.7 MB |

(Rerun after the render-cost work with the short job, BenchmarkDotNet 0.15.8 short job, `[MemoryDiagnoser]`; worker: AMD Ryzen 9 7950X3D, 32 logical cores, .NET SDK 10.0.402 / runtime 10.0.13, load average 2.9 before, 5.7 to 8.6 during and 6.1 after (other jobs on the worker); "before" is the commit before that work, same session.)

### Paint servers results

First run of the 154 rendered `paint-servers` tests passed 11; now 146 pass. The eight failures:

- tile period (deliberate): resvg rounds a pattern tile up to whole pixels and repeats it at that period, so with a tile of 28.8 px its copies drift against the exact geometry; this renderer keeps the exact period, so the seams between tiles fall up to one pixel elsewhere (`pattern/invalid-patternUnits-and-patternContentUnits`, `self-recursive`, `self-recursive-on-child`, `pattern-on-child`: they pass with the rounded period; `out-of-order-referencing` and `recursive-on-child` differ by 2.4% even then, on nested tiles of a few pixels);
- `pattern/transform-and-patternTransform`: a rotation cancelled by its opposite leaves a pattern that is axis-aligned up to rounding noise; the reference smooths its tile, this renderer snaps it (6%, edge pixels of the tile);
- `pattern/text-child`: text in a pattern (the text step);
- `radialGradient/invalid-xlink-href` is excluded (external reference).

Of the `painting/context` and `painting/paint-order` tests, 3 pass and the rest need other steps: markers (`in-marker`, `in-nested-marker`, `in-nested-use-and-marker`, `on-shape-with-zero-size-bbox`, `with-gradient-on-marker`, `with-pattern-on-marker`, `with-viewbox`, and all of `paint-order` except `on-text`/`on-tspan`, which need text), text (`with-text`) and two with other causes: `with-pattern-in-use` (0.8%, tile period) and `with-pattern-objectBoundingBox-in-use` (21%, its tile size does not match the reference, cause not found). The three gradient `transform-origin` tests pass. Gradients and patterns on text (`painting/fill`, `painting/stroke`) wait for the text step. Fifteen `filters` tests that passed before the paint servers (invalid `feConvolveMatrix`, lighting and morphology parameters whose reference shows nothing) now fail: they fill with a pattern, which is drawn now, and the filter that should remove the element is the filter step's.

### Results: style sheets, conditional processing, images and `transform-origin`

With paint servers, clip and mask merged in, `structure` passes 188 of 230 (81.7%). The six `transform-origin` tests on `clipPath`, gradients and patterns now pass (the property is read for `gradientTransform`, `patternTransform` and the `clipPath` transform too): `structure` passes 194 of 230 (84.3%). The table and reasons below were measured on the style-sheet work alone, before that merge.

The `structure` category after this step, by directory (pass / rendered; excluded tests are external files, scripts and DTDs):

| directory | before | now |
|---|---:|---:|
| style (style sheets) | 6 / 17 | 17 / 17 |
| style-attribute | 4 / 4 | 4 / 4 |
| switch | 1 / 13 | 13 / 13 |
| systemLanguage | 4 / 10 | 6 / 10 |
| use, symbol, g | 57 / 60 | 59 / 60 |
| image | 0 / 34 | 13 / 34 |
| transform-origin | 3 / 23 | 15 / 23 |
| svg | 34 / 43 | 35 / 43 |
| transform | 13 / 19 | 13 / 19 |
| defs | 2 / 7 | 2 / 7 |
| **structure** | 124 / 230 (53.9%) | 177 / 230 (77.0%) |

The 53 that still differ, by reason (27 + 23 + 3):

- **Edge anti-aliasing, 27.** The reference rasterizer samples coverage on a 4 x 4 grid, so a vertical or horizontal edge lands on a multiple of a quarter pixel (a stroke edge at 1.875 px is drawn at 2.0, and 5.625 at 5.75); this renderer keeps exact area. At 3.75 output pixels per unit (`viewBox` 80 drawn at 300) the 1 unit frame that ends each of these test files differs by 33 of 255 along its four edges, which is 2.6% of the pixels against the 0.25% allowed. In 12 `image` tests (the raster formats, `nested-*`, `with-transform`) that frame is the only difference: 0% of the pixels in the interior differ, and the pictures match the reference to within bilinear rounding. Seven nested-SVG image tests add 0.3% on the edges of their rounded squares to the frame, six `transform` tests and `svg/no-size` and `svg/preserveAspectRatio=none` differ by 0.27 to 2.6% on edges alone. Comparing each pixel with its eight neighbors in the reference does not absorb it: the difference is in coverage, not position.
- **Another step's feature, 23:** gradients and patterns (`defs` 4, `svg/funcIRI-*` 3, `systemLanguage` on `defs` and a gradient 2, `use/complex-style-resolving-order`), `clipPath` (`systemLanguage/on-clipPath`, `image/objectBoundingBox-clip-on-sliced-image`) and text (`defs/style-inheritance-on-text`, `systemLanguage/on-tspan`, `transform-origin/on-text` and `on-text-path`, `image/embedded-svg-with-text`).
- **Deliberate differences, 3:** `svg/zero-size` and `svg/negative-size` (see above) and `svg/not-UTF-8-encoding`.

Cost of the cascade, local smoke on a loaded shared host (load 13-15, .NET 10.0.400, BenchmarkDotNet short job, high variance): a drawing of 20,000 shapes with 400 style rules (type, class, id, attribute, child, descendant and structural selectors) is parsed, cascaded and turned into a render tree in 276 ms and 94 MB, against 186 ms and 90 MB for the same drawing with every declaration on the element. Hostile sheets against a 2.7 MB document of 100,000 shapes (default limits, same host): a failing descendant chain under 200 nested groups and a 20-step general-sibling chain over 100,000 siblings both reach the 100 million step budget and fail with `ImageLimitException` after 0.4 s and 0.9 s (about 90 MB allocated, 265 MB peak for the process); `:nth-of-type` over 100,000 siblings finishes in 0.4 s because positions are counted once per parent.

### Markers and blending results

`painting` went from 165 to 256 of 307 (53.7% to 83.4%) on the committed subset, on top of the style-sheet step. By subcategory (before, now): marker 7 to 58 of 63, mix-blend-mode 4 to 19 of 21, isolation 1 to 2 of 2, paint-order 0 to 12 of 14, overflow 1 to 5 of 5, context 6 to 13 of 16, shape-rendering 5 to 6 of 8. The 51 `painting` tests that still fail, with their reasons:

- text, which is a later step (22): `*-on-text`, `*-on-tspan`, `tref`, `marker/with-a-text-child`, `marker-on-text`, `context/with-text`, the gradients and patterns on text;
- dash positions (13: `stroke-dasharray` and `stroke-dashoffset`, 0.28 to 0.37% against the 0.25% allowance): this renderer places dash ends by the exact arc length, resvg by a flattened outline, so the ends of the dashes of a circle drift against each other by up to 0.4 px per turn (measured on `even-count`: 0.01 px at the first edge, 0.38 px after one turn). The gap is anti-aliasing at the dash ends, not a wrong shape;
- `visibility/bbox-impact-1`, `-2`, `opacity/bBox-impact` (11.7%): a hidden or transparent element still counts in the bounding box a `clip-path` in `objectBoundingBox` units is resolved against; the clip step's;
- `image-rendering/high-quality`, `optimizeSpeed`, `optimizeSpeed-on-SVG` (2.6 to 2.8%) and `on-feImage` (filters): the image step's;
- `context/with-pattern-in-use` (0.83%) and `with-pattern-objectBoundingBox-in-use` (21.6%): pattern tile period, as described under paint servers;
- `marker/orient=auto-on-M-C-C-4` and `-5` (0.26 and 0.25%): the markers are placed as in the reference; the difference is the stroke of the sharp turn where the two curves meet, anti-aliasing at the limit of the allowance; `orient=auto-on-M-L-Z` (0.44%): the stroke of a closed line that goes there and back was drawn twice as dense as the reference, because the stroke outline's two overlapping halves added their partial coverage. The stroker now merges outlines that lie on themselves (see the drawing page), and these three pass;
- `mix-blend-mode/saturation` (2.4%): the reference is brighter than the W3C non-separable formula gives (we follow the formula);
- `shape-rendering/on-horizontal-line` (0.54%): with anti-aliasing off, a pixel whose center lies exactly on the edge of a 1.5 px line is in the reference and out here;
- `fill/rgba-0-127-0-50percent` (64%): the reference renders black for `rgba()` with a percent alpha; this renderer follows CSS Color 4 and draws the translucent green;
- `shape-rendering/optimizeSpeed-on-text`: text.

Two marker rules were taken from the reference images, not from the specification: the first vertex of a closed subpath has only the outgoing direction (the specification averages in the closing segment), and the vertex a closepath makes at the start of a closed subpath that another subpath follows is not drawn.

A marker- and blend-heavy drawing, 1000 x 800 with 250 paths of 25 vertices carrying arrow, dot and square markers and 60 groups blended with `mix-blend-mode` and `isolation`, and a polyline of 10,000 vertices with a marker on every vertex, both at 1024 px wide (local smoke, load 15 to 16 on a shared host, AMD Ryzen 9 7950X3D, .NET 10.0.11, BenchmarkDotNet short job, `SvgMarkerBenchmarks`):

| row | before | now | allocated before | now |
|---|---:|---:|---:|---:|
| markers and blends, OneImage load + render | 120.6 ms | 39.9 ms | 83.3 MB | 25.3 MB |
| markers and blends, OneImage render (loaded) | 82.6 ms | 28.8 ms | 64.9 MB | 6.7 MB |
| markers and blends, Svg.Skia load + render | 125.3 ms | 103.9 ms | 18.7 MB | 18.7 MB |
| markers and blends, Svg.Skia render (loaded) | 82.8 ms | 69.8 ms | managed 184 B | managed 184 B |
| 10k-vertex polyline, OneImage load + render | 62.0 ms | 30.4 ms | 99.8 MB | 47.8 MB |
| 10k-vertex polyline, OneImage render (loaded) | 26.1 ms | 10.6 ms | 59.8 MB | 7.4 MB |
| 10k-vertex polyline, Svg.Skia load + render | 101.7 ms | 79.2 ms | 30.6 MB | 30.4 MB |
| 10k-vertex polyline, Svg.Skia render (loaded) | 28.4 ms | 28.2 ms | managed 184 B | managed 184 B |

(`SvgMarkerBenchmarks`; BenchmarkDotNet 0.15.8 short job, `[MemoryDiagnoser]`; worker: AMD Ryzen 9 7950X3D, 32 logical cores, .NET SDK 10.0.402 / runtime 10.0.13, load average 2.9 before, 5.7 to 8.6 during and 6.1 after (other jobs on the worker); "before" is the commit before the render-cost work, run in the same session.) The 10,000-vertex document renders with a peak resident set of 136 MB for the whole process (a stopwatch run of ten renders, measured before the work above). Rendering is ahead of Svg.Skia once loaded and including the load. A blended group's layer is read in place and its tiles return to the pool, so the allocation left in the rendering rows is the output array and the per-fill objects; the load rows now spend most of their allocation on parsing and building the render tree.

## Roadmap

Planned order. Each step is a coherent piece with its own observable claim, measured by the conformance table above and the stated tests.

1. **Document model and shapes** (done). The core render-at-size hook and rewrite; typed document; presentation attributes and the `style` attribute; the render tree for `g`, shapes and `path`; solid fill and stroke with all stroke properties; transforms, `viewBox`, `preserveAspectRatio`, nested `svg`, basic `use`/`symbol`; region rendering; bounding-box natural size. Claim: `shapes` and the stroke/fill groups of `painting` pass at a stated rate, and `Thumbnail` of an SVG renders at the target size (compared against rasterizing then resizing). Result: 96.2% of `shapes`; the render-at-size output equals a direct render within 1 level and differs from a raster downscale (see [Results](#results)).
2. **CSS and structure** (done). `<style>`, selectors, cascade, inheritance, `currentColor`, `switch`, `systemLanguage`, `use` budgets and cycle handling, `data:` images, `transform-origin`. Claim: `structure` passes at a stated rate; the CSS cost limits are tested with hostile stylesheets. Result: 77.0% of `structure` on its own, with the reasons for the rest above; every style, switch and `use` test that does not need another step passes.
3. **Paint servers** (done). Gradients (including focal radial and gradient transforms), patterns, `paint-order`, `context-fill`/`context-stroke` through `use`, plus the brush additions in the core. Claim: `paint-servers` pass rate. Result: 146 of 154 (94.8%); see [Paint servers](#paint-servers-results).
4. **Painting extras** (done, see [Markers and blending](#markers-and-blending-results)). Markers, `mix-blend-mode`, `isolation`, group opacity layers, `shape-rendering`, `image-rendering`, `visibility`, `display`. Claim: `painting` pass rate.
5. **Clipping and masking** (done). `clipPath`, `mask`, viewport clipping; the layer-multiply op (`Image.ApplyMask`). Claim: `masking` pass rate (see [Results](#results)).
6. **Filters, part one** (done). The filter graph, regions and subregions, linear-light float evaluation, and the primitives that map onto existing operations, `feDropShadow` and the CSS filter functions. Claim: the corresponding `filters` directories.
7. **Filters, part two** (done). Component transfer, morphology, tile, convolution completions, turbulence, displacement, lighting, and shared output blocks for filters with wide margins. Claim: 395 of the 406 `filters` files (97.3%, with the suite's fonts; 298 before this step), no test of any other category changed.
8. **Text** (done, see [Text results](#text-results)). `text`/`tspan`/`textPath`/`tref`, per-character positioning through the public cluster API in `OneImage.Text`, fonts from `SvgFontOptions`, fallback, decorations, bidirectional text, paint servers on text. Claim: `text` pass rate 72.8% (279 of 383); variable and color fonts wait on `OneImage.Text`.
9. **Hardening and speed.** Fuzz targets for the document, CSS and renderer; hostile-input tests for every limit; benchmarks (24-megapixel and thumbnail renders, large maps, filter-heavy art) against the .NET SVG renderers and libvips/librsvg; the package readme, release notes and publishing setup. Claim: no fuzz findings after the stated run, and the benchmark table.

## Status

Done: package skeleton, format detection (plain and gzip), natural size (including the content-bounds fallback), the strict bounded XML parser, the typed document and styles, style sheets with the cascade, `switch` and conditional attributes, `data:` images (raster and nested SVG), `transform-origin`, the render tree and region renderer for shapes, strokes, layers, transforms, viewports and `use`/`symbol`, render-at-size in the core, the limits listed above, and the conformance harness with the committed test files. Fuzzed: `svg-xml` (3.9 million executions in 150 s) and `svg-render` (0.7 million in 150 s after fixing one crash, a path whose coordinates overflowed a float, whose repro is in `tests/testdata/svg`; then two runs of 130 s (0.55 and 0.44 million executions), no findings, with style sheets, `switch` and images in the seeds and the CSS and image limits lowered).

A 24×24 icon at 256 px and a 1000×800 illustration of about 3,000 shapes at 1024 px wide (`SvgBenchmarks`; BenchmarkDotNet 0.15.8 short job, `[MemoryDiagnoser]`; worker: AMD Ryzen 9 7950X3D, 32 logical cores, .NET SDK 10.0.402 / runtime 10.0.13, load average 2.9 before, 5.7 to 8.6 during and 6.1 after (other jobs on the worker)). "Before" is the same benchmark on the commit before the render-cost work, run in the same session:

| row | before | now | allocated before | now |
|---|---:|---:|---:|---:|
| icon, OneImage load + render | 329 µs | 141 µs | 434 KB | 323 KB |
| icon, OneImage render (loaded) | 298 µs | 118 µs | 387 KB | 276 KB |
| icon, Svg.Skia 5.2.3 load + render | 334 µs | 363 µs | 78 KB | 78 KB |
| icon, Svg.Skia render (loaded) | 192 µs | 183 µs | managed 184 B | managed 184 B |
| illustration, OneImage load + render | 36.4 ms | 25.2 ms | 57.4 MB | 27.6 MB |
| illustration, OneImage render (loaded) | 25.2 ms | 11.5 ms | 34.9 MB | 5.0 MB |
| illustration, Svg.Skia load + render | 81.6 ms | 78.7 ms | 21.0 MB | 21.0 MB |
| illustration, Svg.Skia render (loaded) | 50.4 ms | 38.5 ms | managed 189 B | managed 184 B |

Measured earlier on another host: resvg 0.48.1 as an external program takes 112 ms for the illustration (process, parse, render, PNG write) and 3.0 ms for the icon. What was slow: a 128 x 128 tile render costs a canvas and, for every shape, a flattened path, an edge table and a coverage buffer; those are now reused from fill to fill on a thread (the tile rasterizer clears and sums only the cells an edge touched, not the whole 130 x 128 accumulator), a layer is read in place and its tiles go back to the pool instead of waiting for the garbage collector, the RGBA 8-bit/float conversions that layer compositing runs per row no longer go through temporary float rows, and tile workers no longer contend on a shared scratch bag. The output is byte for byte the same as before (`bench/OneImage.Benchmarks` `svg-hash` renders the sample documents whole and in regions and prints a hash for each), and the resvg harness has the same result for every test. Rendering a small drawing in one pass instead of tile by tile was tried and was slower (icon 0.49 ms against 0.26 ms): the tiles render in parallel, and a single call draws each shape's tiles one after another. Gradients and patterns are measured in [Paint servers](#paint-servers-results).

Paint servers, a 1000 x 800 drawing of about 600 shapes with 56 gradients and one of about 250 shapes with 26 patterns (rotated, skewed, nested), drawn at 1024 px wide (local smoke, load 18–20 on a shared host, .NET 10.0.11, BenchmarkDotNet short job, `SvgPaintBenchmarks`):

| row | mean | allocated |
|---|---:|---:|
| gradients, OneImage load + render | 15.6 ms | 11.7 MB |
| gradients, OneImage render (loaded) | 12.3 ms | 7.1 MB |
| gradients, Svg.Skia load + render | 22.0 ms | 7.4 MB |
| gradients, Svg.Skia render (loaded) | 13.8 ms | managed 184 B |
| patterns, OneImage load + render | 15.0 ms | 31.7 MB |
| patterns, OneImage render (loaded) | 11.8 ms | 7.0 MB |
| patterns, Svg.Skia load + render | 91.2 ms | 87.9 MB |
| patterns, Svg.Skia render (loaded) | 13.2 ms | managed 184 B |


<!-- https://recursiveai.org/oneimage/docs/psd/ -->

# PSD and PSB

`RecursiveAI.OneImage.Psd` (namespace `OneImage.Psd`) reads and writes Photoshop documents. It has two entry points on one parser:

- **The merged image** is an ordinary `Image` format. `PsdFormat` is registered in an `ImageConfiguration` (it is not in the default configuration, because the default cannot reference a separate package), and `Image.Load`, `Identify`, `Thumbnail` and the rest then work on `.psd` and `.psb` like any other file. Saving an `Image` to PSD writes a flat document.
- **The layers**: `PsdFile.Load` returns a `PsdFile` whose `Document` is an `OneImage.Layers.Document` (pixel, group, fill and adjustment layers with masks, blend modes and clipping). `PsdFile.Save` writes it back. Everything the document model cannot express stays in the file model as opaque blocks and is written back unchanged.

```csharp
var config = new ImageConfiguration().Add(PsdFormat.Instance);
Image.Load("poster.psd", new LoadOptions { Configuration = config }).Resize(width: 800).Save("poster.webp");

using PsdFile file = PsdFile.Load("poster.psd");
file.Document.Render().Save("flattened.png");
file.Save("edited.psd");                       // PSB when the document is wider or taller than 30,000 px
```

## Known limitations

- **Edited layer styles are written from the model.** Gradient and pattern overlays, bevel and emboss, gradient and pattern strokes and gradient glows are modelled and written like the other effects; items the model does not carry (noise gradients, perceptual gradients, the bevel contour and texture, dissolve and darker/lighter color modes, unknown keys) are kept from the block that was read, not edited. Written files are checked against independent readers (ImageMagick, and psd-tools used as a black box), not against Photoshop itself. Effects come back grouped by kind, so their order across kinds is not preserved. See [Layer effects](#layer-effects).
- **Fills with no PSD equivalent are written as pixels.** Linear and radial gradients become gradient fill settings and bitmap patterns or hatches pattern fill settings (RGB documents, 8 or 16 bits); any other brush, and fills in gray or 32-bit documents, are written as a pixel layer of what they draw. See [Writing](#writing).
- **Bevel and emboss, and the aligned gradients and patterns of effects, are approximations.** Bevels follow a diffuse-lighting model of the shape (smooth bevels from a blurred copy, chisel from the edge distance) and match Photoshop within a few levels on the sample files, not exactly. The bevel contour, texture and anti-aliased gloss are not modelled; linear dodge and linear burn highlights and shadows are clamped before the opacity mix (Photoshop clamps after), which changes saturated channels. A pattern overlay on a text layer starts the tiling in a different place than Photoshop. The shape burst gradient of a stroke and stroke emboss (the bevel follows the shape's own edge) are not checked against stored pixels.
- Text, smart objects, vector strokes and the layer effects that are not drawn render from their stored pixels. Multichannel documents are refused. Other fidelity gaps are listed under [What is covered](#what-is-covered).

## What is covered

**Multichannel documents are refused** with a typed error, both as a merged image and through `PsdFile.Load`. Every other color mode (bitmap, gray, duotone, indexed, RGB, CMYK, Lab) loads.

**Modelled, and round-tripped through `PsdFile.Save`:** pixel layers with their offsets, groups (pass-through or isolated), the blend modes the layer model has, opacity, fill opacity, visibility, clipping to the layer below, lock flags, raster masks (area, default value, density, feather, disabled flag), vector masks (rasterized to a raster mask), solid color fill layers, gradient and pattern fill layers (drawn from their settings, see [Gradient and pattern fills](#gradient-and-pattern-fills)), and the adjustment layers levels, curves, hue/saturation, brightness/contrast, exposure, invert, threshold and posterize. These render with the library's own engine.

**Layer effects** (`lmfx`/`lfx2`) are read into an `OneImage.Layers.LayerStyle`, drawn when the document is composited, and written back from the model when the style is created or edited; see [Layer effects](#layer-effects).

**Kept only as their stored pixels plus untouched data blocks:** text layers, smart objects, the layer effects that are not drawn (listed under [Layer effects](#layer-effects); a file with only the legacy `lrFX` block is not parsed), vector strokes, and gradient or pattern fills that cannot be drawn (the fallbacks listed under [Gradient and pattern fills](#gradient-and-pattern-fills)). They render from the raster Photoshop stored with the layer, are not redrawn and cannot be edited here, and their blocks are written back unchanged. Dissolve and the darker/lighter color blend modes are also kept as keys but render as Normal, Darken and Lighten.

**Known fidelity gaps** against Photoshop: brightness/contrast in Photoshop's current (non-legacy) mode is a fitted approximation (see below); hard mix and vivid light differ slightly; vector-mask path operations (combine, subtract, intersect) use the non-zero rule only; levels, curves, hue/saturation, brightness/contrast and exposure layers in CMYK and Lab documents are kept but not applied; the base layer's fill opacity in a clipping group applies to the whole group. Figures are in [Fidelity of the layer render](#fidelity-of-the-layer-render).

## Reading the merged image

The merged image is read in the file's own depth: gray, RGB and indexed at 8, 16 and 32 bits (indexed and bitmap deliver 8-bit RGB and gray), bitmap, duotone as gray, CMYK and Lab converted to RGB through the color engine (8-bit, Lab 16-bit stays 16-bit). Raw, run-length, ZIP and ZIP-with-prediction channels are read, 8, 16 and 32 bits. Multichannel documents are refused with a typed error.

- A composite with transparency is stored by Photoshop blended with white. By default `PsdFormat` removes the white matte so the result is straight alpha; `new PsdFormat(unmatte: false)` returns the stored samples.
- A file without a composite (or with a stub of raw data too short for the image) is rendered from its layers instead.
- The composite is bit-exact on the hand-built files of the test suite for every depth, mode and compression. Against ImageMagick's reader on the corpus below, 215 of 313 files are identical; the others are mostly files with transparency (ImageMagick keeps the matte), CMYK and Lab (different color conversion), and 16/32-bit (a Q8 build quantizes).

## Layers: what maps to what

| In the file | In the document | Notes |
|---|---|---|
| Pixel layer | `PixelLayer` at its offset | Layer bounds are kept; an empty or inverted rectangle is an empty layer. |
| Group (open or closed folder) | `GroupLayer` | Pass-through (`pass`) or isolated with its own blend mode; open/closed state is kept in `PsdLayerInfo.GroupOpen`. Nesting is capped by `PsdLimits.MaxNesting`. |
| Blend modes | `BlendMode` | All the Photoshop modes the model has. Dissolve and darker/lighter color have no equivalent: the key is kept and written back, and rendering uses Normal, Darken and Lighten. |
| Opacity, fill opacity (`iOpa`), visibility, clipping | `Opacity`, `FillOpacity`, `Visible`, `ClipToBelow` | Opacity is stored in 8 bits, so values are quantized to 1/255 on write. The hidden flag follows real files (set means hidden). |
| Locks (`lspf`, flags) | `Locks` | |
| Layer id, unicode name | `PsdLayerInfo.LayerId`, `Layer.Name` | The Pascal name is written in Latin-1 with `?` for other characters; `luni` carries the real name. |
| Raster mask | `LayerMask` | Area, default (outside) value, density, feather, disabled flag. Mask parameters are read in either position Photoshop uses. |
| Vector mask (`vmsk`/`vsms`) | A raster mask | The path is rasterized with the non-zero rule at the layer's size. With both kinds, the two are multiplied. The written mask carries the flag that says it already includes the path. |
| Solid color fill (`SoCo`) | `FillLayer` | Written as a document-size layer plus `SoCo`. |
| Levels, curves, hue/saturation, brightness/contrast, exposure, invert, threshold, posterize | `AdjustmentLayer` | Per-channel levels and curves apply before the master set. Posterize, curves and brightness/contrast use Photoshop's formulas, described under [Adjustment formulas](#adjustment-formulas). Levels, curves, hue/saturation, brightness/contrast and exposure layers of CMYK and Lab documents are kept as placeholders (the pixels were converted to RGB, and these act on ink or Lab channels), and written as an identity levels layer, since their parameters mean nothing in an RGB file. Invert, threshold and posterize apply as usual. |
| Gradient and pattern fills (`GdFl`, `PtFl`), shape layers with such fills | `FillLayer` with a gradient or pattern brush | Drawn from the settings; the original block is kept and written back while the brush is untouched, and a new or replaced gradient or pattern brush is written as new settings (see [Writing fills](#writing-fills)). Fills outside the supported subset, or read with `PsdReadOptions.DrawFills = false`, are pixel layers of the stored pixels. |
| Layer effects (`lmfx` preferred, else `lfx2`) | `Layer.Style` | Drop shadow, inner shadow, outer and inner glow, solid stroke, color overlay, satin are drawn; an untouched style is written back byte for byte, a created or edited one is written as a new block that keeps what the model has no field for. See [Layer effects](#layer-effects). |
| Text, smart objects, effects that are not drawn, strokes (`vstk`) | Pixel layer + kept blocks | Drawn from the stored pixels only; the blocks are written back untouched. |
| Image resources, ICC profile, document-level blocks | `PsdFile.Resources`, `SourceProfile`, `DocumentBlocks` | Kept and written back. Document-level odd-length blocks keep their unpadded length so they write back byte for byte. |
| Layer info of 16 and 32-bit files | `Lr16` / `Lr32` blocks | Written like Photoshop does. |

Not stored in the file: the document `Background` (it is a render-time color, so a merged image written with a white background reads back as layers over transparency), and anything the layer model does not have (smart-object contents, vector strokes as editable data, effects the style model has no kind for).

Defaults of the model: 8-bit gray files load as `GrayAlpha8` documents, other files as RGB (`Rgba8`, `Rgba16`, `RgbaF32` by depth), CMYK always as 8-bit RGB. Colors of CMYK/Lab layers go through the color engine, so layers of CMYK files are not bit-for-bit the file's samples.

## Writing

`PsdFile.Save` writes layers with run-length coding (default) or raw channels, 8, 16 and 32 bits, a merged image rendered from the layers (with an alpha channel when the background is not opaque), the sRGB profile, and a PSB when the document is wider or taller than 30,000 px or `PsdWriteOptions.Large` says so (a PSB holds up to 300,000 px). A layer with no PSD equivalent (a custom adjustment) throws `ImageOperationException` instead of being dropped; a fill layer whose brush has no gradient or pattern equivalent is written as a pixel layer of what it draws (see [Writing fills](#writing-fills)), and a style is written as an effects block (see [Layer effects](#layer-effects)). A non-seekable stream is written through a temporary file.

Writing the same loaded file twice gives the same bytes, and a document read back from a file renders to the same pixels as the document that was written (opacities are quantized to 8 bits first).

## Adjustment formulas

These three were derived from the composites Photoshop stored in the sample files (each file applies one setting to a strip of a photograph and a color ramp, so the stored composite against our render of the layers below gives the transfer function exactly), not from any other implementation. The public `Image` methods keep their defaults; the formulas are options (`PosterizeMode.Buckets`, `CurveInterpolation.Natural`, `BrightnessContrastMode.PhotoshopLegacy` / `PhotoshopSmooth`) that the PSD reader selects.

- **Posterize** cuts the range into `levels` equal bins and rounds each bin down. On 8-bit samples a value `v` goes to bin `k = floor(v * levels / 256)` and the output is `floor(k * 255 / (levels - 1))`, so 3 levels give 0, 127, 255 with the edges at 86 and 171, and 13 levels give 0, 21, 42, 63, 85 and so on (rounding down, not to nearest). 16-bit and float samples use `floor(v * levels)` and `k / (levels - 1)`. Exact against the stored 8-bit files (0 error); 16-bit files differ by about 0.1-0.3 levels in the mean, at bin edges.
- **Curves** interpolate the control points with a natural cubic spline (zero curvature at both ends) in 0..255 coordinates, flat before the first and after the last point, with the result clamped; the per-channel curves act first and the composite curve after them. Points that are not in output order give a non-monotone curve, as in Photoshop. Mean error against the stored composites is under 0.01 levels (maximum 1). The public `Curves` keeps its monotone interpolation by default.
- **Brightness/contrast, legacy mode** (a `brit` block without a `CgEd` descriptor, or a descriptor with `useLegacy` set): with brightness `b` in levels (-150..150) and contrast `c` (-100..100), `c8 = trunc(c * 2.55)`; for `c >= 0` the slope is `k = 255 / (255 - c8)` and `out = k * (v + b - 127) + 127`; for `c < 0` it is `k = (255 + c8) / 255` and `out = k * (v - 127) + 127 + b`; results are rounded and clamped. Exact on the sample files except one level at a few values.
- **Brightness/contrast, current mode** (Photoshop CS3 and later keep the real settings in a `CgEd` descriptor next to a zeroed `brit` block; older readers saw no adjustment at all). Photoshop bends the tone curve instead of shifting it, and the exact curve is not documented. `PhotoshopSmooth` is an approximation fitted to four stored settings: a quadratic bow `x + 1.7 * (b / 150) * x * (1 - x)` followed by a soft contrast slope about 0.5 (the legacy slope to the power 0.2). It brings the sample files from about 37 levels of mean error to about 8; individual layers range from 5 to about 25 levels. Treat it as an approximation.

A model-built adjustment written to a PSD file always uses the file's formulas: a posterize layer is written as `post` (buckets), a curve as `curv` (read back as a natural spline) and brightness/contrast as the legacy `brit` block, so build documents meant for PSD with the matching mode. A loaded layer is written back from its own stored block, byte for byte.

## Gradient and pattern fills

Fill layers (`GdFl`, `PtFl`) and shape layers filled with a gradient or pattern are drawn by the library as `FillLayer`s with a gradient or pattern brush, so they scale, move and composite like any layer. `PsdReadOptions.DrawFills` (default true) turns this off: the layers then load as pixel layers of the stored raster, as before. An unchanged fill is written back as its original block plus the brush rendered over the document; a replaced brush is written as described under [Writing fills](#writing-fills).

The rules were derived from the rasters and composites Photoshop stored in the sample files, not from any other implementation.

- **Gradients:** linear, radial, angle, reflected and diamond styles with angle, scale, offset (percent of the box), reverse, color and opacity stops, midpoints and smoothness. Position is evaluated at integer pixel coordinates relative to the box center. The gradient line is the chord through the box center at the angle, of length `scale * min(w / |cos|, h / |sin|)`; radial, reflected and diamond use half of it as the radius, and the angle style starts at the angle and runs clockwise. Between stops the position is bent by the midpoint, then eased by `smoothness` toward a smoothstep. Colors interpolate in encoded values, or in linear light when the fill says so. Stop colors in RGB, gray, CMYK and Lab are converted through the color engine.
- **Patterns:** tiles come from the document's pattern resources (`Patt`, `Pat2`, `Pat3`; RGB or gray, 8 or 16 bits, raw or run-length coded). The tile origin is the document origin for fill layers and one pixel right of the box corner for shape layers.
- **Box:** shape layers use the vector path bounds; fill layers use the layer rectangle, else the raster mask rectangle, else the document; "align with layer" off means the document.
- **Stored colors win:** where Photoshop wrote a raster for the layer, the drawn fill takes its colors from it and keeps its own alpha, so the common case matches Photoshop exactly and the drawing only supplies what was not stored (an enlarged or edited layer).
- **Falls back to the stored pixels** for noise gradients, perceptual interpolation, stop colors that are foreground/background or HSB, boxes with a side under 16 px, patterns with a scale other than 100%, an angle or a phase, missing or unsupported patterns (not RGB or gray, or with alpha), and descriptors that are truncated or out of range. Photoshop snaps gradient direction and length to whole pixels; that is not modelled.

Against the stored rasters without the stored-color rule, patterns are exact, gradients typically differ by 0.1 to 1.2 levels in the mean (worst case 6.8, a 60 degree reflected gradient on 32 px), and gray and CMYK fills by 3 to 6 levels. Midpoint ownership with three or more stops is checked on one file only.

## Writing fills

A fill layer whose brush is still the one read from the file keeps its settings block (see above). A new or replaced brush is written like this (`FillWriter`; the brush is read through its language-neutral `Describe()`):

- **Solid color:** a `SoCo` block, as before.
- **Linear and radial gradients** (`Brush.LinearGradient`, `Brush.RadialGradient`) become a `GdFl` block when the stops lie in 0..1, the repetition is `None`, the document is RGB at 8 or 16 bits (not gray, not 32-bit float), the document is at least 16 px on each side, and translucent stops either are not interpolated premultiplied or share one color. The block holds a custom gradient (`CstS`) with the stops at their 0..4096 positions, midpoints 50 and an opacity stop at each color stop, smoothness 0 (a straight blend between stops, which is what the brush does), "align with layer" off (the box is the document), the angle, a scale of `length / chord` in percent (see the geometry above; accepted from 0.1 % to 10,000 %, while Photoshop's own dialog offers 10 % to 150 %) and the offset of the gradient's middle from the document's middle. The brush measures at pixel centers and the settings at integer coordinates, so the middle moves by half a pixel; radial gradients are written at angle 0 and scale `2 * radius / width`. Drawn back from the settings, such a gradient differs from the brush by at most 2 levels (test), except at a hard edge between two equal positions, which moves by up to a pixel.
- **Bitmap patterns and hatches** (`Brush.Pattern`, `Brush.Hatch`) become a `PtFl` block (pattern at 100 %, angle 0, not aligned) plus a pattern entry in the document's pattern resources (`Patt` for 8-bit documents, `Pat2` for 16-bit, added to the block the document already has): header, name, id, and a virtual memory array list with three raw planes, in the layout of the one example in the sample files. The id is a GUID-shaped string made from a hash of the pixels, so the same tile is stored once however many layers use it, and a saved file is reproducible. Both colors must be opaque and the brush must have no transform; the tile is drawn from the document origin, which is what the brush does, and drawn back from the resource it is identical to the brush.
- **Everything else is written as pixels:** repeating or reflecting gradients, elliptic and path gradients, stops outside 0..1, image brushes, recolor brushes, custom brushes, patterns with a transparent color or a transform, patterns in 32-bit or gray documents, gradients in gray documents or small ones. The layer becomes an ordinary pixel layer named like the fill, covering the document, holding what the brush draws (it loads back as a `PixelLayer`). Its blend mode, opacity, mask and style are written as for any layer.

In every case the raster Photoshop stores beside the settings is the brush drawn over the document, so other readers (and a load with `DrawFills = false`) show the fill, and a load returns the same render and writes the same bytes again.

Independent readers, run as black boxes on files written this way: ImageMagick reads the merged image (equal to the render) and every layer with its name, offset and stored raster; psd-tools 1.26.0 reads the settings (kind gradient fill or pattern fill, the pattern from the resources) and draws radial gradients within 3 levels and hatches exactly. It draws linear gradients with another geometry (angled: a different gradient length; axis aligned: it applies an ease between stops although smoothness is 0), and the geometry used here is the one fitted to Photoshop's own rasters, so that difference is not changed.

## Layer effects

The effects block (`lmfx`, else `lfx2`) of a pixel, shape or fill layer is read into a [`LayerStyle`](https://recursiveai.org/oneimage/docs/layers/#layer-styles) and drawn at composite time from the layer's own shape, so moving or editing the layer redraws them. The master effects switch, a layer's "effects visible" flag (`lrFX` common state) and each effect's enabled flag are respected; disabled effects are read as disabled effects (up to the same number again as the drawn limit), draw nothing, and are written back. Effects that use the global light take the document's light angle (image resource 1037).

**Drawn:** drop shadow, inner shadow, outer glow, inner glow (edge or center source, range, or a gradient instead of the color), a stroke (outside, inside, center; solid, gradient or pattern), color overlay, gradient overlay, pattern overlay, bevel and emboss and satin, each with its blend mode, opacity, color, size, distance, spread/choke and contour. Several effects of one kind (the "multi" lists of newer Photoshop) are drawn in file order. Shadows and glows use a blur of 0.41 x size as the Gaussian sigma; spread and choke grow or shrink the shape by that fraction of the size before blurring.

**Not drawn (counted in `PsdLayerInfo.EffectsNotDrawn`, kept and written back):** gradients that are noise or use perceptual interpolation, a pattern that is not in the document or is not RGB or gray, effects whose blend mode is dissolve or darker/lighter color, effects with a value outside the model's range (size above 250, distance above 30,000, a contour that is not a clean increasing curve of at most 256 points), effects beyond `PsdLimits.MaxEffectsPerLayer` (32), effects on groups and adjustment layers. The random grain of a shadow or glow is dropped and counted in `EffectsApproximated`, as is a layer whose own vector stroke (`vstk`) Photoshop draws inside the effects.

**Rules the renderer follows** (derived from the stored composites of the sample files):

- The shape is the layer's alpha times its mask. Fill layers and layers with a vector mask use the mask coverage alone (a gradient's transparency is fill, not shape).
- An outside stroke is drawn below the layer's pixels with antialiased edge pixels fully covered; an inside stroke replaces the pixels it covers; a centered one does both halves.
- A color overlay recolors the layer's pixels and leaves their alpha alone, so fill opacity scales it; shadows, glows, satin and strokes do not follow fill opacity. With fill 0 a drop shadow shows only outside the shape (knockout).
- A shadow moves by (-cos a, sin a) x distance, y down.
- Drawing order, bottom to top: drop shadows, outer glows, outer parts of bevels and embosses, the pixels, color overlays, gradient overlays, pattern overlays, satin, inner glows, inner shadows, inner parts of bevels and embosses, strokes.
- **Gradient overlays and gradient strokes** use the layout of the gradient fills (position taken at a pixel's integer coordinates, length `scale x chord of the box along the angle`) on the shape's bounds: the outline of a vector mask, else the rectangle around the visible pixels (`LayerStyle.AlignBox`, set by the reader), or the whole document when not aligned. Checked on the Gradient Overlay layer of `layer_effects.psd` (error 0.1 to 0.3 levels inside the letters). A gradient glow maps the glow's falloff onto the gradient with the first stop at the shape (checked on one layer of `layer_params.psd`: the edge pixel differs by 2 levels). A shape burst stroke maps the distance from the edge over the stroke size.
- **Pattern overlays** tile the pattern one pixel right of the shape's bounds and at its top edge (fitted on shape layers; on the text layer of `layer_effects.psd` the tiling starts elsewhere, which was found by scanning for the best offset (47, 75 mod 80) but not explained, so a text layer keeps the rule above and shows the wrong phase). Scale resamples with nearest-neighbor.
- **Bevel and emboss:** the shape becomes a height field of `depth x size x profile`. Smooth bevels use the shape blurred with sigma 0.41 x size (so the slope stays continuous in thin parts: a 163 px disc with size 100 matches the stored shading in red and green within 2 levels), chisel bevels use the signed edge distance as a straight ramp (chisel soft blurs it by 1 px), pillow emboss makes the edge a valley, and `soften` blurs the field. The light is `(cos alt cos angle, -cos alt sin angle, sin alt)`; with the surface normal from the field's gradient, lighting above the flat value `sin alt` is highlight, below it shadow, each scaled so a surface facing the light squarely (or fully away) reaches 100 %, then through the gloss contour, then the highlight or shadow color with its mode and opacity. An inner bevel draws inside the shape only, an outer bevel outside only, emboss and pillow both sides (the outside part under the layer's pixels). Steep slopes that face sideways are darker than the flat middle, as with any diffuse light.

Satin and contours are implemented from Photoshop's description but not verified against stored pixels (no sample file isolates them). Corners of outside strokes are about 0.07 px off, and the glow range and spread/choke rules were fitted on few files.

**Saving** (`EffectsWriter`):

- **Untouched:** a layer whose `Style` is still the object read from the file keeps its effects blocks (`lfx2`/`lmfx` and the legacy `lrFX`) byte for byte.
- **Created or edited:** any other style (including a new but equal one, or `null`) is written as a new effects block, version 0 with a version 16 descriptor, with the items Photoshop writes for each kind (`enab`, `present`, `showInDialog`, mode, color as `RGBC`, opacity in percent, `uglg` false with the explicit angle, distance/choke/size in pixels, `Nose` 0, a contour as a `ShpC` curve on 0..255, `layerConceals`, glow range and source, stroke style, satin inversion). A kind with one effect uses its single key (`DrSh`, `IrSh`, `OrGl`, `SoFi`, `FrFX`, `IrGl`, `ChFX`); several effects of a kind use the list key (`dropShadowMulti`, `innerShadowMulti`, `solidFillMulti`, `frameFXMulti`). Percent values and angles are written as the decimal the float prints as, so reading the block back gives the same float; angles beyond +-360 are written as the same direction within +-360. The legacy `lrFX` block, which would keep showing the old effects, is left out of an edited layer, and an edited block replaces both `lfx2` and `lmfx` where a layer has them.
- **What is kept of the block that was read:** every root item of its descriptor keeps its place and bytes, except the items that became model effects (those are rewritten from the model, which is why they follow the model's order within a kind). So `Scl`, gradient and pattern overlays, bevel and emboss, gradient strokes and glows, an enabled effect that could not be read (dissolve blend, a value out of range), disabled effects the model could not hold, and any unknown key survive an edit of the effects the model does carry. An effect object that is still the very one read from the file is written back as its original item, including grain, anti-aliasing, glow technique and contour names. An effect that is replaced by a new object (effects are immutable, so any edit is one) is written from the model alone: details the model has no field for are not carried over to it. `numModifyingFX`, when present, is set to the number of enabled items.
- **Not kept:** a block whose master switch is off (or that the legacy block hides) is dropped when a style is set, so effects that were never visible do not appear; the legacy `lrFX`; `ShapeFromMask` (it follows the layer's vector mask on reading). Photoshop stores one outer glow, inner glow and satin per layer: a style with more than one of those kinds throws `ImageOperationException` (a disabled one that came from the file gives way to an added one). Reading the block back returns the effects grouped by kind in the reader's fixed order, so the order between kinds can differ from the model's (it does not affect the drawing). A style on a group or an adjustment layer is written too.
- **Written files, second write:** the loaded style is the object read from the block that was written, so saving it again writes that block back and the file is byte-identical.

The item names and structure were taken from the effects blocks of the sample files; Photoshop itself was not available to open the result, so `lrFX` omission and the single-versus-list choice are unverified there.

**Fidelity of the gradient, pattern and bevel effects** (mean error against the stored composite, levels 0-255; before is with these effects drawn from the stored pixels only): clipping-mask2 24.5 to 0.8, effect-enums 8.5 to 1.5, shape-fx2 43.1 to 6.5, stroke-composite 12.9 to 2.0, stroke-effects 11.7 to 5.0, layer_comps 9.0 to 3.8, layer_effects 4.6 to 2.2, layer_params 4.6 to 1.7, patterns 13.3 to 3.5, fill_adjustments 69.8 to 27.1 (its other layers are adjustments that are not drawn). Eight more files count as fully modelled (178 instead of 170); the 170 that were modelled are unchanged to the last digit (median 0.111), and the median over the 178 is 0.1345 because the new files, which carry bevels and approximated patterns, sit between 0.8 and 6.5. Beyond that the files fall short for known reasons: linear burn and dodge clamp (see the limitation above), the text pattern phase, and the corners of strokes on polygons.

**Fidelity of the first effects** (mean error against the stored composite, levels 0-255): 10 files became fully modelled, among them antialiased-stroke-edge 17.4 to 0.14, center-stroke-sizes 20.7 to 0.04, feathered-stroke 28.8 to 0.07, group-clips-child-stroke 34.4 to 0.11, inset-stroke-sizes 14.8 to 0.00, outside-stroke 36.0 to 0.16, shape-stroke-raster-mask 25.6 to 0.13 and stroke-effect-transparent-shape 40.4 to 0.00. Files that also use effects that are not drawn improved without being exact: layer_effects 108 to 4.6, stroke-effects 43 to 12, blend-modes 8.0 to 2.2. `EffectCorpusTests` pins the stroke files at 0.5 levels or less.

## Fidelity of the layer render

Rendering a loaded layer tree and comparing with the file's own stored composite (corpus of 316 PSD/PSB test files from the psd-tools project, MIT licensed, fetched by `tools/fetch-psd-tests.sh`, never committed): 315 load; the one that does not is a multichannel file. Of the 152 files with layers and no feature we do not draw (the set before fills were drawn), the median mean error is 0.134 levels and is unchanged with fills drawn; 160 files are fully modelled now (the 8 added are fill files: gradient-fill went from 8.3 to 0.0 levels, vector-mask2 from 71.9 to 1.0), with a median of 0.108 (106 files at or under 0.5, 115 at or under 2, 128 at or under 10; it was 0.275 before the Photoshop adjustment formulas). Over all 315 loadable files the median went from 0.353 to 0.276. The 19 files with posterize, curves or brightness/contrast layers (or the adjustment compositions that use them) have a median of 0.005 (was 10.5): posterize, curves and legacy brightness/contrast layers are now exact or within a level. The rest differ for known reasons:

- stored composites that are stale or are Photoshop's "not saved with a composite" placeholder (`layers-minimal/*`, `masks/2.psd`, `note.psd`);
- text, smart objects, vector strokes and the layer effects that are not drawn or only approximated (see [Layer effects](#layer-effects)) (gradient and pattern fills outside the supported subset also render from stored pixels);
- brightness/contrast in Photoshop's current mode is approximated (mean error 8 levels on the sample files); hard-mix and vivid-light differ slightly;
- path operations on vector masks (combine, subtract, intersect) use the non-zero rule only;
- adjustments in CMYK and Lab documents.

## Limits and safety

Everything is parsed in safe code. `PsdLimits` bounds layers (20,000), group nesting (64), one block (64 MiB), all blocks (256 MiB), decoded channel bytes in total (16 GiB) and per channel (1 GiB), and descriptor depth (32) and items (65,536), and enabled effects per layer (32); `ImageLimits` bounds pixels, dimensions and the expansion ratio of ZIP channels. Every size is checked against the header before anything is allocated, nesting is followed with explicit stacks, and a 300,000 x 300,000 layer rectangle in a few hundred bytes of file fails on its header. `tests/OneImage.Psd.Tests/HostileFileTests.cs` has a crafted file for each limit, and `EffectsTests.cs` has crafted effect blocks (too many effects, oversized sizes and distances, huge contours, deep nesting, truncated and garbage descriptors); `PaintStyleTests.cs` has the same for gradient, pattern and bevel items (stop counts over 256, angles, scales, depths and sizes out of range, a missing, oversized or lying pattern, unknown gradient kinds, truncated and garbage items), where each is skipped and counted or is a typed limit error, and a save, load and second-write test for every new effect kind; the `psd` target ran 10 minutes again on the final code (2,716 executions from a large, slow corpus, no crashes or hangs); the `psd` fuzz target (see `fuzz/README.md`) ran 10 minutes (61,770 executions) clean; after layer effects it ran 10 minutes again (38,454 executions from the sample files and effect seeds; it found a hue/saturation block with an out-of-range value that threw an argument exception, now kept without being reproduced). When the writing of styles and fills was added the target also edits what it read (a style with an extra effect on every layer, a new gradient on every fill layer) and writes and reads the result again. Its first 10-minute run (26,000 executions) found a contour point that is not a number, which made the contour constructor throw an argument exception instead of skipping the effect (fixed; `AContourPointThatIsNotACleanIncreasingCurveSkipsTheEffect` and `testdata/psd/fuzz-contour-point-not-a-number.psd` pin it); after the fix a 10-minute run (8,300 executions on larger seeds) was clean.

## Speed

A 4000 x 3000 PSD with three full-size layers (run-length coded, 36 MB), BenchmarkDotNet short job, .NET 10.0.13, AMD Ryzen 9 7950X3D (32 threads) shared with other jobs (load average 4.9 before the run, 9.9 after), Magick.NET Q8 as the competitor (ImageSharp has no PSD reader). Our default per-call degree of 4 applies.

| Task | Ours | Magick.NET | Allocated (ours / Magick) |
|---|---|---|---|
| Merged image to `Rgba32` | 42 ms | 79 ms | 2.6 MB / 3 KB (managed only) |
| All layers loaded and flattened | 233 ms | 651 ms (decodes the layers, does not composite them) | 132 MB / 8 KB (managed only) |

The loaded host makes the absolute numbers noisy (the error column of the merged row is 26 ms); the ratios held across the 5 iterations. Magick's allocation is native memory and is not counted. Run with `dotnet run -c Release --project bench/OneImage.Benchmarks -- --filter '*PsdReadBenchmarks*'`.


<!-- https://recursiveai.org/oneimage/docs/pdf/ -->

# PDF

`RecursiveAI.OneImage.Pdf` (namespace `OneImage.Pdf`) draws PDF pages as an ordinary image format. It parses and interprets with [OnePDF](https://www.nuget.org/packages/RecursiveAI.OnePdf) (`RecursiveAI.OnePdf` and `RecursiveAI.OnePdf.Fonts`, 1.2.0 or later) and draws on OneImage's drawing engine, so a page is an `Image` like any other: it can be resized, cropped, converted and saved, and only the part of the page that is asked for is drawn.

```csharp
var config = new ImageConfiguration().Add(new PdfFormat(new PdfRenderOptions { Dpi = 150 }));
var pdf = Image.Load("report.pdf", new LoadOptions { Configuration = config });   // every page is a frame
pdf.Frames[0].ToImage().Save("page1.png");                       // the first page
pdf.Frames[0].ToImage().Resize(width: 400).Save("thumb.webp");   // drawn at 400 px
// Saving `pdf` itself writes every page, as an animation or a multi-page file where the format allows.
```

`PdfFormat` is not in the default configuration (a separate package cannot be). Reading is sniffed from `%PDF-` in the first kilobyte.

## Options

`PdfRenderOptions`: `Dpi` (150), `FirstPage`/`PageCount` (the selected pages are frames; the frame size is the page box, with rotation and user unit applied, times dpi/72, rounded to the nearest pixel), `Box` (crop box, limited to the media box), `Annotations` (view, print or none), `GenerateAppearances` (true), `Background` (opaque white; pass a transparent color for the page content alone), `Password`, `Limits` (`PdfRenderLimits`) and `DocumentLimits` (OnePDF's parsing and interpretation limits). Everything is documented on the types.

## How a page is drawn

- The page is interpreted once, at scale 1 in points, into OnePDF's display list. That list is kept with the loaded image together with the shared picture, shading and pattern caches (under a pixel budget).
- A page is drawn in fixed **128 × 128 pixel cells**. A cell replays only the part of the list under it. A region of any size is the cells it touches, cut out, so **a region is byte for byte the same pixels as that part of a whole render, at any degree of parallelism** (tests at degrees 1, 4 and 16, and with concurrent readers).
- The decoder asks for render-at-size: `Resize`/`Thumbnail` draw the page at the final size rather than drawing it large and reducing it.
- Text is drawn as glyph outlines (no hinting), one path per run, in the fill, stroke or clip mode of the text state. Standard-14 and substitute fonts come from `RecursiveAI.OnePdf.Fonts`.
- Images are reduced by area averaging when the page shows them smaller than they are, then sampled bilinearly through the placement. Stencil masks, soft masks, color-key masks and `/Decode` are applied by OnePDF.
- Color: gray and RGB directly; CMYK through the generic CMYK profile; ICC-based spaces through the color engine; CalGray, CalRGB and Lab through XYZ with Bradford adaptation.
- Shadings (types 1–7), tiling patterns (colored and uncolored), soft masks (alpha and luminosity), transparency groups, blend modes and constant alpha are supported.
- **Forms and markup.** A widget or markup annotation with an appearance stream draws it. One without, and every field of a form that sets `/NeedAppearances true`, draws the appearance OnePDF generates (text and choice values, check marks, radio buttons, highlights, lines and so on) unless `GenerateAppearances` is false. Under `NeedAppearances` OnePDF 1.1 regenerates text and choice fields; stale appearance streams of check boxes, radio buttons and push buttons are drawn as they are stored.

## Image codecs

- **DCT** is OneImage's own JPEG decoder, returning the components as stored (no Adobe inversion; OnePDF applies `/Decode`).
- **JBIG2** is OneImage's own decoder (see [jbig2.md](https://recursiveai.org/oneimage/docs/jbig2/)). It returns the page in the standard's sense, 1 for black, and OnePDF applies the PDF inversion, `/Decode` and `/ImageMask`. `/JBIG2Globals` are passed separately. A **damaged stream throws in the decoder; the bridge treats that as an image that cannot be decoded, leaves it out and draws the rest of the page** (OnePDF records a diagnostic). A stream that exceeds a `Jbig2Limits` or `ImageLimits` bound is left out the same way.
- **JPEG 2000** is OneImage's own decoder (see [jpx.md](https://recursiveai.org/oneimage/docs/jpx/)), registered at `PdfImageCodecs.Jpx`. Colour channels come out in the colour space the file states (sRGB, gray, CMYK; sYCC is converted to RGB; ICC-described RGB, gray and CMYK are converted to sRGB or gray, because a profile cannot be handed to OnePDF) and the opacity channel, if any, comes last, so OnePDF applies `/SMaskInData`, the declared `/ColorSpace` and masks. ISO 32000-2 7.4.9 has `/Decode` ignored for JPX images that are not masks, and OnePDF follows it. An image of more than 2^26 pixels is decoded at a reduced resolution. A file that is damaged inside its tile data, or beyond a limit, gives no image: it is left out and the page draws. The decoder is not told how large the page shows the picture, so smaller placements still decode at full size (only the pixel budget reduces).

## Limits

`PdfRenderLimits` bounds what one file may cost, each checked against the value the file states, before the memory is allocated. They apply together with the `ImageLimits` of the load call and OnePDF's own limits.

| Limit | Default | Behavior beyond it |
|---|---|---|
| frame size (`ImageLimits`) | pixels per frame, dimension | the load fails with `ImageLimitException` before anything is drawn (a 14,400 pt page at 150 dpi, a huge dpi) |
| `MaxFileBytes` | 1 GiB | `ImageLimitException` before reading |
| `MaxImagePixels` | 2²⁶ | the image is skipped without decoding (declared size is read from the dictionary) |
| `MaxNesting` | 24 | groups, soft masks and pattern cells drawn at once; deeper content throws `ImageLimitException` |
| `MaxClipDepth` | 4,096 | `ImageLimitException` |
| `MaxPatternTileSide` | 2,048 | the cell is drawn at a lower resolution |
| `MaxPatternCopies` | 64 | further copies are not drawn into the tile |
| `MaxCachedPixels` | 2²⁶ | pictures beyond the budget are rebuilt when needed instead of kept |

A pattern that paints with itself is bounded by the nesting limit. The tests build one hostile file per row (`tests/OneImage.Pdf.Tests/LimitTests.cs`), including the allocation made before a refusal.

## Fuzzing

`fuzz/run.sh pdf <seconds>` loads a file, draws a resized whole page and two regions under small limits, seeded from `testdata/pdf` and any folders in `ONEIMAGE_PDF_SEEDS`. Seeded from the 307 files of OnePDF's test set and run for 10 minutes: 85,718 executions, no crashes, hangs or out-of-memory inputs.

## Known approximations and limitations

- Transparency groups: a non-isolated group that needs compositing (opacity below 1, a blend mode or a soft mask) is painted on a copy of its backdrop with its own coverage tracked apart, so blend modes inside it see the page and the backdrop is not counted twice (11.4.5, 11.4.8); an opaque backdrop is assumed, a translucent one is approximated. A knockout group (11.4.6) replaces what is under each object instead of accumulating; blend modes of objects inside a knockout group are not applied. A non-isolated group with none of these needs is drawn straight onto its parent, which is exact. Overprint is ignored.
- **Knockout of text and of fill-and-stroke.** `B`, `B*`, `b` and `b*` (11.7.4.4) arrive as one device call; with a translucent stroke the fill is painted without the stroke's area, so the stroke replaces it instead of compositing over it. Text knockout (9.3.8, `/TK`, true by default) is applied to the glyphs of Type 3 fonts, which are drawn as content: while translucent glyph procedures follow each other they share one knockout layer. Outline glyphs of one string are already one shape; overlapping translucent glyphs of *different* strings of a text object (separate `Tj`/`TJ` elements) still accumulate, because the device is not told where a text object begins and ends.
- Image edges are anti-aliased rather than snapped to the pixel grid. A picture shown larger than its samples is drawn with square samples unless it sets `/Interpolate true` (8.9.5.3: interpolation is off by default); the references often smooth it anyway. A reduced picture is area-averaged, then sampled bilinearly.
- Text is unhinted and drawn with exact-area coverage, which looks lighter than PDFium's and heavier than MuPDF's.

### Known limitations

- **Soft-mask `/TR` is treated as identity.** OnePDF does not expose function evaluation to devices. Needed from OnePDF: either a public `PdfFunction.Create(PdfObject)`/`Evaluate(ReadOnlySpan<double>, Span<double>)`, or a 256-entry transfer table on `PdfSoftMaskInfo` (null for identity).
- **Text in a non-embedded CJK font draws blank.** The package carries only the standard Latin fonts; there is no CJK fallback font yet.
- **Check boxes, radio buttons and push buttons under `/NeedAppearances true` keep their stored appearance.** OnePDF regenerates text and choice fields only.

## Render gate

SSIM against other renderers is a signal, not the bar: three renderers disagree with each other on many pages, and none of them is the standard. The standard is ISO 32000-2, so the gate finds the pages worth a look and a person judges each against the specification.

**Method.** Page 1 of each of the 307 files in OnePDF's test set (generated, real-world, US government, PDF 2.0 examples and veraPDF files) is drawn at 150 dpi by this package and by three reference renderers used as black-box programs: PDFium (pypdfium2, with a form environment), MuPDF (`mutool draw`) and pdf.js (headless Chrome). SSIM is computed on luminance with a 7 x 7 window. `tools/pdf-gate/gate.py` flags a page when any of these holds:

1. our SSIM is below 0.98 to at least two references **and** our SSIM to the closest reference is below the best SSIM between any two references on that page (we are further from the references than they are from each other);
2. our SSIM to the closest reference is below 0.90 (floor, a gross-error alarm);
3. we did not draw the page, or no reference drew it;
4. only one reference drew it and we are below 0.98 to it.

Every flagged page gets a row in `tools/pdf-gate/verdicts.csv`: the page, a verdict, the ISO 32000-2 section, the reason and the renderers that deviate. A flagged page without a row is reported as `unreviewed`. The verdicts are:

- **ours-correct**: we follow the specification and the named renderer deviates.
- **ours-wrong**: we depart from the specification. It is fixed or listed under the known limitations.
- **ambiguous**: the specification allows both results. Glyph-edge anti-aliasing is implementation-defined (10.7, scan conversion), so a page that differs only there is `ambiguous`; it counts as `ours-wrong` only if glyph shape, position, weight or coverage departs from what the specification defines. An edge-only page is recognised by: embedded outlines, the same ink within 5%, no offset (best sub-pixel shift 0), and a blurred SSIM (Gaussian sigma 2) of at least 0.99 to the closest reference.

The unflagged pages stay unflagged only while the rule holds, so the gate is re-run after any renderer change and new flags get verdicts. A separate suite of generated PDFs with analytically known pixels (`tests/OneImage.Pdf.Tests/SpecTruth`) checks the specification directly, without any reference renderer.

### Result: 26 of 307 pages flagged

| verdict | pages |
|---|---|
| ambiguous | 24 |
| ours-wrong | 0 |
| ours-correct | 2 |

All 26 have a verdict. By cause:

- **ambiguous, 10.7 scan conversion (edge anti-aliasing only), 10 pages:** cjk-03, cjk-05, math-02, math-04, math-08, multi-column-01, multi-column-02, old-08, report-08, table-02. No renderer is singled out: each differs from the others at glyph edges, PDFium furthest.
- **ambiguous, 10.7 plus 9.6.2.2 and 9.8 (edge anti-aliasing plus non-embedded fonts whose substitutes differ), 7 pages:** cjk-01, cjk-06, rotated-08, rtl-04, rtl-05, table-09, table-05 (PDFium draws lighter, about 83% of our ink).
- **ambiguous, 10.7 and 8.4.3.2 (zero-width rules are drawn as the thinnest line the device can), 1 page:** rotated-07; MuPDF draws the hairlines lighter.
- **ambiguous, 9.6.2.2 and 9.8 (non-embedded Times-like fonts, each renderer substitutes differently), 2 pages:** multi-column-08 and report-10. report-10 is the only page below the 0.90 floor (0.891).
- **ambiguous, 8.9.5.3 (reduction filter of a bilevel scan), 1 page:** 378647; PDFium and MuPDF agree exactly, ours matches pdf.js.
- **ambiguous, 12.5.5 (markup annotations without appearance streams), 2 pages:** raw-appearance-markup and raw-appearance-markup-needap; PDFium omits the shapes.
- **ambiguous, 7.5.6 (damaged file), 1 page:** raw-broken-truncated-stream; all four renderers refuse it.
- **ours-correct, 8.9.5.3 (no interpolation by default), 1 page:** slides-07-zen14027747. A 1536 x 864 noise texture with `/Interpolate false` is shown about 1.3 times enlarged; we draw square samples as the specification asks, and PDFium, MuPDF and pdf.js all smooth it.
- **ours-correct, 7.4.9 (`/Decode` is ignored for JPEG 2000 images), 1 page:** 966677. The banner is one JPEG 2000 image with `/Decode [1 0]` in a Separation color space; we use the samples as stored, as the specification says, and PDFium, MuPDF and pdf.js all apply the array and draw the banner with inverted tones.

By source (flagged / pages; the last column is the strict count, information below):

| source | pages | flagged | 0.98 to two references |
|---|---|---|---|
| generated-chrome | 18 | 0 | 18 |
| generated-enc | 12 | 0 | 12 |
| generated-lo | 6 | 0 | 6 |
| generated-raw | 31 | 3 | 25 |
| generated-tex | 1 | 0 | 1 |
| govdocs | 30 | 2 | 14 |
| pdf20examples | 7 | 0 | 7 |
| realworld | 92 | 21 | 33 |
| verapdf | 110 | 0 | 107 |
| all | 307 | 26 | 223 |

### SSIM tables (information only)

The strict rule (SSIM at least 0.98 to at least two of the other three renderers) applied to each renderer in turn, pages out of the total. It is not the bar; it shows that no renderer, PDFium least of all, meets it everywhere:

| source | pages | ours | PDFium | MuPDF | pdf.js |
|---|---|---|---|---|---|
| generated-chrome | 18 | 18 | 18 | 18 | 18 |
| generated-enc | 12 | 12 | 12 | 3 | 12 |
| generated-lo | 6 | 6 | 5 | 4 | 5 |
| generated-raw | 31 | 25 | 23 | 25 | 25 |
| generated-tex | 1 | 1 | 1 | 1 | 1 |
| govdocs | 30 | 14 | 6 | 12 | 13 |
| pdf20examples | 7 | 7 | 6 | 7 | 6 |
| realworld | 92 | 33 | 12 | 38 | 31 |
| verapdf | 110 | 107 | 107 | 107 | 107 |
| all | 307 | 223 | 190 | 215 | 218 |

By content class (`classify.py`), mean / min SSIM per pair of renderers:

| class | pages | flagged | ours-PDFium | ours-MuPDF | ours-pdf.js | PDFium-MuPDF | PDFium-pdf.js | MuPDF-pdf.js |
|---|---|---|---|---|---|---|---|---|
| dense text | 103 | 21 | 0.945 / 0.783 | 0.968 / 0.856 | 0.977 / 0.891 | 0.948 / 0.788 | 0.938 / 0.786 | 0.970 / 0.843 |
| forms | 21 | 0 | 0.958 / 0.868 | 0.981 / 0.935 | 0.981 / 0.885 | 0.958 / 0.857 | 0.951 / 0.860 | 0.976 / 0.885 |
| images | 13 | 2 | 0.926 / 0.787 | 0.965 / 0.877 | 0.975 / 0.895 | 0.955 / 0.893 | 0.934 / 0.802 | 0.971 / 0.883 |
| sparse | 153 | 1 | 0.998 / 0.939 | 0.998 / 0.982 | 0.998 / 0.952 | 0.998 / 0.927 | 0.997 / 0.939 | 0.998 / 0.952 |
| transparency | 16 | 2 | 0.976 / 0.946 | 0.967 / 0.865 | 0.909 / 0.349 | 0.954 / 0.812 | 0.900 / 0.350 | 0.901 / 0.313 |
| vector | 1 | 0 | 0.996 / 0.996 | 0.999 / 0.999 | 0.998 / 0.998 | 0.997 / 0.997 | 0.996 / 0.996 | 0.998 / 0.998 |
| all | 307 | 26 | 0.973 / 0.783 | 0.984 / 0.856 | 0.984 / 0.349 | 0.974 / 0.788 | 0.966 / 0.350 | 0.981 / 0.313 |

On 67 pages no two references agree at 0.98, so a copy of any one reference would fail the strict rule there. The vector row has a single page and says little.

Tools are in `tools/pdf-gate`: `make_manifest.py`, `render_oracles.py`, `classify.py` and `gate.py`.

## Speed

A whole page to `Rgba32` at 150 dpi from the file's bytes (parse, interpret, draw; BenchmarkDotNet `PdfPageBenchmarks`), against PDFium through pypdfium2 (`tools/pdf-gate/bench_pdfium.py`: open, render, copy to an array). One local run on a Ryzen 9 7950X3D (32 threads) with other work on the host (load 5–8), .NET 10.0.11, information only:

| page | ours | allocated | PDFium |
|---|---|---|---|
| text report, 1275 × 1651 | 8.4 ms | 22.5 MB | 3.8 ms |
| slides with a 2048 × 1152 JPEG and alpha mask, 1500 × 844 | 69 ms | 44 MB | 25 ms |
| form, 1042 × 1626 | 2.7 ms | 3.1 MB | 0.8 ms |


<!-- https://recursiveai.org/oneimage/docs/drawing/ -->

# Drawing

Vector fills and strokes for `Image` and `Canvas`: paths, an anti-aliased rasterizer, solid, gradient, pattern, image and recolor brushes, pens (width, joins, caps, dashes), blend modes. Boolean operations on paths and clipping (see [Boolean operations and clipping](#boolean-operations-and-clipping)) and text build on the same layers (see [Extending](#extending)).

```csharp
using OneImage;
using OneImage.Drawing;
using Path = OneImage.Drawing.Path;   // System.IO is imported by default in most projects

Image img = Image.Load("photo.jpg")
    .Fill(new Rgba32(255, 255, 255, 200), Path.Star(300, 200, 5, 60, 140))
    .Fill(new Rgba32(0, 0, 0, 255), Path.ParseSvg("M10 10 H 90 V 90 Z"), rule: IntersectionRule.EvenOdd);

using var canvas = new Canvas(800, 600, PixelFormat.Rgba8);
canvas.Clear(new Rgba32(255, 255, 255, 255));
canvas.Fill(new Rgba32(30, 90, 200, 255), Path.Circle(400, 300, 200));   // in place
```

## Coordinates

Pixel coordinates, x to the right, y down. Pixel (i, j) covers [i, i+1) × [j, j+1); its center is (i + 0.5, j + 0.5). A rectangle from (2, 2) to (4, 4) fills exactly four pixels.

## Layers

A fill is five steps, each knowing nothing of the next:

1. **Geometry.** `Path` is an immutable list of figures: move, line, quadratic, cubic, close. `PathBuilder`, the shape factories (`Rectangle`, `RoundedRectangle`, `Ellipse`, `Circle`, `Polygon`, `Polyline`, `RegularPolygon`, `Star`, `Combine`) and `Path.TryParseSvg` produce paths; `Transform`, `Translate`, `Scale`, `Rotate` and `Reverse` return new ones. Arcs (SVG elliptical arcs included) are stored as cubics of at most 90°.
2. **Flatten.** Curves become straight segments within 0.1 pixel (`Path.DefaultTolerance`). A curve whose control polygon lies wholly outside the image is replaced by its chord, which has the same winding effect, so curves that are huge or far away cost nothing.
3. **Coverage.** The segments are clipped to the image (above and below dropped; left of the image folded onto x = 0, where it still sets the winding; right of it dropped) and sorted into buckets by tile row. A tile is rasterized from its row's bucket only, so rendering one tile never touches the rest of the shape. Anti-aliasing is exact area accumulation (the signed-area method of font-rs and stb_truetype): each edge adds the area to its right in every pixel it crosses; a running sum along the row gives the covered fraction. Non-zero takes `min(|sum|, 1)`, even-odd folds the sum with period 2. Without anti-aliasing a pixel is in when its center is.
4. **Paint.** A `Brush` supplies the color for the covered pixels, one row at a time (see [Brushes](#brushes)); the rasterizer never sees it and the brush never sees geometry.
5. **Composite.** The paint is combined with the pixels through the same kernels as `Composite` (`BlendMode`, `AlphaComposition`, premultiplied float). The operator is applied at full strength and mixed back by the coverage, so for Normal/source-over this is the usual alpha blend, and other modes keep soft edges. 8-bit RGB and RGBA with Normal/source-over have a direct path; fully covered pixels of replacing operators are written without a blend.

## Semantics worth knowing

- **Color space.** Brush colors are numbers in the image's own space; nothing is converted. By default blending happens on stored (encoded) values, as in an image editor. `linear: true` fills in linear light. For 8-bit gray and RGB pixels in the default space (no embedded profile, not premultiplied) only the covered pixels are decoded through a 256-entry sRGB table, blended in float and encoded back by rounding half up, so the cost is close to an encoded fill and pixels outside the shape are never rewritten; a 2000 x 2000 Rgba32 circle (local smoke, load about 10) takes 2.2 ms on an `Image` and 1.4 ms on a `Canvas`, against 1.8 and 1.3 ms encoded and 74 and 242 ms before; linear gradient 7.5 / 7.9 ms (encoded 5.6 / 5.8), Multiply 22 / 19 ms (encoded 16 / 16), ring stroke 1.9 / 1.5 ms (encoded 1.5 / 1.2); allocation 24 KB to 100 KB in every case, down from 37 to 73 MB. The result agrees with converting the whole tile through float to 1 level. 16-bit and float pixels, premultiplied 8-bit and images with an embedded profile still convert the tiles the path can touch (those pixels may change by rounding).
- **Lazy and in place.** `Image.Fill` returns a lazy image; only tiles the path can touch are computed and the rest are the input's own tiles. A run of fills is computed from the tile under the whole run in one pass. `Canvas.Fill` draws in place, in parallel over tiles, with the same bytes as `Snapshot().Fill(...)`. Output is identical for any thread count.

**After a `Snapshot()`.** The first write to a tile that a snapshot may still read copies it (or, when the whole tile is overwritten, takes a fresh pooled one); the snapshot keeps the old tile. Tiles are reference counted, and nothing can tell when an `Image` is no longer used, so the canvas watches the tile tables it has handed to snapshots. A table that is gone before the next collection takes its tiles with it, which costs the collector nothing. A table that is still alive after surviving a collection (a held undo stack, a snapshot kept across frames) gets a finalizer, and once the last snapshot of it is collected its tiles go back to the pool; `Dispose` and `Image.FromPixels` do the same at once. Giving every table a finalizer from the start was tried and rejected: it kept every replaced tile alive across a collection and doubled the time of small edits (a 200 x 200 `CopyFrom` went from 20 to 48 us). Recycling is bounded by the 48 MiB tile pool, so on a 24 MP canvas about half of each whole-frame draw is reused. On a 2000 x 2000 RGBA canvas a snapshot-then-draw loop allocates 8-10 MB per draw (circle fill 8.5 MB, circle stroke 9.4 MB, whole-canvas clear 10 MB; they were 12.9, 14.9 and 16.8 MB), against 24 KB, 103 KB and 28 KB without snapshots. Drawing without a snapshot, and `linear: true` fills, return every replaced and cached tile to the pool.
- **Animation.** Every frame gets the fill, in its own pixel grid.
- **Failure.** Bad arguments throw at once. A path that flattens to more than `Path.MaxFlattenedPoints` points (2²⁴), or a transform that leaves the finite range, fails with a typed exception when pixels are computed. NaN and infinite coordinates are refused by the builder. Coordinates beyond about ±2²⁴ lose sub-pixel precision when clipped.
- **SVG path data.** `TryParseSvg` reads M, L, H, V, C, S, Q, T, A, Z in both cases. It is strict (first error fails the whole parse), bounded (64 Mi characters, 2²⁵ commands), and never throws. It is fuzzed (`fuzz/run.sh svg`).
- **Known limit.** Where outline parts of opposite direction cross inside one pixel, their areas cancel and that pixel is slightly under-covered.

## Brushes

```csharp
var sunset = Brush.LinearGradient(new Vector2(0, 0), new Vector2(0, 600),
    [new(0f, new Rgba32(255, 200, 80, 255)), new(0.6f, new Rgba32(220, 60, 90, 255)), new(1f, new Rgba32(30, 20, 90, 255))]);
canvas.Fill(sunset, Path.Rectangle(0, 0, 800, 600));
canvas.Fill(Brush.Hatch(HatchStyle.ForwardDiagonal, new Rgba32(255, 255, 255, 120)), Path.Circle(400, 300, 150));
img = img.Fill(Brush.FromImage(texture, offsetX: 10), Path.Star(300, 200, 5, 60, 140));
```

| Factory | Paints |
|---|---|
| `Brush.Solid(color)` | one color |
| `Brush.LinearGradient(start, end, stops, repetition, premultiplied)` | position = projection of the pixel center on the line start→end |
| `Brush.LinearGradient(start, end, stops, transform, repetition, premultiplied)` | the same, with the line given in gradient space and placed in the image by an affine `Matrix3x2` (the position of a pixel is that of its center taken back through the inverse; double precision) |
| `Brush.RadialGradient(center, radius, stops, ...)` | position = distance from the center / radius |
| `Brush.RadialGradient(center, radius, focalCenter, focalRadius, stops, transform, ...)` | a two-circle (focal) gradient as SVG 2 defines it: position *t* where the circle growing linearly from (focal center, focal radius) to (center, radius) passes through the pixel, the larger *t* with a non-negative radius winning. A focal circle outside the end circle makes a cone, outside which pixels are transparent; equal concentric circles paint only their disc in the first color |
| `Brush.EllipticGradient(center, axisEnd, axisRatio, stops, ..., squaredDistance)` | position = normalized distance in an ellipse whose first axis runs from the center to `axisEnd` and whose other axis is `axisRatio` times as long |
| `Brush.PathGradient(points, colors, centerColor, center)` | barycentric blend of the vertex colors and a center color over the triangles (center, point *i*, point *i*+1); transparent outside them |
| `Brush.Pattern(foreground, background, bool[,] cells, transform)` | a tiled two-color bitmap, cells indexed `[row, column]` |
| `Brush.Hatch(HatchStyle, foreground, background, transform)` | `Horizontal`, `Vertical`, `ForwardDiagonal`, `BackwardDiagonal`, `Percent10`, `Percent20`, `Min` (4 × 4 cells) |
| `Brush.FromImage(source, region, offsetX, offsetY, transform, tile)` | the pixels of an image, repeated (or placed once with `tile: false`) |
| `Brush.FromImage(source, sampling, region, offsetX, offsetY, transform, tile)` | the same with `ImageSampling.Bilinear`: each pixel blends the four source pixels around its center, on premultiplied color; tiles wrap without a seam, and with `tile: false` the edge fades over half a source pixel. `Nearest` is the behavior of the overload without `sampling` |
| `Brush.Recolor(source, target, threshold)` | the target color where the pixels already there are close to the source color |

**Coordinates.** A brush works in the image's pixel grid, at pixel centers, and does not move with the shape: two fills with one brush line up. A fill's `transform` moves only the path. Patterns and image brushes take their own `transform` (pattern or source space to image space, row-vector `Matrix3x2`; each pixel takes the cell or source pixel under its center, without smoothing); gradients take their geometry in image pixels.

**Gradient colors.** Stops are sorted by position (stable, so two stops at one position make a hard edge); before the first stop the first color holds and after the last the last. Positions outside 0..1 are allowed. `GradientRepetition` says what happens for positions outside 0..1: `None` extends the end colors, `Repeat` starts over each unit (negative positions too), `Reflect` runs back and forth, `DontFill` leaves them transparent (both ends inclusive).

**Interpolation.** Colors blend linearly in the numbers they are given in, which is the image's encoded values (as CSS, SVG and editors do), and by default *premultiplied* by alpha, so red fading to transparent blue stays red as it fades. `premultiplied: false` blends straight colors, where red to transparent blue passes through purple; this is what ImageSharp.Drawing does, and the two agree when every stop is opaque. With `linear: true` the stop colors are converted to linear light first, interpolation runs in linear light, and the fill converts back with everything else: black to white then has its midpoint at sRGB 188, not 128. The conversion uses the image's own profile curve (a 4096-step table from the same profile conversion the pixels get), so brush colors and pixels agree for matrix/curve profiles; for gray images a color is first reduced to gray with Rec. 709 weights. `PathGradient`, pattern, hatch and recolor colors are converted the same way; an image brush's texels are converted as they are read.

**Recolor.** With *d* the Euclidean distance between a pixel and `source` over straight R, G, B, A in 0..1, the strength is `max(0, 1 − d² / (4 · threshold))` (1 for an exact match, 0 from *d* = 2·√threshold); the pixel then becomes the target painted with its alpha times that strength. Threshold 0 changes exact matches only. The formula was fitted to ImageSharp's `RecolorBrush` on opaque pixels (agreement to 1 level); on pixels with partial alpha ImageSharp's result differs a little, and it is not matched. In linear fills the comparison happens in linear light.

**Image brush.** The source is read once, on first use, as 8-bit straight RGBA from its first frame; a region over 2²⁶ pixels is refused (`ImageLimitException`; pass a smaller `region`). The fill node lists the source image as an input, and its descriptor names that node. Failures reading the source surface when the pixels are computed.

**Hostile input.** Stops with NaN or infinite positions, no stops, a zero-length gradient line or axis, a zero, negative or NaN radius or ratio, empty patterns, singular or non-finite transforms, a negative or NaN threshold and fewer than three path-gradient points are refused with `ArgumentException` or `ArgumentOutOfRangeException` when the brush is built. Rows asked for at any coordinate (including ±2³¹) never throw and never produce NaN.

**Writing a brush.** Derive from `Brush` and implement `FillRow(x, y, rgba)`: write straight RGBA floats (0..1, in the image's space) for the run of pixels starting at image column `x` on row `y`; it is called from several threads on different tiles and must give the same numbers for the same pixel every time. A brush that needs the pixels already there (like `Recolor`) overrides `ReadsBackdrop` and the overload that receives them. `TryGetSolid` lets a one-color brush take the fast path and `Describe` names the brush in the op descriptor (the default says `custom`). In a `linear: true` fill the numbers a custom brush writes are treated as encoded values and converted to linear light after the call.

**Speed.** Opaque brush pixels over fully covered pixels are written without reading the backdrop (8-bit RGBA through a vector kernel, `BrushKernel.RgbaF32ToRgba8`, with a scalar reference); everything else goes through the blend kernels. Measured on this workstation (2000 × 2000 RGBA, 4 threads, load 4–5, .NET 10; local smoke results, see `bench/OneImage.Benchmarks/Drawing/BrushBenchmarks.cs`):

| Fill | OneImage (in place) | ImageSharp.Drawing | allocated |
|---|---|---|---|
| linear gradient, whole image, 3 stops | 5.1 ms | 11.3 ms | 28 KB vs 125 MB |
| radial gradient in a circle | 6.2 ms | 98.8 ms | 24 KB vs 80 MB |
| hatch over a 1000-point polygon | 4.7 ms | 12.5 ms | 63 KB vs 180 KB |
| 64 × 64 image brush over the same polygon | 5.2 ms | 15.8 ms | 63 KB vs 532 KB |

### Compared with ImageSharp.Drawing 2.1.7

The same fill is rendered by both on a 96 × 64 backdrop and the RGBA bytes compared (test: `BrushImageSharpTests`); "mean" is per channel value, in levels.

| Brush and case | mean | max | notes |
|---|---|---|---|
| linear gradient, three stops, None / Repeat / Reflect / DontFill, opaque and translucent backdrop | 0.000 | 0 | start at the image corner, see below |
| hard stops; unsorted stops and stops outside 0..1 | 0.000 | 0 | |
| translucent stops, `premultiplied: false` | 0.10–0.11 | 1 | rounding |
| radial gradient, all four modes | 0.000 | 0 | |
| elliptic gradient, all four modes, `squaredDistance: true`, slanted axis | 0.000–0.0001 | 1 | axis end mirrored, see below |
| path gradient, hexagon (polygon moved half a pixel) | 0.011 | 136 | only on pixels on the outline; 0 of 5464 pixels away from it differ by more than 2 |
| path gradient, concave L shape, default center | 0.009 | 4 | |
| seven hatch presets, whole image and inside a rectangle | 0.000 | 0 | |
| custom pattern, translucent colors | 0.000 | 0 | |
| image brush: whole, region + offset, inside a rectangle, opacity 0.5 | 0.000–0.022 | 0–1 | the offset equals the rectangle's corner |
| recolor, thresholds 0.02 / 0.1 / 0.3 (opaque pixels) | 0.000 | 0–1 | |

Systematic differences, all by choice:

- **Pixels behind a gradient's start.** ImageSharp mirrors them for a slanted line (position −0.3 looks like 0.3) and clamps them for an axis-aligned line even in Repeat mode. Here `None` clamps, `Repeat` continues the pattern backward and `DontFill` leaves them empty, on any line. The comparisons put the start at the image corner so no pixel lies behind it.
- **Elliptic gradients.** ImageSharp turns a slanted ellipse the opposite way from its axis end (an axis pointing down-right draws an ellipse elongated up-right) and uses the *square* of the normalized distance as the position. Here the axis points at `axisEnd` and the position is the distance itself, like the radial gradient; `squaredDistance: true` gives ImageSharp's falloff. The comparison mirrors the axis end.
- **Translucent stops** blend premultiplied by default, as said above.
- **Anchoring.** ImageSharp anchors an image brush at the top-left of the shape's bounds (patterns at the image origin); here every brush is anchored in the image, so to match, use `offsetX`/`offsetY` equal to the shape's corner.
- **Path gradient.** ImageSharp evaluates at pixel corners (x, y) and includes the outline; this library evaluates at pixel centers, so the same picture needs the points moved by half a pixel. The outline is inclusive here too (within 10⁻⁵).
- **Recolor on partially transparent pixels** is not matched.

## Compared with ImageSharp.Drawing 2.1.7 (coverage)

Alpha plane of a white fill on a transparent 140 × 140 image, our output against theirs (test: `ImageSharpCoverageTests`):

| Shape | mean diff (levels) | max diff | Where the maximum sits |
|---|---|---|---|
| rectangle at fractional offsets | 0.13 | 22 | edge pixels |
| thin rectangle (0.4 px wide) | 0.55 | 163 | their output has full alpha on pixels where the exact area is 40% |
| circle / ellipse | 0.18 / 0.12 | 28 | curved edges |
| star, blob (1000 points) | 0.10 / 0.15 | 54 / 22 | vertices |
| pentagram, non-zero / even-odd | 0.11 / 0.15 | 99 | pixels where two edges cross |
| cubic loops | 0.26 | 176 | near the sharp ends of the curve |
| SVG arcs, rounded rectangle, multi-figure holes | 0.05–0.07 | 16–26 | curved edges |

The maxima are single pixels, not investigated further. Without anti-aliasing a pixel is in when its center is. ImageSharp's non-anti-aliased fill truncates crossings to whole pixels and samples rows near their bottom, so integer-aligned shapes match exactly while shapes at fractional positions differ by up to one pixel row or column on their border (mean ≤ 0.4 levels on curves).

Speed (local smoke result, 2000 × 2000 RGBA, solid color, 4 threads, load 4–7): see `bench/OneImage.Benchmarks/Drawing`. A 1000-point polygon takes 1.6 ms (opaque) or 3.2 ms (alpha 160) in place against 8.5 and 7.6 ms; 300 circles take 8.9 and 13.6 ms against 21.4 and 21.6 ms, with about half the allocation.

## Strokes

```csharp
using var canvas = new Canvas(800, 600, PixelFormat.Rgba8);
canvas.Draw(new Rgba32(30, 90, 200, 255), 6, Path.ParseSvg("M50 300 C 200 50 400 550 750 300"));            // color + width
canvas.Draw(Pen.Dash(new Rgba32(200, 30, 30, 255), 3).WithCap(StrokeCap.Round), Path.Circle(400, 300, 120));   // preset dash
canvas.DrawPolygon(new Pen(Brush.Solid(new Rgba32(0, 0, 0, 255)), 12, StrokeJoin.Round), points);             // helpers
Path outline = path.GenerateOutline(width: 8, join: StrokeJoin.Bevel);                                       // the stroke as a Path
```

- **API.** `Image.Draw` (lazy) and `Canvas.Draw` (in place) take a `Pen` or a color and width, with the options of `Fill` (`antialias`, `opacity`, `blend`, `composition`, `linear`, `transform`; no `rule`: strokes are always filled non-zero). Helpers: `DrawLine`, `DrawPolyline`, `DrawPolygon`, `DrawBeziers`, `DrawRectangle`, `DrawEllipse`. `Path.GenerateOutline(pen)` or `GenerateOutline(width, join, cap, miterLimit, dashPattern, dashOffset)` returns the outline: closed contours that, filled non-zero, cover exactly the stroke. A `Pen` is immutable: a `Brush` (any), width, `StrokeJoin` (`Miter`, `Round`, `Bevel`, `Square`), `StrokeCap` (`Butt`, `Round`, `Square`), miter limit and a dash pattern with offset; `Pen.Solid`, `Dash`, `Dot`, `DashDot`, `DashDotDot` are presets and `With...` methods change one property.
- **Defaults.** Width 1, miter joins with limit 4, butt caps, solid. A miter longer than `limit x width / 2` is cut to a bevel (SVG and PostScript). `Square` is Clipper's square join (ImageSharp's `JointStyle.Square`): the corner is cut flat at half the width from the vertex.
- **Geometry.** The stroke is centered on the path (half the width each side). Curves are flattened (0.1 pixel after the transform), then each figure becomes one outline contour (open) or two (closed: outer and inner edge), with the stroke on the same side of every contour so overlaps never cancel and the non-zero fill paints each pixel once: a translucent pen is even where it crosses itself. The rasterizer sums the partial coverage of contours inside an edge pixel, so an outline whose contours lie on top of each other along an edge (a path that doubles back, a closed two-point figure `M a L b Z`, a cusp: any join that turns by more than about 172 degrees) would come out twice as dense there. Such an outline is merged with `Path.Resolve` (a union, so overlaps count once); every other outline skips the merge, so ordinary strokes cost what they did. Outlines over 2^20 commands are not merged. Round joins and caps are exact cubic arcs. Inside a turn the edges are cut at their intersection when both segments are long enough to reach it and otherwise pass through the vertex, so no hole opens however wide the pen. A `transform` is applied to the outline, so it scales the width too (as in SVG). Where two parts of the stroke overlap inside one pixel along an edge, the coverage is a little higher than the exact union.
- **Dashes.** A pattern is alternating on and off lengths in path units, starting with on; an odd-length pattern is repeated once (SVG). The offset moves the start into the pattern and may be negative. Every figure restarts the pattern at its start; a closed figure that is on at both its start and its end gets one dash across the start. Caps apply to every dash, so round or square caps lengthen each dash by half the width at both ends (SVG). Zero-length dashes draw dots with round and square caps. The presets (`Dash` 3:1, `Dot` 1:1, `DashDot` 3:1:1:1, `DashDotDot` 3:1:1:1:1:1) scale with the width as ImageSharp's do; a pattern given to `new Pen`/`WithDash` is absolute.
- **Degenerate input.** Repeated points are ignored. A figure of one point draws nothing, except `M p L p Z`, which draws a dot for round and square caps. Width 0 draws nothing. NaN, infinite or negative widths, miter limits below 1, bad dash patterns and offsets throw `ArgumentOutOfRangeException`; widths up to 2^24 are accepted.
- **Limits.** The outline is built when `Draw` is called (not lazily), in time proportional to the path, even where the path lies outside the image. An outline over 2^23 commands or 2^25 coordinates, a flattening over `Path.MaxFlattenedPoints`, or more than 2^22 dashes throws `ImageLimitException`. Output is identical for any thread count, and `Image` and `Canvas` give the same bytes.

### Compared with ImageSharp.Drawing 2.1.7

Alpha plane of a white stroke on a transparent 140 x 140 image (test: `StrokeImageSharpTests`; the numbers below are the mean and the maximum difference in levels):

| Case | mean | max |
|---|---|---|
| zigzag polyline, miter / round / square joins, width 1, 2.5, 12 | 0.10-0.19 | 33-206 |
| sharp-angle polyline (44 deg), same joins and widths | 0.16-0.18 | 20-51 |
| butt / round / square caps, width 2.5 and 12 | 0.11-0.16 | 39-102 |
| closed pentagon, miter w1 / w2.5, round and square w12 | 0.12-0.17 | 13-65 |
| cubic curve, round joins and caps, width 1 / 2.5 / 12 | 0.14-0.19 | 40-75 |
| circle, width 1 / 2.5 / 12 | 0.37-0.38 | 32-34 |
| dashes (dash, dot, dash-dot, dash-dot-dot), width 1 and 3 | 0.29-0.45 | 118-135 |

Systematic differences:

- **Position.** ImageSharp strokes land half a pixel right and down of where SVG puts them (a width-3 line at y = 30 covers rows 29 to 31 there and 28.5 to 31.5 here); its fills use pixel corners, its pens pixel centers. We follow SVG, so the table above moves our path by (0.5, 0.5) first. When porting, translate by half a pixel to reproduce its exact output.
- **Bevel.** ImageSharp has no bevel join (`Miter`, `Round`, `Square` only); `Bevel` is checked by geometry in tests.
- **Miter limit.** ImageSharp's limit is somewhat above 3.5; our default of 4 agrees on every join in the zigzag. Its tip pixels differ by up to 206 levels at sharp miters.
- **Circles.** The 0.37 mean is a thin difference all along the edge (maximum 34). Our curves are flattened to within 0.1 pixel of the true circle; the cause on their side was not isolated.
- **Dashes.** The maxima are single pixels at dash ends, not investigated further.

Speed (local smoke result, 2000 x 2000 RGBA, solid color, load 0.4 at start, .NET 10.0.11, X64 AVX-512 host; BenchmarkDotNet, 12 iterations): `OneImage Canvas` in place against ImageSharp.Drawing.

| Task | OneImage | ImageSharp.Drawing | Allocated (ours / theirs) |
|---|---|---|---|
| 1000-point polyline, width 3, round joins | 1.15 ms | 8.87 ms | 0.67 / 2.32 MB |
| 300 circles, width 3 | 9.5 ms (6.6 ms as lazy `Image` + copy) | 36.3 ms | 7.4 / 34.8 MB |
| dashed 400-point wave, width 3, 3:1 | 0.80 ms | 6.0 ms | 0.34 / 2.74 MB |

## Boolean operations and clipping

```csharp
Path both = Path.Circle(100, 100, 60).Union(Path.Circle(150, 110, 50));          // one outline around both
Path moon = Path.Circle(100, 100, 60).Subtract(Path.Circle(125, 90, 55));        // the first minus the second
Path lens = a.Intersect(b);   Path odd = a.Xor(b);   Path merged = PathBoolean.UnionAll(circles);
Path clean = Path.Polygon(selfCrossingPoints).Resolve(IntersectionRule.EvenOdd);   // no overlaps, no crossings
Path grown = outline.Offset(12, StrokeJoin.Round);  Path shrunk = outline.Offset(-12);

img = img.Clip(Path.Circle(300, 200, 120), i => i.GaussianBlur(8));             // blur only inside the circle
canvas.Clip(heart, i => i.Invert().Grayscale());                                 // the same, in place
img = img.Fill(Brush.Solid(red), Path.Rectangle(0, 0, 800, 600), clip: heart);   // paint only inside the heart
```

### Path booleans

`BooleanOperation` is `Union`, `Intersection`, `Difference` (subject minus clip) or `Xor`. `path.Boolean(operation, other, subjectRule, clipRule, tolerance)` does any of them, and `Union`, `Intersect`, `Subtract` and `Xor` are the short forms. Each path is read as the region its closed figures enclose under its own `IntersectionRule` (non-zero by default), so self-intersecting paths, shapes with holes and paths that overlap themselves work as they do when filled. `PathBoolean.UnionAll(paths)` merges any number of paths in one pass; it resolves each path on its own first, so a path wound the other way, or with holes, does not cancel its neighbors. `Resolve(rule)` rewrites one path as non-overlapping polygons.

- **Result.** A `Path` of straight-edged, closed polygons: curves are flattened first (`tolerance`, default 0.1 px, like a fill), so a union of two circles is a polygon with arcs of short segments. Outer contours and holes run in opposite directions, nothing overlaps and no two edges cross, so the result fills the same under either rule. Collinear vertices are removed, edges two shapes share on opposite sides vanish, and shapes that only touch at a point stay separate. An empty region gives `Path.Empty`.
- **Exactness.** Every coordinate is rounded to a grid of 1/256 pixel, and intersection points are rounded to it too; all decisions (which side, which order, what crosses) are made in exact integer arithmetic. Collinear and coincident edges, edges meeting at a vertex, spikes, zero-area slivers and edges that cross at tiny angles are therefore handled without tolerances. Rounding an intersection moves the two edges by under 1/512 px, which can make a new crossing nearby; the engine finds and settles those too (a few rounds at most). The result does not depend on thread count (the work is single-threaded) or on the order of the input figures except for where each polygon starts.
- **Limits.** Coordinates beyond ±33,554,432 px or more than 2²² flattened segments fail with `ImageLimitException`, as does an arrangement of more than 2²³ pieces or a comparison count past 2³¹. Time is about n log n plus the number of crossings (a 1000-point polygon against a 24-point star takes about 0.16 ms); a pentagram-like star of 2001 vertices (two million crossings) takes about 12 s.
- **Offset.** `Offset(distance, join, miterLimit, rule)` falls out of the same machinery: the region unioned with (distance > 0) or minus (distance < 0) the band of points within |distance| of its boundary, built from a rectangle per edge and a wedge per corner (`Round`, `Miter` with a limit, `Bevel` or `Square`). Shrinking removes parts thinner than twice the distance. Corners of the result follow the join where the boundary turns away from the offset; elsewhere they stay sharp.

### Clip

`image.Clip(path, operations, antialias, rule, transform)` runs `operations` (a `Func<Image, Image>`, called once, now) and keeps the result only inside `path`: pixels outside are the input's own, pixels inside are the operations' result byte for byte, and pixels along the edge mix the two by the path's coverage (exact area, or the pixel center without `antialias`). The mix is made in premultiplied float values, as a layer mask would, and rounded to the format. Any chain works because it is lazy and ordinary: the operations never see the path. They do see the whole image, so a blur at the edge draws on pixels outside the path, and the operations must keep the image size and frame count (a different pixel format is converted back).

Only tiles the path can reach ask the operations for pixels; tiles wholly inside are the operations' tiles, tiles wholly outside are the input's. On a 2000 x 2000 image a blur clipped to a circle computes the circle's tiles only. `canvas.Clip(...)` is the same in place, in parallel over tiles, with the same bytes as `Snapshot().Clip(...)`; the operations read the pixels as they were before the call, so each rewritten tile is swapped for a fresh pooled one and the old tile goes back to the pool (unless you hold a `Snapshot()`, which keeps the old tiles). Frames of an animation are clipped each with the path in their own grid. Clips nest: the operations can contain a `Clip`. The descriptor is named `clip` with the rule, anti-aliasing, transform and path as parameters.

### Clipped fills and strokes

`Fill` and `Draw` (with a `Pen`, or a color and width) on `Image` and `Canvas` take `clip:` and `clipRule:`. The clip path's coverage is multiplied into the shape's coverage row before painting, so only pixels inside both change and the clip edge is anti-aliased like any other; the clip is in image coordinates and `transform:` does not move it. With `antialias: false` both are sampled at pixel centers. This costs one extra rasterization per touched tile and nothing when `clip` is null. It works with every brush, blend mode and with `linear: true`. The helpers (`DrawLine`, `DrawPolygon`, ...) do not take a clip; wrap them in `Clip(...)`.

### Compared with ImageSharp.Drawing 2.1.7

Alpha plane of a white fill of each result on a transparent 140 x 140 image (test: `BooleanImageSharpTests`; the results of `Boolean` against `IPath.Clip(ShapeOptions, ...)`, each filled by its own library; mean and maximum difference in levels, then the filled area in pixels, ours / theirs):

| Case | Union | Intersection | Difference | Xor |
|---|---|---|---|---|
| two overlapping circles | 0.22 / 32 | 0.11 / 34 | 0.17 / 32 | 0.33 / 32 |
| 5-point star and a rectangle | 0.10 / 112 | 0.02 / 14 | 0.12 / 112 | 0.15 / 112 |
| pentagram (self-intersecting) and a rectangle | 0.12 / 65 | 0.03 / 11 | 0.12 / 65 | 0.20 / 65 |
| pentagram (even-odd) and a circle | 0.12 / 65 | 0.14 / 95 | 0.21 / 148 | 0.29 / 183 |
| square with a square hole (even-odd) and a bar | 0.08 / 16 | 0.02 / 16 | 0.02 / 16 | 0.12 / 16 |
| two rectangles sharing an edge | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 |
| 1000-point blob and a 7-point star | 0.19 / 163 | 0.11 / 91 | 0.15 / 106 | 0.32 / 187 |
| self-crossing bow tie and a circle | 0.13 / 127 | 0.15 / 76 | 0.13 / 127 | 0.27 / 127 |

The maxima are single pixels at vertices, where the two libraries round slightly differently. Filled areas agree within about 1% (the largest gap is a small 680-pixel lens, 1.1%; most are under 0.3%); ours are exact on the 1/256 grid, which `BooleanTests` checks against analytic areas and a point-by-point brute-force definition of each operation, including random polygons and lattice polygons whose edges overlap and cross at lattice points constantly.

Differences by choice:

- ImageSharp's `IPath.Clip(...)` defaults to *difference*; here the operation is always named. Its `ShapeOptions.IntersectionRule` applies to both operands; here each has its own rule.
- ImageSharp's `Clip` on a context applies the processors to the path's bounding rectangle and then masks with the path; here the operations are lazy and only the tiles the path reaches are computed.
- Results are polygons of straight segments in both libraries; ours are snapped to 1/256 px and have collinear vertices removed.

Speed (local smoke result, 2000 x 2000 RGBA, .NET 10.0.11, X64 AVX-512 host, shared workstation with load 4.7 at start rising to about 10 during the run, so treat as rough; see `bench/OneImage.Benchmarks/Drawing/ClipBenchmarks.cs`): union of 200 circles 7.2 ms vs 11.1 ms (3.2 MB vs 23 MB allocated); a star minus a 1000-point polygon 0.158 ms vs 0.134 ms (33 KB vs 205 KB; the one row slower than ImageSharp.Drawing, split about evenly between finding the crossings and the sweep); a Gaussian blur clipped to a circle 12.3 ms lazy + copy-out and 12.9 ms in place on a Canvas, vs 56 ms (the Canvas row allocates 88 KB, the lazy row 52 KB, ImageSharp.Drawing 423 KB).

## ImageSharp.Drawing names

| ImageSharp.Drawing | OneImage |
|---|---|
| `ctx.Fill(color, path)` | `img.Fill(color, path)` / `canvas.Fill(color, path)` |
| `ctx.Fill(brush, path)`, `Brushes.Solid(c)` | `img.Fill(Brush.Solid(c), path)` |
| `LinearGradientBrush`, `RadialGradientBrush`, `EllipticGradientBrush`, `PathGradientBrush`, `ColorStop`, `GradientRepetitionMode` | `Brush.LinearGradient`, `RadialGradient`, `EllipticGradient`, `PathGradient`, `ColorStop`, `GradientRepetition` |
| `PatternBrush`, `Brushes.Horizontal` ... `Brushes.Min` | `Brush.Pattern`, `Brush.Hatch(HatchStyle, ...)` |
| `ImageBrush`, `RecolorBrush` | `Brush.FromImage`, `Brush.Recolor` |
| `ctx.Fill(color)` (whole image) | `img.Fill(color)`; `Clear(color)` replaces pixels |
| `GraphicsOptions.Antialias` | `antialias:` |
| `ShapeOptions.IntersectionRule` | `rule:` (`IntersectionRule.NonZero` is the default; set `rule:` explicitly when porting) |
| `GraphicsOptions.BlendPercentage`, `ColorBlendingMode`, `AlphaCompositionMode` | `opacity:`, `blend:`, `composition:` |
| `DrawingOptions.Transform` | `transform:` or `path.Transform(matrix)` |
| `PathBuilder` (`AddLine`, `AddCubicBezier`, `AddArc`, `CloseFigure`) | `PathBuilder` (`LineTo`, `CubicBezierTo`, `ArcTo`, `Close`) |
| `RectangularPolygon`, `EllipsePolygon`, `RegularPolygon`, `Star`, `Polygon`, `ComplexPolygon` | `Path.Rectangle`, `Ellipse`/`Circle`, `RegularPolygon`, `Star`, `Polygon`, `Path.Combine` |
| `Path.TryParseSvgPath` | `Path.TryParseSvg` |
| `path.Transform`, `path.Bounds`, `path.Flatten()` | the same names on `Path` |
| `subject.Clip(new ShapeOptions { ClippingOperation = ..., IntersectionRule = ... }, clips)` | `subject.Boolean(BooleanOperation, clip, subjectRule, clipRule)`; `Union`, `Intersect`, `Subtract`, `Xor`; `PathBoolean.UnionAll(paths)` |
| `ClippingOperation.Union/Intersection/Difference/Xor` | `BooleanOperation.Union/Intersection/Difference/Xor` |
| `ctx.Clip(path, c => c.GaussianBlur(8))` | `img.Clip(path, i => i.GaussianBlur(8))` / `canvas.Clip(path, ...)` |
| `ctx.Fill(options, brush, path)` with a clipped region | `img.Fill(brush, path, clip: clipPath)` |
| `ctx.Draw(pen, path)`, `ctx.Draw(color, width, path)` | `img.Draw(pen, path)`, `img.Draw(color, width, path)` / `canvas.Draw(...)` |
| `Pens.Solid`, `Pens.Dash`, `Dot`, `DashDot`, `DashDotDot` | `Pen.Solid`, `Pen.Dash`, `Pen.Dot`, `Pen.DashDot`, `Pen.DashDotDot` |
| `new SolidPen(new PenOptions(color, width) { JointStyle, EndCapStyle })` | `new Pen(brush, width, join, cap, miterLimit)` |
| `PatternPen`, `PenOptions` stroke pattern (multiples of width) | `new Pen(..., dashPattern:)` (absolute lengths) or `pen.WithDash(...)` |
| `JointStyle.Miter/Round/Square`, `EndCapStyle.Butt/Round/Square` | `StrokeJoin.Miter/Round/Square` (plus `Bevel`), `StrokeCap.Butt/Round/Square` |
| `ctx.DrawLine`, `DrawPolygon`, `DrawBeziers`, `Draw(pen, new RectangularPolygon(...))` | `DrawLine`, `DrawPolygon`, `DrawPolyline`, `DrawBeziers`, `DrawRectangle`, `DrawEllipse` |
| `path.GenerateOutline(width, pattern, isClosed, joint, endcap)` | `path.GenerateOutline(pen)` / `path.GenerateOutline(width, join, cap, miterLimit, dashPattern, dashOffset)` |

Text: see [text.md](https://recursiveai.org/oneimage/docs/text/#imagesharp-names) (`RecursiveAI.OneImage.Text`).

## Extending

- **Stroker.** Done: see [Strokes](#strokes). Any new geometry (text outlines, boolean results) can be stroked by passing it to `Draw`.
- **Brushes.** Subclass `Brush` (see *Writing a brush* above): `FillRow(x, y, rgba)` writes straight RGBA floats for a run of pixels; the paint step handles every brush through that row call, mixing by coverage and blend mode, in linear light too. Pens take any `Brush`.
- **Clipping.** Done: see [Boolean operations and clipping](#boolean-operations-and-clipping). A clip is a second coverage source multiplied into the coverage before the paint step (`TileRasterizer.ApplyClip`), and `ClipNode` is the same coverage used as a mask between an image and its processed copy.
- **Text.** Glyph outlines are `Path`s; text is a fill of their combination.
- **Layers.** A layer's mask is the same coverage plane; `BlendKernel.Row` is the composite step.


<!-- https://recursiveai.org/oneimage/docs/layers/ -->

# Layers

A layered document that renders on demand: pixel layers with offsets, groups, fill and adjustment layers, masks, clipping, all 24 blend modes, and a cache that recomputes only what an edit touched. It lives in the core package, namespace `OneImage.Layers`, and is built on the same tiles, blend kernels and drawing as the rest of the library.

```csharp
using OneImage;
using OneImage.Layers;
using Path = OneImage.Drawing.Path;

using var doc = new Document(1920, 1080, new DocumentOptions { Background = new Rgba32(255, 255, 255, 255) });

PixelLayer photo = doc.Add(doc.CreatePixelLayer("photo", Image.Load("photo.jpg"), x: 100, y: 50));
LayerMask mask = photo.AddMask(revealAll: false, area: doc.Bounds);   // the mask canvas is in document coordinates here
mask.Pixels.Fill(new Rgba32(255, 255, 255, 255), Path.Circle(700, 450, 300));
mask.Feather = 12;

AdjustmentLayer warm = doc.Add(doc.CreateAdjustmentLayer("levels", Adjustment.Levels(inBlack: 0.05, gamma: 1.1)));
warm.Opacity = 0.8f;

PixelLayer paint = doc.Add(doc.CreatePixelLayer("paint"));
paint.BlendMode = BlendMode.Multiply;
paint.Pixels.Draw(new Rgba32(200, 40, 40, 255), 8f, Path.Polyline([new(300, 300), new(500, 380), new(700, 320)]));

doc.Render().Save("out.webp");        // lazy: only the tiles a save needs are computed
paint.Pixels.Fill(new Rgba32(0, 0, 0, 255), Path.Circle(900, 500, 20));
doc.Render().Save("out2.webp");       // recomputes just the tiles the circle touched
```

## The model

| Type | What it is |
|---|---|
| `Document` | Size, pixel format, color profile, background color, a root group, the render cache and (optionally) a spill store. Single-writer, `IDisposable`. |
| `DocumentSnapshot` | An immutable frozen state, taken in O(layers). Render it from any thread while you keep editing. |
| `Layer` | Base class: `Name`, `Visible`, `Opacity`, `FillOpacity`, `BlendMode`, `ClipToBelow`, `Locks`, `Mask`, `Bounds`. |
| `PixelLayer` | A `Canvas` (the document's pixel format) placed at `X`, `Y`. Paint on `Pixels` with any `Canvas` operation. |
| `GroupLayer` | Children, bottom first; `PassThrough` or isolated. The document's `Root` is a group. |
| `LayerStyle` | Optional `Layer.Style`: drop shadow, inner shadow, outer and inner glow, stroke, color overlay, gradient overlay, pattern overlay, bevel and emboss and satin, drawn from the layer's shape at composite time. See [Layer styles](#layer-styles). |
| `FillLayer` | A `Brush` (solid or gradient) covering the whole document. |
| `AdjustmentLayer` | An `Adjustment` (a point operation) applied to everything below it in its scope. |
| `LayerMask` | An 8-bit gray canvas placed at `X`, `Y` in document coordinates with `Density`, `Feather`, `OutsideValue` and `Enabled`. |
| `LayerLocks` | Lock flags carried as plain data; the model never refuses an edit because of them. |

Layers are created by the document (`CreatePixelLayer`, `CreateGroup`, `CreateFillLayer`, `CreateAdjustmentLayer`), put into a group with `Add`/`Insert`, and edited in place. `GroupLayer.Remove` detaches a layer without disposing it; `Move` reorders. Groups nest to `GroupLayer.MaxDepth` (64). A layer belongs to one document.

**Pixel format and color.** A document is RGB or gray, straight alpha, 8-bit (the default `Rgba8`), 16-bit or float. `DocumentOptions.ColorProfile` names the color space the pixel values are in (sRGB or the sRGB-curve gray profile by default); `CreatePixelLayer(name, image)` converts an image into it. CMYK and Lab documents are not supported yet; the profile model is part of the options so they can be added. Brush and background colors are in the document's color space.

## How a render is composited

For every output tile, the renderer folds the layers over the background from the bottom up. Each step is the same code as `Image.Composite(overlay, x, y, opacity, linear: false, blend, alpha)`:

- **Stack equals chain.** A stack of pixel layers renders to exactly the bytes of the equivalent chain of `Composite` calls (checked for every blend mode, with and without alpha in the background). Layers use source-over coverage with their `BlendMode` colors (the W3C rule `Cs' = (1 − αb)·Cs + αb·B(Cb, Cs)`), computed on premultiplied float, rounded half up on output.
- **Opacity.** The effective opacity is `Opacity × FillOpacity` (a float product). Without a layer style the two are interchangeable (a style's effects follow the opacity, while fill opacity scales only the pixels and overlays; see [Layer styles](#layer-styles)); Photoshop treats a few blend modes differently under fill opacity, and this model does not.
- **Hidden and empty.** Invisible layers and layers with zero effective opacity are skipped; a layer whose pixels (or whose sparse canvas tiles) cannot touch a tile costs nothing for that tile.
- **Linear light.** `DocumentOptions.BlendInLinearLight` makes every compositing step behave like `Composite(..., linear: true)`: both sides go to linear light, blend there, and come back. The default blends the stored values, as image editors do.

### Masks

The coverage of a pixel is `mask / 255`; **density** `d` mixes it toward fully visible, `255·(1 − d) + d·mask`; **feather** blurs the mask first with a Gaussian of that standard deviation in pixels (not in linear light, edges clamp). Outside the mask canvas the value is `OutsideValue` (255 for `AddMask(revealAll: true)`, 0 otherwise) before density and feather. The coverage multiplies the layer's alpha after the layer is positioned: `alpha' = round(alpha × coverage / 255)` on 8-bit data. A disabled mask is ignored. Masks apply to groups, fill and adjustment layers the same way.

### Groups

```csharp
GroupLayer g = doc.Add(doc.CreateGroup("highlights", passThrough: true));
```

- **Pass-through** (default). The children are composited straight onto what is below, so a child's `Multiply` sees the real backdrop and an adjustment inside the group adjusts everything below the group. At full opacity and no mask the result is bit-identical to the same layers without the group. Below full opacity or with a mask, the result is mixed with the untouched backdrop: `backdrop + k·(result − backdrop)` on premultiplied floats, `k = opacity × mask`. The group's own blend mode is ignored.
- **Isolated** (`PassThrough = false`). The children are composited onto a transparent surface, and the surface is laid over the backdrop as one layer with the group's blend mode, opacity and mask. A `Multiply` child of an isolated group over an empty surface shows its own color (Multiply with a transparent backdrop is the source); give the *group* the Multiply mode to multiply the whole group into the backdrop. Example: on a backdrop (200, 100, 50), a child (100, 200, 255) in Multiply gives (78, 78, 50) pass-through, and (100, 200, 255) isolated; with the group set to Multiply the isolated version gives (78, 78, 50) again.

### Clipping

A layer with `ClipToBelow = true` is drawn only where the nearest layer below it that is not itself clipped (its *base*) has coverage. The base and the layers clipped to it are drawn into a transparent surface (the base normally, each clipped layer with its own blend mode, opacity and mask, source-atop so the base's shape never grows), and that surface is laid over the backdrop with the **base's** blend mode, opacity and mask. This is Photoshop's "blend clipped layers as group" (Adobe's help: clipped layers take the opacity and blending mode of the base layer).

The edge cases, and where they follow Photoshop and where they do not:

- **Hidden base.** A hidden base, or one with zero opacity, hides everything clipped to it, whatever the clipped layers' own settings. Photoshop does the same: the base's visibility is the clipping group's visibility. A hidden *clipped* layer is skipped and the run goes on.
- **Fill opacity of the base.** `FillOpacity` multiplies into the opacity of the whole clipping group. Photoshop applies a base's fill opacity to the base's own pixels only (the usual trick of fill 0% on the base to show just the clipped layers, which needs the "blend clipped layers as group" option off). That is a deliberate difference; an "off" mode is not modelled.
- **No base.** A clipped layer at the bottom of its group, or after an adjustment layer (which cannot be a base), is drawn as an ordinary layer.
- **Group as the base.** Layers clipped to a group clip to the group's composited shape; the group is drawn on its own surface (isolated), whatever its pass-through setting, and its blend mode, opacity and mask are the clipping group's. Photoshop allows a group as a base.
- **Group clipped to a base.** Photoshop cannot clip a group (only layers); the flag exists in PSD files written by other tools, so it is handled here as an extension. An *isolated* group is composited on its own and drawn onto the surface source-atop with the group's blend mode, opacity and mask. A *pass-through* group has no surface of its own: its layers are drawn onto the clipping surface one after another, each as if it were clipped to the base (a child's blend mode sees what is already on the surface, an adjustment inside adjusts the surface), so at full opacity and no mask it is bit-identical to the same layers clipped one by one. Below full opacity, or with a mask, the result is mixed with the surface as it was before the group. A child's own `ClipToBelow` is ignored inside such a group, because every child is clipped to the base.
- **Adjustment layers.** A clipped adjustment adjusts only the base's surface.

### Adjustment layers

`Adjustment` has factories for `Levels`, `Curves`, `HueSaturation`, `BrightnessContrast`, `Exposure`, `Gamma`, `Invert`, `Threshold`, `Posterize`, `Grayscale` and `ColorMatrix` (the defaults are those of the `Image` method of the same name; `Curves`, `BrightnessContrast` and `Posterize` also have overloads that take a `CurveInterpolation`, `BrightnessContrastMode` or `PosterizeMode` to select Photoshop's formulas, which is what the PSD reader uses), and `Custom(name, Func<Image, Image>)`. An adjustment must be a **point operation**: each output pixel depends only on the same input pixel. Tiles are adjusted one at a time, so an operation that looks at neighbors (blur, resize) would show tile seams; the built-in factories are all point operations. Alpha is untouched. The adjusted backdrop is blended back as `backdrop + k·(adjusted − backdrop)`, `k = opacity × mask`; with a blend mode other than Normal the adjusted backdrop is first blended over the backdrop with that mode (Luminosity or Color make an adjustment touch tone only).

## Layer styles

`Layer.Style` (null by default) holds a `LayerStyle`: an immutable list of up to 64 effects, each an immutable `LayerEffect` with a blend mode, opacity (0..1) and color. Kinds: `DropShadowEffect`, `InnerShadowEffect`, `OuterGlowEffect`, `InnerGlowEffect`, `StrokeEffect` (outside, inside, center), `ColorOverlayEffect`, `GradientOverlayEffect`, `PatternOverlayEffect`, `BevelEmbossEffect` and `SatinEffect`; shadows, glows, satin and the bevel's gloss take an `EffectContour` (a piecewise-linear falloff remap of up to 256 points). Sizes are 0..250 px, distances 0..30000 px, spread and choke fractions 0..1, angles degrees counter-clockwise from the right; a value outside throws `ArgumentOutOfRangeException` when the effect is built. `Describe()` lists the style as `style.*` parameters with language-neutral names (`drop-shadow`, `stroke`, ...). A style survives a PSD save and load (see the [PSD page](https://recursiveai.org/oneimage/docs/psd/#layer-effects)).

**Defaults** (as in Photoshop): shadows Multiply, 75 %, black, light 120 degrees, distance 5, size 5; glows Screen, 75 %, light yellow, size 5; stroke Normal, 100 %, black, 3 px outside; overlay Normal, 100 %, black; satin Multiply, 50 %, black, 19 degrees, distance 11, size 14, inverted.

**Gradients, patterns and bevels.** `EffectGradient` holds color stops and opacity stops (locations and midpoints 0..1, up to 256 each, smoothness 0..1, optional linear-light blending); `EffectGradientFill` lays it out as linear, radial, angle, reflected or diamond (and, for strokes, shape burst) with an angle, scale (0.1..10), reverse, align-with-layer and offsets. `GradientOverlayEffect.Fill` is one; `StrokeEffect.Gradient` paints a stroke with one, and `OuterGlowEffect.Gradient` / `InnerGlowEffect.Gradient` color a glow by its falloff (first stop at the shape). `EffectPattern` is an RGBA tile (up to 2^24 pixels) and `EffectPatternFill` tiles it with a scale (0.01..10), link-with-layer and a phase; `PatternOverlayEffect.Fill` and `StrokeEffect.PatternFill` use it. "Aligned with the layer" means `LayerStyle.AlignBox` when set, else the layer's bounds (the PSD reader sets the box to the shape's bounds); otherwise the document. `BevelEmbossEffect` (style, technique, depth 0..10, size 0..250, soften 0..16 px, up or down, angle and altitude, highlight and shadow mode, color and opacity, gloss contour) lights the shape as a height field; the base `Opacity` scales both its highlight and shadow, and its base `Blend` and `Color` are unused. Gradients, patterns and bevels are computed per tile over a window around it like the other effects, so a region render equals the same pixels of a whole render.

**Drawing.** The shape is the layer's alpha times its mask (fill layers and `LayerStyle.ShapeFromMask` use the mask coverage alone). Bottom to top: drop shadows, outer glows, the outside part of bevels and embosses, the layer's pixels, color overlays, gradient overlays, pattern overlays, satin, inner glows, inner shadows, the inside part of bevels and embosses, strokes; the same kind draws in list order. The layer's opacity scales every effect. Fill opacity scales the pixels and, since an overlay recolors the pixels without changing their alpha, the overlays; shadows, glows, satin and strokes ignore it, and a drop shadow is knocked out where the shape is (`KnockedOut`, default true). Shadows and glows blur with sigma 0.41 x size (exact Gaussian up to sigma 2.5, three box blurs beyond); strokes and edge falloffs come from an exact signed distance of the antialiased alpha. Effects are computed per tile over a window around it, so a region render equals the same pixels of a whole render at any degree.

**Which layers.** Pixel and fill layers draw their style. A style on a group or an adjustment layer is kept in the model but not drawn. A layer clipped to the layer below, and the base of a clipping run, draw effects in a simpler pass (cut to the base; interior effects laid over rather than mixed in). Disabled effects are skipped.

**Dirty tiles.** An effect reaches beyond the layer by its distance plus size, and an inner effect (inner shadow, inner glow, bevel, inside stroke) sees the shape that far away: a layer edit or a style change marks the layer's bounds, or the edited area, widened by the larger of the two (`Layer.Reach`), so a stroke painted next to a shadow recomputes the tiles the shadow reaches and no others. Replacing `Style` marks both the old and the new reach.

## Render on demand and dirty regions

`document.Render()` returns an `Image` and computes nothing. Pulling a region (`CopyPixelsTo`, `Save`, `Crop` then save) computes only the document tiles it covers, and only the layers that touch each tile. A region render equals the same pixels of a whole render, at any degree of parallelism.

Composited tiles are cached per document (`DocumentOptions.RenderCacheBytes`, 256 MiB by default; the oldest are dropped and recomputed). `Snapshot()` finds out what changed:

1. For every pixel layer and mask it takes an O(1) snapshot of the canvas's tile table and compares it with the table from the previous snapshot. Canvas writes are copy-on-write, so a tile that was written is a different object, and the comparison is a pointer check per tile. Nothing needs to be told about strokes, fills or `Lock` writes.
2. Property and structure changes (opacity, blend mode, visibility, mask settings, adding, removing, moving and reordering layers, `Background`) mark the area they can change: a layer's bounds, or for a move the layers it passed. Adjustment and fill layers cover the whole document. A feathered mask widens its dirty area by four sigma.
3. The marked tiles get a new revision. A later render recomputes a cached tile only if it changed after the cache entry was made.

`Document.TilesComputed` and `TilesReused` count tile requests, for tests and tuning. Snapshots share the cache: rendering an old snapshot after an edit is correct (tiles changed since then are recomputed for it).

## Storage and the disk-spill store

Without options everything stays in memory. With `DocumentOptions.Spill` the document's canvases (and its cached composited tiles) are rented from a store that keeps at most `BudgetBytes` of **sealed** tiles in memory and parks the rest in a temporary file, reading them back when their pixels are touched:

```csharp
var doc = new Document(6000, 4000, new DocumentOptions
{
    Spill = new SpillOptions { BudgetBytes = 256L << 20, Directory = "/var/tmp" },
});
// ... add layers; call layer.Flush() after painting a big layer so its tiles can move to disk
Console.WriteLine(doc.SpillStatistics);   // tiles written/read, resident and file bytes
```

- A tile is sealed when a canvas snapshot makes it immutable: `Document.Snapshot()` and `PixelLayer.Flush()` do that for every tile of a layer. Tiles that can still be written in place are never moved, so while you paint a layer its tiles count against the budget but cannot leave memory. Flush a layer when you finish with it.
- Eviction is least-recently-used with a second chance. A tile is written once; later evictions of the same unchanged tile only drop the memory.
- The file is created on first use, named `oneimage-spill-*.tmp`, unlinked immediately on Unix and opened delete-on-close on Windows, so it cannot outlive the process. `SpillOptions.MaxFileBytes` (64 GiB) bounds it; going over throws `ImageLimitException`. Dispose the document to close it.
- Images rendered from a spilling document read from the file: do not use them after the document is disposed.
- An evicted tile's memory is reused once no reader can still see it, with no forced garbage collection. Code that reads spill tiles for a known stretch wraps it in a read scope (the layer renderer does this per rectangle it composites, and the copy-out per tile it copies); a buffer evicted meanwhile waits in an epoch until every scope that was open at eviction has closed, then goes to a small free list that rentals and page-ins draw from. A tile read by code outside a scope (a user reading a layer canvas, a codec saving a canvas) is marked, and its buffer is left to the garbage collector when evicted, since a span may still point at it. The wait is bounded (32 MiB of waiting buffers, 64 MiB of idle ones); past that, buffers go to the collector. Peak resident memory is the budget plus the layer being painted, the tile objects and the usual slack of the managed heap (about 540 MB for 100 layers of 24 MP under 256 MiB).

## Descriptions

`Document.Describe()` and `Layer.Describe()` return a `LayerDescription`: a kind (`document`, `pixel`, `group`, `fill`, `adjustment`), parameters whose values are only `long`, `double`, `bool` or `string`, and the children of a group. Names are lower-case and hyphenated: `name`, `visible`, `opacity`, `fill-opacity`, `blend` (`multiply`, `color-dodge`, … or `pass-through`), `clip-to-below`, `lock-transparent-pixels`, `lock-pixels`, `lock-position`, `x`, `y`, `width`, `height`, `mask-x`, `mask-y`, `mask-width`, `mask-height`, `mask-outside`, `mask-density`, `mask-feather`, `mask-enabled`, `pass-through`, `brush.*`, `adjustment` and `adjustment.*`. Pixels are not part of a description.

## What the PSD reader and writer map onto

| PSD concept | Here |
|---|---|
| Layer record: name, visible, opacity, fill opacity, blend key, clipping, lock flags | `Layer` properties of the same names |
| Blend keys (norm, mul, scrn, over, …) | `BlendMode` (the 24 modes); dissolve, darker/lighter color and pass-through-as-blend are not modes here (pass-through is `GroupLayer.PassThrough`) |
| Pixel channels and layer rectangle | `PixelLayer.Pixels` and `X`, `Y` |
| Layer mask and vector mask, density, feather, default color | `LayerMask` (raster masks; vector masks would be rasterized into one) |
| Layer group / section divider | `GroupLayer`, isolated or pass-through |
| Solid color and gradient fill layers | `FillLayer` |
| Adjustment layers (levels, curves, hue/saturation, …) | `AdjustmentLayer` with the matching `Adjustment` |
| Document size, depth, color mode, profile | `Document` size, `DocumentOptions.Format` and `ColorProfile` |
| Layer effects | `LayerStyle` (see [layer styles](#layer-styles)); [OneImage.Psd](https://recursiveai.org/oneimage/docs/psd/#layer-effects) reads and writes them |
| Smart objects, text layers | not modeled |

## Limits and edge behavior

- Layer canvases are checked against `ImageLimits` (or `DocumentOptions.Limits`) when created; the engine's hard caps apply.
- A layer may lie partly or wholly outside the document; the outside is kept but not drawn.
- `Opacity`, `FillOpacity` and `Density` throw `ArgumentOutOfRangeException` outside 0..1. A failing adjustment (one that changes the size or format) throws `ImageOperationException` when a tile is pulled, not when the layer is created.
- A document is single-writer. Snapshots and the images rendered from them are safe to use from any thread.
- Rendering an `Image` after `Document.Dispose()` throws `ObjectDisposedException` when a spill store was used.

## Measured

Ryzen 9 7950X3D (16 cores, 32 threads), .NET 10.0.13, on a shared machine with other jobs running (load 4-12 during the runs); documents of full-size 24 MP Rgba8 layers at 50% opacity, Normal blend. "Default" is the library per-call thread limit (4); "32" raises it for the call. The ImageSharp 3.1.12 rows clone a 24 MP image and chain DrawImage calls, using every core. "AVX2 only" rows run with `DOTNET_EnableAVX512=0`.

| Task | OneImage, default | OneImage, 32 threads | ImageSharp |
|---|---|---|---|
| Flatten 10 layers, every tile recomputed | 77 ms, 0.25 MB allocated | 34 ms | 72 ms |
| Flatten 50 layers, every tile recomputed | 361 ms, 0.25 MB allocated | 129 ms | 297 ms |
| Flatten 10 layers, AVX2 only | 115 ms | 40 ms | 91 ms |
| Flatten 50 layers, AVX2 only | 544 ms | 157 ms | 340 ms |
| Stroke on one of 20 layers, re-render, 512 x 512 viewport | 0.48 ms | | |
| Same, whole image into a caller buffer (24 MP copy-out dominates) | 8.0 ms | | |
| Same document, all 1504 tiles recomputed | 358 ms | | |

After a stroke, 2 of the 1504 tiles are recomputed and the other 1502 come from the cache. A 100-layer 24 MP document (9.6 GB of pixels) renders in 1.4 s with a 256 MiB spill budget at about 540 MB peak resident; 151,862 tiles are written and 150,368 read back, and the process makes no forced collection.

At the default degree, flattening 10 layers (77 ms) is slower than ImageSharp's 72 ms on all cores; it is published as an exception in [performance.md](https://recursiveai.org/oneimage/docs/performance/#layer-flatten-exception).


<!-- https://recursiveai.org/oneimage/docs/migrating/ -->

# Migrating from ImageSharp and System.Drawing

The OneImage side of every snippet below is compiled and run by `tests/OneImage.Tests/Docs/MigrationExamples.cs`. The ImageSharp side is compiled there too, against ImageSharp 3.1.12 (`ImageSharpSide.cs`). The System.Drawing side is **not** compiled in this repository (System.Drawing.Common is Windows-only and is not a dependency of the test project); it shows the usual idioms and is there for orientation.

## Concepts that differ

| | ImageSharp | System.Drawing | OneImage |
|---|---|---|---|
| Evaluation | Eager: each operation runs immediately on a decoded image | Eager | **Lazy**: operations are recorded; pixels are computed in tiles when you save or read |
| Mutation | `image.Mutate(x => ...)` changes the image in place; `Clone(...)` copies | Draw into a `Graphics`; `Bitmap` is mutable | **No `Mutate`.** Operations return a new immutable `Image`; chain them. Use a `Canvas` for in-place pixel edits |
| Pixel type | `Image<TPixel>` generic; `Image` is the non-generic base | `Bitmap` (GDI+ formats) | **`Image` is not generic.** It has a runtime `PixelFormat`; a pixel struct (`Rgba32`, ...) appears only where you read or write pixels |
| Disposal | `IDisposable` | `IDisposable` | `Image` has **no `Dispose`**. Only `Canvas` is disposable |
| Errors | Decode errors at `Load` | `ArgumentException`/`ExternalException` | Header errors at `Load`; **data errors may appear at `Save`**. Use `Validate = true` to fail at `Load` ([guide](https://recursiveai.org/oneimage/docs/guide/#errors-can-surface-at-save)) |
| Orientation | Not applied unless you call `AutoOrient()` | Not applied | **Applied at load** by default; `LoadOptions.AutoOrient = false` to opt out |
| Color | Pixel values as stored | GDI+ may convert | Values kept as decoded, ICC profile carried through; resampling in linear light |
| Metadata | Preserved on save unless removed | Property items | Preserved; `Thumbnail` strips EXIF/XMP/IPTC by default |
| Limits | `DecoderOptions` (some) | none | `ImageLimits` on by default; checked from headers |
| Platform | Cross-platform | Windows-only on current .NET | Cross-platform, pure managed |

A consequence of laziness: `Image.Load(path)` does not read the pixels, so the file must stay unchanged and present until you are done with the image (see [sources and lifetime](https://recursiveai.org/oneimage/docs/guide/#sources-and-lifetime)). To detach from the file, load from a `Stream` or `byte[]`.

Coordinates and rectangles are `int x, int y, int width, int height` (or `ImageRect`), zero-based, right and bottom edges exclusive.

## Side by side

### Load, resize, save

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Mutate(x => x.Resize(300, 0)); // 0 = keep aspect ratio
image.Save(output);
```

System.Drawing (not compiled here):

```csharp
using var src = new Bitmap(input);
using var dst = new Bitmap(300, src.Height * 300 / src.Width);
using (var g = Graphics.FromImage(dst))
{
    g.InterpolationMode = InterpolationMode.HighQualityBicubic;
    g.DrawImage(src, 0, 0, dst.Width, dst.Height);
}
dst.Save(output, ImageFormat.Png);
```

OneImage:

```csharp
Image.Load(input).Resize(width: 300).Save(output);
```

`Resize` takes optional `width` and `height`; leave one out to keep the aspect ratio. The output format comes from the extension of `output`.

### Thumbnail that fills a box

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Mutate(x => x.Resize(new ResizeOptions { Size = new Size(200, 200), Mode = ResizeMode.Crop, Position = AnchorPositionMode.Center }));
image.Save(output);
```

OneImage:

```csharp
Image.Load(input).Resize(width: 200, height: 200, fit: Fit.Cover, anchor: Anchor.Center).Save(output);

// Or the one-liner: upright, never enlarged, sRGB, without EXIF/GPS.
Image.Thumbnail(input, 200, 200, fit: Fit.Cover).Save(output);
```

| ImageSharp `ResizeMode` | OneImage |
|---|---|
| `Max` | `Fit.Contain` (default), also spelled `Fit.Max` |
| `Crop` | `Fit.Cover`, also spelled `Fit.Crop` |
| `Stretch` | `Fit.Stretch` |
| `Pad` | `Fit.Pad` (with `background:`) |
| `BoxPad` | `Fit.BoxPad`: like `Pad`, but an image that already fits keeps its size |
| `Min` | `Fit.Min`: covers the box without cropping, never enlarges |
| `Manual` with `TargetRectangle` | `ResizeInto(canvasWidth, canvasHeight, new ImageRect(x, y, width, height))` |

Sizes and placement match ImageSharp 3.1.12 in the cases we compared (all of them within one pixel, nearly all identical). Three small differences remain: a derived side that lands exactly on .5 rounds up here and to even in ImageSharp, an odd leftover when centering goes to the bottom/right here and to the top/left there, and `Min` or `Max` with only one side given use that side exactly.

`Resize` enlarges unless you pass `upscale: false`; `Image.Thumbnail` never enlarges unless you pass `upscale: true`. ImageSharp's `KnownResamplers` map to `ResamplingFilter`: `Lanczos3`, `CatmullRom`, `Bicubic`≈`CatmullRom`, `Triangle` → `Bilinear`, `NearestNeighbor` → `Nearest`, and `Hermite`, `Lanczos5`, `Lanczos8`, `Robidoux`, `RobidouxSharp`, `Spline` and `Welch` have the same names (ResamplingFilter.Bicubic and .Triangle exist as aliases). Our resize output with these is within 0.3 of a level on average of ImageSharp's. The default `Auto` picks Lanczos3 when shrinking and Catmull-Rom when enlarging.

### Crop

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Mutate(x => x.Crop(new Rectangle(10, 10, 100, 100)));
image.Save(output);
```

System.Drawing (not compiled here):

```csharp
using var src = new Bitmap(input);
using var cropped = src.Clone(new Rectangle(10, 10, 100, 100), src.PixelFormat);
cropped.Save(output);
```

OneImage:

```csharp
Image.Load(input).Crop(10, 10, 100, 100).Save(output);
```

The rectangle must lie fully inside the image; `Pad` first if you want to extract beyond an edge. Tiles outside the rectangle are never decoded.

### Rotate and flip

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Mutate(x => x.Rotate(90).Flip(FlipMode.Horizontal));
image.Save(output);
```

System.Drawing (not compiled here):

```csharp
using var bmp = new Bitmap(input);
bmp.RotateFlip(RotateFlipType.Rotate90FlipX);
bmp.Save(output);
```

OneImage:

```csharp
Image.Load(input).Rotate(90).Flip(FlipAxis.Horizontal).Save(output);
```

Both libraries rotate clockwise for positive angles. Multiples of 90 are exact pixel moves. Other angles grow the canvas to the bounding box (`expand: true`); pass `background:` for the corners. System.Drawing's EXIF auto-rotation, which you did by hand, is the default at load here.

### Perspective transforms

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Mutate(x => x.Transform(new ProjectiveTransformBuilder().AppendTaper(TaperSide.Left, TaperCorner.Both, 0.6f)));
image.Save(output);
```

OneImage:

```csharp
Image.Load(input)
    .Perspective(new ProjectiveTransformBuilder().AppendTaper(TaperSide.Left, TaperCorner.Both, 0.6))
    .Save(output);

// Pin the four corners (top-left, top-right, bottom-right, bottom-left) to chosen points:
Image.Load(input).Perspective([(30, 10), (150, 40), (120, 130), (10, 100)]).Save(output);

// Or a 3x3 matrix directly (column vectors; the top two rows are the same as Affine's a, b, tx and c, d, ty):
Image.Load(input).Perspective(new ProjectiveMatrix(1, 0.1, 0, 0, 1, 0, 0.001, 0, 1)).Save(output);
```

`ProjectiveTransformBuilder` has the same steps as ImageSharp's (`AppendTaper`, `AppendRotationDegrees`, `AppendScale`, `AppendSkewDegrees`, `AppendTranslation`, `AppendMatrix` and the `Prepend` forms) and takes `double` rather than `float`. Tapers give the same corner positions as ImageSharp's, and the default Catmull-Rom output is within about 1.5 levels on average of ImageSharp's `Transform` on smooth images. Differences to know about:

- ImageSharp's matrices are `Matrix4x4` with row vectors; `ProjectiveMatrix` is 3×3 with column vectors. To convert: `M11 = m11, M12 = m21, M13 = m41, M21 = m12, M22 = m22, M23 = m42, M31 = m14, M32 = m24, M33 = m44`.
- The output is the bounding box of the transformed image with its top-left corner at the origin (`expand: true`, as in `Rotate` and `Affine`), so a translation does not shift the picture; ImageSharp keeps the offset. Pass `expand: false` to apply the matrix in the input frame.
- A matrix that sends part of the image through the horizon (where `w` is zero) throws `ImageOperationException` instead of producing a picture.
- Interpolation runs in linear light on premultiplied alpha by default; pass `linear: false` to filter stored values as ImageSharp does.

### Convert format and set quality

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Save(output, new JpegEncoder { Quality = 85 });
image.SaveAsWebp(output + ".webp", new WebpEncoder { Quality = 80 });
```

System.Drawing (not compiled here):

```csharp
using var bmp = new Bitmap(input);
var jpeg = ImageCodecInfo.GetImageEncoders().First(e => e.FormatID == ImageFormat.Jpeg.Guid);
var p = new EncoderParameters(1);
p.Param[0] = new EncoderParameter(Encoder.Quality, 85L);
bmp.Save(output, jpeg, p);
```

OneImage:

```csharp
Image image = Image.Load(input);
image.Save("out.jpg", new SaveOptions { EncoderOptions = new JpegEncoderOptions { Quality = 85 } });
image.Save("out.webp", new SaveOptions { EncoderOptions = new WebPEncoderOptions { Quality = 80 } });
```

| Setting | OneImage |
|---|---|
| JPEG quality / subsampling / progressive | `JpegEncoderOptions.Quality`, `.Subsampling`, `.Progressive` |
| PNG compression / filter | `PngEncoderOptions.CompressionLevel`, `.Filter`, `.ColorMode` |
| WebP lossless / quality / effort | `WebPEncoderOptions.Lossless`, `.Quality`, `.Effort` |
| GIF palette / dither | `GifEncoderOptions.MaxColors`, `.Dither` |
| TIFF compression | `TiffEncoderOptions.Compression` |

Save to a stream with the format named: `image.Save(stream, JpegFormat.Instance, options)`. There is no format sniffing from the stream; there is from the file extension.

### Pixel access

ImageSharp:

```csharp
using Image<Rgba32> image = Image.Load<Rgba32>(input);
image.ProcessPixelRows(accessor =>
{
    Span<Rgba32> row = accessor.GetRowSpan(0);
    for (int x = 0; x < row.Length; x++)
    {
        row[x].G = 0;
    }
});
```

System.Drawing (not compiled here): `bmp.GetPixel`/`SetPixel`, or `LockBits` for speed.

OneImage:

```csharp
Image image = Image.Load(input);
Rgba32[] pixels = image.ToArray<Rgba32>();     // read: any pixel struct, converted from the image's format

using Canvas canvas = image.ToCanvas();        // edit
using (PixelLock<Rgb24> l = canvas.Lock<Rgb24>(new ImageRect(0, 0, canvas.Width, 1), LockAccess.ReadWrite))
{
    Span<Rgb24> row = l.GetRow(0);
    for (int x = 0; x < row.Length; x++)
    {
        row[x] = row[x] with { G = 0 };
    }
}
Image edited = canvas.Snapshot();
```

Two things to know. `Image.ToArray<T>()` and `CopyPixelsTo<T>()` convert to `T`, but `Canvas.Lock<T>` requires `T` to match the canvas format exactly (a decoded JPEG is `PixelFormat.Rgb8`, whose struct is `Rgb24`). Check `canvas.Format`, or build the canvas with `new Canvas(w, h, PixelFormat.Rgba8)`. And pixel structs are immutable records: assign a new value (`row[x] = row[x] with { G = 0 }`) rather than writing a field.

For a whole-image edit that is a per-pixel function, prefer the built-in ops (`Invert`, `Levels`, `ChannelMixer`, ...), which are vectorized and lazy.

### Draw an image on another (watermark)

ImageSharp:

```csharp
using Image image = Image.Load(input);
using Image overlay = Image.Load(mark);
image.Mutate(x => x.DrawImage(overlay, new Point(20, 20), 0.8f));
image.Save(output);
```

System.Drawing (not compiled here):

```csharp
using var bmp = new Bitmap(input);
using var overlay = new Bitmap(mark);
using (var g = Graphics.FromImage(bmp))
{
    var cm = new ColorMatrix { Matrix33 = 0.8f };
    var attrs = new ImageAttributes();
    attrs.SetColorMatrix(cm);
    g.DrawImage(overlay, new Rectangle(20, 20, overlay.Width, overlay.Height), 0, 0, overlay.Width, overlay.Height, GraphicsUnit.Pixel, attrs);
}
bmp.Save(output);
```

OneImage:

```csharp
Image.Load(input).Composite(Image.Load(mark), x: 20, y: 20, opacity: 0.8f).Save(output);
```

`Composite` is source-over with premultiplied alpha and color management by default. The overlay can be negative-offset or partly outside the base. The overlay is itself an `Image`, so resize or fade it first with the normal ops.

ImageSharp's `DrawImage(image, point, PixelColorBlendingMode, opacity)` and `GraphicsOptions.AlphaCompositionMode` map to the `blend:` and `alpha:` parameters of `Composite`:

```csharp
// ImageSharp: img.Mutate(c => c.DrawImage(mark, new Point(20, 20), PixelColorBlendingMode.Multiply, 0.8f));
Image.Load(input).Composite(Image.Load(mark), x: 20, y: 20, opacity: 0.8f, blend: BlendMode.Multiply).Save(output);
```

| ImageSharp | OneImage |
|---|---|
| `PixelColorBlendingMode` Normal, Multiply, Add, Subtract, Screen, Darken, Lighten, Overlay, HardLight | `BlendMode` with the same names. The values agree with ImageSharp within a few levels at 8 bits (ImageSharp rounds through 8-bit intermediates). |
| `PixelAlphaCompositionMode` SrcOver, Clear, Src, SrcAtop, SrcIn, SrcOut, Dest, DestAtop, DestIn, DestOut, DestOver, Xor (and `Plus`, which ImageSharp lacks) | `AlphaComposition` with the same names. Like `DrawImage`, only the pixels under the overlay change. A base without alpha accepts only the operators that keep it opaque (SrcOver, SrcAtop, Dest, DestOver). |
| (not in ImageSharp) | Also ColorDodge, ColorBurn, SoftLight, Difference, Exclusion, LinearBurn, LinearDodge, VividLight, LinearLight, PinLight, HardMix, Divide, Hue, Saturation, Color and Luminosity. |

### Metadata

ImageSharp:

```csharp
using Image image = Image.Load(input);
string? make = null;
if (image.Metadata.ExifProfile != null && image.Metadata.ExifProfile.TryGetValue(ExifTag.Make, out IExifValue<string>? value))
{
    make = value.Value;
}
image.Metadata.ExifProfile = null; // strip EXIF
image.Save(output);
```

OneImage:

```csharp
Image image = Image.Load(input);
string? make = image.Metadata.ReadExif()?.Make;      // typed: Orientation, Make, Model, CaptureTime, Gps
image.StripMetadata().Save(output);                  // EXIF, XMP, IPTC and ICC removed; StripMetadata(keepIcc: true) keeps the profile
```

OneImage parses only the common EXIF tags. The raw `Exif`, `Xmp`, `Iptc` and `IccProfile` blobs are always available on `Image.Metadata` if you need others. Metadata is preserved by default and corrected for the saved size and orientation. System.Drawing exposes EXIF through `PropertyItems`; there is no direct equivalent API.

### Blur, sharpen, median, edges, histogram

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Mutate(x => x.GaussianBlur(2f));
image.Mutate(x => x.BoxBlur(3));
image.Mutate(x => x.GaussianSharpen(1.2f));
image.Mutate(x => x.MedianBlur(1, true));
image.Mutate(x => x.DetectEdges());
image.Save(output);

// Histogram: count it yourself.
var counts = new long[256];
image.ProcessPixelRows(accessor =>
{
    for (int y = 0; y < accessor.Height; y++)
    {
        foreach (Rgba32 p in accessor.GetRowSpan(y)) counts[p.R]++;
    }
});
```

OneImage:

```csharp
Image.Load(input)
    .GaussianBlur(2)
    .BoxBlur(3)
    .Sharpen(amount: 1, radius: 1.2)
    .Median(1)
    .Sobel()
    .Save(output);

long[] red = Image.Load(input).Histogram().Channel(0).ToArray();   // 256 bins; Statistics() gives min/max/mean/stddev
```

| ImageSharp | OneImage | Differences |
|---|---|---|
| `GaussianBlur(sigma)` | `GaussianBlur(sigma)` | Linear light by default (`linear: false` for stored values); edge mode defaults to clamp. |
| `BoxBlur(radius)` | `BoxBlur(radius)` | Same window `2r+1`. |
| `GaussianSharpen(sigma)` | `GaussianSharpen(sigma)` | The same kernel (see [Effects](#effects)). `Sharpen(amount, radius, threshold)` is a different operator, an unsharp mask with an `amount` and a `threshold`; its default is linear light, pass `linear: false` for the look most editors have. |
| `MedianBlur(radius, preserveAlpha)` | `Median(radius)` | Alpha is filtered like a color channel; there is no `preserveAlpha`. |
| `DetectEdges()` (Sobel by default) | `DetectEdges()` or `Sobel(scale)` | `DetectEdges` is ImageSharp's operator, unscaled (see [Effects](#effects)); `Sobel(scale)` divides by 4 so that a black-to-white step gives full scale, and always returns a gray image without alpha. |
| custom convolution | `Convolve(float[,] kernel, divisor, offset)` | Correlation (not flipped); divisor defaults to the sum of the weights. |
| none built in | `Histogram(bins)`, `Statistics()` | Per channel, whole frame 0, computed in parallel. |

### Effects

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Mutate(x => x.Pixelate(8));
image.Mutate(x => x.OilPaint(10, 15));
image.Mutate(x => x.Vignette(Color.Black));
image.Mutate(x => x.Glow(Color.White));
image.Mutate(x => x.BokehBlur(32, 2, 3f));
image.Mutate(x => x.GaussianSharpen(1.2f));
image.Mutate(x => x.DetectEdges(KnownEdgeDetectorKernels.Kirsch));
image.Mutate(x => x.EntropyCrop(0.5f));
image.Save(output);
```

OneImage:

```csharp
Image.Load(input)
    .Pixelate(8)
    .OilPaint(levels: 10, brushSize: 8)
    .Vignette(new Rgba32(0, 0, 0, 255))
    .Glow(new Rgba32(255, 255, 255, 255))
    .BokehBlur(radius: 32, components: 2, gamma: 3)
    .GaussianSharpen(1.2)
    .DetectEdges(EdgeDetector.Kirsch)
    .EntropyCrop(0.5f)
    .Save(output);
```

| ImageSharp | OneImage | Differences |
|---|---|---|
| `Pixelate(size)` | `Pixelate(size)` | Identical output: each block takes the color of the pixel at its center (not an average), in any pixel format. |
| `OilPaint(levels, brushSize)` | `OilPaint(levels, brushSize)` | ImageSharp's window reaches only up and left of the pixel and is `brushSize / 2 + 1` wide, which shifts the picture by about a quarter of the brush. OneImage centers a full `brushSize` window, so its strokes are about twice as wide for the same number and nothing shifts; use about half the brush size for a similar look. Where two intensity bins tie, ImageSharp keeps the one reached first while scanning and OneImage the brighter. |
| `Vignette(color, radiusX, radiusY, rectangle)` | `Vignette(color, radiusX, radiusY, area)` | Same falloff (within 1 level). Radii of 0 mean half the area's width and height, as in ImageSharp. Gray and RGB images only. |
| `Glow(color, radius, rectangle)` | `Glow(color, radius, area)` | Same falloff (within 1 level), and the same default color: black, which darkens the center. |
| `BokehBlur(radius, components, gamma)` | `BokehBlur(radius, components, gamma)` | Same complex-kernel family and defaults (32, 2, 3), computed on the stored premultiplied values like ImageSharp. With `gamma: 1` the results agree within 1 level; with a higher gamma, nearly black channels can differ by up to 20 levels, elsewhere 1 level. |
| `GaussianSharpen(sigma)` | `GaussianSharpen(sigma)` | Same kernel and defaults (sigma 3), within 2 levels. It filters stored values like ImageSharp; pass `linear: true` for linear light. |
| `DetectEdges(KnownEdgeDetectorKernels.X, grayscale)` | `DetectEdges(EdgeDetector.X, grayscale)` | Same kernels (Sobel, Prewitt, Scharr, RobertsCross, Kayyali, Laplacian3x3, Laplacian5x5, LaplacianOfGaussian, Kirsch, Robinson), same results to the level. With `grayscale: true` (the default) the result is a gray image without alpha, where ImageSharp returns an RGB image of equal channels. |
| `EntropyCrop(threshold)` | `EntropyCrop(threshold)` | Same rectangle. Eager, like `Trim`; an image with no detail is returned as it is. |
| `HistogramEqualization(options)` (`Method`, `LuminanceLevels`, `ClipHistogram`, `ClipLimit`, `NumberOfTiles`) | `HistogramEqualization(method, luminanceLevels, clipHistogram, clipLimit, tiles)` | Same defaults (global, 256, no clipping, 350, 8) and output within 1 level at 8 bits on our comparisons, for global, `AdaptiveTileInterpolation` and `AdaptiveSlidingWindow`, with and without clipping. Like ImageSharp it equalizes luminance (Rec. 709) and writes the new luminance to all three color channels, so color is not preserved; alpha is carried over. `tiles` is at least 2. ImageSharp refuses an image shorter than the sliding window; this does not. |

### Color matrix, preset looks, color blindness, opacity

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Mutate(x => x.Sepia(0.8f));
image.Mutate(x => x.Kodachrome());
image.Mutate(x => x.ColorBlindness(ColorBlindnessMode.Deuteranopia));
image.Mutate(x => x.Opacity(0.5f));
image.Mutate(x => x.Filter(new ColorMatrix(
    1f, 0f, 0f, 0f,
    0f, 1f, 0f, 0f,
    0f, 0f, 1f, 0f,
    0f, 0f, 0f, 1f,
    0.1f, 0f, 0f, 0f)));
image.Save(output);
```

OneImage:

```csharp
Image.Load(input)
    .Sepia(0.8f)
    .Kodachrome()
    .ColorBlindness(ColorBlindnessMode.Deuteranopia)
    .Opacity(0.5f)
    .ApplyColorMatrix(new ColorMatrix(
        1f, 0f, 0f, 0f,
        0f, 1f, 0f, 0f,
        0f, 0f, 1f, 0f,
        0f, 0f, 0f, 1f,
        0.1f, 0f, 0f, 0f))
    .Save(output);
```

`ColorMatrix` has ImageSharp's layout (`M11`..`M54`, the pixel as a row vector, row 5 the offsets), so a matrix copies over value for value. The presets use ImageSharp's matrices, and the 8-bit results agree with ImageSharp to within one step (checked in the test suite).

| ImageSharp | OneImage | Differences |
|---|---|---|
| `Filter(ColorMatrix)` | `ApplyColorMatrix(ColorMatrix)` | Works on straight color on the stored values, like ImageSharp. Integer results clamp; float results are not clamped (alpha always is). Gray images become RGB. |
| `Sepia(amount)`, `BlackWhite()`, `Kodachrome()` | `Sepia(amount)`, `BlackWhite()`, `Kodachrome()` | Same matrices. `Sepia(0)` returns the image unchanged. `BlackWhite` is a hard, high-contrast matrix, not a luminance conversion; use `Grayscale` for that. |
| `Lomograph()`, `Polaroid()` | `Lomograph()`, `Polaroid()` | The full looks, within one level of ImageSharp at 8 bits: `Lomograph` is the matrix plus a dark-green `Vignette`; `Polaroid` is the matrix plus a dark-orange `Vignette` and an orange `Glow`. The matrix alone is `ApplyColorMatrix(ColorMatrix.Lomograph)` / `ColorMatrix.Polaroid`, which are the same values as ImageSharp's `KnownFilterMatrices` and have no vignette. |
| `ColorBlindness(mode)` | `ColorBlindness(mode)` | Same eight modes and matrices. |
| `Opacity(amount)` | `Opacity(amount)` | Multiplies alpha. An image without alpha gains an alpha channel. |
| `KnownFilterMatrices` | `ColorMatrix.Sepia(amount)`, `.BlackWhite`, `.Kodachrome`, `.Lomograph`, `.Polaroid`, `.ColorBlindness(mode)`, `.Opacity(amount)` | Matrices as values you can inspect, multiply (`a * b` applies `a`, then `b`) and pass to `ApplyColorMatrix`. |

These ops fuse with the other color ops (`Gamma`, `Levels`, `Invert`, ...) into one pass over each tile, so `Sepia().BrightnessContrast(...).Opacity(...)` reads the pixels once.

### Histograms, thresholds and dithering

ImageSharp:

```csharp
using Image image = Image.Load(input);
image.Mutate(x => x.HistogramEqualization(new HistogramEqualizationOptions { Method = HistogramEqualizationMethod.AutoLevel }));
image.Mutate(x => x.AdaptiveThreshold(Color.White, Color.Black, 0.85f));
image.Mutate(x => x.BinaryDither(KnownDitherings.Bayer4x4));
image.Mutate(x => x.Dither(KnownDitherings.Stucki, new[] { Color.Black, Color.White, Color.Red }));
image.Mutate(x => x.Quantize(KnownQuantizers.Octree));
image.Save(output);
```

OneImage:

```csharp
Image.Load(input)
    .AutoLevel()
    .AdaptiveThreshold(new Rgba32(255, 255, 255, 255), new Rgba32(0, 0, 0, 255), 0.85f)
    .BinaryDither(Dither.Bayer4x4)
    .Dither([new Rgba32(0, 0, 0, 255), new Rgba32(255, 255, 255, 255), new Rgba32(255, 0, 0, 255)], Dither.Stucki)
    .Quantize(256, quantizer: Quantizer.Octree)
    .Save(output);
```

| ImageSharp | OneImage | Differences |
|---|---|---|
| `HistogramEqualization` with `Method = AutoLevel`, `SyncChannels` | `AutoLevel(syncChannels)` | A method of its own rather than an option value. Per-channel (`syncChannels: false`) is within 1 level of ImageSharp, synchronized (the default) within 2. |
| `AdaptiveThreshold(upper, lower, limit)` | `AdaptiveThreshold(upper, lower, thresholdLimit)` | Same Bradley window and defaults (white over black, 0.85). Identical on gray input; on photos a pixel or two on the border can differ (2 of 31,871 in the test image). |
| `BinaryDither(dither, upper, lower)` | `BinaryDither(dither, upper, lower)` | Same dithers, black and white by default. |
| `Dither(dither, palette)` | `Dither(palette, dither, scale, fastMatch)` | All the `KnownDitherings` map to `Dither` members: Atkinson, Burkes, JarvisJudiceNinke, Sierra2, Sierra3, SierraLite, StevensonArce, Stucki, FloydSteinberg, Bayer2x2, Ordered3x3, Bayer4x4, Bayer8x8, Bayer16x16. See below for exactness. |

How exact the dithers are:

- **Error diffusion** (all nine kernels) is bit-identical to ImageSharp with the default `fastMatch: true`. ImageSharp finds the nearest palette color through a cache keyed by the top five bits of each channel and keeps the first answer for a cell, so its result depends on the order colors are met. Pass `fastMatch: false` to answer for the exact color of every pixel instead, which is more accurate but slower (about 1.1× ImageSharp's time with the web palette on one thread).
- **Ordered dithers** use the same matrices and the same amplitude rule as ImageSharp. With small palettes the output is identical; with the web-safe and Werner palettes up to about 2.5% of pixels differ, from the same cache effect.
- **Threads.** Ordered dithering runs on all tiles in parallel. Error diffusion is a single pass in row order, so it uses one thread whatever the setting, and its output never depends on the thread count.
- `Dither` takes a palette as a list of `Rgba32`; a palette with one transparent entry works with opaque photos.
- ImageSharp's `CalculateIntegralImage` has no public counterpart; `AdaptiveThreshold` uses a window sum internally.

## Behavior to expect after porting

- **Orientation is applied for you.** If your old code called `AutoOrient()` or rotated by the EXIF tag, remove that, or the picture will be turned twice.
- **Resize quality differs slightly.** Resampling is done in linear light on premultiplied alpha, so edges and gradients can look a little different from a gamma-space resize. Pass `linear: false` to compare.
- **Errors surface later.** Wrap the `Save`, not only the `Load`, in your `try` block, or load with `Validate = true`.
- **There is nothing to dispose** on an `Image`; delete `using` statements and let `Canvas` carry the `using`.
- **Operations are cheap to build and run once.** Don't save an intermediate just to reuse it: keep the `Image` and derive more images from it. Each save recomputes its own path, though shared tiles are cached under the engine's memory budget.
- **Limits are on.** Very large or suspicious files throw `ImageLimitException`; raise the limits or use `ImageLimits.Unrestricted` for trusted data.

## Not in OneImage yet

This is the one list of what ImageSharp 3.1.x has that OneImage does not, or has only in part; for drawing, text and the web middleware it also says what OneImage has in their place. It was built by going through the public API of ImageSharp 3.1.12 (the version this guide is checked against) and, for shapes, text and the web middleware, the public API and XML documentation of SixLabors.ImageSharp.Drawing 2.1.7, SixLabors.Fonts 2.1.3 and SixLabors.ImageSharp.Web 3.2.0. These are the last releases of those packages that build without a license key, matching the ImageSharp reference version; newer releases may offer more. "Coming soon" means the work is planned and next in line; it is not a promise of a date. "Not planned" means we are not working on it and are not promising it.

Where OneImage has part of a feature, the table says what it covers and what it does not.

### Drawing and text

Drawing is SixLabors.ImageSharp.Drawing 2.1.7; text layout and fonts are SixLabors.Fonts 2.1.3. Text is in the separate package `RecursiveAI.OneImage.Text` (see [text.md](https://recursiveai.org/oneimage/docs/text/)); the rows below say what it covers.

| ImageSharp | OneImage today | Closest workaround |
|---|---|---|
| `Fill(...)` (whole image, rectangle, path, polygon, path collection), `Draw(...)` (rectangle, path, path collection), `DrawLine`, `DrawPolygon`, `DrawBeziers`, `DrawPath`, `FillPolygon`, `Clear(...)` | `img.Fill(color)`, `Fill(brush, path)`, `Draw(pen, path)` and `Draw(color, width, path)` (lazy, on `Image`) and the same on `Canvas` (in place); `DrawLine`, `DrawPolyline`, `DrawPolygon`, `DrawBeziers`, `DrawRectangle`, `DrawEllipse`; `Clear(color)`. | The names and the differences (default fill rule, edge rule without anti-aliasing, pixel coordinates, strokes half a pixel from ImageSharp's) are in [drawing.md](https://recursiveai.org/oneimage/docs/drawing/). |
| Shapes and paths: `IPath`, `Path`, `PathBuilder` (lines, arcs, quadratic and cubic Béziers, SVG arc, figures, transforms), `Path.TryParseSvgPath`, `Polygon`, `ComplexPolygon`, `RectangularPolygon`, `RegularPolygon`, `Star`, `EllipsePolygon`, `PathCollection`; path `Translate`/`Scale`/`Rotate`/`Reverse`/`ComputeLength`; `GenerateOutline` (stroke to outline) | `Path`, `PathBuilder`, the shape factories (`Rectangle`, `RoundedRectangle`, `Ellipse`, `Circle`, `Polygon`, `Polyline`, `RegularPolygon`, `Star`, `Combine`), `Path.TryParseSvg`; `Transform`, `Translate`, `Scale`, `Rotate`, `Reverse`, `Bounds`, `Flatten()`; `GenerateOutline`. | Name by name in [drawing.md](https://recursiveai.org/oneimage/docs/drawing/#imagesharpdrawing-names); `ComputeLength` has no counterpart there. |
| Boolean clipping of shapes: `IPath.Clip(ShapeOptions, IPath[])` with `ClippingOperation` Union, Intersection, Difference (the default there) and Xor | `path.Union(other)`, `Intersect`, `Subtract`, `Xor`, `path.Boolean(BooleanOperation, other, subjectRule, clipRule)`, `PathBoolean.UnionAll(paths)`, `Resolve(rule)` and `Offset(distance)`; results are polygons of straight segments on a 1/256 px grid. | Agreement and differences are in [drawing.md](https://recursiveai.org/oneimage/docs/drawing/#boolean-operations-and-clipping): filled results agree with ImageSharp.Drawing 2.1.7 to a mean of 0.02 to 0.33 levels. The operation is always named, and each operand has its own rule. |
| Brushes: `SolidBrush`, `LinearGradientBrush`, `RadialGradientBrush`, `EllipticGradientBrush`, `PathGradientBrush` (all with `ColorStop`s and `GradientRepetitionMode` None/Repeat/Reflect/DontFill where applicable), `PatternBrush` and the `Brushes` hatch presets (horizontal, vertical, diagonals, 10%, 20%, min), `ImageBrush`, `RecolorBrush` | `Brush.Solid`, `Brush.LinearGradient`, `RadialGradient`, `EllipticGradient`, `PathGradient`, `Brush.Pattern`, `Brush.Hatch(HatchStyle, ...)`, `Brush.FromImage`, `Brush.Recolor`, passed to `Fill(brush, path)`. `GradientRepetition` has the same four modes. | Differences are listed under *Brushes* in [drawing.md](https://recursiveai.org/oneimage/docs/drawing/#brushes): brushes are anchored at the image origin (ImageSharp anchors image brushes at the shape's top-left, so pass `offsetX`/`offsetY`); gradient stops blend premultiplied unless `premultiplied: false`; slanted gradients do not mirror the pixels behind their start; elliptic gradients turn toward the axis end and change linearly unless `squaredDistance: true`; `PathGradient` samples pixel centers. |
| Pens: `Pen`, `SolidPen`, `PatternPen`, `Pens` (solid, dash, dot, dash-dot, dash-dot-dot), `PenOptions` (width, brush fill, dash pattern, `JointStyle` miter/round/square, `EndCapStyle` butt/round/square/joined/polygon) | `Pen` (any `Brush`, width, `StrokeJoin` `Miter`/`Round`/`Bevel`/`Square`, `StrokeCap` `Butt`/`Round`/`Square`, miter limit, dash pattern), `Pen.Solid`, `Pen.Dash`, `Pen.Dot`, `Pen.DashDot`, `Pen.DashDotDot`. | Dash patterns are absolute lengths, not multiples of the width, and there are no joined or polygon caps; see [drawing.md](https://recursiveai.org/oneimage/docs/drawing/#strokes). |
| Clipping: `ctx.Clip(path, action)` (apply any processors only inside a path) | `img.Clip(path, i => ...)` (lazy) and `canvas.Clip(path, ...)` (in place); `Fill` and `Draw` take `clip:` to limit one shape to a clip path. | Pixels outside the path are untouched and the edge blends by anti-aliased coverage; see [drawing.md](https://recursiveai.org/oneimage/docs/drawing/#boolean-operations-and-clipping). |
| Options: `DrawingOptions` (`GraphicsOptions`, `ShapeOptions`, `Transform`), `ShapeOptions.IntersectionRule` (non-zero, even-odd), `GraphicsOptions` anti-aliasing and blending | `antialias:`, `rule:`, `opacity:`, `blend:`, `composition:`, `transform:` on each call. | None. |
| `DrawText` (string or `RichTextOptions`, with a `Brush`, a `Pen` or both, also along a path with `RichTextOptions.Path`), `RichTextRun` (per-run brush, pen, underline, strikeout and overline pens), `TextBuilder.GenerateGlyphs` (text as a path) | `img.DrawText(text, options, brush, pen)` and `canvas.DrawText(...)` in the separate package `RecursiveAI.OneImage.Text`; `TextOptions.TextRuns` (`TextRun`: font, size, `TextAttributes`, `TextDecorations`, per-run `Brush`/`Pen`, `UnderlinePen`/`StrikeoutPen`/`OverlinePen`) and `TextOptions.Path` (text along a `Path`); `TextBuilder.GeneratePath`. | Runs that overlap are resolved per character (the later run wins). Glyph placement on a path matches to 0.001 px except where noted in [text.md](https://recursiveai.org/oneimage/docs/text/#agreement-with-imagesharp). |
| Fonts: `Font`, `FontFamily`, `FontCollection`, `SystemFonts`; TrueType, OpenType with CFF outlines, TrueType collections and WOFF/WOFF2 files; `FontStyle` and `TextAttributes` (sub/superscript), `TextDecorations` | `Font`, `FontFamily`, `FontCollection` and `SystemFonts` (installed fonts found by scanning the standard directories, nothing loaded until a family is asked for); TrueType, OpenType/CFF, TrueType Collections, WOFF 1.0 and WOFF 2.0 ([text.md](https://recursiveai.org/oneimage/docs/text/#woff2)); `FontStyle`, `TextAttributes`, `TextDecorations`. | None. |
| Text layout: `TextOptions` (origin, wrapping length, line spacing, tab width, horizontal and vertical alignment, `TextAlignment`, `TextJustification` inter-word/inter-character, `KerningMode`, `HintingMode`, `WordBreaking`, `Dpi`, `LayoutMode` horizontal and vertical modes, `FeatureTags`), `TextMeasurer`/`TextRenderer`/`TextLayout` | `TextOptions` with every item, `HintingMode` ([hinting](https://recursiveai.org/oneimage/docs/text/#hinting)) and `LayoutMode` ([vertical layout](https://recursiveai.org/oneimage/docs/text/#vertical-layout)) included; `TextDirection` is `Auto`, `LeftToRight` or `RightToLeft` (per paragraph; forced directions follow UAX #9, see [text.md](https://recursiveai.org/oneimage/docs/text/#arabic-and-hebrew)); `FeatureTags` is `Features`; `TextMeasurer` (advance, bounds, lines, character boxes). | In vertical modes, bidirectional reordering, decorations and text on a path are not applied ([text.md](https://recursiveai.org/oneimage/docs/text/#vertical-layout)). |
| Complex text in SixLabors.Fonts 2.1.3: OpenType GSUB/GPOS shaping (ligatures, kerning, marks), Arabic and Indic shapers, the Unicode bidirectional algorithm (`TextDirection` auto/LTR/RTL) and line breaking, font fallback (`TextOptions.FallbackFontFamilies`), color fonts (`ColorFontSupport.MicrosoftColrFormat`: COLR/CPAL) | GSUB/GPOS shaping, the Unicode bidirectional algorithm (UAX #9), an Arabic joining shaper (Arabic, Syriac, N'Ko), Hebrew, an Indic shaper (Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam), a Universal Shaping Engine shaper (Khmer, Myanmar, Sinhala, Tibetan, Balinese, Javanese and more), Thai and Lao shaping, and Unicode line breaking (UAX #14, no dictionaries: Thai, Lao, Khmer and Burmese break only at spaces and punctuation) and grapheme clusters (UAX #29); `FallbackFontFamilies`; COLR version 0 / CPAL color glyphs (`ColorFontSupport`, `ColorPaletteIndex`), also inside rich-text runs and fallback faces. COLR version 1 paint graphs too ([text.md](https://recursiveai.org/oneimage/docs/text/#colr-version-1)). The differences for right-to-left text are listed in [text.md](https://recursiveai.org/oneimage/docs/text/#agreement-with-sixlaborsfonts), those for Indic and Southeast Asian scripts in [text.md](https://recursiveai.org/oneimage/docs/text/#complex-scripts-indic-southeast-asian-and-the-universal-shaping-engine) (the reference throws on some Gurmukhi, Telugu, Khmer and Malayalam input; we do not). | Scripts outside the Indic, USE, Thai and Lao lists need another tool for now. |

Not in Fonts 2.1.3 either, so not part of the gap: CFF2 outlines (rejected with "CFF2 Fonts are not currently supported") and a public API for variable-font axes (the package lists the `rvrn` feature tag but exposes no axis settings). Also not covered by the colour-font option: SVG, `sbix`, CBDT and other bitmap colour glyphs.

### Effects and filters: coming soon

| ImageSharp | OneImage today | Closest workaround |
|---|---|---|
| `CalculateIntegralImage()` | None as a public API (`AdaptiveThreshold` sums windows internally). | `Histogram` and `Statistics` cover the common uses. |

`BackgroundColor` is covered by `Flatten(color)`, `Skew` and `AffineTransformBuilder` by `Affine(a, b, c, d, tx, ty)`, and `ProjectiveTransformBuilder` by `Perspective` (see [Perspective transforms](#perspective-transforms)). `Rotate`, `Pad`, `Trim`, `Grayscale`, `Invert`, `GaussianBlur`, `BoxBlur`, `Median`, `Convolve`, brightness/contrast, hue/saturation/lightness and the rest of the list under [Side by side](#side-by-side) do exist.

### Web middleware: in OneImage.Web

SixLabors.ImageSharp.Web 3.2.0 (it depends on ImageSharp 3.1.11) maps to the separate `RecursiveAI.OneImage.Web` package. [The web guide](https://recursiveai.org/oneimage/docs/web/) has the details; the short version:

| ImageSharp.Web | OneImage.Web |
|---|---|
| `AddImageSharp()` / `UseImageSharp()` | `AddOneImage()` / `UseOneImage()`. The builder offers `AddProvider`, `ClearProviders`, `SetCache`, `SetCacheKey`, `SetCacheHash`, `Configure` and `ConfigureCache`. |
| Query commands `width`, `height`, `xy`, `rmode`, `ranchor`, `rsampler`, `color`, `bgcolor`, `orient`/`autoorient`, `compand`, `format`, `quality`; `PresetOnlyQueryCollectionRequestParser` | All accepted (alongside shorter names such as `w`, `h`, `fit`, `q`); `PresetsOnly = true`. `rmode=manual` and the samplers `welch`, `hermite`, `spline`, `robidoux`, `lanczos5`, `lanczos8` are rejected with 400. Call `options.UseImageSharpDefaults()` to get ImageSharp.Web's default of cropping and enlarging when a width and height are given. |
| `PhysicalFileSystemProvider`, `WebRootImageProvider`, `FileProviderImageProvider`, `IImageProvider`, `ProcessingBehavior` | `PhysicalFileImageProvider`, `WebRootImageProvider`, `FileProviderImageProvider`, `IImageProvider` (a simpler interface: `Match` and `GetAsync` returning a source with a modified time, a length and a stream), `ProcessingBehavior`. |
| `PhysicalFileSystemCache`, `IImageCache`, `ICacheKey`, `ICacheHash`, `CacheFolderDepth`, `CacheHashLength`, `BrowserMaxAge`, `CacheMaxAge`, conditional requests | Same names and meanings. The default cache folder is `oneimage-cache` in the content root rather than under `wwwroot`, the default hash length is 32, and ETags are known without reading the cache. There is no in-memory resolver cache. |
| `HMACSecretKey`, `HMACUtilities`, `ImageTagHelper`, `HmacTokenTagHelper` | `HmacSecretKey`, `HmacUtilities`, `ImageUrlSigner` and `ImageTagHelper` (`oi-width`, `oi-format` and so on; it adds the token itself). Tokens are not interchangeable with ImageSharp.Web's; regenerate signed URLs. A request that needs a token and lacks one gets 403. |
| `OnParseCommandsAsync`, `OnBeforeSaveAsync`, `OnProcessedAsync`, `OnPrepareResponseAsync`; custom `IImageWebProcessor` | The same four hooks (`OnBeforeLoadAsync` and `OnComputeHMAC` are not offered). A custom processor becomes work on the lazy `Image` in `OnBeforeSaveAsync`. |

Cloud storage providers (Azure Blob, AWS S3) and cache are not in the 3.2.0 package; they ship as separate ImageSharp.Web provider packages, which this comparison did not check.

### Formats: not planned

ImageSharp reads and writes more formats than OneImage. We are not working on these and are not promising them.

| ImageSharp | OneImage today |
|---|---|
| `TgaDecoder` / `TgaEncoder` (TGA) | Not supported. |
| `PbmDecoder` / `PbmEncoder` (PBM, PGM, PPM, PFM) | Not supported. |
| `QoiDecoder` / `QoiEncoder` (QOI) | Not supported. |

OneImage reads and writes PNG, JPEG, WebP, GIF, TIFF, BMP and ICO. ImageSharp 3.1.12 has no CUR support, so there is nothing to port there. Formats neither library has (AVIF, JPEG XL, HEIC, camera RAW) are listed on the [comparison page](https://recursiveai.org/oneimage/docs/comparison/#where-the-others-are-the-better-fit). PSD and PSB ([psd.md](https://recursiveai.org/oneimage/docs/psd/)), SVG ([svg.md](https://recursiveai.org/oneimage/docs/svg/)) and PDF ([pdf.md](https://recursiveai.org/oneimage/docs/pdf/)) are not in ImageSharp; OneImage reads them through its add-on packages.

### Programming model

| ImageSharp | OneImage today | Closest workaround |
|---|---|---|
| `IImageProcessor` and `ApplyProcessors` plug-ins | No public processor interface. | Transform pixels after `ToArray`, or write into a `Canvas`. |
| `ProcessPixelRows`, `ProcessPixelRowsAsVector4`, `PixelRowOperation` | No row-callback API. | `Canvas.Lock` gives row spans. |
| Typed IPTC and XMP editing (`IptcProfile`, `XmpProfile`) | The blobs are kept and can be stripped; they cannot be edited tag by tag. | Edit the blob with another tool. |
| Pixel types beyond OneImage's list (`Bgra32`, `Argb32`, `Bgr24`, `NormalizedByte4`, `Short4`, `HalfVector4`, ...) | `Rgb24`, `Rgba32`, `Rgb48`, `Rgba64`, `RgbaHalf`, `RgbFloat`, `RgbaFloat`, `Gray8`, `Gray16`, `GrayFloat`, `GrayAlpha8`. | Convert at the edge with `CopyPixelsTo<T>`. |

### Not in ImageSharp

Layers, masks and groups with Photoshop blend modes, PSD, and vector formats are not in ImageSharp. OneImage has them: [layers](https://recursiveai.org/oneimage/docs/layers/) in the core package, PSD and PSB in [OneImage.Psd](https://recursiveai.org/oneimage/docs/psd/), SVG in [OneImage.Svg](https://recursiveai.org/oneimage/docs/svg/) and PDF pages in [OneImage.Pdf](https://recursiveai.org/oneimage/docs/pdf/).

## Drawing shapes

Filling and stroking shapes with a solid color, a brush or a pen maps closely to ImageSharp.Drawing; the names and the differences (default fill rule, non-anti-aliased edge rule, pixel-coordinate conventions, strokes landing half a pixel from ImageSharp's) are in [drawing.md](https://recursiveai.org/oneimage/docs/drawing/). Gradient, pattern, image and recolor brushes are described in [drawing.md](https://recursiveai.org/oneimage/docs/drawing/#brushes). Clipping and boolean operations on paths are in [drawing.md](https://recursiveai.org/oneimage/docs/drawing/#boolean-operations-and-clipping); text is in [text.md](https://recursiveai.org/oneimage/docs/text/).


<!-- https://recursiveai.org/oneimage/docs/comparison/ -->

# Comparison

How OneImage compares with the four libraries most .NET projects reach
for: ImageSharp, SkiaSharp, Magick.NET and NetVips. It says where
OneImage is the better fit and where one of them is.

**Versions.** Checked on 2026-10-22 against ImageSharp 3.1.12 (the last
release that builds without a license key, and the one used in our
benchmarks), SkiaSharp 4.153.1, Magick.NET-Q8-AnyCPU 15.0.0, and NetVips
3.2.0 with libvips 8.18.7. Details of the other libraries come from their
own documentation and from using them in our tests; they change, so
check theirs before you decide. Performance numbers are on the
[performance page](https://recursiveai.org/oneimage/docs/performance/).

## What each library is

- **OneImage** is pure managed C# with no dependency beyond the .NET base
  class library. `Image` is a lazy, immutable description of a pipeline,
  computed in 128×128 tiles; `Canvas` is a mutable tiled surface.
  Licensed MIT OR Apache-2.0.
- **ImageSharp** is pure managed C#. It decodes eagerly into an
  `Image<TPixel>` and edits it with `Mutate`. Its license is Six Labors'
  Split License: free for open source and small companies, a paid
  commercial license otherwise.
- **SkiaSharp** wraps Google's Skia graphics library: a 2D drawing
  engine with paths, text and GPU backends, whose image codecs come with
  it. MIT for the wrapper; Skia is BSD-licensed.
- **Magick.NET** wraps ImageMagick: very broad format support and a very
  large operation set. Apache-2.0 for the wrapper; ImageMagick has its
  own permissive license.
- **NetVips** wraps libvips, a demand-driven, streaming image library
  written in C. MIT for the wrapper; libvips is LGPL 2.1 or later,
  shipped as a native binary.

## Like with like

| | OneImage | ImageSharp | SkiaSharp | Magick.NET | NetVips |
|---|---|---|---|---|---|
| Native dependency | none | none | native Skia per platform | native ImageMagick per platform | native libvips per platform |
| Evaluation | lazy, tiled, streaming | eager | eager | eager | lazy, streaming |
| Pixel type in the API | one `Image`, runtime format | `Image<TPixel>` | `SKBitmap` / `SKImage` | `MagickImage` | `Image` |
| Formats we use it for | PNG, JPEG, WebP, GIF, TIFF, BMP, ICO | JPEG, PNG, GIF, BMP, TIFF, WebP and a few more | JPEG, PNG, WebP, GIF, BMP decode, more through Skia | well over a hundred | what your libvips build includes |
| ICC color management | ICC v2/v4 profiles, CMYK to sRGB, four intents | did not convert in our CMYK task | color spaces via Skia | LittleCMS | LittleCMS |
| NativeAOT and trimming | supported, checked in CI | see its documentation | see its documentation | see its documentation | see its documentation |
| Drawing, text, vectors | paths, brushes, strokes and layers in the core package; text in the separate OneImage.Text package | via the separate Drawing and Fonts packages | yes, a drawing engine | yes | limited |
| Thumbnail a large JPEG | decodes at reduced scale, bounded memory | decodes with a target size | scaled decode | `jpeg:size` hint | `thumbnail` shrink-on-load |

Notes on the table:

- **Streaming and memory.** OneImage and NetVips both compute only what
  the output needs. In our thumbnail rows OneImage's peak working memory
  is a few MiB, and NetVips's measured peak is tens of MiB. The numbers
  are on the [performance page](https://recursiveai.org/oneimage/docs/performance/).
- **ICC.** In our CMYK JPEG task OneImage, NetVips and Magick.NET apply
  the embedded profile, and ImageSharp's `Load` does not convert it, so
  its output is far from the ICC-correct reference. The page shows the
  color error for each library.
- **Native dependencies** mean a package per platform and architecture,
  and a native library in your attack surface and your deployment. They
  also mean decades of optimization and format coverage.

## Where OneImage is the better fit

- You want one package with no native binaries: serverless, containers
  without a libc story, trimmed or NativeAOT apps, or places where
  shipping a native library is a review problem.
- You open files you did not write and want the parsers to be managed,
  bounds-checked code with limits on by default (see
  [limits](https://recursiveai.org/oneimage/docs/guide/#limits)).
- You want thumbnails that are fast and small in memory, with EXIF
  orientation applied and GPS stripped by default.
- You want a permissive license without a commercial tier.
- You want both one-line batch work and an editable tiled surface
  (`Canvas`) on the same engine.

## Where the others are the better fit

- **NetVips is faster when you can use every core.** It is ahead of
  OneImage on multi-page TIFF reads (about 3× at OneImage's default
  per-call thread limit, about 1.8× with the limit raised to all
  cores), on JPEG encoding (1.58×) and on one PNG encode input. If raw
  throughput on a many-core machine matters more than avoiding a native
  dependency, use NetVips. Its dedicated resize is also ahead of ours
  when downscaling an already decoded image.
- **Magick.NET covers far more formats and operations.** If you need
  HEIC, AVIF, JPEG XL, JPEG 2000 or camera RAW input,
  or ImageMagick's long tail of operations, OneImage does not have it.
  OneImage reads and writes PNG, JPEG, WebP, GIF, TIFF, BMP and ICO; PSD
  and PSB ([OneImage.Psd](https://recursiveai.org/oneimage/docs/psd/)), PDF ([OneImage.Pdf](https://recursiveai.org/oneimage/docs/pdf/)) and SVG
  ([OneImage.Svg](https://recursiveai.org/oneimage/docs/svg/)) come as add-on packages.
- **SkiaSharp is a drawing engine.** Paths, text, gradients, GPU
  surfaces and UI integration are Skia's job. OneImage has vector
  [drawing](https://recursiveai.org/oneimage/docs/drawing/) and [layers](https://recursiveai.org/oneimage/docs/layers/) in the core package and
  text in [OneImage.Text](https://recursiveai.org/oneimage/docs/text/). SkiaSharp also decodes
  our 50-frame GIF test in less than half the time.
- **ImageSharp has a larger ecosystem of processors and a longer
  record,** and its Drawing and Fonts packages cover shapes, gradients and text, including complex-script shaping and right-to-left layout. If
  your license situation is fine and you rely on those, staying is
  reasonable. The [migration guide](https://recursiveai.org/oneimage/docs/migrating/) shows the differences
  if you decide to move.
- **You target a framework other than .NET 10.** OneImage runs on
  `net10.0` only. The others support older frameworks.
- **You need ARM64 performance numbers or a long field record.** OneImage
  is checked for correctness on ARM64 but has no published ARM64
  timings, and it is new.

## Not in OneImage yet

Compared with ImageSharp 3.1.12 and its Drawing 2.1.7, Fonts 2.1.3 and Web 3.2.0 packages (the last releases that build without a license key), OneImage does not have yet:

- **Effects:** the public integral image (`CalculateIntegralImage`). Coming soon.
- **Formats:** TGA, PBM and QOI. Not planned.

Coming soon means planned, without a date. The [full list](https://recursiveai.org/oneimage/docs/migrating/#not-in-oneimage-yet) has the exact ImageSharp APIs and what to use in the meantime.

## Choosing

- Thumbnails, crops and conversions for the web, in a service, with no
  native dependencies: OneImage.
- Maximum throughput on many cores and you can ship libvips: NetVips.
- Many formats, or a long tail of operations: Magick.NET.
- Drawing, text, GPU or a UI toolkit: SkiaSharp.
- An existing ImageSharp codebase that works for you: stay, and look at
  the [migration guide](https://recursiveai.org/oneimage/docs/migrating/) when that changes.


<!-- https://recursiveai.org/oneimage/docs/performance/ -->

# Performance

OneImage is faster than ImageSharp 3.1.12 on every task in the benchmark
set except one that is a tie, and one where ImageSharp does less work
(CMYK, below). It is not faster than every native wrapper, and on peak
memory it has one exception and several ties. Drawing and clipping
against ImageSharp.Drawing have one exception of their own
([below](#drawing-and-clipping-exceptions)), and flattening a layered
document at the default thread limit has another
([below](#layer-flatten-exception)). This page prints all of
it: the table, the ties, the losses and the method.

Every number here comes from the reports in
[`bench/results/`](https://github.com/recursive-ai-oss/oneimage-csharp/tree/main/bench/results),
measured on a shared workstation (see [Method](#method)). Treat them as
local measurements, not as promises for your hardware.

## Results at a glance

Time is the BenchmarkDotNet mean for one operation, in milliseconds.
Peak is the growth of the process's resident set during the operation,
in MiB, as the median of three runs with the run-to-run spread (max −
min) in brackets. A time within 5% of ImageSharp's is a tie. Native
wrappers are SkiaSharp (`skia`), NetVips (`netvips`) and Magick.NET
(`magick`) through their .NET packages; the column shows the fastest of
the three.

One OneImage row per task is shown: its fastest idiomatic one-call path
to the stated output, writing into a caller buffer where the competitors
reuse pooled storage. Every row of every library is in the raw reports.

![Bar chart: how many times faster OneImage is than ImageSharp on each task, log scale, higher is better; ties and slower tasks are marked.](https://recursiveai.org/oneimage/docs/img/oneimage-hero-light.svg)

The chart is drawn from the same table by
[`tools/make-hero-chart.py`](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/tools/make-hero-chart.py).
Ratios there come from the unrounded report values, so they can differ
in the last digit from a division of the rounded milliseconds below.

| Task | OneImage ms | ImageSharp ms | Time vs ImageSharp | Fastest native wrapper | OneImage time ÷ fastest native | Peak MiB: OneImage | Peak: ImageSharp | Peak: NetVips | Peak vs ImageSharp |
|---|--:|--:|---|---|--:|--:|--:|--:|---|
| thumb-jpeg | 37.5 | 47.0 | 1.25× faster | magick 40.3 | 0.93× | 2.2 (±0.2) | 1.2 (±0.1) | 64.4 | **higher** (exception) |
| thumb-webp | 46.9 | 65.4 | 1.39× faster | magick 46.0 | 1.02× | 3.0 (±0.1) | 9.5 (±0.1) | 64.2 | lower |
| png-to-webp (natural) | 79.1 | 1511.5 | 19.11× faster | netvips 155.1 | 0.51× | 41.9 (±4.0) | 86.8 (±1.4) | 121.6 | lower |
| png-to-webp (photo) | 90.5 | 1025.2 | 11.33× faster | magick 157.6 | 0.57× | 41.9 (±4.0) | 86.8 (±1.4) | 121.6 | lower |
| png-to-webp (screenshot) | 95.8 | 236.5 | 2.47× faster | magick 162.3 | 0.59× | 41.9 (±4.0) | 86.8 (±1.4) | 121.6 | lower |
| jpeg-decode | 41.2 | 77.2 | 1.87× faster | netvips 102.3 | 0.40× | 0.5 (±0.0) | 3.5 (±0.1) | 360.6 | lower |
| jpeg-encode | 87.4 | 100.6 | 1.15× faster | netvips 55.3 | 1.58× | 5.3 (±3.2) | 4.1 (±0.8) | 67.3 | tie (within the run-to-run spread) |
| png-decode (natural) | 11.4 | 39.1 | 3.43× faster | skia 19.6 | 0.58× | 0.2 (±0.1) | 0.3 (±0.0) | 90.3 | lower |
| png-decode (photo) | 18.3 | 22.2 | 1.21× faster | skia 21.9 | 0.83× | 0.2 (±0.1) | 0.3 (±0.0) | 90.3 | lower |
| png-decode (screenshot) | 2.9 | 4.2 | 1.45× faster | skia 4.2 | 0.71× | 0.2 (±0.1) | 0.3 (±0.0) | 90.3 | lower |
| png-encode (natural) | 219.6 | 1064.3 | 4.85× faster | netvips 96.0 | 2.29× | 11.2 (±1.1) | 33.6 (±0.6) | 24.1 | lower |
| png-encode (photo) | 52.3 | 318.6 | 6.09× faster | netvips 96.7 | 0.54× | 11.2 (±1.1) | 33.6 (±0.6) | 24.1 | lower |
| png-encode (screenshot) | 50.8 | 95.0 | 1.87× faster | netvips 39.8 | 1.27× | 11.2 (±1.1) | 33.6 (±0.6) | 24.1 | lower |
| webp-decode (lossy) | 16.9 | 31.0 | 1.83× faster | skia 17.9 | 0.94× | 2.3 (±0.3) | 2.9 (±0.1) | 162.8 | lower |
| webp-decode (lossless) | 24.9 | 68.2 | 2.74× faster | skia 35.0 | 0.71× | 2.3 (±0.3) | 2.9 (±0.1) | 162.8 | lower |
| webp-encode (lossless-2000x1500) | 146.8 | 1107.1 | 7.54× faster | skia 101.4 | 1.45× | 24.2 (±0.5) | 97.1 (±0.7) | 73.1 | lower |
| webp-encode (lossy-2000x1500) | 101.6 | 590.5 | 5.81× faster | magick 162.3 | 0.63× | 24.2 (±0.5) | 97.1 (±0.7) | 73.1 | lower |
| webp-encode (lossy-400x300) | 5.4 | 23.7 | 4.39× faster | magick 7.0 | 0.76× | 24.2 (±0.5) | 97.1 (±0.7) | 73.1 | lower |
| gif-decode | 2.3 | 6.1 | 2.65× faster | skia 1.0 | 2.23× | 0.3 (±0.0) | 0.4 (±0.0) | - | lower |
| gif-encode | 13.3 | 16.8 | 1.26× faster | magick 70.3 | 0.19× | 1.2 (±0.1) | 2.0 (±1.1) | - | lower |
| gif-resize | 40.4 | 47.1 | 1.17× faster | magick 802.4 | 0.05× | 2.4 (±0.3) | 2.6 (±0.0) | 81.6 | lower |
| tiff-multipage-decode | 52.3 | 620.3 | 11.87× faster | netvips 26.6 | 1.96× | 2.5 (±0.2) | 54.7 (±0.1) | 85.1 | lower |
| tiff-encode | 44.4 | 134.6 | 3.03× faster | magick 68.5 | 0.65× | 28.5 (±0.3) | 32.1 (±0.6) | 40.3 | lower |
| bmp-decode | 0.4 | 0.7 | 1.75× faster | skia 1.2 | 0.32× | 0.1 (±0.0) | 0.1 (±0.0) | - | tie |
| bmp-encode | 2.8 | 4.9 | 1.75× faster | magick 7.1 | 0.39× | 7.0 (±0.4) | 21.6 (±0.8) | - | lower |
| upscale-2x | 6.3 | 12.3 | 1.95× faster | netvips 9.7 | 0.64× | 0.5 (±0.1) | 0.5 (±0.1) | 40.7 | tie |
| watermark | 4.9 | 4.9 | tie | netvips 61.9 | 0.08× | 0.3 (±0.0) | 0.5 (±0.1) | 183.8 | lower |
| cmyk-jpeg-to-srgb | 243.4 | 148.3 | 1.64× slower (ImageSharp skips the ICC conversion) | netvips 252.0 | 0.97× | 2.2 (±0.4) | 1.3 (±0.1) | 441.1 | higher (ImageSharp skips the ICC conversion) |
| jpeg-decode-rgba | 43.4 | 79.4 | 1.83× faster | skia 146.4 | 0.30× | 0.5 (±0.0) | 0.7 (±0.1) | - | lower |

### Reading the table

- **Ties are ties.** bmp-decode and upscale-2x are ties on peak memory
  (0.1 vs 0.1 MiB and 0.5 vs 0.5 MiB, both within their spreads).
  watermark is a tie on time (4.9 ms against 4.9 ms). Neither is a win.
- **jpeg-encode peak is a tie within its spread.** OneImage 5.3 MiB
  (spread ±3.2) against ImageSharp 4.1 MiB (spread ±0.8): the 1.2 MiB
  difference is smaller than OneImage's own run-to-run spread. The
  gate report's stricter 5% rule lists it as a miss; we do not call it a
  win, and we do not claim it is lower. Time is a win, 87.4 against
  100.6 ms.
- **The one exception: thumb-jpeg uses 1.0 MiB more peak working memory
  than ImageSharp, 2.2 vs 1.2 MiB.** The time is a win. The gap is about
  1 MiB; five repeats before the last changes gave the same 1.5–2.5 MiB
  range, so it is not new. Both are tiny next to NetVips's 64 MiB for the
  same task.
- **CMYK JPEG to sRGB is slower than ImageSharp, and that comparison is
  not like for like.** ImageSharp does not apply the embedded ICC
  profile; OneImage, NetVips and Magick.NET do. The fair bar is the
  libraries that convert: OneImage (243.4 ms, 2.2 MiB peak) is faster
  than NetVips (252.0 ms, 441.1 MiB) and Magick.NET (1015.9 ms,
  159 MiB). The colour error shows what skipping the conversion costs:
  mean CIEDE2000 against an ICC-correct reference is 0.190 for
  OneImage, 0.885 for NetVips, 0.889 for Magick.NET, 0.909 for
  SkiaSharp and 11.329 for ImageSharp (max 27.193).

  OneImage's number is lower than the others' because it applies black
  point compensation by default, as Photoshop does; the others do not
  unless asked. Against the LittleCMS result (Magick.NET) it sits 0.935
  mean / 2.764 max ΔE00 away by default and 0.062 / 1.443 with
  `blackPointCompensation: false`.
- **Peak memory** is the table's last column. OneImage is lower than
  ImageSharp on every task except the ones named above (ties,
  jpeg-encode, thumb-jpeg and the CMYK row), and far below NetVips's on
  every streaming task.

## Where OneImage is slower than a native wrapper

The gate asks for thumbnail and codec tasks within 1.5× of the fastest
native wrapper. These are the rows that are not:

| Task | OneImage | Fastest | Ratio |
|---|--:|---|--:|
| tiff-multipage-decode, default degree | 52.3 ms | netvips 26.6 ms | 1.96× |
| png-encode (natural) | 219.6 ms | netvips 96.0 ms | 2.29× |
| gif-decode | 2.3 ms | skia 1.0 ms | 2.23× |
| jpeg-encode | 87.4 ms | netvips 55.3 ms | 1.58× |

Notes:

- **TIFF multi-page.** OneImage limits a single call to min(4, cores)
  threads by default, so a server does not oversubscribe its cores;
  NetVips uses every core. With the per-call degree raised the same read
  takes 51.4 ms at 8 threads and 46.5 ms on all cores (1.93× and 1.75×
  NetVips). The raised rows are shown for information; the default row is
  the one that counts. The 10 strips of a page are the units of parallel
  work (an LZW stream cannot be split), so four threads need three rounds
  per page and more than ten cannot help. Each strip costs about 1.3 ms of
  LZW decoding and 0.06 ms of predictor undo, and a copy-out of about 0.25
  ms per strip comes on top.
  The row and these figures were re-measured on the worker after the LZW
  and predictor work (only these rows; the peak columns are from the
  earlier full run). Same worker, same configuration, baseline and new
  build alternated three times under load 2 to 11 from other jobs: the
  gate row went from 60.3 to 54.6 ms (means; best runs 59.3 and 51.4 ms).
  On a local run of the same two builds (another job was running) the read went from 188 to
  160 ms at one thread and from 61 to 51 ms at four. The gap to NetVips is
  still about 2×; the floor is LZW decoding in safe code.
  **Direct whole-frame read.** A whole-frame read of a TIFF of 1 Mpixel or more
  (`CopyPixelsTo`, `ToArray`) no longer goes through 128×128 tiles: strips and
  tiles are handed out one at a time to the call's threads, each decoded into
  pooled memory and converted row by row straight into its own part of the
  caller's buffer, so the pixels are copied once instead of three times (block,
  band, tile, caller). Output is byte-identical (hash-compared over the test
  corpora at degrees 1, 4 and 16, with AVX2 and all intrinsics off). Same worker
  (Ryzen 9 7950X3D, 32 logical cores, .NET 10.0.13, AVX-512 off), before and
  after, one run each, other jobs on the host raised the load to 4-5 during the
  "after" run: the gate row 49.9 → 46.9 ms and allocation 965 → 92 KB; with the
  per-call degree raised to 8 42.7 → 32.0 ms, and to all cores 46.9 → 27.1 ms
  (NetVips 26.3 ms on all cores). At the default degree the 10 strips of a page
  still need three rounds, so the LZW decode, not the copy, sets the time.
  Reads under 1 Mpixel, region reads and frames whose strip is over 16 MiB of
  raw samples keep the tile path, which caches blocks for later reads.
- **Resize.** The thumbnail rows are where resize cost shows: thumb-jpeg
  is 37.5 ms against NetVips's 49.5 ms and thumb-webp 46.9 against 55.1,
  and 2× upscale is 6.3 ms against 9.7 ms. Those rows are decode-bound (the
  resize runs on a 1/8-size decode). A downscale of an already decoded
  24 MP RGBA image is where NetVips's dedicated resize is ahead. Measured on
  the worker at the default degree of 4 (AVX2, minimum of 40 runs, load 4-7;
  base and new alternated three times): 24 MP to 400 px went from 11.5 to
  8.8 ms, a 3× reduction (6000 to 2000) from 30.0 to 25.3 ms and a 2×
  upscale from 5.35 to 4.85 ms. NetVips measured 6.2-7.4 ms and 17.5-18.1 ms
  on the first two with every core, so the gap that remains is 1.2-1.5×;
  it comes from the per-call degree, not from CPU time (a local count shows
  NetVips using about as much CPU as we do on the first row and 2.5× as much
  on the second). The `resize` benchmark category
  (`--anyCategories resize`) runs these rows.
- **png-encode.** Only the natural-content input is beyond 1.5×; the
  photo and screenshot inputs take 0.54× and 1.27× of NetVips's time.
- **gif-decode** is 1.3 ms behind SkiaSharp on a 50-frame 500×500 file.
- **jpeg-encode** uses optimized Huffman tables by default (smaller
  files), which costs extra work. The gap to NetVips shrank from
  2.72× to 1.58× after the last fixes and is a goal, not a gate; the
  encoder pass described under "JPEG encode pass" closed it (0.96×).

## JPEG entropy decoding

The thumbnail row is bound by Huffman decoding, which cannot be spread
over cores without restart markers. The decoder resolves most AC symbols
(code and magnitude bits) with one lookup in a 12-bit table, refills its
bit buffer once per symbol without branching on the fill level, and skips
the AC data of any component that only contributes its DC coefficient at
the requested scale (at 1/8 of a 4:2:0 image that is the luma, two thirds
of the blocks). Output is byte-identical to the earlier decoder.

Same code, same worker (Ryzen 9 7950X3D, 32 logical CPUs, .NET 10.0.402,
AVX-512 off, shared with other jobs: load ranged from 1.4 to 12 over
the four runs, so read the differences, not the digits).
Gate harness rows, mean ms:

| Task | Before | After | ImageSharp (same run) | Peak MiB before → after (ImageSharp) |
|---|--:|--:|--:|--:|
| thumb-jpeg | 38.5 / 40.0 | 28.2 / 27.3 | 47.4-49.5 | 2.3 → 2.4 (1.3) |
| jpeg-decode | 56.6* / 44.8 | 58.7* / 42.2 | 80.1-119.5 | 0.5 → 0.7 (3.6) |
| jpeg-decode-rgba | 44.9 / 47.0 | 98.2* / 44.5 | 86.7-112.4 | 0.5 → 0.6 (0.7) |
| cmyk-jpeg-to-srgb | 235.8 / 275.8 | 243.9 / 303.0 | 149.7-200.0 (skips ICC) | 2.0 → 2.1 (1.3) |
| tiff-multipage-decode | 138.8* / 73.6 | 71.5 / 87.3 | 591.6-637.9 | 1.8 → 2.0 (54.8) |

Each cell shows two runs; * marks a run during a load spike that moved
ImageSharp's row by the same factor. The rows other than thumb-jpeg do
not change beyond that spread: full-size 4:2:0 decoding was bound by the
transform thread (about 38 ms for 24 MP), not by Huffman decoding (see
the next section). The
thumb-jpeg peak stays the published exception (about 1 MiB over
ImageSharp). Decoder only on a desktop host (one core for entropy decoding plus
the transform thread, best of 30, a 6000x4000 4:2:0 file of 5.8 MB): 1/8 scale 38.6 to 28.3 ms, and the
scan decoder is the whole of that time in both (37.9 and 28.4 ms inside
the decoder); 24 MP CMYK file of 16.5 MB, full size 111 to 90 ms.
Progressive full-size decoding stays dominated by refinement scans
(about 205 ms for a noisy 24 MP file against 218 before).

## JPEG encode pass

Encoding got faster with byte-identical output (the same bytes at
degrees 1, 4 and 16, with AVX-512 off, AVX2 off and intrinsics off, for
quality 30/75/90/100 × 4:4:4/4:2:2/4:2:0/4:4:0/gray × optimized/standard
tables × baseline/progressive, at 0.1 MP and 4.6 MP).

- RGB to YCbCr is an SSSE3/SSE4.1 multiply-add kernel and the chroma
  averaging is portable 128-bit code, each with its scalar loop as the
  reference. Quantized blocks are put into zigzag order by placing only
  the non-zero values.
- Without restart markers, every worker takes the next MCU row and does
  all its work (convert, downsample, transform, count or code), so
  there is no barrier between stages. Symbol counts, including the DC
  differences across row boundaries, are gathered in the same pass that
  transforms. When coding, a row needs only the last DC of the row
  before it, which its owner publishes right after quantizing. Finished
  rows are appended to the output in order by whichever worker is free.
  Memory is the same as before: the per-worker row buffers and one tile
  row of pixels.

Measured on the worker (Ryzen 9 7950X3D, 32 logical CPUs, .NET 10.0.13,
AVX-512 off, default degree 4, load 1.0-5.0 before, during and after
both runs, no other benchmark running):

| Row | Before | After | ImageSharp 3.1.12 | NetVips |
|---|---|---|---|---|
| jpeg-encode 24 MP q90 4:2:0, optimized (BenchmarkDotNet) | 82.8 ms | 51.7 ms | 101.7 ms | 53.3 ms |
| same, standard tables | 46.4 ms | 30.7 ms | | |
| gate report jpeg-encode | 86.8 ms | 50.4 ms | 101.0 ms | 52.4 ms |
| gate peak working memory | 4.9 (±1.4) MiB | 3.1 (±0.9) MiB | 4.1 (±1.3) MiB | |
| 3 MP q90 4:2:0, optimized | 7.31 ms | 5.18 ms | 15.8 ms | 7.56 ms |

## JPEG full-size transform split

Full-size decoding of a sequential 4:2:0 file was bound by one thread
doing inverse DCT, chroma upsampling, color conversion and sink writes
(about 38 ms of 24 MP) while entropy decoding took 31. The transform is
now two stages, each on its own thread beside the entropy decoder, with
four plane-ring slots so a row is transformed while its predecessor is
emitted. Per-call thread use rises from two to three (one more with
three or more cores); on two cores the entropy thread does the inverse
DCT. Output is byte-identical at every stage count, scale, region and
hardware level (SHA-256 over the test corpus plus generated 4:2:0, 4:2:2,
4:4:0, 4:4:4 and progressive files at 1, 1/2, 1/4, 1/8, with and without
hardware intrinsics).

Desktop host, 6000x4000 file, best of 20 into a null sink, AVX2 only:

| File | One thread | Entropy + transform+emit | Three threads |
|---|--:|--:|--:|
| 4:2:0 q90, 8.9 MB | 78 ms | 64 ms | 43 ms (was 43) |
| 4:4:4 q90, 9.4 MB | 94 ms | 82 ms | 55 ms (was 53) |
| 4:2:0 q90, 2.1 MB (smooth) | 50 ms | 35 ms | 20 ms (was 34) |
| 4:4:4, 2.1 MB (smooth) | 62 ms | 55 ms | 31 ms (was 39) |

Noisy photographs are entropy-bound (43 ms is the Huffman time), so the
split helps where the transform was the longer stage: images with fewer
bits per pixel, which includes most web photographs. Progressive files
are bound by their coefficient scans (110-280 ms) and move by under 5%.

Worker rows (Ryzen 9 7950X3D, 32 logical CPUs, .NET 10.0.402 SDK with
runtime 10.0.13, AVX-512 off, shared: load 1.2 to 5), mean ms, two paired
runs of before / after, ImageSharp alongside:

| Task | Before | After | ImageSharp |
|---|--:|--:|--:|
| jpeg-decode | 55.2 / 43.8 | 31.8 / 31.7 | 81.7-97.1 |
| jpeg-decode-rgba | 55.8 / 44.9 | 31.3 / 33.2 | 86.9-97.8 |
| thumb-jpeg | 34.8 / 27.7 | 27.6 / 29.3 | 47.8-50.1 |
| cmyk-jpeg-to-srgb | 419* / 257 / 237 / 274 | 262* / 291 / 252 / 255 | 150-157 (skips ICC) |
| tiff-multipage-decode | 93.8 / 60.2 | 78 / 118 / 61.5 / 60.1 | 599-735 |

* a run under load above 6 that moved ImageSharp by the same factor.
The thumb-jpeg, CMYK and TIFF rows do not use the split path or do not
change beyond their spread; peaks are unchanged (jpeg-decode 1 MiB,
cmyk 2 MiB, thumb-jpeg 2 MiB).

## JPEG restart intervals

Baseline JPEGs that carry restart markers (many cameras and phones write one interval per MCU row) are entropy-decoded on several threads. Each restart interval starts with fresh DC predictors and a flushed bit buffer, so whole intervals decode independently: the calling thread cuts the compressed scan into work units of whole intervals (about one MCU row each), workers decode them into a deeper coefficient ring, and finished units are handed on as complete MCU rows, in order. The worker count is the per-call degree (default min(4, cores)). Only sequential single-scan Huffman files of 1 MP or more with at least two work units take this path; files without restart markers, progressive and arithmetic files, and files whose intervals are few and huge decode as before, at the same speed.

The output is identical to the single-threaded decoder at every scale, degree and hardware path. A damaged file behaves the same too: a worker runs the same per-MCU loop over the same bytes, and when a unit fails the rows before the failing MCU are delivered first and the earliest failure is the one thrown, so a request that those rows complete still succeeds. Peak working memory grows by the deeper ring (about 3.5 MB for a 6000-pixel-wide 4:2:0 frame; the ring is capped at 16 MiB) plus the compressed bytes of the units in flight.

Measured on the shared worker (Ryzen 9 7950X3D, 32 logical CPUs, .NET 10.0.402, `DOTNET_EnableAVX512=0`, default degree 4; machine load 1-4 around the runs, no other benchmark running during the runs). A 24 MP 4:2:0 q90 file written by this library with restart interval 375 (one MCU row) and the same picture without restarts, BenchmarkDotNet mean (allocated):

| Row | no restarts, before | no restarts, after | restarts, before | restarts, after | ImageSharp 3.1.12 | NetVips |
|---|---|---|---|---|---|---|
| full size, caller's Rgb24 buffer | 31.8 ms (52 KB) | 32.4 ms (52 KB) | 32.3 ms | **25.5 ms** (54 KB) | 79.2 ms | 98.0 ms |
| 1/8 (`Resize(750)`) | 27.4 ms (1147 KB) | 27.3 ms | 27.0 ms | **9.0 ms** (1150 KB) | 46.6 ms (TargetSize) | 38.9 ms (shrink=8) |
| thumbnail 400 px | 27.8 ms (360 KB) | 27.6 ms | 27.1 ms | **9.0 ms** (376 KB) | | |

The gate rows are unchanged (their files have no restart markers): jpeg-decode 32.2 vs 32.7 ms, jpeg-decode-rgba 32.4 vs 32.0 ms, thumb-jpeg 27.6 vs 27.5 ms. At full size the decode is now bound by the transform and delivery threads (about 24 ms), not by entropy decoding, so scales 1/2 and 1/4, which are transform-bound, do not change. The "before" runs started at load 3.9 (falling to 1.6) and the "after" runs at load 1.0; the two share the same machine and settings but not the same minute.

## Progressive JPEG decoding

Progressive JPEGs (common on the web) used to decode several times slower than
baseline ones, because their refinement scans were read one coefficient at a
time. Two changes, both with output identical to before at every scale, degree
and hardware path (984 decodes hashed per setting: default, AVX2 off,
intrinsics off):

- Refinement scans keep a 64-bit mask of the nonzero positions of each block, so
  the correction bits between two symbols are read at once and applied without
  branches. The coefficient-by-coefficient reader stays as the reference.
- The scans of a progressive Huffman file of 1 MP or more decode side by side,
  each with its own reader, waiting only for the rows of earlier scans that touch
  the same coefficients; finished rows go to the transform while the last scan
  is still running. Errors are ranked by scan order, so a damaged file fails
  with the same exception as before, though it may deliver some rows first.

Measured on the worker (Ryzen 9 7950X3D, 32 logical CPUs, .NET 10.0.13,
`DOTNET_EnableAVX512=0`, default degree 4, load 0.4 to 1.6), 24 MP files:

| Row | Before | After | ImageSharp 3.1.12 | NetVips |
|---|--:|--:|--:|--:|
| noisy, full size | 389.0 ms | 68.5 ms | 432.0 ms | 404.2 ms |
| smooth, full size | 199.0 ms | 62.3 ms | 209.7 ms | 257.4 ms |
| noisy, 1/8 scale | 38.5 ms | 12.8 ms | 396.8 ms | 335.8 ms |
| smooth, 1/8 scale | 35.1 ms | 12.7 ms | 182.7 ms | 185.0 ms |

Baseline rows are unchanged (jpeg-decode 32.5 to 31.8 ms, thumb-jpeg 27.3 to
26.8 ms). The last luma refinement scan is now the critical path.

## WebP encode memory

The lossy encoder held a 4-bytes-per-pixel copy of the frame, whole source
and reconstructed YUV planes, and every macroblock's 400 quantized levels
(800 bytes) until the file was written, and joined its output through
several doubling buffers. It now keeps:

- the source YUV planes (1.5 bytes per pixel), filled strip by strip from
  the frame, so no RGBA copy exists (alpha, one byte per pixel, is gathered
  only if some pixel is translucent);
- for reconstruction, the last pixel line of each finished macroblock row
  plus each worker's current row, not whole planes;
- the levels in a compact per-row form (a count per block, then zigzag
  variable-length values), about a quarter of their size on a noisy photograph,
  released row by row while the tokens are written;
- partitions written in 64 KiB chunks and joined once into the frame, and the
  file written to the destination chunk by chunk.

The lossless encoder packs its 32-bit pixels band by band instead of via an
RGBA copy of the frame. Output bytes are unchanged: 498 SHA-256 hashes of
lossy (q50/75/90, effort 0/4/6, RGB, RGBA opaque and translucent, degrees
1/4/16, four odd sizes), lossless (exact on and off) and animated encodes
match the previous build on default hardware, `DOTNET_EnableAVX512=0`,
`DOTNET_EnableAVX2=0` and `DOTNET_EnableHWIntrinsic=0`, and a 2000x1500
set matches too.

Peak working memory (the method below: peak resident minus resident before,
warmed up, median of three processes, spread in parentheses, competitors
two to three processes; the runs were on the development host, because the
worker was held by other benchmarks, and resident memory does not depend on
load). The `webp-encode-24mp` and `webp-encode-lossless-24mp` tasks of
`gate-peak` use a 6000x4000 plasma-and-noise image (the `webp-encode` input
at 24 MP); all rows are quality 75, effort 4:

| Task | Before | After | SkiaSharp | Magick.NET | NetVips | ImageSharp |
|---|--:|--:|--:|--:|--:|--:|
| webp-encode-24mp (lossy) | 303.5 MB (±1.0) | 101.6 MB (±6.5) | 86.3 (±0.5) | 173.6 (±1.0) | 241.0 (±14.5) | 1450 (±1) |
| webp-encode-lossless-24mp | 1055.8 MB (±2.4) | 377.1 MB (±1.0) | 663.4 (±1.2) | 736.5 (±1.8) | | |
| webp-encode (lossy-2000x1500) | 22.2 MB (±2.9) | 4.6 MB (±0.2) | 0.7 | 1.3 | 107.9 | 98.1 |
| png-to-webp (photo) | 43.4 MB (±1.5) | 22.6 MB (±4.9) | 38.3 | 26.0 | 203.7 | 87.6 |
| thumb-webp | 4.7 MB (±0.6) | 4.6 MB (±0.3) | 0.7 | 1.9 | 83.2 | 9.9 |

SkiaSharp and Magick.NET encode straight from the caller's pixel buffer; the
lossy encoder converts to YUV first, which is the 36 MB of planes at 24 MP.

### Lossless encoder state

The lossless encoder used to hold, at 24 MP, the packed pixels plus one
full-size copy for each transform (subtract green, predictor, cross-color), a
12-byte token for every pixel, a 4-byte hash-chain entry for every pixel, and
a bit-writer array that doubled and was then copied. Now:

- the transforms run in place on the packed pixels (the encoder owns them; a
  first plan at effort 5 and 6 works on a copy). The predictor reads its
  neighbors' original values from a private copy of its tile row plus the row
  above, so tile rows still run in any order;
- there is no token array: the token stream is the pixels with the matches cut
  out, so state grows with the number of matches. The color cache is simulated
  as the tokens are visited, once for each cache-size estimate and once for
  each of the counting and writing passes;
- hash chains are built a few bands at a time and only the last 2^20 entries
  are kept (about 13 MB at degree 4, 38 MB at degree 16), with the same entries
  as one whole-image chain;
- the size of the main token stream follows from the symbol counts and code
  lengths, so the output is written into one array of exactly its final size
  and returned without a copy.

Output bytes are unchanged: 1011 SHA-256 hashes of lossless encodes (photo-like
RGB and RGBA at 703x499, 256x256, 17x33, 1x1, 3x2 and 1024x700, palette images
of 2, 3, 12 and 200 colors, a repeating image and a 33x16000 one; effort 0 to
6, degrees 1/4/16, Exact on and off) plus the animated lossless encodes match
the previous build on default hardware, `DOTNET_EnableAVX512=0`,
`DOTNET_EnableAVX2=0` and `DOTNET_EnableHWIntrinsic=0`.

Peak working memory, gate-peak method (median of three processes, spread in
parentheses, AVX-512 off, on the development host; resident memory does not
depend on load). The 2000x1500 row is the new `webp-encode-lossless` task:

| Task | Before | After | SkiaSharp | Magick.NET |
|---|--:|--:|--:|--:|
| webp-encode-lossless-24mp | 851.7 MB (±0.9) | 377.1 MB (±1.0) | 663.4 (±1.2) | 736.5 (±1.8) |
| webp-encode-lossless (2000x1500) | 106.7 MB (±5.4) | 46.0 MB (±1.5) | 62.4 (±1.4) | 81.9 (±1.1) |

What is left at 24 MP is the packed pixels (96 MB), the source rows the core
materializes while packing, the output (67 MB for this noisy image) and the
output stream the benchmark writes to.

Time and allocation, BenchmarkDotNet ShortRun, AVX-512 off, on the worker
(Ryzen 9 7950X3D, 32 logical CPUs, .NET SDK 10.0.402, load 2 to 3.2 before,
during and after), base and new alternating, two rounds, mean per call:

| Case | Before | After | Allocated before | Allocated after |
|---|--:|--:|--:|--:|
| lossy 400x300 | 5.40 / 5.23 ms | 5.35 / 5.32 ms | 1.65 MB | 0.92 MB |
| lossy 2000x1500 | 103.8 / 103.7 ms | 104.1 / 103.9 ms | 32.05 MB | 9.27 MB |
| lossy 6000x4000 | 777 / 781 ms | 784 / 788 ms | 252.4 MB | 66.5 MB |
| lossless 2000x1500 | 141.5 / 141.6 ms | 138.5 / 138.5 ms | 117.8 MB | 100.1 MB |
| lossless 6000x4000 | 1097 / 1107 ms | 1073 / 1071 ms | 1034 MB | 817 MB |

The lossless coder state change, same method (worker under the benchmark
lock: Ryzen 9 7950X3D, 32 logical CPUs, .NET SDK 10.0.402, load 0.1 before,
2 to 5 during, 3.5 after), base and new alternating, mean per call:

| Case | Before | After | Allocated before | Allocated after |
|---|--:|--:|--:|--:|
| lossless 2000x1500 | 132.8 / 135.6 ms | 131.2 / 129.7 / 127.7 ms | 100.1 MB | 53.7 MB |
| lossless 6000x4000 | 1072 / 1076 ms | 949 / 980 / 957 ms | 817 MB | 369 MB |
| lossy 2000x1500 (unchanged) | 104.5 / 104.7 ms | 104.9 / 104.4 / 106.0 ms | 9.3 MB | 9.3 MB |

### Small and medium encodes

Where the memory of a small encode goes, from allocation sampling and the
gate-peak runner:

- **Lossy, 2000x1500:** 4.5 MB of source YUV planes (1.5 bytes per pixel).
  They are needed in full: the segment analysis looks at the whole frame
  before any macroblock is coded, so they cannot be streamed. The rest is the
  coded levels, the token partition and the joined frame, each about the size
  of the output. The peak is what remains after those, about 5 MiB. Renting
  these buffers from the array pool lowered the gate row, but only by moving
  the memory into the pool's retention (the absolute peak and the footprint of
  a loop of encodes went up), so the lossy encoder allocates them as before.
- **Lossless, 400x300:** the match-search hash table, a 1 MiB array allocated
  for every entropy-coded image. A file codes several (the picture and its
  small transform maps, a few hundred pixels each), so those arrays were 9.7 MB
  of the 12 MB a 400x300 lossless encode allocated, whatever the image size.
- **thumb-webp:** the encoder itself is 0.4 MB of a 400x267 image. What the
  gate row shows beyond that is the runtime's tiered JIT, a one-time cost. With
  the gate's single warm-up call, hot methods of the JPEG decoder, resampler
  and WebP encoder are still recompiled during the measured calls, which costs
  2 to 3 MiB of resident code and compiler memory once per .NET process;
  native libraries do not pay it. `GATE_WARMUPS=N` makes `gate-peak` do N
  warm-ups (default 1, the gate's method, unchanged) to show this: with 40
  the same row is 2.0 MiB at 31.6 ms (information only, not a gate figure).

What changed: the lossless match search of an image of up to 16384 pixels
uses an open-addressing map sized to the image instead of the 2^18-entry
table. It has the same hash and chain order, so matches and output bytes do
not change. Bigger images keep the full table, so the 24 MP lossless row is
unaffected. A 400x300 lossless encode allocates 4.9 MB instead of 12 MB and a
2000x1500 one 44 MB instead of 54 MB.

Hash check: 456 SHA-256 hashes of the output (lossy q30 to 100 and lossless;
effort 0, 2, 4, 5, 6; degrees 1, 4, 16; RGB, gradient alpha and cut-out alpha;
11 sizes from 1x1 to 2000x1500; repeating, flat and noisy images; an animated
GIF to lossy and lossless WebP) are the same before and after on default
hardware, `DOTNET_EnableAVX512=0`, `DOTNET_EnableAVX2=0` and
`DOTNET_EnableHWIntrinsic=0`; six larger encodes (2400x1800 and 3000x2000
lossy and lossless at degrees 1, 4 and 16, 400x300 lossless, 6000x4000
lossless) are the same too.

Gate-peak, AVX-512 off, peak minus resident-before in MiB and the absolute
peak, median of three processes (spread), one warm-up. **Local run** on the
development host (main against this change, same method, alternating):

| Task | Before: delta / absolute peak | After: delta / absolute peak |
|---|--:|--:|
| webp-encode (lossy 2000x1500) | 4.6 (±0.6) / 223.7 | 4.6 (±0.8) / 223.9 |
| thumb-webp | 4.1 (±0.9) / 217.9 | 3.7 (±1.4) / 217.4 |
| png-to-webp (photo) | 19.3 (±0.8) / 108.2 | 19.0 (±5.3) / 107.9 |
| webp-encode-lossless 2000x1500 | 44.1 (±2.2) / 279.2 | 40.1 (±1.6) / 276.1 |
| webp-encode-24mp (lossy) | 102.6 (±0.3) / 1172.8 | 101.1 (±3.4) / 1172.9 |
| webp-encode-lossless-24mp | 375.9 (±3.4) / 1457.5 | 369.4 (±0.2) / 1451.7 |

On the worker (Ryzen 9 7950X3D, 32 logical CPUs, .NET SDK 10.0.402, load 0.5 to
1.8, under the benchmark lock) the changed build measured: lossy 2000x1500
4.9 / 229.8 (SkiaSharp 1.2), thumb-webp 3.8 / 221.9 (Skia 0.6; 2.0 with 40
warm-ups), png-to-webp 23.0 / 116.5 (Skia 37.6), lossless 2000x1500 38.8 /
279.9 (Skia 57.6), lossy 24 MP 98.8 / 1175.3 (Skia 87.8) and lossless 24 MP
371.0 / 1459.0 (Skia 664.6). Times: the lossless 2000x1500 encode took 128.0 ms on main and 131.1 ms with the hash-map change plus the lossy pooling since removed (BenchmarkDotNet ShortRun, StdDev ±3 ms), and the 150-encode local loops ran at 138 to 140 ms (lossy) and 177 to 179 ms (lossless) on both builds; The
SkiaSharp gaps on the lossy 2000x1500 and thumb-webp rows remain (about 4 MiB
and 3 MiB); the first is the source planes above, the second is JIT.

## Drawing and clipping exceptions

The drawing operations are compared with ImageSharp.Drawing 2.1.7 in
`bench/OneImage.Benchmarks/Drawing` (BenchmarkDotNet with the memory
diagnoser, 2000 x 2000 RGBA, .NET 10.0.11, X64 AVX-512). These were
local smoke runs on a shared workstation with a load of 4.7 at the
start, rising to about 10, so treat them as rough. Fills, strokes and
brushes are faster with less allocation on every row; see
[drawing.md](https://recursiveai.org/oneimage/docs/drawing/). Clipping has one exception:

| Row | OneImage | ImageSharp.Drawing | Allocated (OneImage vs ImageSharp) | |
|---|--:|--:|---|---|
| union of 200 circles | 7.2 ms | 11.1 ms | 3.2 MB vs 23 MB | faster, less |
| star minus a 1000-point polygon | 158 µs | 134 µs | 33 KB vs 205 KB | **slower** (exception) |
| blur clipped to a circle, lazy `Image` | 12.3 ms | 56 ms | 52 KB vs 423 KB | faster, less |
| blur clipped to a circle, in place on a `Canvas` | 12.9 ms | 56 ms | 88 KB vs 423 KB | faster, less |

- **Star minus a 1000-point polygon is 1.18× slower.** The time is
  split evenly between finding crossings and the sweep. The boolean
  engine works in exact integer arithmetic on a 1/256-pixel grid, and
  for an input this small the candidate-pair search costs more than it
  saves. It allocates a sixth as much.
- **`Canvas.Clip` allocates 88 KB** (the `Image` path 52 KB). It used to
  allocate 9.6 MB: it read the canvas through a public snapshot, so every
  rewritten tile was copied and the replaced tiles, together with the
  tiles the clipped graph cached, went to the garbage collector. It now
  reads a private copy of the tile table, swaps fresh pooled tiles in and
  returns the replaced and cached tiles to the pool afterwards. Time is
  unchanged (12.9 ms against 13.4 ms before).

## Layer flatten exception

Flattening a layered document (`OneImage.Layers`, see [layers.md](https://recursiveai.org/oneimage/docs/layers/))
is compared with ImageSharp 3.1.12 cloning a 24 MP image and chaining
`DrawImage` calls. Full-size 24 MP Rgba8 layers at 50% opacity, Normal blend,
every tile recomputed; Ryzen 9 7950X3D (16 cores, 32 threads), .NET 10.0.13,
on a shared machine with other jobs running (load 4-12 during the runs).

| Row | OneImage, default (4 threads) | OneImage, degree raised to 32 | ImageSharp, all cores | Allocated (OneImage) |
|---|--:|--:|--:|---|
| flatten 10 layers | 77 ms | 34 ms | 72 ms | 0.25 MB |
| flatten 50 layers | 361 ms | 129 ms | 297 ms | 0.25 MB |
| flatten 10 layers, AVX2 only | 115 ms | 40 ms | 91 ms | |
| flatten 50 layers, AVX2 only | 544 ms | 157 ms | 340 ms | |

- **Flatten of 10 layers at 24 MP is slower than ImageSharp at the default
  thread limit: 77 ms against 72 ms (1.07×), an exception.** It is not
  published as a tie. The 50-layer and AVX2-only rows are slower in the same
  way.
- **The comparison is not on equal cores.** OneImage's default per-call degree
  is 4 threads, so a server is not oversubscribed by one call; ImageSharp's
  `DrawImage` chain uses every core. With the degree raised to 32 for the
  call, OneImage takes 34 ms, 2.1× faster than ImageSharp's 72 ms. The
  default stays at 4.
- A cold flatten allocates 0.25 MB. The raw figures and the method (the
  benchmark is in `bench/OneImage.Benchmarks`) are in
  [layers.md](https://recursiveai.org/oneimage/docs/layers/#measured).

## Whole-frame copy-out

Copying a computed 24 MP image (6000×4000, tiles in memory) into a caller's buffer, `CopyPixelsTo`, same worker as above (AVX-512 off, load 1-3 from
other jobs, `CoreHotPathBenchmarks`):

| Row | 1 thread | default (4) | 8 threads |
|---|--:|--:|--:|
| Rgba32 from tiles (96 MB) | 9.3 ms | 6.1 ms | 5.7 ms |
| Rgb24 from tiles (72 MB) | 7.5 ms | 4.4 ms | 4.2 ms |
| Same 96 MB as plain contiguous copies on the same threads (floor) | 5.0 ms | 3.1 ms | 2.9 ms |
| ImageSharp `CopyPixelDataTo` Rgba32 (single-threaded) | 6.1 ms | | |

The copy scales with threads and sits at 1.9× the contiguous floor at every
degree. The gap is the layout, not the engine: a tile row is 512 bytes of
Rgba32, so a frame is 192,000 separate 512-byte copies into rows 24 KB apart. A
stand-alone test of that loop (no engine) takes 10-11 ms against 6 ms for one
contiguous copy, and walking the destination in row-major order or in bands of
8 or 32 rows, or copying rows with 256-bit loads and stores, moved it by less
than 10%. Writing whole tiles to contiguous memory is not an option for a caller
buffer in row-major order. The extra copies that could be removed were in
decoders, and TIFF (above) was the one left; PNG, GIF, WebP and BMP already decode
straight into the caller's buffer on a whole-frame read.

## AVX-512 (information)

The gate runs with AVX-512 disabled so that its numbers describe the
AVX2 path every x64 server has. The same suite with native AVX-512
enabled on this CPU gave the times below (OneImage ms; the AVX2 gate
column repeats the table above). They change little. The raw reports are
[gate-final-avx512.md](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/bench/results/gate-final-avx512.md)
and
[gate-rerun-avx512.md](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/bench/results/gate-rerun-avx512.md).

| Task | AVX2 gate: OneImage ms | AVX-512: OneImage ms | AVX-512: ImageSharp ms | AVX-512 time vs ImageSharp |
|---|--:|--:|--:|---|
| thumb-jpeg | 37.5 | 38.1 | 48.2 | 1.27× faster |
| thumb-webp | 46.9 | 45.9 | 65.6 | 1.43× faster |
| png-to-webp (natural) | 79.1 | 76.7 | 1489.1 | 19.41× faster |
| png-to-webp (photo) | 90.5 | 90.8 | 1041.1 | 11.47× faster |
| png-to-webp (screenshot) | 95.8 | 99.4 | 251.0 | 2.53× faster |
| jpeg-decode | 41.2 | 41.7 | 76.5 | 1.83× faster |
| jpeg-encode | 87.4 | 81.8 | 100.9 | 1.23× faster |
| png-decode (natural) | 11.4 | 11.4 | 39.3 | 3.45× faster |
| png-decode (photo) | 18.3 | 17.9 | 22.1 | 1.23× faster |
| png-decode (screenshot) | 2.9 | 2.9 | 4.1 | 1.41× faster |
| png-encode (natural) | 219.6 | 222.7 | 1104.4 | 4.96× faster |
| png-encode (photo) | 52.3 | 53.2 | 322.4 | 6.06× faster |
| png-encode (screenshot) | 50.8 | 52.7 | 96.5 | 1.83× faster |
| webp-decode (lossy) | 16.9 | 16.8 | 31.2 | 1.86× faster |
| webp-decode (lossless) | 24.9 | 24.5 | 69.0 | 2.82× faster |
| webp-encode (lossless-2000x1500) | 146.8 | 146.0 | 1095.1 | 7.50× faster |
| webp-encode (lossy-2000x1500) | 101.6 | 103.0 | 581.8 | 5.65× faster |
| webp-encode (lossy-400x300) | 5.4 | 5.4 | 23.9 | 4.43× faster |
| gif-decode | 2.3 | 2.3 | 6.1 | 2.65× faster |
| gif-encode | 13.3 | 13.6 | 19.5 | 1.43× faster |
| gif-resize | 40.4 | 39.1 | 47.5 | 1.21× faster |
| tiff-multipage-decode† | 84.3 | 87.5 | 583.7 | 6.67× faster |
| tiff-encode | 44.4 | 43.8 | 131.2 | 3.00× faster |
| bmp-decode | 0.4 | 0.4 | 0.7 | 1.89× faster |
| bmp-encode | 2.8 | 2.7 | 4.8 | 1.78× faster |
| upscale-2x | 6.3 | 6.3 | 12.5 | 1.98× faster |
| watermark | 4.9 | 4.9 | 5.7 | 1.16× faster |
| cmyk-jpeg-to-srgb | 243.4 | 241.2 | 149.4 | 1.61× slower (ImageSharp skips the ICC conversion) |
| jpeg-decode-rgba | 43.4 | 44.2 | 79.5 | 1.80× faster |

† Measured before the TIFF LZW and predictor work. The AVX2 gate figure is now 52.3 ms (table above); the AVX-512 columns were not re-run.

## Vector kernels on AVX2 and SSE

The .NET vector API compiles to one instruction only where the CPU has it.
Unsigned 32-bit lanes converted to float (and back), unsigned compares,
64-bit lane multiplies and saturating float-to-int conversions are native
with AVX-512 but expanded into several instructions on AVX2 and SSE, so
benchmarks on an AVX-512 desktop hide them while the AVX2 gate pays for
them. Every kernel in `Kernels/` was checked for these (by reading the
code and by scanning the generated assembly of every kernel the test
suite and a sweep of about fifty operations and codecs reach, with AVX-512 off and AVX2 off). Four
needed work, and their output did not change by a bit.

One thread, 1024 x 1024 pixels, minimum of 12 runs, nanoseconds per pixel
(AMD Ryzen 9 7950X3D, .NET 10.0.11; the host was shared, load average
about 1.5 to 2.5, so differences under 10% are noise):

| Kernel or operation | AVX-512 before | AVX-512 after | AVX2 before | AVX2 after | SSE only before | SSE only after |
|---|--:|--:|--:|--:|--:|--:|
| Error diffusion, Floyd-Steinberg, fast match | 19.6 | 18.8 | 60.8 | 18.5 | 60.8 | 18.8 |
| Error diffusion, Floyd-Steinberg, exact match | 34.5 | 33.7 | 68.2 | 33.5 | 64.7 | 33.5 |
| Error diffusion, Atkinson, exact match | 39.1 | 39.0 | 93.0 | 38.8 | 92.5 | 38.4 |
| Equalization luma kernel (multiply form) | 0.21 | 0.18 | 0.35 | 0.18 | 0.87 | 0.34 |
| Color matrix kernel, RGBA to RGBA | 1.36 | 1.25 | 2.64 | 1.53 | 3.72 | 3.07 |
| Color matrix kernel, RGB to RGB | 1.23 | 1.21 | 1.64 | 1.39 | 3.79 | 2.49 |
| Float-path RGBA composite kernel | 1.66 | 1.07 | 2.15 | 1.12 | 4.27 | 2.25 |
| `Composite` operation, 8-bit RGBA | 2.43 | 1.85 | 2.99 | 1.89 | 4.88 | 2.70 |

The other kernels and the codecs measured within 10% of their AVX-512 time
on AVX2 (resize, blur, JPEG, PNG, WebP, GIF, TIFF, geometry, tone and the
remaining filters). The JPEG transforms have an AVX2 path and a 128-bit path (SSE2/SSE4.1 on
x64, AdvSimd on ARM64); all three give identical bits. With AVX2 turned off
(`DOTNET_EnableAVX2=0`, same host, load 1.6 to 10) a 24 MP decode took 47 ms
(79 ms before the 128-bit path; 32 ms with AVX2) and a q90 4:2:0 encode
179 ms (225 ms before; 86 ms with AVX2). Per 8x8 block the inverse DCT takes
40 ns (scalar 145, AVX2 19) and the forward DCT with quantization 71 ns
(scalar 131, AVX2 47). The AVX2 times did not change. The rest of the
SSE-only gap is the other JPEG stages (entropy coding, color conversion,
upsampling), not the transforms.

The reduced-size transforms used for DCT scaling (4x4 at 1/2, 2x2 at 1/4) also have a
128-bit path now, identical in output to the scalar one (hashes of the sample corpus and of
24 MP files at scales 1, 1/2, 1/4 and 1/8 match across AVX-512, AVX2, SSE-only and scalar
runs). Measured on the worker (Ryzen 9 7950X3D, 32 threads, .NET 10.0.13,
`DOTNET_EnableAVX512=0`, load 1.1 to 5 from other work, no other benchmark running), per block:
4x4 72 ns before and 26 ns after, 2x2 32 ns before and 20 ns after. A 24 MP 4:2:0 decode into
a reused buffer at 1/2 takes 38.9 ms before and 31.9 ms after, at 1/4 31.7 and 31.1 ms, at 1/8 26.4 and 26.0 ms
(full size 32.0 and 32.6 ms, unchanged within noise). The smooth test photograph is
entropy-bound at about 31 ms, so the transform no longer limits 1/2; noisier files with more
coefficients spend more time in the transform. The thumbnail row (24 MP to 400 px, shrink-on-load at 1/8, which does not
use these transforms) measured 27.3 ms before and 28.1 ms after, within the run spread.

## Method

- **Libraries.** OneImage, measured against
  ImageSharp 3.1.12 (the last release that builds without a license key,
  so it is the reference; newer versions are not measured here),
  SkiaSharp, NetVips and Magick.NET, each through its .NET package.
- **Rows.** Each library runs its idiomatic one-call path to the same
  output, from and to memory, on inputs generated deterministically.
  Where a competitor writes into reused or pooled storage, OneImage
  writes into a caller buffer too; rows that allocate a fresh result are
  kept beside them in the raw reports. A library that cannot do a task
  has no row: SkiaSharp has no BMP, TIFF or animated GIF encoder and no
  TIFF decoder here, and NetVips's native build has no BMP loader.
- **Time.** BenchmarkDotNet with `MemoryDiagnoser`, throughput strategy,
  2–3 warm-up and 8–12 measured iterations per row; the mean is shown.
- **Peak memory.** One process per task and library, repeated three
  times. Each process runs the operation once to warm up, collects
  garbage, resets the resident-set high-water mark, runs the operation
  four times, and reports the peak minus the resident size before:
  the working memory of the operation, native allocations included.
  The median and the spread are shown. A peak difference counts as a tie
  when it is within the larger of 2 MiB and either library's spread,
  and within 5%; see the exceptions above for the rows read as ties.
- **Parallelism.** A single OneImage call uses at most min(4, cores)
  threads by default. Rows with a raised degree are marked as such and
  are information only.
- **Hardware.** AMD Ryzen 9 7950X3D (16 cores, 32 logical), 125 GiB RAM,
  Ubuntu 26.04, .NET SDK 10.0.400, runtime 10.0.11. The gate run has
  AVX-512 turned off (`DOTNET_EnableAVX512=0`, so `Avx2.IsSupported` is
  true and `Avx512F.IsSupported` false); the information run has it on.
- **A shared workstation.** The machine was not idle. The load average
  was 3.98 at the start of the full gate run, between 1.0 and 3.3 during
  it and 1.2 at the end; the re-run of changed rows saw 1.0 to 2.2. Every
  minute's sample is in the raw reports. Absolute times carry that noise;
  ratios on one machine in one window are steadier.
- **Two runs.** The full gate ran on 2026-10-22. The rows for JPEG
  encode and decode, thumb-jpeg, the CMYK conversion and GIF decode and
  resize were measured again later the same day after changes to them;
  the table uses the later numbers for those rows and the first run for
  all others. Both reports are kept:
  [gate-final.md](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/bench/results/gate-final.md),
  [gate-rerun.md](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/bench/results/gate-rerun.md).
  ARM64 is checked for correctness only; no ARM64 timings are published.

## Raw reports

Each report lists every library's row, with allocated memory, and the
load samples.

- [gate-final.md](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/bench/results/gate-final.md): full run, AVX2 gate.
- [gate-rerun.md](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/bench/results/gate-rerun.md): changed rows, AVX2 gate.
- [gate-final-avx512.md](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/bench/results/gate-final-avx512.md): full run, native AVX-512.
- [gate-rerun-avx512.md](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/bench/results/gate-rerun-avx512.md): changed rows, native AVX-512.

To run it yourself: `bench/gate.sh` (see [CONTRIBUTING.md](https://github.com/recursive-ai-oss/oneimage-csharp/blob/main/CONTRIBUTING.md#benchmarks)).
The libvips-based competitors need their native packages for your platform.


<!-- https://recursiveai.org/oneimage/docs/jbig2/ -->

# JBIG2 decoding

JBIG2 (ITU-T T.88) is the bilevel codec scanned PDF pages use. OneImage ships a decode-only implementation inside
the core package. It is internal: it is not in the default `ImageConfiguration` and not a public format. It exists
so that a PDF renderer in the same library family can reach JBIG2 images through core's internals, with core's
limits, kernels and fuzz harness, and without adding a dependency.

Entry points (`OneImage.Codecs.Jbig2.Jbig2Codec`):

- `Decode(data, globals, limits, jbig2Limits, cancellationToken)`: an *embedded* stream as a PDF holds it (segments
  only, no file header), preceded by the segments of the optional `/JBIG2Globals` stream. Returns a `Jbig2Page`.
- `DecodeFile(file, pageNumber, ...)`: a standalone `.jb2`/`.jbig2` file, sequential or random-access organisation.
- `TryReadPageSize(data, out width, out height)`: reads the page information segment only.

`Jbig2Page` holds `Width`, `Height`, `Stride` and `Data`: one bit per pixel, most significant bit first, rows padded
to whole bytes with zero bits, **1 = black** (the sense the standard uses). A PDF consumer inverts this for
`DeviceGray`, and honours `/Decode` and `/ImageMask` itself.

## What is decoded

Generic regions (arithmetic with all four templates and any adaptive-pixel positions, typical prediction, and MMR),
generic refinement regions (both templates, typical prediction), symbol dictionaries (arithmetic and Huffman, with
refinement/aggregate symbols, collective bitmaps and export flags), text regions (arithmetic and Huffman, refinement,
all reference corners and transposition, the combination operators), pattern dictionaries and halftone regions
(gray-scale image decoding of annex C), custom Huffman tables (B.2) and the 15 standard ones (annex B), page make-up with
all combination operators and default pixel, striped pages and pages of unknown height, immediate/lossless/
intermediate segment variants, and both file organisations. Profile, extension and unknown segments are skipped.

Not decoded: the extended generic template (flag bits 4-7 of the generic region flags) is refused with a format
error. Colour JBIG2 extensions are not part of what PDF uses.

MMR reuses the CCITT G4 code the TIFF reader has (`TiffCcitt.DecodeMmr`, which also reports how many bytes it used).
The TIFF `Decode` path is untouched.

## Strictness

A stream is decoded as the standard describes. Where the data is damaged the decoder throws `ImageFormatException`
rather than rendering a partial page: a text region with more instances than it declares, a truncated segment, a
reference to a segment that does not exist. Some PDF viewers instead paint what they managed to decode; a caller that
wants that behaviour has to catch the exception and fall back.

## Limits

Everything that reads the stream is safe, bounds-checked C#; there is no `unsafe` code. Page size is bounded by
`ImageLimits` (pixels per frame, dimension). `Jbig2Limits` bounds the parts of a JBIG2 stream that can ask for far
more work than their size suggests; each is checked against header values before the allocation it guards:

| Limit | Default | Guards |
|---|---|---|
| `MaxSegments` | 131072 | segments in globals plus page data |
| `MaxReferredSegments` | 65536 | segments one segment refers to |
| `MaxSymbolsPerDictionary` | 1048576 | symbols a dictionary defines, exports or imports |
| `MaxSymbolPixels` | 16 Mi | pixels in one symbol or pattern |
| `MaxRetainedBytes` | 128 MiB | symbol and pattern bitmaps kept for later segments |
| `MaxInstances` | 32 Mi | symbol instances drawn in a stream |
| `MaxDecodedPixels` | 512 Mi | pixels allocated and decoded in total |
| `MaxHuffmanTableLines` | 65536 | lines of a custom Huffman table |
| `MaxPixelsPerCodedByte` | 1 Mi | declared region pixels per byte of coded data |
| `MaxPatterns` | 65536 | patterns in a dictionary |
| `MaxHalftoneCells` | 16 Mi | cells in a halftone grid |

Unknown-height pages grow stripe by stripe and are checked against the frame limits at every growth. Loops over
input-controlled counts (height classes, Huffman lines, instances) are bounded by these budgets, nothing recurses on
input depth, and cancellation is observed once per row of the larger regions.
`tests/OneImage.Tests/Jbig2/Jbig2LimitTests.cs` has one crafted stream per limit and checks the bytes allocated
before the refusal.

## Conformance

- The T.88 Annex H example (3 pages: Huffman and MMR coding, arithmetic coding, refinement and aggregation) decodes, and
  the pages the standard codes in different ways agree pixel for pixel (page 1 Huffman/MMR equals page 2 arithmetic;
  page 3 refinement/aggregation equals the text region of page 1).
- The MQ decoder reproduces the H.2 test sequence.
- A corpus of 2327 JBIG2 streams taken from public PDF files (US government documents) was decoded and compared with
  the images poppler's `pdfimages` writes from the same files. `tools/jbig2-corpus.sh` builds it from PDFs you
  supply; the test `Jbig2CorpusTests` runs it when `ONEIMAGE_JBIG2_CORPUS` names the directory. The extracted images
  are never committed.

| Class | Streams | Explanation |
|---|---|---|
| bits identical | 1925 | |
| exactly the inverse, every pixel | 402 | The PDF image dictionary says `/Decode [1 0]` (401 streams) or `/ImageMask true` (1 stream); `pdfimages` applies that polarity when it writes the bitmap, and our decoder returns the raw JBIG2 bits (1 = black) for the caller to interpret. Not a decoder defect. |
| anything else (size mismatch, partly different bits, error) | 0 | |

How the 402 were classified: the test accepts a stream as inverted only when *every* pixel is the exact complement of the
reference (padding bits ignored), so a decoder fault cannot hide in that class; a single wrong pixel would be reported as a
difference. The cause was then confirmed in the PDFs themselves: in each of the 23 documents with inverted streams, the
number of JBIG2 image dictionaries carrying `/Decode [1 0]` or `/ImageMask true` equals the number of inverted streams
from that document (for example 126845: 59 of 59, 882166: 108 of 108, 966625: 33 of 288 images, 33 inverted). No stream
of the corpus is a quirk of the reference beyond this polarity handling.

Four small streams are committed as `tests/testdata/jbig2/pdf-*.jb2e` (with `.jb2g` globals for three of them), excerpts
of public US government PDFs, with their page hashes in `Jbig2PdfStreamTests`. One of them (`966625-006`) is an inverted
class member; the others match without inversion. The full corpus stays outside the repository because of its size.

## Fuzzing

`fuzz/run.sh jbig2 <seconds>` drives the embedded decoder (with and without globals) and the file decoder under small
limits. Seeds are Annex H and the committed PDF streams.

## Speed

`bench/OneImage.Benchmarks/Jbig2` decodes the committed pages (BenchmarkDotNet ShortRun, .NET 10.0.402, AMD Ryzen 9
7950X3D, 32 logical cores; machine load 8 at the start of the run because the benchmark project had just been built
on it, 6 at the end, so treat the numbers as upper bounds):

| Page | Size | Mean | Allocated |
|---|---|---|---|
| 504344-001 (nearly blank, globals) | 3600x4576 | 3.8 ms | 4.0 MB |
| 714558-003 (text, symbol globals) | 2089x3152 | 5.6 ms | 1.9 MB |
| 714748-174 (text, symbol globals) | 2552x3304 | 3.7 ms | 2.3 MB |
| 966625-006 (generic region) | 1321x1814 | 7.1 ms | 0.65 MB |

For orientation only: `pdfimages -f P -l P` (poppler, a separate process on another, loaded machine) took 16-20 ms per run
for the pages holding the same images, which includes starting the process, parsing the PDF and writing a PBM file, so it
is not a like-for-like decoder timing.


<!-- https://recursiveai.org/oneimage/docs/jpx/ -->

# JPEG 2000 decoding

JPEG 2000 Part 1 (ITU-T T.800 / ISO 15444-1) is the wavelet codec PDF files use for `/JPXDecode` images. OneImage ships a
decode-only implementation inside the core package. It is internal: it is not in the default `ImageConfiguration` and not a
public format (JPEG 2000 stays out of the public format list). It exists so that a PDF renderer in the same library family
can reach it through core's internals, with core's limits, kernels and fuzz harness, and without adding a dependency.

Entry points (`OneImage.Codecs.Jpx.JpxCodec`):

- `Identify(data, options)`: reads the main header and the JP2 boxes; returns size, component count, bit depths, tile count,
  the number of reduction levels available, layers and colour space. No tile data is read.
- `Decode(data, options, cancellationToken)`: returns a `JpxImage` of 16-bit sample planes, one per channel, after the palette
  (`pclr`/`cmap`), channel definitions (`cdef`) and the sYCC to sRGB conversion.
- `DecodeComponents(...)`: the raw component planes at their own sampling, for conformance testing.

`JpxDecodeOptions` selects a reduction level (`ReductionLevels`, clamped to what the stream has: each level halves the
size and skips the finest wavelet level), a `Region` of the output (only the tiles it touches are decoded), `Strict`, and the
resource limits below.

## What is decoded

Raw codestreams and JP2 files; all five progression orders and progression order changes; tiles and tile-parts; precincts;
layers; packed packet headers (PPM, PPT); SOP/EPH markers; all code-block styles (bypass, reset, terminate-each-pass, vertically
causal, predictable termination, segmentation symbols); the reversible 5-3 and irreversible 9-7 wavelets; RCT and ICT;
region-of-interest max-shift; 1 to 16 bits per sample, signed or not; sub-sampled components (replicated to the output grid, no
interpolation); palettes, channel definitions, ICC and enumerated colour spaces. Part 2 extensions are ignored. More than 16 bits
per sample and more than 30 magnitude bit-planes are refused with `ImageFormatException`.

## Behavior

- Lossless (5-3) streams decode bit-exactly. Lossy (9-7) output is computed in single-precision float, one operation at a time
  (no fused multiply-add), and rounds half up, so it is identical on every hardware path; against OpenJPEG it differs by at
  most one level at 8 bits (two at 16 bits).
- A coefficient that was not fully decoded sits at the middle of its uncertainty interval (reconstruction parameter r = 1/2).
- Truncated or damaged tile data decodes as far as it goes and sets `JpxImage.Damaged`; with `Strict` it throws
  `ImageFormatException`. Missing bytes of a bypass segment read as 0xFF.
- The output grid is the reference grid divided by the finest component sampling, so a stream whose components all share a
  sampling yields its natural size.
- Output is deterministic: tiles are decoded in parallel (one tile per thread, up to `MaxDegreeOfParallelism`, default
  `min(4, cores)`) and write disjoint samples; a single large tile spreads its code-blocks and wavelet rows over the threads
  instead. The result never depends on the degree. When several tiles fail, the lowest-numbered tile's error is reported.

## Limits (checked before the allocation they guard)

| Limit | Default | Failure |
|---|---|---|
| Pixels per frame, dimension | `ImageLimits` (2²⁸, 65,535) | `ImageLimitException` |
| Components | 256 (`MaxComponents`) | `ImageLimitException` |
| Tiles | 65,535 (the standard's bound) | `ImageFormatException` |
| Code-blocks plus precincts per tile | 2²¹ (`MaxCodeBlocksPerTile`) | `ImageLimitException` |
| Output samples against the data size | `MaxExpansionRatio` × bytes, floor 64 Msamples | `ImageLimitException` |
| Working memory (planes and one tile's coefficients) | 1 GiB (`MaxWorkingBytes`) | `ImageLimitException` |
| Coding-pass work (sample visits) | 2²⁷ + 2048 × bytes | `ImageLimitException` |
| Progression order changes | 1,024 | `ImageLimitException` |
| Progression positions visited | 2²⁷ | `ImageLimitException` |
| Tile-parts | 1,000,000 | `ImageLimitException` |
| Magnitude bit-planes | 30 | `ImageFormatException` |

Output planes for the declared size are allocated before the first tile is read, so a small file can cost up to the
expansion floor (128 MiB of 16-bit samples) before its tile data is refused.

## Testing

- `tests/OneImage.Tests/Jpx`: the T.803 Class 1 conformance set (Profile 0 and 1, 52 component comparisons against the
  suite's reference images under its own tolerances), the committed generated corpus (`testdata/jpx/gen`), API behavior, one
  hostile stream per limit, prefixes and bit flips of every corpus file, and a determinism test that pins output hashes and
  compares degree 1 with degree 8. The conformance files are not in the repository: `tools/fetch-jpx-tests.sh <dir>` downloads
  them at a pinned commit and `ONEIMAGE_JPX_CORPUS=<dir>` enables the test.
- `testdata/jpx/gen` is made by `tools/gen-jpx-corpus.py`, using OpenJPEG as a black-box encoder and decoder on synthetic images.
- Fuzz target `jpx` (`fuzz/run.sh jpx 600`).
- Benchmark: `JpxBenchmarks` (files from `tools/gen-jpx-bench.py` and conformance stream p0_07).

## Speed

BenchmarkDotNet (`JpxBenchmarks`, medium job), Ryzen 9 7950X3D, .NET 10.0.400, Linux x64, default degree 4, wall time per decode
into 16-bit planes. Run on a shared host with a load average of about 5 from other work (not the quiet benchmark worker), so
read the ratios, not the absolute values. "OpenJPEG" is libopenjp2 through glymur with its default settings, best of 5, including
a copy into a numpy array; it is information only.

| File | Reduction | Before | After | Allocated before / after | OpenJPEG |
|---|---|---|---|---|---|
| lossy 2048x1536 RGB, one tile (471 KB) | 0 | 54.8 ms | 44.5 ms | 56.8 / 20.6 MB | 84.7 ms |
| same, 3 levels dropped | 3 | 3.25 ms | 2.69 ms | 1.3 / 0.6 MB | |
| lossy, 256-pixel tiles (465 KB) | 0 | 74.5 ms | 27.8 ms | 77.5 / 19.2 MB | 74.7 ms |
| lossless gray 3000x2000 (4.0 MB) | 0 | 161 ms | 156 ms | 36.0 / 12.8 MB | 366.6 ms |
| 12-bit 2048x2048x3, 256 tiles, 7.9 MB (conformance p0_07) | 0 | 539 ms | 319 ms | 141 / 28.6 MB | 805.6 ms |
| same, 3 levels dropped | 3 | 33.5 ms | 8.4 ms | 6.5 / 3.9 MB | |

Single-threaded the same decodes take 1.19 s (p0_07), 115 ms (lossy), 552 ms (lossless gray). The tier-1 entropy decoder is
the cost of dense files (about 95% of p0_07): in safe code it runs at roughly 1.5× OpenJPEG's single-thread time, and it
scales over code-blocks and tiles. What changed: tiles run in parallel (one per thread, so no fork-join per code-block batch or
wavelet level), the wavelet lifting steps work on the separated low- and high-pass runs with `Vector<T>` (the scalar path is the
reference; the output hashes are identical with vectors on or off), the MQ decoder state lives in locals, and the coefficient
buffers, wavelet scratch and per-thread block decoders are pooled.


<!-- https://recursiveai.org/oneimage/docs/pdf-spec-truth/ -->

# PDF spec-truth tests

`tests/OneImage.Pdf.Tests/SpecTruth/` checks the page renderer (`RecursiveAI.OneImage.Pdf`) against pages whose correct pixels follow from the PDF specification alone. No other renderer is involved: each test builds a small PDF in code, renders it at 72 dpi (one pixel per point), and compares the result with a raster computed in the test from the spec's own formulas.

Reference renderers disagree with each other, and none is always right, so they cannot be ground truth. These tests are the part of the render check that depends on none of them.

## What is covered

| Family | Examples |
|---|---|
| Color fills | DeviceGray/RGB/CMYK, ICCBased (sRGB, gray), Indexed, Separation with a type 2 tint transform |
| Shapes and fill rules | aligned and fractional rectangles, triangle and circle areas, non-zero vs even-odd on overlapping, opposite-direction, concentric and pentagram paths |
| Matrix | translate, scale, mirror, rotate 90/180/270 and 45°, concatenation order, `q`/`Q` |
| Page geometry | `/Rotate` (including 360, -90, 450), MediaBox and CropBox offsets, reversed corners, `/UserUnit`, dpi |
| Clipping | rectangular, nested, even-odd, restore by `Q`, clip after the painting operator, strokes and images under a clip |
| Transparency | `ca`/`CA`, all 12 separable and 4 non-separable blend modes, blend with alpha, `/BM` arrays, luminosity and alpha soft masks, `/SMask /None`, the mask's CTM |
| Groups | isolated vs non-isolated, group opacity, knockout, plain forms vs groups, form `/BBox` and `/Matrix` |
| Images | 1/2/4/8/16-bit samples, `/Decode`, Indexed, 7 placements, stencil masks, explicit masks of another resolution, `/SMask` (with `/Decode` and `/Matte`), color key masks, inline images, Flate with and without a predictor |
| Strokes | width, hairline, caps, joins, miter limit, degenerate subpaths, dash patterns (the spec's own examples), dashes under a matrix, caps on dashes, fill-then-stroke operators |
| Text | Type 3 fonts made of rectangles: `Td`, `Tm`, `TJ`, `Tc`, `Tw`, `Tz`, `Ts`, `TL`, `T*`, `'`, `"`, `TD`, text state across `BT`/`ET`, render modes, `d0`/`d1` colors, text knockout; one clip-mode case with a standard font |
| Shadings | axial and radial, `/Extend`, function types 0, 2 and 3, function arrays, `/Domain`, `sh` with clip, `/BBox` and alpha, shading patterns (`/Matrix`, `/Background`) |
| Tiling patterns | colored and uncolored, pattern matrix, steps larger than the BBox, BBox clipping, stroking |
| Annotations | appearance placed by `/Rect` and `/Matrix`, `/AS` states, hidden and print flags, drawn after page content |
| Structure | content stream arrays, inherited MediaBox and Resources |

Every test carries `[Trait("Section", "...")]` with the ISO 32000 section it tests, and a comment quoting the rule where it is not obvious. Section numbers are those of ISO 32000-1:2008, which ISO 32000-2 keeps for the parts used here.

## How the expected raster is derived

`Expected` is a plain RGB raster. Tests paint into it in PDF user space (origin bottom-left):

- rectangles by exact area coverage, composited source-over in device space;
- images by inverse-mapping each pixel center through the placement matrix;
- shadings by evaluating the spec's parametric formulas at each pixel center;
- blend modes with the formulas of 11.3.5, written out in `BlendMath.cs`;
- anything else with a short per-pixel function.

CMYK has no conversion in the specification, so its expectation is the library's documented one (the generic CMYK profile), obtained through the public `ConvertColor` API.

## Tolerances

- **Exact**: integer-valued expectations (pixel-aligned geometry, whole-level colors). The rendered pixel must equal the expected pixel.
- **Within 1 level**: where rounding is left open (half levels from alpha, gradients sampled at pixel centers, 16-bit and Decode scaling).
- **Edge (3 levels)**: pixels partly covered by a shape. Anti-aliasing is implementation-defined, so only the covered area is checked, as a per-pixel area fraction or as the sum over a shape (triangle, circle, round caps and joins). Curves allow for flattening, which the specification leaves to the flatness tolerance.
- **Not compared**: pixels where the specification gives no single answer, listed in the test next to the reason. Examples: partial pixels on a shading's boundary, and the region between sample centers of an enlarged image, which a reader may interpolate (see below).
- Stroke geometry where renderers legitimately differ (the join of two arms of a self-overlapping path) is skipped in that test only.

## Known failures

Tests for behavior the renderer gets wrong are marked with an xunit `Skip` that names the defect and the section, so the suite stays green and the list is greppable (`grep -rn "Skip =" tests/OneImage.Pdf.Tests/SpecTruth`). Remove the `Skip` when the behavior is fixed.

## Running

```
dotnet test tests/OneImage.Pdf.Tests -- --filter-namespace '*SpecTruth*'
```

The whole suite runs in about a second, needs no network and no external tools, and is deterministic. Set `ONEIMAGE_SPEC_TRUTH_DUMP=<directory>` to keep every generated PDF (named by content hash, with an index of test names) for looking at in another viewer.

## Image interpolation

Section 8.9.5.3 makes interpolation opt-in (`/Interpolate true`) and lets a reader skip it. Enlarged images are therefore compared only where any interpolation returns the sample itself (a pixel exactly at a sample center, or the outer half of an edge sample). One dedicated test requires a block-exact enlargement by default.


<!-- https://recursiveai.org/oneimage/docs/changelog/ -->

# Changelog

All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow [Semantic Versioning](https://semver.org/).

## [Unreleased]

## [1.10.1] - 2026-10-25

### Fixed

- Valid PNG files could fail to decode, in every release from 1.0.0 to 1.10.0. The deflate decoder's fast loop could read a length/distance pair from bits it had not yet loaded when the pair followed a literal with a long code, which happens in files whose compressed data uses long codes for rare literals and for far, long matches (some optimizing encoders produce this; zlib and this library's own encoder did not in any test file). The stream then went out of step, and the read failed with "Invalid DEFLATE block type", "Stored block length check failed", "Invalid literal/length code", "Invalid scanline filter type", an Adler-32 mismatch, or an `ArgumentOutOfRangeException` from the data reader. The same decoder reads TIFF Deflate strips and tiles, PSD ZIP channels, SVGZ, WOFF tables and PNG `iCCP`/`zTXt` text, so those formats could fail the same way. The decoder now reloads its bits before such a pair.
- Wrong pixels without an error were possible for unusual compressed data, though rare in practice. The damaged bytes were caught only by the Adler-32 checksum or by the PNG scanline-header check, never by the decoder itself. In tests on the old decoder, using data that did trigger the bug, a whole-image read of a PNG, TIFF or PSD never returned wrong pixels: all of them failed (the six reported PNGs, 72 generated PNGs with the pattern at three densities, 40 generated streams each as TIFF and as PSD). Reading only part of a PNG could: a crop, region or band that ends inside the damaged data and before the next scanline header could return wrong pixels in its last rows with no error (1 of 956 partial reads of the reported files, in 1 of the 6 files; 43 of 11,448 partial reads of the generated files, in 29 of 72). Ordinary compressors (zlib at every level and strategy, and this library's own encoder) did not produce the pattern in any of about 200 test files; the six reported files came from an encoder that emits long codes for rare literals and for far, long matches.
- Complete reads of deflate data now check the checksum at the end of the stream, which an earlier release did only when the four trailer bytes happened to arrive with the last rows (about one PNG in ten thousand missed it). What is checked: a PNG read of every row, a TIFF Deflate strip or tile, a PSD ZIP channel, a WOFF table and a gzip-compressed SVG each verify the zlib Adler-32 (gzip: CRC-32 and size) and fail with a format error when a trailer that is present in full does not match. What is tolerated, as in earlier releases: a file that ends right after the last row or byte, or after 1 to 3 trailer bytes (gzip: fewer than the 8), is accepted and its pixels are returned unchanged; deflate data that ends before everything was produced is still an error. `iCCP` profiles and compressed XMP with a bad or missing trailer are dropped without failing the image. What is not checked: a read of only part of a PNG (a crop, a region, a streaming window) holds only part of the stream, so it cannot verify the checksum; only the chunk CRCs of the chunks it read cover it.
- A decode started from an image loaded with `Image.Load(Stream)` or `LoadAsync(Stream)` could read overwritten bytes if the `Image` became unreachable while the decode was still running (for example `Image.Load(stream).Save(...)` or `.ToArray<T>()` on a temporary). The compressed bytes of such an image live in a pooled buffer that is handed back to the pool when the image is collected, and the stream the decoder reads from did not keep that buffer alive; another thread could rent and overwrite it mid-read. Formats with checksums or strict structure (PNG, GIF, WebP, TIFF compression) then failed with a format error such as "Invalid DEFLATE block type", "Too many length or distance codes" or an Adler-32 mismatch; for data without redundancy (raw or lightly compressed pixels, JPEG coefficients) wrong pixels without an error were possible in principle. Present since 1.0.0. The stream now holds the buffer's owner. Loading from a file path or from memory you pass in (`ReadOnlyMemory<byte>`) is not affected by this.

## [1.10.0] - 2026-10-24

### Changed

- `RecursiveAI.OneImage.Text` is built on [`RecursiveAI.OneFont`](https://github.com/recursive-ai-oss/onefont-csharp) 1.2 or later for font parsing and shaping, instead of carrying its own copy: the sfnt, CFF and TrueType outline readers, the GSUB/GPOS engine and the script shapers, the bidirectional algorithm, line breaking and grapheme segmentation, and the Unicode tables. WOFF, WOFF2, hinting, color glyphs, vertical metrics, word-breaking modes and the layout stay here. The public API of `OneImage.Text` is unchanged and drawing and measuring are byte-identical to 1.9.0 over the test fonts, the complex-script case files and the SVG text tests. `OneFont` is the package's one new dependency; `RecursiveAI.OneImage` itself gains none.

### Fixed

- `TextShaping.ShapeRun` returns clusters that start at offset 0 and meet without gaps even when the shaper drops characters: a leading zero width non-joiner before a Kannada letter now belongs to the first cluster, and text of only joiners gives one empty cluster instead of none.
- A glyph id that the font does not have (a character map or shaping result pointing past the glyph count) is drawn and measured as the missing glyph instead of taking the last glyph's advance.

## [1.9.0] - 2026-10-24

### Added

- `ImageFrame.ReleaseDecodedPixels()` is public, so one frame of a multi-frame image can give its decoded pixels back.
- `CopyPixelsTo(destination, rect, useRegionCache: false)` on `Image` and `ImageFrame`: one region or band read that builds no region plane and counts toward none, whatever `ImageEngine.RegionCacheBytes` says. Bands read from the top down decode the image once and hold only the decoder's few tile rows; a read that has to go back above them decodes again for that call and keeps nothing afterwards. Pixels are identical.

### Fixed

- `ReleaseDecodedPixels()` now gives back everything decode-derived: it also clears the cached tiles of every operation above the decode (a gray conversion, a resize) and of a random-access decode (TIFF), where before only the region plane and sequential-decode rows went. Releasing through `frame.ToImage()` (or the image the frame came from) now frees the frame's region plane; planes used to belong to the frame object, so a single-frame image made from it had its own empty set.

## [1.8.1] - 2026-10-24

### Changed

- Reading an 8-bit RGB or RGBA image as `Gray8`, `Gray16` or gray+alpha (`CopyPixelsTo`, `ToArray`, direct decodes, region reads) is several times faster: the RGB-to-gray conversion now runs in integer SIMD (AVX2, 128-bit, scalar) instead of through float32 rows. A pixel whose exact value lies close to a rounding boundary is recomputed with the float expression, so every output byte is identical to before (checked for all 2^24 RGB triples and every alpha). A 4 MP-class page read as `Gray8` now costs about the same as the `Rgb24` read.

## [1.8.0] - 2026-10-24

### Added

- `ImageEngine.RegionCacheBytes` (default 64 MiB per frame, 0 = off) and `Image.ReleaseDecodedPixels()`: repeated `CopyPixelsTo` region reads (bands, random rectangles) of a large JPEG or PNG no longer decode the image again. See the guide's pixel-access section.

### Changed

- Region reads of large JPEG/PNG frames: from the second region read on, the rows read are kept in a plane in the requested pixel format (at most `RegionCacheBytes` per frame, released by `ReleaseDecodedPixels()` or when the image is collected). Reading 44 Gray8 bands or 20 random rectangles of an A4 page now costs about one decode instead of up to three, and a rotated (EXIF) image no longer restarts decoding for each output row. The price is memory: a Gray8 plane of an A4 page is about 8.7 MB and an Rgb24 plane about 26 MB, kept while the image is alive. Set `RegionCacheBytes = 0` for the previous behaviour. Pixel values are unchanged.
- The first `Image.Load` of a PNG or JPEG costs less resident memory (about +2.5 MB instead of +6 to +11 MB): the header parsers are split so the JIT compiles small methods instead of one large one.

## [1.7.0] - 2026-10-23

### Added

- `PixelResizer`: an allocation-free resize from a span to a span (`Resize<TPixel>` for the pixel structs, `ResizeRaw` for any `PixelFormat` with up to four channels, and `PixelResizer.GetSize` for the size `Image.Resize` would scale to). Output is byte for byte what `Image.Resize(w, h, Fit.Stretch, ...)` gives for every filter and mode (checked against 2,500 hashes captured from 1.6.0, on the scalar, AVX2 and AVX-512 paths). The resizer keeps its buffers, so after a warm-up it allocates nothing per call even when every call has a new size; `ScratchBytes`, `maxScratchBytes` and `Trim()` bound and release them. Calls with enough pixels split their output rows over up to `maxDegree` threads without allocating. On 2300x60 gray lines to height 32 (Lanczos3, linear light) it takes 70 us at the default degree (255 us on the calling thread alone) against 255 us for 1.6.0 `Image.Resize`, and allocates nothing per call against 6 KB (same size) or 140 KB (a new width each call). See the guide.

### Changed

- `Image.Resize` allocates less when it meets a size it has not seen: the tap tables are built in per-thread scratch and only their exact size is allocated (140 KB to 77 KB per call for 2300x60 to height 32 with a new width each time). The 8-bit gray conversions are faster (255 to 205 us for the same-size case). Output is unchanged.

## [1.6.0] - 2026-10-23

### Added

- JPEG 2000 decoding (internal, decode-only), for the PDF bridge: JP2 files and raw codestreams, all progression orders, tiles, precincts, layers, every code-block style, the 5-3 and 9-7 wavelets, palettes, channel definitions, sYCC, reduction levels and regions; lossless streams are bit-exact and lossy ones agree with OpenJPEG within one level at 8 bits. Passes ITU-T T.803 Class 1 (52 of 52 components), refuses hostile headers before allocating (limits in `docs/jpx.md`), and was fuzzed for 10 minutes without findings. Tiles decode in parallel with deterministic output; a 12-bit 2048x2048x3 stream with 256 tiles takes 319 ms instead of 539. It is not in the default `ImageConfiguration`.
- `RecursiveAI.OneImage.Pdf` (new package): PDF pages as an image format on OnePDF 1.2 display lists. Each page is a frame, drawn in 128 px cells on demand (a region is byte for byte the same as that part of a whole render, at any degree), at the requested size when resized. Paths, strokes, clips, text, images (JPEG, JPEG 2000 and JBIG2 decoded by OneImage; damaged JPEG 2000 and JBIG2 images are left out), shadings, tiling patterns, transparency groups (isolated, non-isolated and knockout), text and fill-and-stroke knockout, soft masks, blend modes, and form and markup annotations through OnePDF's generated appearances (`PdfRenderOptions.GenerateAppearances`). `PdfRenderLimits` bound files, images, nesting, clips and pattern tiles, with a hostile-file test each, and `fuzz/run.sh pdf` fuzzes the whole path. Rendering is checked against PDFium, MuPDF and pdf.js as a signal: 26 of 307 pages of OnePDF's test set are flagged for review against ISO 32000-2 (24 ambiguous, 2 where the renderer follows the specification and the references do not, none wrong), with a verdict and section for each. Known gap: soft-mask `/TR` is treated as identity. See [docs/pdf.md](https://recursiveai.org/oneimage/docs/pdf/).
- JBIG2 decoding (internal, decode-only), for the PDF bridge: generic, refinement, symbol dictionary, text, pattern dictionary and halftone regions, MMR, custom and standard Huffman tables, striped and unknown-height pages, standalone files and PDF-embedded streams with globals. Bounded by `Jbig2Limits` (one crafted-stream test per limit) and fuzzed (`fuzz/run.sh jbig2`). Checked against T.88 Annex H and 2327 streams from public PDFs (1925 identical to `pdfimages`, 402 the exact inverse because of `/Decode [1 0]` or `/ImageMask`, none different). See [docs/jbig2.md](https://recursiveai.org/oneimage/docs/jbig2/).
- `OneImage.Layers`: layer styles draw gradient overlays, pattern overlays and bevel and emboss. `GradientOverlayEffect` and `EffectGradient`/`EffectGradientFill` (linear, radial, angle, reflected, diamond; midpoints, opacity stops, smoothness, reverse, scale, offset, align), `PatternOverlayEffect` with `EffectPattern`/`EffectPatternFill` (scale, link with layer, phase), `BevelEmbossEffect` (inner and outer bevel, emboss, pillow emboss and stroke emboss; smooth, chisel hard and soft; depth, size, soften, up or down, angle and altitude, highlight and shadow mode, color and opacity, gloss contour) and gradient or pattern paint for `StrokeEffect` (and a shape burst gradient) and a gradient for the outer and inner glow. `LayerStyle.AlignBox` sets the rectangle that aligned gradients and patterns are laid out on. The new effects have language-neutral `Describe()` names and bounded parameters, and are drawn per tile with the same dirty-rectangle reach as the other effects.
- `RecursiveAI.OneImage.Psd`: gradient and pattern overlays, bevel and emboss, gradient and pattern strokes and gradient glows are read from `lfx2`/`lmfx` and drawn, and are written when a style is created or edited (a pattern that the document does not hold is added to its pattern resources). 8 more sample files are fully modelled; the files that use these effects are 1.5 to 20 levels closer to their stored composite, and the files that were modelled are unchanged. Bevels, pattern phase on text and linear dodge/burn are approximations (see the PSD page).
- `RecursiveAI.OneImage.Psd`: `PsdFile.Save` writes layer styles and gradient and pattern fills that are created or edited in the model. A style that differs from the one read is written as a new effects block (`lfx2`) from the model, keeping the items of the original block that the model has no field for (gradient and pattern overlays, bevel and emboss, gradient strokes and glows, grain, and so on) and writing unchanged effects back as they were; an untouched style is still written back byte for byte. A new or replaced linear or radial gradient, bitmap pattern or hatch brush on a fill layer is written as `GdFl`/`PtFl` settings (patterns go to the document's pattern resources) beside its raster, and a brush with no such equivalent is written as a pixel layer instead of making `Save` throw. Disabled effects are now read as disabled `LayerEffect`s instead of being left out of the style. See [docs/psd.md](https://recursiveai.org/oneimage/docs/psd/#writing-fills).

### Changed

- WebP lossless encoding of small images uses less memory, with byte-identical output: the match-search hash table of an image of up to 16384 pixels (the picture and the predictor, color-transform and palette maps of a file) is sized to the image instead of a 1 MiB array per entropy-coded image. A 400x300 lossless encode allocates 4.9 MB instead of 12 MB and a 2000x1500 one 44 MB instead of 54 MB. The lossy encoder is unchanged: its 2000x1500 source planes are needed in full, and the thumb-webp gate row's excess over native encoders is one-time JIT cost (see [docs/performance.md](https://recursiveai.org/oneimage/docs/performance/#small-and-medium-encodes)). `gate-peak` takes an optional `GATE_WARMUPS=N` to show that cost; the default stays one warm-up.
- Progressive JPEG decoding is much faster, with identical output. Refinement scans read their correction bits through a mask of the nonzero coefficient positions instead of one coefficient at a time, and the scans of a progressive Huffman file of 1 MP or more decode side by side, each waiting only for the rows of earlier scans it depends on; rows reach the transform while the last scan is still running. On a 24 MP file: 389 to 68.5 ms (noisy) and 199 to 62.3 ms (smooth) at full size, 38.5 to 12.8 ms at 1/8 scale (ImageSharp 3.1.12: 432 and 210 ms; NetVips: 404 and 257 ms). A progressive file that fails in a late scan may now deliver some rows to the destination before the exception, as the streaming decoders already do; the exception is the same as before.

### Fixed

- `RecursiveAI.OneImage.Text`: hinting no longer lets a hostile font throw out of the interpreter: `ABS`, the cut-in compares of `MIAP`/`MIRP`/`MDRP` and the other absolute values no longer overflow on the most negative integer, and `ISECT` divides in 128 bits. The twilight zone is now kept as the control value program leaves it (each glyph starts from a copy), so fonts whose `prep` places twilight points hint as intended. All programs of one top-level glyph share a budget of 2^20 instructions; a composite that exceeds it is drawn unhinted instead of costing up to 2^18 per component.
- `RecursiveAI.OneImage.Psd`: a pattern channel whose rectangle claims more data than the file holds is refused before its buffer is allocated, and the linear-light interpolation of a gradient glow is written and read back like that of other gradients.
- `OneImage.Layers`: an edit of a layer's pixels now also recomputes the tiles that an inner effect (inner shadow, inner glow, inside stroke) draws from the edited shape, not only the ones outer effects reach. The pixels were correct after a fresh render; an incremental render could leave a stale tile next to the edit.
- `RecursiveAI.OneImage.Psd`: an effect contour with a point that is not a number, or two points a hair apart that become one float, is skipped and counted in `EffectsNotDrawn` instead of throwing an argument exception (found by fuzzing).

## [1.5.0] - 2026-10-23

### Added

- `RecursiveAI.OneImage.Psd`: gradient and pattern fill layers (and shape layers filled with them) are drawn from their settings as `FillLayer`s instead of loading as stored pixels. Gradients cover linear, radial, angle, reflected and diamond styles with midpoints, opacity stops, smoothness, reverse, scale, offset and linear-light interpolation; patterns come from the document resources. Where Photoshop stored a raster the colors are taken from it (alpha stays the drawn one); noise or perceptual gradients, scaled or rotated patterns, boxes under 16 px and malformed descriptors fall back to the stored pixels. Unchanged fills are written back from their original block. `PsdReadOptions.DrawFills` (default true) restores the old behavior. The median error over the 152 previously modelled sample files stays 0.134 levels; 160 files are now fully modelled (median 0.108), and `gradient-fill.psd` goes from 8.3 to 0.0 levels. See [docs/psd.md](https://recursiveai.org/oneimage/docs/psd/#gradient-and-pattern-fills).
- Photoshop-style options on three tone operations, with the existing overloads unchanged: `Image.Posterize(levels, linear, PosterizeMode.Buckets)` (equal input bins rounded down), `Image.Curves(points, channel, linear, CurveInterpolation.Natural)` (a natural cubic spline) and `Image.BrightnessContrast(brightness, contrast, linear, BrightnessContrastMode)` with `PhotoshopLegacy` (exact) and `PhotoshopSmooth` (an approximation of the current mode). `Adjustment.Posterize`, `Curves` and `BrightnessContrast` have the same overloads. They fuse with other tone steps like the rest.
- `OneImage.Layers`: layer styles. `Layer.Style` takes a `LayerStyle` of drop shadows, inner shadows, outer and inner glows, strokes (outside, inside, center), color overlays and satin, each with blend mode, opacity, color, size, distance, spread or choke and an optional `EffectContour`. Effects are drawn from the layer's shape when the document is composited, with exact signed-distance strokes and Gaussian blurs, and an edit recomputes only the tiles the effects reach. See [docs/layers.md](https://recursiveai.org/oneimage/docs/layers/#layer-styles).
- `RecursiveAI.OneImage.Psd`: layer effects (`lmfx`/`lfx2`) are read into `Layer.Style` and drawn; `PsdLimits.MaxEffectsPerLayer` (32) bounds them, and `PsdLayerInfo.EffectsNotDrawn` / `EffectsApproximated` count what is not reproduced (gradient and pattern overlays and strokes, gradient glows, bevel and emboss, random grain). The effects block is written back byte for byte; saving a layer with a changed style throws `ImageOperationException`. Against the stored composites of the sample files, 10 more files are fully modelled (170, median 0.111 levels); the stroke files went from 15-40 levels to 0.00-0.16, and layer_effects from 108 to 4.6. See [docs/psd.md](https://recursiveai.org/oneimage/docs/psd/#layer-effects).

### Changed

- JPEG decoding is faster, with identical output. Full size: the per-row transform is split in two (inverse DCT; then upsampling, color conversion and delivery) and, with three or more cores, each runs on its own thread beside the entropy decoder; with two cores the entropy thread does the inverse DCT itself, and progressive or multi-scan frames overlap the delivery with the transform. A 24 MP 4:2:0 photograph decodes into a reused buffer in 32 ms (was 44-55 on the same loaded worker; ImageSharp 82-97); noisy 8.9 MB files stay entropy-bound at 43 ms, and a smooth 2 MB one goes from 34 to 20 ms on a desktop host. The entropy decoder may now fail on data past the last row a request needs without failing the request, as the single-threaded path never read it. Restart markers: the restart intervals of baseline Huffman scans (1 MP or more) are entropy-decoded on worker threads at the per-call degree, then delivered in order; damaged files give the same rows and the same exception as before. A 24 MP 4:2:0 file with one interval per MCU row decodes in 25.5 ms instead of 32.3 ms at full size and in 9.0 ms instead of 27.0 ms at 1/8 (thumbnail 400 px: 9.0 ms instead of 27.1 ms); files without restart markers are unchanged. Reduced sizes: the 4x4 and 2x2 inverse DCTs of 1/2 and 1/4 scale decoding run on 128-bit vectors (SSE/AVX2 hosts and ARM64 AdvSimd) with scalar references, for 8-bit and 12-bit samples; a 4x4 block takes 26 ns instead of 72 and a 2x2 block 20 ns instead of 32, and a 24 MP decode at 1/2 goes from 38.9 to 31.9 ms (the entropy floor of that file, so 1/4 and 1/8 do not change). 128-bit transforms: the full-size inverse DCT and the forward DCT with quantization have an SSE2/SSE4.1 and AdvSimd path between AVX2 and scalar, bit-identical to both. With AVX2 turned off, a 24 MP decode takes 47 ms (was 79) and a q90 encode 179 ms (was 225); AVX2 times are unchanged. Decode hashes of the sample corpus and of 24 MP files at every scale and hardware setting are the same as before. `tools/JpegHash` writes the test files and prints decode hashes for comparing two builds.
- JPEG encoding is faster, with byte-identical output. Color conversion and chroma averaging use vector kernels, quantized blocks are reordered by placing only their non-zero values, and without restart markers each worker takes the next MCU row and does all of its work (so there is no barrier between stages, and symbol counts are gathered in the same pass as the transform). Finished rows are appended to the output by whichever worker is free. A 24 MP q90 4:2:0 encode with optimized tables takes 51.7 ms at the default degree (was 82.8; ImageSharp 101.7, NetVips 53.3), the gate peak memory went from 4.9 to 3.1 MiB, and a 3 MP encode from 7.3 to 5.2 ms.
- TIFF reading is faster, with identical pixels at every degree and hardware path. Whole-frame reads of a frame of 1 Mpixel or more (`CopyPixelsTo`, `ToArray`) decode strips and tiles in parallel straight into the caller's buffer instead of through 128×128 tiles; blocks are handed out one at a time and returned to the pool as soon as they are converted, so memory stays at a few blocks per thread. MSB-first LZW strips (the usual TIFF kind) go through a whole-block decoder that holds short strings inline, and the 8-bit horizontal predictor is undone with a vector prefix sum; on a corrupt block whose output is already full, a trailing bad code is now ignored, as libtiff does. The 10-page 2000×1500 LZW read takes 46.9 ms at the default degree (was about 60 before the LZW work and 49.9 after it) and allocates 92 KB (was 965); at 8 threads 32.0 ms and on all cores 27.1 ms (NetVips 26), measured on the benchmark worker under load from other jobs. Smaller frames, region reads and frames with a strip over 16 MiB of raw samples keep the tile path. The tile-to-buffer copy of a computed image was measured at 1.9 times a contiguous copy of the same bytes (6.1 ms for 24 MP Rgba32 at the default degree) and left as it is; see [docs/performance.md](https://recursiveai.org/oneimage/docs/performance/#whole-frame-copy-out).
- WebP encoding needs much less working memory, with byte-identical output. A lossy still image is converted to the encoder's YUV planes strip by strip instead of through a whole-frame RGBA copy (alpha is gathered, one byte per pixel, only if some pixel is translucent); the lossless encoder packs its 32-bit pixels band by band the same way. The lossy encoder no longer keeps whole reconstructed planes (only the last line of each macroblock row and the row being coded), stores the quantized levels compactly (about 1/4 of their former size on a noisy photograph), writes its partitions in 64 KiB chunks instead of doubling arrays, and the file is written to the destination chunk by chunk rather than assembled first. Peak working memory of a 24 MP lossy q75 encode went from 304 to about 101 MB (SkiaSharp 87, Magick.NET 173, NetVips 237, ImageSharp 1450); a 3 MP lossy encode from 22 to 5 MB; a 24 MP lossless encode from 1055 to 851 MB (and to 377 MB by the lossless-state work below). See [docs/performance.md](https://recursiveai.org/oneimage/docs/performance/#webp-encode-memory).
- The lossless WebP encoder needs less than half the working memory, with byte-identical output. Its transforms run in place on the packed pixels, matches are stored instead of one token per pixel, hash chains cover only the last 2^20 pixels, and the output is written into one array of its exact size. Peak working memory of a 24 MP lossless encode went from 852 to 377 MB (SkiaSharp 663, Magick.NET 737) and a 3 MP one from 107 to 46 MB; time did not change beyond noise (24 MP: 1.07 s to about 0.96 s on the benchmark worker). See [docs/performance.md](https://recursiveai.org/oneimage/docs/performance/#lossless-encoder-state).
- `RecursiveAI.OneImage.Psd`: posterize, curves and brightness/contrast layers read from PSD files use Photoshop's formulas, and brightness/contrast in Photoshop's current mode is read from its `CgEd` descriptor (it was read as no adjustment). Against the stored composites of 19 sample files the median mean error went from 10.5 to 0.005 levels, and the median over the 152 fully modelled files from 0.275 to 0.134. A model-built posterize, curves or brightness/contrast adjustment saved to PSD reads back with those formulas. See [docs/psd.md](https://recursiveai.org/oneimage/docs/psd/#adjustment-formulas).

### Fixed

- `RecursiveAI.OneImage.Psd`: a hue/saturation adjustment with saturation or lightness outside -100..100 (found by fuzzing) is kept and not reproduced instead of throwing an argument exception when the file is loaded.
- `bench/gate.sh --skip-peak` no longer crashes while writing its report.

### Known limitations

- Known limitations of the PSD package: saving a PSD after a layer style was edited or added throws `ImageOperationException`, and so does saving after a gradient or pattern fill's brush was replaced; writing layer styles from the model is not built yet. A style or fill left unchanged is written back byte for byte. See [docs/psd.md](https://recursiveai.org/oneimage/docs/psd/#known-limitations).

## [1.4.0] - 2026-10-23

### Added

- `OneImage.Layers`: a layered document that renders on demand. `Document` holds pixel layers (a `Canvas` at an offset), pass-through and isolated groups, fill layers (solid or gradient brush) and adjustment layers (`Adjustment.Levels`, `Curves`, `HueSaturation`, `ColorMatrix`, ...), each with visibility, opacity, fill opacity, any `BlendMode`, a raster mask (density, feather, outside value), clipping to the layer below and lock flags. `Document.Render()` is a lazy `Image`; a stack of layers renders to exactly the bytes of the equivalent chain of `Composite` calls. `Snapshot()` takes O(layers) and finds the tiles that changed by comparing canvas tile tables, so a re-render after an edit recomputes only the dirty tiles. Layers and documents have serializable descriptions with language-neutral names. See [docs/layers.md](https://recursiveai.org/oneimage/docs/layers/).
- `DocumentOptions.Spill`: an opt-in disk-spill tile store for a document. Cold tiles move to a temporary file (unlinked on Unix, delete-on-close on Windows) under a byte budget and come back on demand.
- `RecursiveAI.OneImage.Psd` (new package, namespace `OneImage.Psd`): Photoshop PSD and PSB. `PsdFormat` reads the merged image (gray, RGB, indexed, bitmap, CMYK, Lab; 8, 16 and 32 bits; raw, RLE and ZIP channels) as an ordinary `Image` and writes flat documents; `PsdFile` loads the layer tree into an `OneImage.Layers.Document` (pixel layers with offsets, groups, blend modes, opacity and fill opacity, raster and vector masks, clipping, solid fills, levels/curves/hue-saturation/brightness-contrast/exposure/invert/threshold/posterize adjustments) and writes it back, keeping what the model cannot express as blocks (text, smart objects, layer effects, gradient and pattern fills and vector strokes render from their stored pixels and are written back untouched; multichannel documents are refused). Limits for every size read from the file, a `psd` fuzz target and a crafted file per limit. See [docs/psd.md](https://recursiveai.org/oneimage/docs/psd/).

### Changed

- Layers: rendering is fast and bounded in memory. A layer is composited onto a tile by reading its tiles in place and writing into a tile the render owns, with no per-tile nodes or descriptors, and the disk-spill store reuses an evicted tile's memory as soon as no reader can still hold a span of it, without forcing garbage collections. A cold flatten of 10 full-size 24 MP layers takes 77 ms at the default per-call degree of 4 threads and 34 ms at degree 32, and 50 layers take 361 and 129 ms, allocating 0.25 MB; ImageSharp 3.1.12 takes 72 and 297 ms using every core, so at the default degree this is slower than ImageSharp on those rows (published as an exception in [docs/performance.md](https://recursiveai.org/oneimage/docs/performance/#layer-flatten-exception)). With AVX2 only, 115 and 544 ms. A 100-layer 24 MP document renders in 1.4 s at about 540 MB peak resident under a 256 MiB spill budget. A pass-through group clipped to a layer below draws its layers onto the clip surface one after another, as if each were clipped to the base. See [docs/layers.md](https://recursiveai.org/oneimage/docs/layers/).
- `Image.Composite` of 8-bit RGBA onto 8-bit RGBA with the Normal blend mode and source-over runs a vector kernel with bit-identical output to the float path, at about a fifth of the CPU time. The kernel converts through signed integers (AVX2 has no unsigned conversions, so the old code emulated them) and skips the alpha work over an opaque backdrop, which makes it 6.8 times faster on CPUs with AVX2 but without AVX-512 (12.2 to 1.8 ns per pixel).
- Vector kernels no longer lean on conversions that CPUs without AVX-512 have to emulate. Error-diffusion dithering (`Dither`, `Quantize` with a dither), the luma step of `HistogramEqualization`, the 8-bit color-matrix kernel (`ColorMatrix`, `Sepia`, ...) and the float-path RGBA `Composite` kernel converted unsigned 32-bit lanes to float and back, which AVX2 and SSE do not have; they now go through signed lanes and the non-saturating conversion where the range is known. Output is byte-identical on every hardware path (checked by hash under default, AVX-512 off, AVX2 off and intrinsics off). Per pixel on one thread with AVX-512 off: error-diffusion Floyd-Steinberg 60.8 to 18.5 ns (3.3 times), the equalization luma step 0.35 to 0.18 ns, the color-matrix kernel 2.6 to 1.5 ns, the float RGBA composite kernel 2.15 to 1.12 ns. The color matrix also has a four-pixel path for CPUs with 128-bit vectors only (3.7 to 3.1 ns RGBA, 3.8 to 2.5 ns RGB).
- JPEG entropy decoding is faster, with identical output. AC symbols of images of 256 K pixels or more resolve their Huffman code and magnitude bits with one lookup in a 12-bit table; the bit buffer is topped up once per symbol without a branch on its fill level; and progressive AC scans keep the buffer in locals. At a reduced scale where a component contributes only its DC coefficient (the luma of a 4:2:0 image at 1/8), that component's AC data is read past without being stored, and progressive AC scans of such a component are skipped (before, only images where every component was DC-only did this). A 24 MP 4:2:0 photograph decodes at 1/8 scale in 28 ms (was 38), and a 24 MP CMYK file in 90 ms (was 111) on one host; a 24 MP thumbnail (`thumb-jpeg`) takes 27-28 ms (was 38-40) on the benchmark machine. Full-size 4:2:0 decodes are bound by the transform thread, not by entropy decoding, and are unchanged. Decoded pixels are identical to before at every scale and mode (checked by hash over the test corpus with and without hardware intrinsics, and by a test that compares the lookahead path with the plain tables on good and damaged files).
- Resize costs less CPU, with identical output: a box pre-reduce of 8-bit RGB/RGBA now converts and averages in one pass instead of writing a float row first, the horizontal pass computes four output pixels at a time and the vertical pass four vectors at a time (both hide add latency; every sum keeps its tap order). On a decoded 24 MP image at the default degree, 24 MP to 400 px takes 8.8 ms (was 11.5) and a 3x reduction 25.3 ms (was 30.0).
- `RecursiveAI.OneImage.Svg`: filter speed. Gaussian blur and the 8-bit/float/linear-light conversions of filters run on AVX kernels with scalar references and byte-identical output (a 1024 px blur of 400 shapes 10.7 ms against 33.5, a 4096 px blur 156 ms against 491, a drop shadow 17.8 ms against 44.1); the blur works in place without a second buffer, skips empty lines and runs in parallel bands.

## [1.3.0] - 2026-10-22

### Added

- `AlphaComposition.Plus` (descriptor name `plus`): the Porter-Duff plus operator, CSS `plus-lighter`. Premultiplied color and alpha of overlay and backdrop add and clamp at 1; an empty overlay leaves the backdrop, and an opaque backdrop stays opaque.
- `OneImage.Text`: right-to-left text. The Unicode Bidirectional Algorithm (UAX #9, Unicode 17) runs per paragraph, lines are reordered after wrapping, and `TextOptions.TextDirection` (`Auto`, `LeftToRight`, `RightToLeft`) sets the base direction. `TextAlignment.Start` and `End` follow the paragraph direction. Left-to-right text without right-to-left characters skips the algorithm.
- `OneImage.Text`: an Arabic joining shaper (also used for Syriac and N'Ko) with per-glyph form features, and Hebrew with points and cantillation marks.
- `OneImage.Text`: complex-script shaping. An Indic shaper (Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam: syllables, reph, half forms, pre-base matras, split vowels, dotted circle for broken clusters), a Universal Shaping Engine shaper (Khmer, Myanmar, Sinhala, Tibetan, Balinese, Javanese and the other USE scripts) and Thai/Lao shaping (SARA AM). Unicode property tables for them are generated by `tools/gen_unicode_tables.py`. Syllable length, reordering and run size are bounded. Line breaking for Thai, Lao, Khmer and Myanmar stays UAX #14 without dictionaries. Against SixLabors.Fonts 2.1.3 on 1,042 cases in 17 Noto subsets, 897 match exactly, 119 differ deliberately (listed with reasons in `docs/text.md`) and the reference throws on 26. A Devanagari paragraph measures in 1.4 ms against 4.0 ms and draws in 2.5 ms against 10.2 ms; a Khmer paragraph 0.53 against 2.8 ms and 1.4 against 7.0 ms (local smoke, loaded host). A `complex` fuzz target covers the shapers.
- `OneImage.Text`: vertical and bottom-to-top layout (`TextOptions.LayoutMode`, with the members of SixLabors.Fonts' enum), from `vhea`, `vmtx`, `VORG`, the `vert`/`vrt2` features and the UAX #50 orientation property; TrueType hinting (`TextOptions.HintingMode.Standard` runs the font's instructions at the drawing size, y positions only, under hard limits; measuring is unchanged); and COLR version 1 paint graphs (gradients, transforms, clips, composite modes) painted by `DrawText`. Compared with SixLabors.Fonts 2.1.3 (vertical: 296 of 296 measurement cases; hinting: mean 0.45 against 1.47 levels unhinted at 9-16 px) and SkiaSharp (COLR v1: mean 0.36 levels). `fuzz/run.sh font` covers hinting and paint graphs. See `docs/text.md`.
- Tests run the official `BidiTest.txt` and `BidiCharacterTest.txt` in full and compare glyphs and layout with SixLabors.Fonts 2.1.3; a `bidi` fuzz target covers mixed-direction text.
- `RecursiveAI.OneImage.Svg` (new package): SVG and gzip `.svgz` as an image format, registered with `new ImageConfiguration().Add(SvgFormat.Instance)` (not part of `ImageConfiguration.Default`, so it trims away when unused). It is drawn directly at the size you ask for, one region at a time (see `DecoderCapabilities.RenderAtSize` below), as 8-bit sRGB RGBA. It draws shapes and paths with fills and strokes (caps, joins, dashes, `paint-order`), linear and radial gradients (focal point, `spreadMethod`, `href` inheritance) and patterns, markers, opacity, `mix-blend-mode` with every CSS blend mode and `isolation`, transforms and `transform-origin`, nested `svg`, `use` and `symbol`, `clipPath` and `mask`, `<style>` sheets (type, class, id, attribute, combinator and structural selectors, specificity, `!important`), `switch` with `systemLanguage`, `data:` images (any raster format the library reads, and nested SVG), all filter primitives and the CSS filter functions, and text (`tspan`, `textPath`, per-character positioning, bidirectional and vertical text, decorations, fallback, paint servers on text, text as a clip) with fonts from `SvgFontOptions` (files, bytes, streams, generic families, installed fonts; `DefaultFontSize` is 16, the CSS `medium` size). It never does I/O: external references, `@font-face`, scripts, SMIL animation and `foreignObject` are not loaded or run, and the XML parser (our own, iterative) refuses DTDs and entity declarations. Documents are untrusted: `SvgLimits` bounds document size, elements, nesting, attributes, style sheets and matching work, path segments, `use` fan-out and reference depth, layers, pattern tiles, embedded images, filter size and text, a document that exceeds one fails with `ImageLimitException` before the memory is allocated, and every limit has a hostile-document test. The XML, path-data and render fuzz targets ran clean. Against the public test collection of the resvg project (its files and reference PNGs only; a test passes at no more than 0.25% of pixels differing by more than 24 of 255 over white), 1,513 of 1,706 files pass (88.7%): shapes 128 of 133, painting 277 of 307, structure 197 of 230, paint-servers 146 of 154, masking 91 of 93, filters 395 of 406 (97.3%), text 279 of 383 (72.8%; variable and color fonts are not supported). Edge-only failures come from exact-area anti-aliasing against the reference's supersampling. An icon at 256 px renders in 141 µs including the load and a 3,000-shape illustration at 1024 px in 25 ms, against 363 µs and 79 ms for Svg.Skia 5.2.3. See `docs/svg.md`.
- `OneImage.Text`: `TextShaping` (`GetBidiLevels`, `GetVisualOrder`, `ShapeRun`, `IsUprightInVerticalText`), `ShapedCluster` (advance, outline, `VerticalAdvance`, `GetUprightOutline`), `ShapingOptions` (including `Vertical`) and `FontFaceInfo`, for callers that lay text out themselves: shaped clusters with their advances and outlines, one bidirectional paragraph at a time, upright or rotated in a vertical column.
- `OneImage.Text`: subtables the shaping engine cannot use now count against a run's work budget, so a font with lookups of tens of thousands of them no longer costs seconds per run (a fuzz-found font that took 3.5 s per 1,200 glyphs now takes milliseconds; shaping results are unchanged).
- `Brush.LinearGradient(..., Matrix3x2 transform, ...)` places a gradient through an affine transform; `Brush.RadialGradient(center, radius, focalCenter, focalRadius, ...)` is a two-circle (focal) gradient with an optional transform; `Brush.FromImage(source, ImageSampling.Bilinear, ...)` reads an image brush with bilinear sampling on premultiplied color (new `ImageSampling` enum). The existing brushes are unchanged.
- `DecoderCapabilities.RenderAtSize` and `DecodeRequest.TargetWidth`/`TargetHeight`: a vector decoder is asked for the frame at its final size when a resize sits directly on the load, so nothing is scaled as a raster.
- `Image.ApplyMask(mask, channel, x, y, linear)` and `MaskChannel`: multiplies an image's coverage by a per-pixel mask taken from another image (its alpha, or its luminance times alpha), lazily and tile by tile; everything outside the mask becomes transparent. This is the layer-mask operation the SVG renderer composites masked groups with.

### Changed

- Tiles replaced by a write after `Canvas.Snapshot()` are reference counted. When a snapshot's tile table has outlived a collection, its tiles go back to the tile pool once the last snapshot reading them is collected, instead of being left to the garbage collector; `Canvas.Dispose` and `Image.FromPixels` do the same at once. Ten whole-frame draws on a 24 MP canvas, each after a dropped snapshot, allocate about 400 MB instead of about 940 MB, and in-place draws after a snapshot on a 2000 x 2000 canvas allocate a third less. Snapshots that are dropped within one collection are not tracked, so small edits cost what they did.
- `Resize` with `Fit.Cover` pushes its crop down to a decoder that can produce a region.
- Drawing and SVG rendering cost less per shape: a `Canvas` fill reuses its flattened path, edge table and buckets from one fill to the next on a thread, the tile rasterizer sums and clears only the accumulator cells an edge touched, tile workers no longer share one scratch bag, and 8-bit/float RGBA row conversion skips its temporary float rows. Output is unchanged. In `RecursiveAI.OneImage.Svg`, opacity and blend layers are read in place and give their tiles back to the pool, which cuts the allocation of a blend-heavy drawing from 65 MB to 7 MB per render; an icon at 256 px renders in 118 µs (298 µs before) and the 3,000-shape illustration in 11.5 ms (25.2 ms).
- Packaging: `RecursiveAI.OneImage.Text` and `RecursiveAI.OneImage.Svg` use internals of the packages they build on, so they now depend on the exact version they were built with (`[x.y.z]` of `RecursiveAI.OneImage`, and of `RecursiveAI.OneImage.Text` for Svg) instead of "x.y.z or later"; upgrading the core package alone can no longer end in a `MissingMethodException`. `RecursiveAI.OneImage.Web` keeps its range.

## [1.2.0] - 2026-10-22

### Added

- `RecursiveAI.OneImage.Text`, a separate package for fonts and text: `FontCollection` loads TrueType, OpenType/CFF, TrueType Collections and WOFF 1.0 (own inflate); `TextOptions` (origin, wrapping, line spacing, tab width, dpi, horizontal, vertical and text alignment, kerning), `TextMeasurer` (advance, ink bounds, lines, character boxes), `TextBuilder.GeneratePath` (text as a `Path`) and `DrawText` on `Image` and `Canvas` with a brush and/or pen. Outlines, advances, kerning, line counts and bounds match SixLabors.Fonts 2.1.3; rendering agrees with ImageSharp.Drawing 2.1.7 DrawText to coverage differences. See `docs/text.md`. A fuzz target `font` covers the parsers.
- OpenType shaping in `RecursiveAI.OneImage.Text`: GDEF glyph classes and mark filtering sets, GSUB lookup types 1-8 and GPOS types 1-9 with all lookup flags, so ligatures (`fi`, `ffl`), `ccmp` compositions, language forms (`locl`), contextual alternates, pair kerning and mark positioning on bases, ligatures and other marks work for Latin, Greek and Cyrillic. `TextOptions.Features` (`FontFeature.On("smcp")`, `Off("liga")`, alternates by value) and `TextOptions.Language` choose features and language forms; `KerningMode.None` is the `kern` feature off. Lookups are bounded in depth, work and growth, and damaged layout tables are ignored. Glyph ids and origins match SixLabors.Fonts 2.1.3 on Noto Sans; measuring and drawing a ligature-heavy paragraph is 8x and 19x faster. See `docs/text.md`.
- Unicode text segmentation in `RecursiveAI.OneImage.Text`: wrapping now ends lines at the break opportunities of the Unicode line breaking algorithm (UAX #14, Unicode 17.0: spaces, hyphens, soft hyphen, zero width space, no-break space and word joiner, quotation marks and brackets, numbers, East Asian text, Korean syllables, emoji sequences, flags), and never inside an extended grapheme cluster (UAX #29): `GetCharacterBounds` returns one box per cluster. New `TextOptions.WordBreaking` (`Standard`, `BreakAll`, `KeepAll`, `BreakWord`) and `TextOptions.TextJustification` (`None`, `InterWord`, `InterCharacter`), with ImageSharp's names and behavior. The property tables (72 KB) are generated from the Unicode Character Database by `tools/gen_unicode_tables.py`; `LineBreakTest.txt` (19,338 cases) and `GraphemeBreakTest.txt` (766 cases) pass in full. Ordinary text wraps at the same places as SixLabors.Fonts 2.1.3 (1,590 cases, none different), and justification matches it to 0.0001 px; text with break opportunities inside words differs, and `docs/text.md` lists why.
- Rich text, font fallback, text on a path and installed fonts in `RecursiveAI.OneImage.Text`. `TextOptions.TextRuns` (`TextRun`: its own font and size, `TextAttributes` super- and subscript, `TextDecorations` underline, strikeout and overline at the font's positions and thicknesses, brush, pen and per-decoration pens) works through layout, measuring, `TextBuilder.GeneratePath` and `DrawText`; lines mix sizes and faces. `TextOptions.FallbackFontFamilies` shapes characters a font lacks in the first fallback family that has them. `TextOptions.Path` lays text along a `Path`, rotating each glyph to the tangent, with open paths continued straight and closed ones wrapped. `SystemFonts` / `SystemFontSet` find installed fonts by scanning the standard directories of Windows, macOS and Linux, reading only name tables until a family is requested. Glyph ink boxes, advances, line counts and decoration segments match SixLabors.Fonts 2.1.3 to 0.01 px or better and text on a path matches ImageSharp.Drawing 2.1.7 to 0.001 px on lines; the differences (wrapping with fallback, nested runs, one reference kerning quirk, closed-path edges) are listed in `docs/text.md`. Run counts (16,384), fallback families (32), scan depth and file counts are bounded. Color glyphs (COLR v0) work inside runs and in fallback faces: a run's brush fills the foreground layers, layers with their own color keep it, and the pens draw last. New fuzz targets `richtext` and `sysfont`.

### Changed

- Strokes whose outline lies on itself along an edge (a path that doubles back, a closed two-point figure, a cusp) are drawn with the coverage of the union, not the sum: their edge pixels were up to twice as dense. The outline is merged only when such a turn (sharper than about 172 degrees) occurs, so other strokes are unchanged in output and time (stroke benchmark rows within noise).
- `Canvas.Fill(..., linear: true)` (and `Draw` with `linear: true`) no longer reads the canvas through a public snapshot: without an outside snapshot it swaps in fresh pooled tiles and returns the replaced ones, and it gives back the tiles its one-shot graph cached, which used to fill the shared tile cache (up to its 256 MiB budget) until the canvas was collected. A linear-light fill of a circle on a 2000 x 2000 canvas allocates 65 MB instead of 82 MB, with identical output. The color for a linear-light solid fill is now computed without leaving a pooled tile behind.
- Linear-light fills and strokes (`linear: true`) on 8-bit gray and RGB images and canvases without an embedded profile now decode, blend and encode only the covered pixels instead of converting whole tiles to float. On a 2000 x 2000 Rgba32 image a solid circle fill took 74 ms and allocated 52 MB, and on a canvas 242 ms and 65 MB; now both take about 2 ms (encoded: 1.9 and 1.3 ms) and allocate 24 KB. Gradient, Multiply and stroke fills are within 1.5x of their encoded cost. Output agrees with the whole-tile conversion path to 1 level at 8 bits (untouched pixels are now never rewritten). Other formats and images with an embedded profile keep the whole-tile path.
- `Canvas.Clip` no longer copies tiles through a public snapshot: it swaps in fresh pooled tiles and returns the replaced and cached ones to the pool. A blur clipped to a circle on a 2000 x 2000 canvas allocates 88 KB instead of 9.6 MB, at the same speed and with identical output.

- WOFF 2.0 fonts in `RecursiveAI.OneImage.Text`: `FontCollection.Add` and `AddCollection` read single fonts and collections, with the transformed `glyf`/`loca` and `hmtx` tables, on the package's own Brotli decoder (RFC 7932, safe managed code; the BCL decoder is native and is not used). Declared sizes and expansion are bounded before anything is allocated. Faces, outlines, advances, kerning and shaping equal the source fonts'. A fuzz target `brotli` joins `font`. See `docs/text.md`.
- Color glyphs in `RecursiveAI.OneImage.Text`: `TextOptions.ColorFontSupport` (`MicrosoftColrFormat` by default, as in SixLabors.Fonts; `None` turns it off) and `ColorPaletteIndex` make `DrawText` on `Image` and `Canvas` paint COLR version 0 layers with CPAL palette colors or the brush (palette index 0xFFFF); `Font.ColorPaletteCount` and `Font.HasColorGlyph`. Matches ImageSharp.Drawing 2.1.7 to a mean of 0.07 levels on a layered test font. COLR version 1 glyphs draw as their plain outline. Text as a path stays monochrome.

## [1.1.0] - 2026-10-22

### Added

- Vector drawing foundation (`OneImage.Drawing`): `Path`, `PathBuilder` (lines, quadratic and cubic Béziers, SVG elliptical arcs), shape factories (rectangle, rounded rectangle, ellipse, circle, polygon, regular polygon, star, combine), transforms, reverse, length, bounds, flattening, and strict bounded SVG path-data parsing (`Path.TryParseSvg`). `Image.Fill`, `Image.Clear`, `Canvas.Fill` and `Canvas.Clear` fill paths with a solid `Brush`: exact-area anti-aliasing (or none), non-zero and even-odd rules, blend modes, Porter-Duff operators, opacity, a transform, and linear-light blending. `Image` fills are lazy and a run of fills computes in one pass; `Canvas` fills draw in place in parallel with identical bytes. See `docs/drawing.md`. A fuzz target `svg` covers the path parser.
- Strokes: `Image.Draw` / `Canvas.Draw` with a `Pen` (any brush, width, `StrokeJoin` Miter/Round/Bevel/Square with a miter limit, `StrokeCap` Butt/Round/Square, dash patterns with offset, presets Dash/Dot/DashDot/DashDotDot) or a color and width; helpers `DrawLine`, `DrawPolyline`, `DrawPolygon`, `DrawBeziers`, `DrawRectangle`, `DrawEllipse`; and `Path.GenerateOutline` returning the stroke as a `Path`. Overlapping parts of one stroke are painted once, so translucent pens are even. 6 to 7 times faster than ImageSharp.Drawing on strokes with a fifth to a quarter of the allocation; see `docs/drawing.md`.
- Brushes for fills (`OneImage.Drawing.Brush`): linear, radial and elliptic gradients with color stops and the repetition modes none, repeat, reflect and dont-fill; a path gradient; pattern brushes with the hatch presets (horizontal, vertical, forward and backward diagonal, 10%, 20%, min); an image brush with region, offset, transform and tiling; and a recolor brush. Gradients interpolate premultiplied colors in encoded values by default and blend in linear light with `linear: true`, which now works with every brush. `Brush` is public to derive from: implement `FillRow` (and `ReadsBackdrop` for brushes that read the existing pixels). Opaque brush colors over fully covered pixels are written directly, through a vector kernel for 8-bit RGBA. Agrees with ImageSharp.Drawing 2.1.7 to rounding on every brush and mode; see `docs/drawing.md` for the differences.
- `Image.Composite(..., blend:, alpha:)`: all 24 Photoshop/W3C blend modes (`BlendMode`: Multiply, Screen, Overlay, Darken, Lighten, Color Dodge/Burn, Hard/Soft/Vivid/Linear/Pin Light, Hard Mix, Difference, Exclusion, Add, Subtract, Linear Burn, Divide, Hue, Saturation, Color, Luminosity) and the twelve Porter-Duff operators (`AlphaComposition`). Normal source-over output is unchanged.
- `Image.Perspective`: a projective (perspective) transform from a `ProjectiveMatrix`, a `ProjectiveTransformBuilder` (taper, rotation, scale, skew, translation, matrices, with `Append` and `Prepend` forms) or four corner points. `ProjectiveMatrix` also builds quad-to-quad maps.
- `Fit.BoxPad` and `Fit.Min` (ImageSharp's `ResizeMode.BoxPad` and `Min`), the aliases `Fit.Max` and `Fit.Crop`, and `Image.ResizeInto` for resizing into a rectangle of a canvas (`ResizeMode.Manual`).
- Resampling filters `Hermite`, `Lanczos5`, `Lanczos8`, `Robidoux`, `RobidouxSharp`, `Spline` and `Welch`, with the aliases `Bicubic` and `Triangle`, in `Resize` and in the rotate, affine and perspective samplers.
- Neighbourhood effects, matching ImageSharp 3.1.12: `Pixelate`, `OilPaint`, `Vignette`, `Glow`, `BokehBlur`, `GaussianSharpen`, `DetectEdges` (`EdgeDetector`: Sobel, Prewitt, Scharr, RobertsCross, Kayyali, Laplacian3x3/5x5, LaplacianOfGaussian, Kirsch, Robinson) and `EntropyCrop`. `OilPaint` centers its window, where ImageSharp's is shifted; see the migration guide.
- Color matrix: `Image.ApplyColorMatrix(ColorMatrix)` with a public `ColorMatrix` (ImageSharp's 5x4 layout), and the looks built on it: `Sepia`, `BlackWhite`, `Kodachrome`, `Lomograph`, `Polaroid`, `ColorBlindness(ColorBlindnessMode)` and `Opacity`. `Lomograph` and `Polaroid` include ImageSharp's vignette and glow; `ColorMatrix.Lomograph` and `.Polaroid` are the plain matrices. They fuse with the other color ops into one pass per tile, and a color chain directly on a decode now runs on rows as they are decoded when the whole frame is read at once.
- `Image.HistogramEqualization`: global, adaptive tile interpolation and adaptive sliding window equalization with histogram clipping, luminance levels and tile count, matching ImageSharp 3.1.12 within 1 level at 8 bits (`HistogramEqualizationMethod`). The luminance is mapped and written to all color channels, as in ImageSharp.
- `RecursiveAI.OneImage.Web`, a separate package with ASP.NET Core middleware for on-the-fly image processing (`AddOneImage()` / `UseOneImage()`): URL commands for size, fit, anchor and focal point, filter, background, format, quality and orientation, with ImageSharp.Web query names accepted too; presets and a presets-only mode; web root, folder, `IFileProvider` and custom providers; a disk cache with configurable layout, ETag and Last-Modified validators with 304 answers, source-change invalidation and single processing of concurrent identical requests; HMAC-signed URLs with a signer and a Razor tag helper; request hooks; and size, source and concurrency limits. See `docs/web.md`.
- Histograms, thresholds and dithering, matching ImageSharp 3.1.12: `Image.AutoLevel`, `Image.AdaptiveThreshold`, and a public `Image.Dither(palette, dither, scale, fastMatch)` (`fastMatch` defaults to true: ImageSharp's order-dependent cell matching, bit-identical to its output; `false` matches each pixel exactly) and `BinaryDither`. The `Dither` enum gains Atkinson, Burkes, JarvisJudiceNinke, Sierra2, Sierra3, SierraLite, StevensonArce, Stucki, Bayer2x2, Ordered3x3, Bayer4x4, Bayer8x8 and Bayer16x16 (they also work in `Quantize` and the GIF encoder). `Quantizer` (Wu, Octree, WebSafe, Werner) selects the palette builder in `Quantize` and `GifEncoderOptions.Quantizer`, and `KnownPalettes.WebSafe` and `KnownPalettes.Werner` are public. Existing GIF and indexed-PNG output is unchanged.
- Boolean operations on paths: `PathBoolean` (`path.Boolean(BooleanOperation, other, ...)`, `Union`, `Intersect`, `Subtract`, `Xor`, `UnionAll`, `Resolve`, `Offset`) with exact integer geometry on a 1/256 px grid, per-operand non-zero or even-odd rules, and polygon results without overlaps. `Image.Clip(path, operations)` / `Canvas.Clip` run any operations only inside a path with anti-aliased edges, and `Fill` / `Draw` take `clip:` to limit a shape to a clip path. A 200-circle union takes 7 ms against ImageSharp.Drawing's 11 ms with one seventh of the allocation, and a Gaussian blur clipped to a circle on 2000 x 2000 takes 12-13 ms against 56 ms; see `docs/drawing.md`.

## [1.0.0] - 2026-10-22

First release, published on NuGet as `RecursiveAI.OneImage` (namespace `OneImage`).

### Added

- Lazy, immutable `Image` and mutable tiled `Canvas` on one engine, with O(1) snapshots.
- Codecs: PNG (including APNG and indexed output), JPEG (baseline, progressive, arithmetic, 12-bit, CMYK, shrink-on-load), WebP (lossy, lossless, animation), GIF (animation, quantizing, dithering), TIFF (including BigTIFF, CCITT and multi-page), BMP and ICO.
- ICC color management (v2 and v4 profiles, built-in profiles, a generic CMYK profile), resampling in linear light, geometry, tone and filter operations, analysis, and normal-mode compositing.
- `Image.Thumbnail`, which applies EXIF orientation, converts to sRGB and strips EXIF, XMP and IPTC by default.
- Size limits on by default, checked from headers before allocation; typed exceptions; a fuzz target for every decoder and parser.
- Depends only on the .NET base class library; NativeAOT- and trim-compatible.
- Documentation: a guide, a migration guide from ImageSharp and System.Drawing, a comparison with other libraries, and a [performance page](https://github.com/recursive-ai-oss/oneimage-csharp/blob/v1.0.0/docs/performance.md) with the benchmark method and every loss.

[Unreleased]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.10.1...HEAD
[1.10.1]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.10.0...v1.10.1
[1.10.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.9.0...v1.10.0
[1.9.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.8.1...v1.9.0
[1.8.1]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.8.0...v1.8.1
[1.8.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.7.0...v1.8.0
[1.7.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.6.0...v1.7.0
[1.6.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.5.0...v1.6.0
[1.5.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.4.0...v1.5.0
[1.4.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.3.0...v1.4.0
[1.3.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.2.0...v1.3.0
[1.2.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/recursive-ai-oss/oneimage-csharp/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/recursive-ai-oss/oneimage-csharp/releases/tag/v1.0.0