ImageArchive 1.0.0

ImageArchive

Embed any archive (Git repository, zip, tar, or raw bytes) inside a multi-frame APNG or animated WebP image with a visual header and footer, QR codes, and SHA-256 integrity.

The container format is defined by RFC 1.0.0: docs/ImageArchive-RFC.md.

Features

• Fixed 1024×1024 frames (50 px header, 924 px data, 50 px footer)
• Data region capacity 2,838,528 bytes per frame (RGB, zero-padded final frame)
• Header: free-form text, image, or numbered folder round-robin; top-right QR
• Footer: left QR (frame data SHA-256), Frame N of M + SHA text, right QR (tool commit URL)
• Required camelCase text metadata (encoderName, jsonManifest, jsonSchema, …) plus streamSha256
• Archive types: raw (default), git (compressed tar of .git + worktree), zip, tar
• Default codec path: SkiaSharp raster + real APNG / animated WebP containers
• Multi-target: net8.0;net9.0;net10.0
• Tests: xUnit v3 (unit + integration, including flagship E2E)

Solution layout

ImageArchive.slnx
src/ImageArchive/                 # library
src/ImageArchive.Cli/             # encode / decode CLI
tests/ImageArchive.UnitTests/
tests/ImageArchive.IntegrationTests/
schema/imagearchive-schema.json
examples/example-manifest.json

Build and test

Requires .NET SDK 8, 9, and 10.

dotnet build ImageArchive.slnx
dotnet test ImageArchive.slnx

Nuke build

Bootstrap entrypoints: build.ps1 / build.sh (or dotnet run --project build/_build.csproj --).

# Local
./build.ps1 Compile
./build.ps1 Test --configuration Release
./build.ps1 Pack --configuration Release

# Publish library to nuget.org
./build.ps1 PublishLibrary --configuration Release --nuget-api-key $env:NUGET_API_KEY

# Optional: also publish CLI tool package
./build.ps1 PublishCliTool --configuration Release --nuget-api-key $env:NUGET_API_KEY

# Install CLI tool from local pack output
dotnet tool install ImageArchive.Cli --add-source ./artifacts/packages --version 1.0.0
# then: imagearchive encode --manifest ...

Optional version override: --package-version 1.2.3. Optional source: --nuget-source https://api.nuget.org/v3/index.json.

Planning package check (docs/schema receipt):

pwsh -File docs/verify-planning-package.ps1

CLI

dotnet run --project src/ImageArchive.Cli -- encode --manifest path/to/manifest.json
dotnet run --project src/ImageArchive.Cli -- decode --input archive.png --output extracted.bin

Manifest output.path and output.format (png or webp) control encode output. Optional env IMAGEARCHIVE_TOOL_COMMIT_URL sets the footer right QR.

Library (quick start)

using ImageArchive;
using ImageArchive.Manifest;

var manifest = ManifestJson.Deserialize(File.ReadAllText("manifest.json"));
using var archive = File.OpenRead(manifest.Archive.Source);
using var output = File.Create(manifest.Output.Path);

new ImageArchiveEncoder().Encode(manifest, archive, output, new ImageArchiveEncodeOptions
{
    WorkingDirectory = Environment.CurrentDirectory,
    ToolCommitUrl = "https://github.com/sharpninja/ImageArchive"
});

using var image = File.OpenRead(manifest.Output.Path);
var result = new ImageArchiveDecoder().Decode(image);
// result.ArchiveStream holds the recovered payload

Public entry points include IImageArchiveEncoder / IImageArchiveDecoder, IImageEncoder / IImageDecoder (Skia defaults), IManifestValidator, and FrameGeometry constants.

Documentation

License

GPL-3.0-only

Repository

https://github.com/sharpninja/ImageArchive