Olve.OpenRaster 0.38.0

Olve.OpenRaster

Lightweight, read-only access to OpenRaster (.ora) files in native C#. OpenRaster is a layered image format used by digital painting applications like GIMP and Krita.

Installation

dotnet add package Olve.OpenRaster

Overview

Usage

Reading an OpenRaster file

ReadOpenRasterFile opens an .ora file, parses stack.xml, and returns the full layer hierarchy.

// ../../tests/Olve.OpenRaster.Tests/ReadmeDemo.cs#L13-L22

var operation = new ReadOpenRasterFile();
var request = new ReadOpenRasterFile.Request(filePath);

var result = operation.Execute(request);
if (result.TryPickValue(out var file, out var problems))
{
    Console.WriteLine($"Version: {file.Version}");
    Console.WriteLine($"Canvas: {file.Width}x{file.Height} @ {file.XResolution} DPI");
    Console.WriteLine($"Layers: {file.Layers.Count}, Groups: {file.Groups.Count}");
}

Inspecting layers and groups

Each Layer carries its metadata from the .ora file. Layers track which Groups they belong to, and groups track their contained Layers.

// ../../tests/Olve.OpenRaster.Tests/ReadmeDemo.cs#L39-L50

foreach (var layer in file!.Layers)
{
    Console.WriteLine($"  {layer.Name} ({layer.Source})");
    Console.WriteLine($"    opacity={layer.Opacity}, visible={layer.Visible}");
    Console.WriteLine($"    position=({layer.X}, {layer.Y})");
    Console.WriteLine($"    blend={layer.CompositeOperation.Key}");
}

foreach (var group in file.Groups)
{
    Console.WriteLine($"  Group: {group.Name} ({group.Layers.Count} layers)");
}

Reading a layer image

The library does not bundle an image decoder. Instead, ReadLayerAs<T> delegates to your ILayerParser<T> implementation, so you can use whichever image library you prefer.

For example, using the BigGustave PNG library:

// ../../tests/Olve.OpenRaster.Tests/ReadmeDemo.cs#L142-L151

public class PngLayerParser : ILayerParser<Png>
{
    public Result<Png> ParseLayer(Stream stream)
    {
        var ms = new MemoryStream();
        stream.CopyTo(ms);
        ms.Position = 0;
        return Png.Open(ms);
    }
}

Then read a specific layer by its source path (found on Layer.Source):

// ../../tests/Olve.OpenRaster.Tests/ReadmeDemo.cs#L63-L70

var parser = new PngLayerParser();
var request = new ReadLayerAs<Png>.Request(filePath, "data/layer0.png", parser);

var result = new ReadLayerAs<Png>().Execute(request);
if (result.TryPickValue(out var png, out _))
{
    Console.WriteLine($"Layer image: {png.Width}x{png.Height}");
}

Composite operations

Each layer and group carries a CompositeOperation describing how it blends with layers beneath it. A CompositeOperation combines a BlendingFunction (how colors mix) with a CompositingOperator (how alpha channels interact), following the W3C Compositing and Blending specification.

All standard OpenRaster blend modes are supported:

You can also parse a composite operation from its SVG key string:

// ../../tests/Olve.OpenRaster.Tests/ReadmeDemo.cs#L81-L86

var result = CompositeOperation.FromKey("svg:multiply");
if (result.TryPickValue(out var op, out _))
{
    Console.WriteLine(op.BlendingFunction);    // Multiply
    Console.WriteLine(op.CompositingOperator); // SourceOver
}

Error handling

All operations return Result<T> from Olve.Results instead of throwing exceptions. Use TryPickValue or TryPickProblems to inspect outcomes:

// ../../tests/Olve.OpenRaster.Tests/ReadmeDemo.cs#L95-L103

var operation = new ReadOpenRasterFile();
var request = new ReadOpenRasterFile.Request("/nonexistent/file.ora");

var result = operation.Execute(request);
if (result.TryPickProblems(out var problems))
{
    foreach (var problem in problems)
        Console.WriteLine(problem.Message);
}

Documentation

Full API reference: https://olivervea.github.io/Olve.Utilities/api/Olve.OpenRaster.html

License

MIT License © OliverVea