ImageSaveOptions Class

Namespace:
GemBox.Document
Assembly:
GemBox.Document.dll

Represents a class which stores saving options for image files.

public sealed class ImageSaveOptions : SaveOptions
Public NotInheritable Class ImageSaveOptions
    Inherits SaveOptions
Inheritance:
System.Object
ImageSaveOptions
Remarks

For more information about a level of support for image formats, see supported file formats.

Constructors

ImageSaveOptions()

Initializes a new instance of the ImageSaveOptions class.

public ImageSaveOptions()
Public Sub New

ImageSaveOptions(ImageSaveFormat)

Initializes a new instance of the ImageSaveOptions class for a specific image format.

public ImageSaveOptions(ImageSaveFormat imageFormat)
Public Sub New(imageFormat As ImageSaveFormat)
Parameters
imageFormat
ImageSaveFormat

The image format.

Properties

ContentType

Gets the content-type for image file format:

public override string ContentType { get; }
Public Overrides ReadOnly Property ContentType As String
Property Value
System.String

The content-type for image file format.

Overrides

Dither

Gets or sets the value that indicated whether dithering should be applied when converting to pixel formats BlackWhite, Gray2, and Gray4.

Default value: true.

This property is currently ignored when RenderingMode is resolved to Skia.

public bool Dither { get; set; }
Public Property Dither As Boolean
Property Value
System.Boolean

true if dithering should be applied when converting to pixel formats BlackWhite, Gray2, and Gray4; otherwise, false.

DpiX

Gets or sets the horizontal dots per inch (dpi) of the image.

Default value is System.Double.NaN, which means that component specific default value will be used (currently 300).

public double DpiX { get; set; }
Public Property DpiX As Double
Property Value
System.Double

The horizontal dots per inch (dpi) of the image; that is, the dots per inch (dpi) along the x-axis.

Exceptions
System.ArgumentOutOfRangeException

Value is not greater than 0.

DpiY

Gets or sets the vertical dots per inch (dpi) of the image.

Default value is System.Double.NaN, which means that component specific default value will be used (currently 300).

public double DpiY { get; set; }
Public Property DpiY As Double
Property Value
System.Double

The vertical dots per inch (dpi) of the image; that is, the dots per inch (dpi) along the y-axis.

Exceptions
System.ArgumentOutOfRangeException

Value is not greater than 0.

Format

Gets or sets the image format.

public ImageSaveFormat Format { get; set; }
Public Property Format As ImageSaveFormat
Property Value
ImageSaveFormat

The image format.

Height

Gets or sets the image height in pixels.

public double Height { get; set; }
Public Property Height As Double
Property Value
System.Double

The image height in pixels.

Remarks

If both Width and Height are not specified, then image size will be equal to the page size.

If only one of the Width or Height is specified, then the specified dimension will be respected and other dimension will be calculated so that original aspect ratio is maintained.

If both Width and Height are specified, then both specified dimensions will be respected (which may result in non-uniformly scaled image, if aspect ratio is not equal to the original one.

MetafileScaleFactor

Gets or sets the scaling factor for rendering metafile (WMF and EMF) images. Greater scaling factor improves quality but also increases file size. Default value is 1.

public double MetafileScaleFactor { get; set; }
Public Property MetafileScaleFactor As Double
Property Value
System.Double

The metafile scale factor for rendering metafile (WMF and EMF) images.

Remarks

Windows Metafile Format (WMF) and Enhanced Metafile Format (EMF) are vector image formats which contain a series of graphics drawing commands usually executed in Windows GDI layer.

Metafile drawing commands could also be executed in PDF (or XPS) file which is also vector format, but for that Metafile drawing commands would have to be converted to PDF drawing commands.

GemBox.Document currently doesn't perform this conversion of drawing commands, instead it uses Windows GDI to execute Metafile drawing commands into bitmap which is then encoded to PNG format and embedded into PDF file.

MetafileScaleFactor specifies the size of the bitmap surface, based from the original Metafile surface size, into which Metafile should be drawn / rasterized.

PDF viewer will still scale the bitmap to the original Metafile size, but if the page is zoomed or viewed on a larger surface, quality of the image will be better since it contains more pixels / dots which will become visible while PDF viewer scales down the image.

MetafileScaleFactor increases the quality of the Metafile image in PDF file, but it also increases the size of the PDF file because greater MetafileScaleFactor means greater bitmap surface and more space to store bitmap pixel / color data. PNG encoding / compression helps in reducing the space requirement and for complex Metafiles (with a lot of drawing instructions), MetafileScaleFactor of 5 or even greater, might not incur any space overhead relative to the original (complex) Metafile.

Default value for MetafileScaleFactor is 1.

PixelFormat

Gets or sets a pixel format, which will be used for the image.

public PixelFormat PixelFormat { get; set; }
Public Property PixelFormat As PixelFormat
Property Value
PixelFormat

The pixel format, which will be used for the image.

RenderingMode

Gets or sets the rendering mode used when saving the content to an image.

public RenderingMode RenderingMode { get; set; }
Public Property RenderingMode As RenderingMode
Property Value
RenderingMode

The rendering mode used when saving the content to an image.

Exceptions
System.NotSupportedException

The rendering mode is not supported because of the reasons explained in the exception's System.Exception.Message.

TiffCompression

Gets or sets compression schema, which will be used when exporting to Tagged Image File Format (TIFF).

public TiffCompression TiffCompression { get; set; }
Public Property TiffCompression As TiffCompression
Property Value
TiffCompression

The compression schema, which will be used when exporting to Tagged Image File Format (TIFF).

Width

Gets or sets the image width in pixels.

public double Width { get; set; }
Public Property Width As Double
Property Value
System.Double

The image width in pixels.

Remarks

If both Width and Height are not specified, then image size will be equal to the page size.

If only one of the Width or Height is specified, then the specified dimension will be respected and other dimension will be calculated so that original aspect ratio is maintained.

If both Width and Height are specified, then both specified dimensions will be respected (which may result in non-uniformly scaled image, if aspect ratio is not equal to the original one.

Events

ProgressChanged

Occurs when saving progress of a document has changed.

public event EventHandler<OperationProgressChangedEventArgs> ProgressChanged
Public Event ProgressChanged As EventHandler(Of OperationProgressChangedEventArgs)
Event Type
System.EventHandler<OperationProgressChangedEventArgs>

Inherited Properties

DocxDefault

Gets the default saving options for Microsoft Word file format. Word file will be saved in Docx format.

(Inherited from SaveOptions)

HtmlDefault

Gets the default saving options for HyperText Markup Language (HTML) format.

(Inherited from SaveOptions)

ImageDefault

Gets the default saving options for image file format. Image will be saved in Bmp format.

(Inherited from SaveOptions)

OdtDefault

Gets the default saving options for Open Document file format.

(Inherited from SaveOptions)

PageCount

Gets or sets the number of pages which should be saved.

(Inherited from SaveOptions)

PageNumber

Gets or sets the zero-based page number of the document's page which should be saved.

(Inherited from SaveOptions)

PdfDefault

Gets the default saving options for Portable Document Format (PDF).

(Inherited from SaveOptions)

RtfDefault

Gets the default saving options for Rich Text (RTF) format.

(Inherited from SaveOptions)

TxtDefault

Gets the default saving options for Plain Text (TXT) format.

(Inherited from SaveOptions)

XmlDefault

Gets the default saving options for XML file format.

(Inherited from SaveOptions)

XpsDefault

Gets the default saving options for XML Paper Specification (XPS) format.

(Inherited from SaveOptions)

See Also