Convert images

Some image formats are not supported depending on the output document, e.g.

• WEBP, AVIF, JXL, PICT in DOCX
• SVG, GIF, TIFF, JPEG2000, ICO, PCX in RTF
• TIFF, WMF, EMF, JPEG2000, PCX, PICT in HTML, or when viewing Markdown in a web browser.

However, JPEG2000/PCX in DOCX documents and PICT in RTF documents are very rare.

Some of these images can be automatically converted to PNG if you install and configure an extra NuGet package (DocSharp.ImageSharp or DocSharp.SystemDrawing). Alternatively, you can create a custom implementation of IImageConverter.

Difference between built-in image converters:

• DocSharp.ImageSharp:
  • Depends on ImageSharp, VectSharp, CoreJ2K
  • Cross-platform and fully managed C# code (no native dependencies). Maximum portability, but might be slightly slower than native libraries.
  • Supports JPEG, GIF, PNG, TIFF, BMP, WEBP via ImageSharp (possibly other formats in a future ImageSharp release, ICO is implemented in v4 that is not published yet, AVIF is being worked on)
  • Supports SVG via VectSharp
  • Supports JPEG2000 via CoreJ2k
  • Metafiles (WMF/EMF), AVIF, JXL are currently not supported
  • Supported on .NET only (no .NET Framework)
• DocSharp.SystemDrawing
  • Depends on System.Drawing.Common, SVG.NET, CoreJ2K
  • Supported on Windows only (.NET Framework or net8.0-windows / net9.0-windows / net10.0-windows), as System.Drawing.Common uses GDI+ and is not supported on non-Windows platforms since .NET 6.
  • Supports JPEG, GIF, PNG, TIFF, BMP, WMF, EMF, ICO via System.Drawing
  • Supports SVG via SVG.NET
  • Supports JPEG2000 via CoreJ2k
  • AVIF and JXL are not supported; WEBP should work starting from Windows 10 1809 according to the documentation.
• DocSharp.MagickNET
  • Depends on Magick.NET-Q8-AnyCPU
  • Supports all relevant formats
  • Cross-platform for Windows/MacOS/Linux and supports both .NET and .NET Framework
  • Bundles many native libraries and may not work on non-desktop platforms (Android/iOS/WASM). Few image types are only supported on specific platforms, for example WMF/EMF on Windows, while most (including WEBP, AVIF, HEIF, JXL) are cross-platform.
  • Much heavier dependency than System.Drawing.Common/ImageSharp

How to use:

1. Install the DocSharp.ImageSharp, DocSharp.SystemDrawing or DocSharp.MagickNET package
2. Set the ImageConverter property on the desired converter, for example:

var converter = new DocxToMarkdownConverter()
{
     // ...
     ImageConverter = new SystemDrawingConverter()
};

var converter = new DocxToRtfConverter()
{
     // ...
     ImageConverter = new ImageSharpConverter()
};

var converter = new MarkdownConverter()
{
     // ...
     ImageConverter = new MagickConverter()
};