https://github.com/olivervea/olve.openraster
A lightweight, read-only C# library for parsing OpenRaster (.ora) files with minimal dependencies.
https://github.com/olivervea/olve.openraster
csharp csharp-library dotnet dotnet-core openraster openraster-image ora
Last synced: 4 months ago
JSON representation
A lightweight, read-only C# library for parsing OpenRaster (.ora) files with minimal dependencies.
- Host: GitHub
- URL: https://github.com/olivervea/olve.openraster
- Owner: OliverVea
- License: mit
- Created: 2025-03-14T12:05:35.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-03-18T06:23:14.000Z (about 1 year ago)
- Last Synced: 2025-09-28T04:59:57.113Z (8 months ago)
- Topics: csharp, csharp-library, dotnet, dotnet-core, openraster, openraster-image, ora
- Language: C#
- Homepage:
- Size: 69.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Olve.OpenRaster
[](https://www.nuget.org/packages/Olve.OpenRaster)[](LICENSE)
The purpose of this library is to provide simple read-only access to `.ora`, or [OpenRaster](https://www.openraster.org/), files, with a simple native C# library with minimal dependencies, in fact, [`Olve.Results`](https://github.com/OliverVea/Olve.Utilities/tree/master/src/Olve.Results), [`Olve.Operations`](https://github.com/OliverVea/Olve.Utilities/tree/master/src/Olve.Operations), and, transiently, `Microsoft.Extensions.DependencyInjection.Abstractions` are the only dependencies of this project.
## Installation
Simply run the following command to add a dependency for the nuget package to your project:
```bash
dotnet add package Olve.OpenRaster
```
## Usage
This package only contains two operations:
### ReadOpenRasterFile
[**`ReadOpenRasterFile`**](Olve.OpenRaster/Operations/ReadOpenRasterFile.cs) reads an `.ora` file and returns the metadata and layer data as an easily-consumable class hierarchy.
```csharp
using Olve.Results;
namespace Olve.OpenRaster.Test;
public static class ReadOpenRasterFile_Example
{
public static void ReadOpenRasterFile()
{
ReadOpenRasterFile operation = new();
ReadOpenRasterFile.Request request = new("map_1.ora");
var result = operation.Execute(request);
if (!result.TryPickValue(out var openRasterFile, out var problems))
{
problems.Prepend(new ResultProblem("could not read OpenRaster file '{0}'", request.FilePath));
foreach (var problem in problems)
{
Console.WriteLine(problem.ToDebugString());
}
return;
}
Console.WriteLine($"Successfully read OpenRaster file '{request.FilePath}' with {openRasterFile.Layers.Count} layers and {openRasterFile.Groups.Count} groups");
}
}
```
### ReadLayerAs
[**`ReadLayerAs`**](Olve.OpenRaster/Operations/ReadLayerAs.cs) takes a layer source string and parses the layer image into the output type `T` with a provided [`ILayerParser`](Olve.OpenRaster/ILayerParser.cs).
```csharp
using BigGustave;
using Olve.OpenRaster;
using Olve.Results;
public static class ReadLayerAs_Example
{
public static void ReadLayerAsPng()
{
PngLayerParser pngLayerParser = new();
ReadLayerAs readLayerAsPng = new();
ReadLayerAs.Request request = new("map_1.ora", "data/002.png", pngLayerParser);
var result = readLayerAsPng.Execute(request);
if (!result.TryPickValue(out var png, out var problems))
{
problems.Prepend(new ResultProblem("could not read layer image '{0}' in file '{1}'", request.LayerSource, request.FilePath));
foreach (var problem in problems)
{
Console.WriteLine(problem.ToDebugString());
}
return;
}
Console.WriteLine($"Successfully decoded {png.Width}x{png.Height} PNG image");
return;
}
}
```
> [!TIP]
> The `ReadLayerAs` operation is a generic operation that can be used to read any layer type, as long as you provide an implementation of `ILayerParser`.
>
> For example, an `ILayerParser` could be used to convert a heightmap layer into a 3D mesh, isolating the logic for this conversion from the rest of your code.
Currently, no default implementations of `ILayerParser` have been added to the library, you will have to convert the byte stream to an image file yourself, but the `.ora` structure is handily abstracted away, so you will most likely only need to parse a `.png` file yourself.
The [`BigGustave`](https://github.com/EliotJones/BigGustave) library is a good candidate for this, as it is a simple and lightweight PNG decoder. Here is an example of how you could implement this:
```csharp
using BigGustave;
using Olve.Results;
namespace Olve.OpenRaster.Test;
public class PngLayerParser : ILayerParser
{
public Result ParseLayer(Stream stream)
{
return Png.Open(stream);
}
}
```
And don't forget to add the `BigGustave` package to your project:
```bash
dotnet add package BigGustave
```
## Future
I want to expand this in the future with:
1. Reading all content. Currently, the following is not supported:
- Thumbnail images
- Merged image
1. Writing operations to both stack and all images.