SeasonImage 0.2.0

SeasonImage

SeasonImage is a small .NET wrapper around stable-diffusion.cpp for image generation.

It focuses on a simple text-to-image workflow and ships the required Windows native runtimes in runtimes/win-x64/native.

Repository

• GitHub: SeasonRealms/SeasonImage

• stable-diffusion.cpp: https://github.com/leejet/stable-diffusion.cpp

Features

• Minimal P/Invoke wrapper over stable-diffusion.dll
• Simple context creation API
• Text-to-image generation
• Log and progress callbacks
• Windows native runtimes bundled with the package
• Backend selection through native backend / params_backend strings

Current Scope

• Supported runtime: Windows x64
• Native backend build included in the package: CPU, CUDA, Vulkan
• Current managed wrapper focus: image generation

On non-Windows platforms the assembly can still load, but the native stable diffusion runtime is not provided and the API will throw platform-specific exceptions when invoked.

Installation

Install from NuGet:

dotnet add package SeasonImage

Quick Start

This example follows the same usage pattern as SeasonImageGenerate(string prompt) in the sample project.

using SeasonImage;

StableDiffusion.SetProgressCallback(progress =>
{
    Console.WriteLine($"{progress.Step}/{progress.TotalSteps} ({progress.Progress:P1})");
});

using var ctx = StableDiffusion.CreateContext(new StableDiffusionContextOptions
{
    ModelPath = @"../../../../../../Models/StableDiffusion/v1-5-pruned-emaonly-f16.gguf",
    Backend = "cpu",
    ParamsBackend = "cpu",
    ThreadCount = Environment.ProcessorCount,
    EnableMmap = true,
    FlashAttention = false
});

var images = ctx.GenerateImages(new StableDiffusionImageGenerationOptions
{
    Prompt = "a cinematic portrait, ultra detailed",
    NegativePrompt = "low quality, blurry",
    Width = 1024,
    Height = 1024,
    SampleSteps = 20,
    GuidanceScale = 7.0f,
    Seed = 123456789,
    BatchCount = 1
});

var first = images[0];
File.WriteAllBytes("output.rgba", first.Data);

Saving PNG In SeasonEngine

In SeasonEngine samples, the generated bytes are converted into NativeImageData and saved through DeviceServices.Image.SaveImage(...):

var first = images[0];
byte[] rgbaBytes = first.Channels switch
{
    4 => first.Data,
    3 => ExpandRgbToRgba(first.Data),
    1 => ExpandGrayToRgba(first.Data),
    _ => throw new NotSupportedException($"Unsupported image channel count: {first.Channels}")
};

using var nativeImageData = new NativeImageData(first.Width, first.Height, rgbaBytes);
var pngBytes = DeviceServices.Image.SaveImage(nativeImageData, Season.Basic.ImageFormat.Png);
StorageService.SaveFile(StorageService.DirectoryBase, "SeasonImage.png", pngBytes);

This is under development...

Context Options

Common StableDiffusionContextOptions values:

• ModelPath: single-file model path
• DiffusionModelPath, ClipLPath, ClipGPath, T5XxlPath, VaePath, LlmPath: split-model paths for newer architectures
• Backend: runtime backend, such as cpu, cuda0, vulkan0, gpu, auto
• ParamsBackend: parameter placement backend, such as cpu, cuda0, vulkan0, disk
• MaxVram: optional VRAM budget string such as cuda0=8

Examples:

Backend = "cpu";
ParamsBackend = "cpu";

Backend = "cuda0";
ParamsBackend = "cpu";

Backend = "te=cpu,vae=cpu,diffusion=cuda0";
ParamsBackend = "te=cpu,vae=cpu,diffusion=cuda0";

convert ：

StableDiffusion.Convert(new StableDiffusionConvertOptions
{
    InputPath = @"C:\Models\model.safetensors",
    OutputPath = @"C:\Models\model.gguf",
    OutputType = StableDiffusionWeightType.F16,
    ConvertTensorNames = true
});

LoRA ：

var images = ctx.GenerateImages(new StableDiffusionImageGenerationOptions
{
    Prompt = "masterpiece portrait",
    Width = 1024,
    Height = 1024,
    Loras =
    [
        new StableDiffusionLora { Path = @"C:\Lora\style.safetensors", Multiplier = 0.8f }
    ]
});

preview callback ：

StableDiffusion.SetPreviewCallback(
    preview => Console.WriteLine($"preview step={preview.Step}, frames={preview.Frames.Count}"),
    new StableDiffusionPreviewCallbackOptions
    {
        Mode = StableDiffusionPreviewMode.Vae,
        Interval = 2,
        IncludeDenoised = true
    });

upscaler ：

using var upscaler = StableDiffusion.CreateUpscaler(new StableDiffusionUpscalerOptions
{
    ModelPath = @"C:\Models\RealESRGAN_x4plus_anime_6B.pth",
    Backend = "cpu",
    ParamsBackend = "cpu"
});

var upscaled = upscaler.Upscale(first.ToInputImage(), 4);

img2img ：

var img2img = ctx.GenerateImages(new StableDiffusionImageGenerationOptions
{
    Prompt = "anime illustration",
    InitImage = first.ToInputImage(),
    Strength = 0.65f,
    Width = first.Width,
    Height = first.Height
});

controlnet ：

using var ctx = StableDiffusion.CreateContext(new StableDiffusionContextOptions
{
    ModelPath = @"C:\Models\sd15.gguf",
    ControlNetPath = @"C:\Models\controlnet-canny.safetensors",
    Backend = "cpu",
    ParamsBackend = "cpu"
});

var controlled = ctx.GenerateImages(new StableDiffusionImageGenerationOptions
{
    Prompt = "city street at night",
    ControlImage = cannyImage,
    ControlStrength = 0.9f,
    Width = cannyImage.Width,
    Height = cannyImage.Height
});

Notes

• stable-diffusion.cpp progress and log callbacks are global callbacks
• The current wrapper keeps the API intentionally small
• Advanced features such as img2img, controlnet, preview callback, upscaler, and video can be added later on top of the same native binding layer