Skip to content

Commit f5d79fd

Browse files
nikola-yankovnikola-yankov
committed
image load options
1 parent 8603204 commit f5d79fd

1 file changed

Lines changed: 201 additions & 0 deletions

File tree

‎net/developer-guide/advanced-usage/loading/load-options-for-different-document-types/load-image-document-with-options.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
id: load-image-document-with-options
3+
url: conversion/net/load-image-document-with-options
4+
title: Load Image Documents with Options
5+
weight: 20
6+
description: "Learn how to use ImageLoadOptions to configure image document loading in GroupDocs.Conversion for .NET. Control format specification, font handling, and more."
7+
keywords: ImageLoadOptions, load image, PNG, JPG, GIF, BMP, TIFF, image conversion, GroupDocs.Conversion
8+
productName: GroupDocs.Conversion for .NET
9+
hideChildren: False
10+
---
11+
12+
## Introduction
13+
14+
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.
15+
16+
ImageLoadOptions works with all common image formats including PNG, JPG, GIF, BMP, TIFF, WEBP, PSD, and more.
17+
18+
## Properties
19+
20+
| Property | Type | Description |
21+
|----------|------|-------------|
22+
| `Format` | `ImageFileType` | Explicitly specify the input image format (get; set;) |
23+
| `DefaultFont` | `string` | Default font for PSD, EMF, WMF images containing text (get; set;) |
24+
| `ResetFontFolders` | `bool` | Reset font folders before loading document (get; set;) |
25+
26+
## Basic Usage
27+
28+
For most scenarios, GroupDocs.Conversion automatically detects the image format. However, you can explicitly specify it using ImageLoadOptions:
29+
30+
```csharp
31+
using (var converter = new Converter(
32+
"product-photo.png",
33+
(LoadContext loadContext) => new ImageLoadOptions
34+
{
35+
Format = ImageFileType.Png
36+
}))
37+
{
38+
converter.Convert("product-photo.pdf", new PdfConvertOptions());
39+
}
40+
```
41+
42+
## Property Examples
43+
44+
### Specifying Format
45+
46+
Explicitly specify the input image format when automatic detection might be ambiguous or when you want to ensure a specific format is used:
47+
48+
```csharp
49+
using (var converter = new Converter(
50+
"company-logo.png",
51+
(LoadContext loadContext) => new ImageLoadOptions
52+
{
53+
Format = ImageFileType.Png
54+
}))
55+
{
56+
converter.Convert("company-logo.pdf", new PdfConvertOptions());
57+
}
58+
```
59+
60+
**Supported formats:** Jpg, Png, Gif, Bmp, Tiff, Webp, Jpeg, Ico, Psd, Heic, and more.
61+
62+
### DefaultFont for Vector Images
63+
64+
When converting vector images (PSD, EMF, WMF) that contain text, you can specify a fallback font to use if the original font is missing:
65+
66+
```csharp
67+
using (var converter = new Converter(
68+
"design-mockup.psd",
69+
(LoadContext loadContext) => new ImageLoadOptions
70+
{
71+
DefaultFont = "Arial"
72+
}))
73+
{
74+
converter.Convert("design-mockup.pdf", new PdfConvertOptions());
75+
}
76+
```
77+
78+
**When to use:**
79+
- Converting Photoshop files (PSD) with text layers
80+
- Converting Enhanced Metafiles (EMF) containing text
81+
- Converting Windows Metafiles (WMF) with embedded text
82+
- Ensuring consistent rendering when fonts are unavailable
83+
84+
### ResetFontFolders
85+
86+
Control font folder configuration when loading images:
87+
88+
```csharp
89+
using (var converter = new Converter(
90+
"banner-ad.png",
91+
(LoadContext loadContext) => new ImageLoadOptions
92+
{
93+
ResetFontFolders = true
94+
}))
95+
{
96+
converter.Convert("banner-ad.pdf", new PdfConvertOptions());
97+
}
98+
```
99+
100+
**Use case:** When you need to ensure a clean font environment for consistent rendering across different systems.
101+
102+
## Using All Properties Together
103+
104+
Combine all ImageLoadOptions properties for complete control:
105+
106+
```csharp
107+
using (var converter = new Converter(
108+
"banner-ad.png",
109+
(LoadContext loadContext) => new ImageLoadOptions
110+
{
111+
Format = ImageFileType.Png,
112+
DefaultFont = "Calibri",
113+
ResetFontFolders = true
114+
}))
115+
{
116+
converter.Convert("banner-ad.docx", new WordProcessingConvertOptions());
117+
}
118+
```
119+
120+
## Common Scenarios
121+
122+
### Converting Different Image Formats
123+
124+
GroupDocs.Conversion supports converting images to various output formats:
125+
126+
#### Image to PDF
127+
128+
```csharp
129+
using (var converter = new Converter(
130+
"profile-picture.png",
131+
(LoadContext loadContext) => new ImageLoadOptions { Format = ImageFileType.Png }))
132+
{
133+
converter.Convert("profile-picture.pdf", new PdfConvertOptions());
134+
}
135+
```
136+
137+
#### Image to Word Document
138+
139+
```csharp
140+
using (var converter = new Converter(
141+
"screenshot.png",
142+
(LoadContext loadContext) => new ImageLoadOptions { Format = ImageFileType.Png }))
143+
{
144+
converter.Convert("screenshot.docx", new WordProcessingConvertOptions());
145+
}
146+
```
147+
148+
#### Image to Excel Spreadsheet
149+
150+
```csharp
151+
using (var converter = new Converter(
152+
"thumbnail.png",
153+
(LoadContext loadContext) => new ImageLoadOptions { Format = ImageFileType.Png }))
154+
{
155+
converter.Convert("thumbnail.xlsx", new SpreadsheetConvertOptions());
156+
}
157+
```
158+
159+
## When to Use ImageLoadOptions
160+
161+
Use ImageLoadOptions when you need to:
162+
163+
1. **Explicitly specify format** - When automatic detection might be insufficient or you want to enforce a specific format
164+
2. **Handle missing fonts** - When converting vector images (PSD, EMF, WMF) that might have font availability issues
165+
3. **Control font behavior** - When you need to reset font folders for consistent rendering
166+
4. **Process ambiguous files** - When files have incorrect extensions or no extensions
167+
168+
## Without ImageLoadOptions
169+
170+
For simple conversions, you can rely on automatic format detection:
171+
172+
```csharp
173+
using (var converter = new Converter("product-photo.png"))
174+
{
175+
converter.Convert("product-photo.pdf", new PdfConvertOptions());
176+
}
177+
```
178+
179+
GroupDocs.Conversion automatically detects the format in most cases, so ImageLoadOptions is optional unless you need the specific configuration it provides.
180+
181+
## Supported Image Formats
182+
183+
ImageLoadOptions works with:
184+
- **Raster formats**: PNG, JPG/JPEG, GIF, BMP, TIFF, WEBP, HEIC
185+
- **Vector formats**: EMF, WMF, SVG
186+
- **Professional formats**: PSD (Photoshop), ICO (Icons)
187+
188+
## Summary
189+
190+
ImageLoadOptions provides fine-grained control over image document loading:
191+
- **Format**: Explicitly specify the input image format
192+
- **DefaultFont**: Set fallback font for vector images with text
193+
- **ResetFontFolders**: Control font folder configuration
194+
195+
All examples on this page have been verified through automated testing to ensure accuracy.
196+
197+
## See Also
198+
199+
- [Context Objects - Complete Guide]({{< ref "../../basic-usage/context-objects-complete-guide" >}})
200+
- [Convert Images]({{< ref "../../basic-usage/convert" >}})
201+
- [ImageFileType API Reference](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.filetypes/imagefiletype/)

0 commit comments

Comments
 (0)