Photostax 0.2.2

Photostax .NET Binding

A .NET wrapper for the photostax library — access Epson FastFoto photo repositories from C#.

Overview

This package provides idiomatic C# access to Epson FastFoto photo repositories. It groups scanner output files (original, enhanced, back scans) into PhotoStack objects and provides metadata reading and writing.

Architecture

PhotostaxRepository is a managed wrapper around the Rust StackManager — the unified cache and query engine that powers photostax. Each PhotostaxRepository instance creates a StackManager internally with a single repository, giving you:

• O(1) stack lookups by opaque ID
• Unified Query() API for search + pagination in one call
• Lazy metadata loading — scan first, load EXIF/XMP on demand
• Filesystem watching and reactive cache updates (Rust-only for now)

Multi-repo support: The Rust core supports managing multiple repositories through a single StackManager (via add_repo()). This capability is now also available in the .NET binding via the StackManager class.

Multi-repo with StackManager

using var mgr = new StackManager();
mgr.AddRepo("/photos/2024", recursive: true);
mgr.AddRepo("/photos/2023", recursive: true);

mgr.Scan();
Console.WriteLine($"Managing {mgr.RepoCount} repos");

// Query across all repos
var page = mgr.Query(new SearchQuery().WithText("birthday"), offset: 0, limit: 20);
foreach (var stack in page.Items)
    Console.WriteLine($"{stack.Name} ({stack.Id})");

Installation

dotnet add package Photostax

Quick Start

using Photostax;

// Open a repository
using var repo = new PhotostaxRepository("/path/to/photos");

// Query all stacks (no filter, no pagination)
var all = repo.Query();

foreach (var stack in all.Items)
{
    // stack.Id is a 16-char hex hash (e.g. "a1b2c3d4e5f67890")
    // stack.Name is the human-readable display name
    Console.WriteLine($"{stack.Name} ({stack.Id})");
    Console.WriteLine($"  Folder: {stack.Folder ?? "(root)"}");
    Console.WriteLine($"  Original: {stack.OriginalPath}");
    Console.WriteLine($"  Enhanced: {stack.EnhancedPath}");
    Console.WriteLine($"  Back: {stack.BackPath}");
    Console.WriteLine($"  Format: {stack.Format}");
}

// Search with filter and pagination using Query()
var page = repo.Query(
    new SearchQuery().WithText("birthday").WithHasBack(true),
    offset: 0,
    limit: 20
);

Console.WriteLine($"Page has {page.Items.Count} of {page.TotalCount} total");
Console.WriteLine($"Has more: {page.HasMore}");

// Iterate pages
foreach (var stack in page.Items)
    Console.WriteLine($"{stack.Name} ({stack.Id})");

if (page.HasMore)
{
    var nextPage = repo.Query(
        new SearchQuery().WithText("birthday"),
        offset: 20, limit: 20);
}

// Read image bytes
var imageData = repo.ReadImage(all.Items[0].OriginalPath!);

// Write metadata (use stack.Id for lookups)
var metadata = new Metadata().WithCustomTag("album", "Family Photos");
repo.WriteMetadata(all.Items[0].Id, metadata);

Note — Stack IDs changed in v0.2.x: Stack IDs are now opaque 16-character hex strings (truncated SHA-256 hashes) rather than human-readable stems. Use stack.Name when displaying a stack to users and stack.Id for programmatic lookups such as GetStack() or WriteMetadata().

API Overview

PhotostaxRepository

The main entry point for working with photo repositories.

Query() — Preferred Search & Pagination API

Query() is the recommended way to search and paginate as of v0.2.x. The older Search(), ScanPaginated(), and SearchPaginated() methods still work but are now convenience wrappers around Query().

// All stacks (no filter, no pagination)
var all = repo.Query();

// With filter and pagination
var page = repo.Query(
    new SearchQuery().WithText("birthday").WithHasBack(true),
    offset: 0,
    limit: 20
);

// Iterate pages
foreach (var stack in page.Items)
    Console.WriteLine($"{stack.Name} ({stack.Id})");

if (page.HasMore)
{
    var nextPage = repo.Query(
        new SearchQuery().WithText("birthday"),
        offset: 20, limit: 20);
}

PhotoStack

Represents a photo stack with its associated images and metadata.

SearchQuery

Builder for constructing search queries.

var query = new SearchQuery()
    .WithText("vacation")           // Free-text search
    .WithExifFilter("Make", "EPSON") // EXIF tag filter
    .WithCustomFilter("album", "2020") // Custom tag filter
    .WithHasBack(true)              // Has back scan
    .WithHasEnhanced(true);         // Has enhanced scan

Building from Source

Prerequisites

• .NET SDK 8.0+
• Rust toolchain (for building native library)

Build Steps

# 1. Build native library
cd <repo_root>
cargo build --release -p photostax-ffi

# 2. Build .NET library
cd bindings/dotnet
dotnet build

# 3. Run tests
dotnet test

Native Library Location

The native library must be in your application's runtime directory:

Running Tests

cd bindings/dotnet
dotnet test

# Skip integration tests (no native library required)
dotnet test --filter "Category!=Integration"

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.

← Back to main README | FFI Documentation