Load Image Documents with Options Leave feedback

The ImageLoadOptions class enables you to configure how image documents are loaded in GroupDocs.Conversion. This is particularly useful when you need to explicitly specify the format, configure font handling for vector images, or control font folder behavior.

ImageLoadOptions works with all common image formats including PNG, JPG, GIF, BMP, TIFF, WEBP, PSD, and more.

For most scenarios, GroupDocs.Conversion automatically detects the image format. However, you can explicitly specify it using ImageLoadOptions:

using (var converter = new Converter(
    "product-photo.png",
    (LoadContext loadContext) => new ImageLoadOptions
    {
        Format = ImageFileType.Png
    }))
{
    converter.Convert("product-photo.pdf", new PdfConvertOptions());
}

Explicitly specify the input image format when automatic detection might be ambiguous or when you want to ensure a specific format is used:

using (var converter = new Converter(
    "company-logo.png",
    (LoadContext loadContext) => new ImageLoadOptions
    {
        Format = ImageFileType.Png
    }))
{
    converter.Convert("company-logo.pdf", new PdfConvertOptions());
}

Supported formats: Jpg, Png, Gif, Bmp, Tiff, Webp, Jpeg, Ico, Psd, Heic, and more.

When converting vector images (PSD, EMF, WMF) that contain text, you can specify a fallback font to use if the original font is missing:

using (var converter = new Converter(
    "design-mockup.psd",
    (LoadContext loadContext) => new ImageLoadOptions
    {
        DefaultFont = "Arial"
    }))
{
    converter.Convert("design-mockup.pdf", new PdfConvertOptions());
}

When to use:

• Converting Photoshop files (PSD) with text layers
• Converting Enhanced Metafiles (EMF) containing text
• Converting Windows Metafiles (WMF) with embedded text
• Ensuring consistent rendering when fonts are unavailable

Control font folder configuration when loading images:

using (var converter = new Converter(
    "banner-ad.png",
    (LoadContext loadContext) => new ImageLoadOptions
    {
        ResetFontFolders = true
    }))
{
    converter.Convert("banner-ad.pdf", new PdfConvertOptions());
}

Use case: When you need to ensure a clean font environment for consistent rendering across different systems.

Combine all ImageLoadOptions properties for complete control:

using (var converter = new Converter(
    "banner-ad.png",
    (LoadContext loadContext) => new ImageLoadOptions
    {
        Format = ImageFileType.Png,
        DefaultFont = "Calibri",
        ResetFontFolders = true
    }))
{
    converter.Convert("banner-ad.docx", new WordProcessingConvertOptions());
}

GroupDocs.Conversion supports converting images to various output formats:

using (var converter = new Converter(
    "profile-picture.png",
    (LoadContext loadContext) => new ImageLoadOptions { Format = ImageFileType.Png }))
{
    converter.Convert("profile-picture.pdf", new PdfConvertOptions());
}

using (var converter = new Converter(
    "screenshot.png",
    (LoadContext loadContext) => new ImageLoadOptions { Format = ImageFileType.Png }))
{
    converter.Convert("screenshot.docx", new WordProcessingConvertOptions());
}

using (var converter = new Converter(
    "thumbnail.png",
    (LoadContext loadContext) => new ImageLoadOptions { Format = ImageFileType.Png }))
{
    converter.Convert("thumbnail.xlsx", new SpreadsheetConvertOptions());
}

Use ImageLoadOptions when you need to:

1. Explicitly specify format - When automatic detection might be insufficient or you want to enforce a specific format
2. Handle missing fonts - When converting vector images (PSD, EMF, WMF) that might have font availability issues
3. Control font behavior - When you need to reset font folders for consistent rendering
4. Process ambiguous files - When files have incorrect extensions or no extensions

For simple conversions, you can rely on automatic format detection:

using (var converter = new Converter("product-photo.png"))
{
    converter.Convert("product-photo.pdf", new PdfConvertOptions());
}

GroupDocs.Conversion automatically detects the format in most cases, so ImageLoadOptions is optional unless you need the specific configuration it provides.

ImageLoadOptions works with:

• Raster formats: PNG, JPG/JPEG, GIF, BMP, TIFF, WEBP, HEIC
• Vector formats: EMF, WMF, SVG
• Professional formats: PSD (Photoshop), ICO (Icons)

ImageLoadOptions provides fine-grained control over image document loading:

• Format: Explicitly specify the input image format
• DefaultFont: Set fallback font for vector images with text
• ResetFontFolders: Control font folder configuration

All examples on this page have been verified through automated testing to ensure accuracy.

• Context Objects - Complete Guide
• ImageFileType API Reference
• ImageLoadOptions API Reference