SlideGenerator.Framework

A .NET framework for generating PowerPoint files from Excel data.

Docs:

• English
• Vietnamese

Quick links:

• Overview
• Usage

Modules

• Cloud: resolve supported cloud URLs to direct download links.
• Sheet: workbook and worksheet access for Excel/CSV data.
• Slide: template loading, slide cloning, text replacement, image replacement.
• Image: ROI detection, cropping, and resizing helpers.

Prerequisites

EmguCV Runtime

This framework relies on EmguCV for advanced image processing (ROI detection, face detection). You must ensure that the appropriate native runtime package for your target architecture is installed in your final application project:

• Windows (x64): Emgu.CV.runtime.windows
• Linux (x64): Emgu.CV.runtime.ubuntu-x64 (or other corresponding Linux runtimes)

For more details, see Emgu.CV Installation.

Ensure the runtime version matches the Emgu.CV version used in the framework (currently 4.12.0.5764). Without the proper runtime, image processing features will fail with DllNotFoundException or TypeInitializationException.

You can configure your .csproj to automatically include the correct runtime based on the target RuntimeIdentifier:

<ItemGroup Condition="'$(RuntimeIdentifier)'=='win-x64'">
	<PackageReference Include="Emgu.CV.runtime.windows" Version="4.12.0.5764" />
</ItemGroup>
<ItemGroup Condition="'$(RuntimeIdentifier)'=='linux-x64'">
	<PackageReference Include="Emgu.CV.runtime.ubuntu-x64" Version="4.12.0.5764" />
</ItemGroup>
<ItemGroup Condition="'$(RuntimeIdentifier)'=='linux-arm'">
	<PackageReference Include="Emgu.CV.runtime.debian-arm" Version="4.12.0.5764" />
</ItemGroup>
<ItemGroup Condition="'$(RuntimeIdentifier)'=='linux-arm64'">
	<PackageReference Include="Emgu.CV.runtime.debian-arm64" Version="4.12.0.5764" />
</ItemGroup>

Note: macOS is not supported in these script because the Emgu.CV runtime does not support it directly out of the box in this context. For more details, see Emgu.CV MacOS installation.

Cloud

Key type:

• SlideGenerator.Framework.Cloud.CloudUrlResolver

Usage:

var uri = await CloudUrlResolver.ResolveLinkAsync("https://drive.google.com/file/d/.../view");

Supported services:

• Google Drive
• OneDrive
• Google Photos

Sheet

Key types:

• SlideGenerator.Framework.Sheet.Models.Workbook
• SlideGenerator.Framework.Sheet.Contracts.IWorksheet

Usage:

using var workbook = new Workbook("data.xlsx");
var sheets = workbook.GetWorksheetsInfo();
var firstSheet = workbook.Worksheets["Sheet1"];
var row = firstSheet.GetRow(1);

Notes:

• Workbook is IDisposable. Dispose it when done.

Slide

Key types:

• SlideGenerator.Framework.Slide.Models.TemplatePresentation
• SlideGenerator.Framework.Slide.Models.WorkingPresentation
• SlideGenerator.Framework.Slide.TextReplacer
• SlideGenerator.Framework.Slide.ImageReplacer

Usage:

using var template = new TemplatePresentation("template.pptx");
using var working = template.SaveAs("output.pptx");

// Discover image placeholders from the template.
var previews = template.GetAllPreviewImageShapes();
var shapeId = previews.Keys.First(); // example

// Clone the template slide for each output slide (per data row).
// position: 1-based. If omitted, it appends to the end.
var slidePart = working.CopySlide(template.MainSlideRelationshipId, position: 2);

// Replace text placeholders (use keys without {{ }}).
await TextReplacer.ReplaceAsync(slidePart, new Dictionary<string, string>
{
    ["Name"] = "Alice",
    ["Title"] = "Engineer"
});

// Replace image by shape id.
var shape = Presentation.GetShapeById(slidePart, shapeId);
using var png = File.OpenRead("photo.png");
ImageReplacer.ReplaceImage(slidePart, shape!, png);

// Remove the original template slide (now duplicated at the beginning).
working.RemoveSlide(1);
working.Save();

Notes:

• Template presentations must contain exactly one slide; the template index is fixed at 1.
• When the template has more than one slide, NotOnlyOneSlidePresentation is thrown.
• Use GetAllPreviewImageShapes() to discover image shape ids and previews.
• Use ImageReplacer.ReplaceImage(...) for image placeholders.
• Call CopySlide(...) for each row, then Save() the working presentation.

Image

Key types:

• SlideGenerator.Framework.Image.ImageProcessor
• SlideGenerator.Framework.Image.Configs.RoiOptions
• SlideGenerator.Framework.Image.Enums.RoiType
• SlideGenerator.Framework.Image.Enums.CropType

Usage:

var processor = new ImageProcessor(new RoiOptions());
var selector = processor.GetRoiSelector(RoiType.Center);
await ImageProcessor.CropToRoiAsync(imageData, targetSize, selector, CropType.Crop);

Notes:

• Face model init is async and serialized inside ImageProcessor.
• Exceptions are thrown for unsupported or invalid inputs; callers should catch and handle.

Contributors:

• Main Developer: @thnhmai06
• Cloud Logic: @Hair-Nguyeenx