Class ImageSaveOptions
Namespace: Aspose.Words.Saving
Assembly: Aspose.Words.dll (25.12.0)
Allows to specify additional options when rendering document pages or shapes to images.
To learn more, visit the Specify Save Options documentation article.
public class ImageSaveOptions : FixedPageSaveOptionsInheritance
object ← SaveOptions ← FixedPageSaveOptions ← ImageSaveOptions
Inherited Members
FixedPageSaveOptions.Equals(object) , FixedPageSaveOptions.AssertValidIdPrefix(string) , FixedPageSaveOptions.IsValidIdPrefix(string) , FixedPageSaveOptions.PageSet , FixedPageSaveOptions.PageSavingCallback , FixedPageSaveOptions.NumeralFormat , FixedPageSaveOptions.MetafileRenderingOptions , FixedPageSaveOptions.JpegQuality , FixedPageSaveOptions.ColorMode , FixedPageSaveOptions.OptimizeOutput , SaveOptions.CreateSaveOptions(SaveFormat) , SaveOptions.CreateSaveOptions(string) , SaveOptions.SaveFormat , SaveOptions.ExportGeneratorName , SaveOptions.TempFolder , SaveOptions.PrettyFormat , SaveOptions.UseAntiAliasing , SaveOptions.UseHighQualityRendering , SaveOptions.DmlRenderingMode , SaveOptions.DmlEffectsRenderingMode , SaveOptions.ImlRenderingMode , SaveOptions.DefaultTemplate , SaveOptions.UpdateFields , SaveOptions.UpdateLastSavedTimeProperty , SaveOptions.UpdateLastPrintedProperty , SaveOptions.UpdateCreatedTimeProperty , SaveOptions.MemoryOptimization , SaveOptions.UpdateAmbiguousTextFont , SaveOptions.Dml3DEffectsRenderingMode , SaveOptions.ProgressCallback , SaveOptions.AllowEmbeddingPostScriptFonts , SaveOptions.CustomTimeZoneInfo , object.GetType() , object.MemberwiseClone() , object.ToString() , object.Equals(object?) , object.Equals(object?, object?) , object.ReferenceEquals(object?, object?) , object.GetHashCode()
Examples
Shows how to specify a resolution while rendering a document to PNG.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.Font.Name = "Times New Roman";
builder.Font.Size = 24;
builder.Writeln("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.");
builder.InsertImage(ImageDir + "Logo.jpg");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Png);
// Set the "Resolution" property to "72" to render the document in 72dpi.
options.Resolution = 72;
doc.Save(ArtifactsDir + "ImageSaveOptions.Resolution.72dpi.png", options);
// Set the "Resolution" property to "300" to render the document in 300dpi.
options.Resolution = 300;
doc.Save(ArtifactsDir + "ImageSaveOptions.Resolution.300dpi.png", options);Shows how to configure compression while saving a document as a JPEG.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.InsertImage(ImageDir + "Logo.jpg");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions imageOptions = new ImageSaveOptions(SaveFormat.Jpeg);
// Set the "JpegQuality" property to "10" to use stronger compression when rendering the document.
// This will reduce the file size of the document, but the image will display more prominent compression artifacts.
imageOptions.JpegQuality = 10;
doc.Save(ArtifactsDir + "ImageSaveOptions.JpegQuality.HighCompression.jpg", imageOptions);
// Set the "JpegQuality" property to "100" to use weaker compression when rending the document.
// This will improve the quality of the image at the cost of an increased file size.
imageOptions.JpegQuality = 100;
doc.Save(ArtifactsDir + "ImageSaveOptions.JpegQuality.HighQuality.jpg", imageOptions);Renders a page of a Word document into an image with transparent or colored background.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.Font.Name = "Times New Roman";
builder.Font.Size = 24;
builder.Writeln("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.");
builder.InsertImage(ImageDir + "Logo.jpg");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions imgOptions = new ImageSaveOptions(SaveFormat.Png);
// Set the "PaperColor" property to a transparent color to apply a transparent
// background to the document while rendering it to an image.
imgOptions.PaperColor = Color.Transparent;
doc.Save(ArtifactsDir + "ImageSaveOptions.PaperColor.Transparent.png", imgOptions);
// Set the "PaperColor" property to an opaque color to apply that color
// as the background of the document as we render it to an image.
imgOptions.PaperColor = Color.LightCoral;
doc.Save(ArtifactsDir + "ImageSaveOptions.PaperColor.LightCoral.png", imgOptions);Constructors
ImageSaveOptions(SaveFormat)
Initializes a new instance of this class that can be used to save rendered images in the Aspose.Words.SaveFormat.Tiff, Aspose.Words.SaveFormat.Png, Aspose.Words.SaveFormat.Bmp, Aspose.Words.SaveFormat.Jpeg, Aspose.Words.SaveFormat.Emf, Aspose.Words.SaveFormat.Eps, Aspose.Words.SaveFormat.WebP or Aspose.Words.SaveFormat.Svg format.
public ImageSaveOptions(SaveFormat saveFormat)Parameters
saveFormat SaveFormat
Can be Aspose.Words.SaveFormat.Tiff, Aspose.Words.SaveFormat.Png, Aspose.Words.SaveFormat.Bmp, Aspose.Words.SaveFormat.Jpeg, Aspose.Words.SaveFormat.Emf, Aspose.Words.SaveFormat.EpsAspose.Words.SaveFormat.WebP or Aspose.Words.SaveFormat.Svg format.
Examples
Shows how to configure compression while saving a document as a JPEG.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.InsertImage(ImageDir + "Logo.jpg");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions imageOptions = new ImageSaveOptions(SaveFormat.Jpeg);
// Set the "JpegQuality" property to "10" to use stronger compression when rendering the document.
// This will reduce the file size of the document, but the image will display more prominent compression artifacts.
imageOptions.JpegQuality = 10;
doc.Save(ArtifactsDir + "ImageSaveOptions.JpegQuality.HighCompression.jpg", imageOptions);
// Set the "JpegQuality" property to "100" to use weaker compression when rending the document.
// This will improve the quality of the image at the cost of an increased file size.
imageOptions.JpegQuality = 100;
doc.Save(ArtifactsDir + "ImageSaveOptions.JpegQuality.HighQuality.jpg", imageOptions);Properties
HorizontalResolution
Gets or sets the horizontal resolution for the generated images, in dots per inch.
public float HorizontalResolution { get; set; }Property Value
Examples
Shows how to edit the image while Aspose.Words converts a document to one.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an image, we can pass a SaveOptions object to
// edit the image while the saving operation renders it.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Png)
{
// We can adjust these properties to change the image's brightness and contrast.
// Both are on a 0-1 scale and are at 0.5 by default.
ImageBrightness = 0.3f,
ImageContrast = 0.7f,
// We can adjust horizontal and vertical resolution with these properties.
// This will affect the dimensions of the image.
// The default value for these properties is 96.0, for a resolution of 96dpi.
HorizontalResolution = 72f,
VerticalResolution = 72f,
// We can scale the image using this property. The default value is 1.0, for scaling of 100%.
// We can use this property to negate any changes in image dimensions that changing the resolution would cause.
Scale = 96f / 72f
};
doc.Save(ArtifactsDir + "ImageSaveOptions.EditImage.png", options);Remarks
This property has effect only when saving to raster image formats and affects the output size in pixels.
The default value is 96.
ImageBrightness
Gets or sets the brightness for the generated images.
public float ImageBrightness { get; set; }Property Value
Examples
Shows how to edit the image while Aspose.Words converts a document to one.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an image, we can pass a SaveOptions object to
// edit the image while the saving operation renders it.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Png)
{
// We can adjust these properties to change the image's brightness and contrast.
// Both are on a 0-1 scale and are at 0.5 by default.
ImageBrightness = 0.3f,
ImageContrast = 0.7f,
// We can adjust horizontal and vertical resolution with these properties.
// This will affect the dimensions of the image.
// The default value for these properties is 96.0, for a resolution of 96dpi.
HorizontalResolution = 72f,
VerticalResolution = 72f,
// We can scale the image using this property. The default value is 1.0, for scaling of 100%.
// We can use this property to negate any changes in image dimensions that changing the resolution would cause.
Scale = 96f / 72f
};
doc.Save(ArtifactsDir + "ImageSaveOptions.EditImage.png", options);Remarks
This property has effect only when saving to raster image formats.
The default value is 0.5. The value must be in the range between 0 and 1.
ImageColorMode
Gets or sets the color mode for the generated images.
public ImageColorMode ImageColorMode { get; set; }Property Value
Examples
Shows how to set a color mode when rendering documents.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an image, we can pass a SaveOptions object to
// select a color mode for the image that the saving operation will generate.
// If we set the "ImageColorMode" property to "ImageColorMode.BlackAndWhite",
// the saving operation will apply grayscale color reduction while rendering the document.
// If we set the "ImageColorMode" property to "ImageColorMode.Grayscale",
// the saving operation will render the document into a monochrome image.
// If we set the "ImageColorMode" property to "None", the saving operation will apply the default method
// and preserve all the document's colors in the output image.
ImageSaveOptions imageSaveOptions = new ImageSaveOptions(SaveFormat.Png);
imageSaveOptions.ImageColorMode = imageColorMode;
doc.Save(ArtifactsDir + "ImageSaveOptions.ColorMode.png", imageSaveOptions);Remarks
This property has effect only when saving to raster image formats.
The default value is Aspose.Words.Saving.ImageColorMode.None.
ImageContrast
Gets or sets the contrast for the generated images.
public float ImageContrast { get; set; }Property Value
Examples
Shows how to edit the image while Aspose.Words converts a document to one.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an image, we can pass a SaveOptions object to
// edit the image while the saving operation renders it.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Png)
{
// We can adjust these properties to change the image's brightness and contrast.
// Both are on a 0-1 scale and are at 0.5 by default.
ImageBrightness = 0.3f,
ImageContrast = 0.7f,
// We can adjust horizontal and vertical resolution with these properties.
// This will affect the dimensions of the image.
// The default value for these properties is 96.0, for a resolution of 96dpi.
HorizontalResolution = 72f,
VerticalResolution = 72f,
// We can scale the image using this property. The default value is 1.0, for scaling of 100%.
// We can use this property to negate any changes in image dimensions that changing the resolution would cause.
Scale = 96f / 72f
};
doc.Save(ArtifactsDir + "ImageSaveOptions.EditImage.png", options);Remarks
This property has effect only when saving to raster image formats.
The default value is 0.5. The value must be in the range between 0 and 1.
ImageSize
Gets or sets the size of a generated image in pixels.
public Size ImageSize { get; set; }Property Value
Examples
Shows how to render every page of a document to a separate TIFF image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.Writeln("Page 1.");
builder.InsertBreak(BreakType.PageBreak);
builder.Writeln("Page 2.");
builder.InsertImage(ImageDir + "Logo.jpg");
builder.InsertBreak(BreakType.PageBreak);
builder.Writeln("Page 3.");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Tiff);
for (int i = 0; i < doc.PageCount; i++)
{
// Set the "PageSet" property to the number of the first page from
// which to start rendering the document from.
options.PageSet = new PageSet(i);
// Export page at 2325x5325 pixels and 600 dpi.
options.Resolution = 600;
options.ImageSize = new Size(2325, 5325);
doc.Save(ArtifactsDir + $"ImageSaveOptions.PageByPage.{i + 1}.tiff", options);
}Remarks
This property has effect only when saving to raster image formats.
The default value is (0 x 0), which means that the size of the generated image will be calculated according to the size of the image in points, the specified resolution and scale.
JpegQuality
Gets or sets a value determining the quality of the generated JPEG images.
public int JpegQuality { get; set; }Property Value
Examples
Shows how to configure compression while saving a document as a JPEG.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.InsertImage(ImageDir + "Logo.jpg");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions imageOptions = new ImageSaveOptions(SaveFormat.Jpeg);
// Set the "JpegQuality" property to "10" to use stronger compression when rendering the document.
// This will reduce the file size of the document, but the image will display more prominent compression artifacts.
imageOptions.JpegQuality = 10;
doc.Save(ArtifactsDir + "ImageSaveOptions.JpegQuality.HighCompression.jpg", imageOptions);
// Set the "JpegQuality" property to "100" to use weaker compression when rending the document.
// This will improve the quality of the image at the cost of an increased file size.
imageOptions.JpegQuality = 100;
doc.Save(ArtifactsDir + "ImageSaveOptions.JpegQuality.HighQuality.jpg", imageOptions);Remarks
Has effect only when saving to JPEG.
Use this property to get or set the quality of generated images when saving in JPEG format. The value may vary from 0 to 100 where 0 means worst quality but maximum compression and 100 means best quality but minimum compression.
The default value is 95.
MetafileRenderingOptions
Allows to specify how metafiles are treated in the rendered output.
public MetafileRenderingOptions MetafileRenderingOptions { get; }Property Value
Examples
Shows how to set the rendering mode when saving documents with Windows Metafile images to other image formats.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.InsertImage(ImageDir + "Windows MetaFile.wmf");
// When we save the document as an image, we can pass a SaveOptions object to
// determine how the saving operation will process Windows Metafiles in the document.
// If we set the "RenderingMode" property to "MetafileRenderingMode.Vector",
// or "MetafileRenderingMode.VectorWithFallback", we will render all metafiles as vector graphics.
// If we set the "RenderingMode" property to "MetafileRenderingMode.Bitmap", we will render all metafiles as bitmaps.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Png);
options.MetafileRenderingOptions.RenderingMode = metafileRenderingMode;
// Aspose.Words uses GDI+ for raster operations emulation, when value is set to true.
options.MetafileRenderingOptions.UseGdiRasterOperationsEmulation = true;
doc.Save(ArtifactsDir + "ImageSaveOptions.WindowsMetaFile.png", options);Remarks
When Aspose.Words.Saving.MetafileRenderingMode.Vector is specified, Aspose.Words renders metafile to vector graphics using its own metafile rendering engine first and then renders vector graphics to the image.
When Aspose.Words.Saving.MetafileRenderingMode.Bitmap is specified, Aspose.Words renders metafile directly to the image using the GDI+ metafile rendering engine.
GDI+ metafile rendering engine works faster, supports almost all metafile features but on low resolutions may produce inconsistent result when compared to the rest of vector graphics (especially for text) on the page. Aspose.Words metafile rendering engine will produce more consistent result even on low resolutions but works slower and may inaccurately render complex metafiles.
The default value for Aspose.Words.Saving.MetafileRenderingMode is Aspose.Words.Saving.MetafileRenderingMode.Bitmap.
PageLayout
Gets or sets the layout used when rendering multiple pages into a single output.
public MultiPageLayout PageLayout { get; set; }Property Value
Examples
Shows how to save the document into JPG image with multi-page layout settings.
Document doc = new Document(MyDir + "Rendering.docx");
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Jpeg);
// Set up a grid layout with:
// - 3 columns per row.
// - 10pts spacing between pages (horizontal and vertical).
options.PageLayout = MultiPageLayout.Grid(3, 10, 10);
// Alternative layouts:
// options.PageLayout = MultiPageLayout.Horizontal(10);
// options.PageLayout = MultiPageLayout.Vertical(10);
// Customize the background and border.
options.PageLayout.BackColor = Color.LightGray;
options.PageLayout.BorderColor = Color.Blue;
options.PageLayout.BorderWidth = 2;
doc.Save(ArtifactsDir + "ImageSaveOptions.GridLayout.jpg", options);Remarks
Use one of the factory methods of Aspose.Words.Saving.MultiPageLayout to configure this property.
For Aspose.Words.SaveFormat.Tiff the default value is Aspose.Words.Saving.MultiPageLayout.TiffFrames. For other formats the default value is Aspose.Words.Saving.MultiPageLayout.SinglePage.
This property has effect only when saving to the following formats: Aspose.Words.SaveFormat.Jpeg, Aspose.Words.SaveFormat.Gif, Aspose.Words.SaveFormat.Png, Aspose.Words.SaveFormat.Bmp, Aspose.Words.SaveFormat.Tiff, Aspose.Words.SaveFormat.WebP
PageSet
Gets or sets the pages to render. Default is all the pages in the document.
public PageSet PageSet { get; set; }Property Value
Examples
Shows how to extract pages based on exact page ranges.
Document doc = new Document(MyDir + "Images.docx");
ImageSaveOptions imageOptions = new ImageSaveOptions(SaveFormat.Tiff);
PageSet pageSet = new PageSet(new PageRange(1, 1), new PageRange(2, 3), new PageRange(1, 3),
new PageRange(2, 4), new PageRange(1, 1));
imageOptions.PageSet = pageSet;
doc.Save(ArtifactsDir + "ImageSaveOptions.ExportVariousPageRanges.tiff", imageOptions);Shows how to specify which page in a document to render as an image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world! This is page 1.");
builder.InsertBreak(BreakType.PageBreak);
builder.Writeln("This is page 2.");
builder.InsertBreak(BreakType.PageBreak);
builder.Writeln("This is page 3.");
Assert.That(doc.PageCount, Is.EqualTo(3));
// When we save the document as an image, Aspose.Words only renders the first page by default.
// We can pass a SaveOptions object to specify a different page to render.
ImageSaveOptions saveOptions = new ImageSaveOptions(SaveFormat.Gif);
// Render every page of the document to a separate image file.
for (int i = 1; i <= doc.PageCount; i++)
{
saveOptions.PageSet = new PageSet(1);
doc.Save(ArtifactsDir + $"ImageSaveOptions.PageIndex.Page {i}.gif", saveOptions);
}Shows how to render every page of a document to a separate TIFF image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.Writeln("Page 1.");
builder.InsertBreak(BreakType.PageBreak);
builder.Writeln("Page 2.");
builder.InsertImage(ImageDir + "Logo.jpg");
builder.InsertBreak(BreakType.PageBreak);
builder.Writeln("Page 3.");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Tiff);
for (int i = 0; i < doc.PageCount; i++)
{
// Set the "PageSet" property to the number of the first page from
// which to start rendering the document from.
options.PageSet = new PageSet(i);
// Export page at 2325x5325 pixels and 600 dpi.
options.Resolution = 600;
options.ImageSize = new Size(2325, 5325);
doc.Save(ArtifactsDir + $"ImageSaveOptions.PageByPage.{i + 1}.tiff", options);
}Shows how to render one page from a document to a JPEG image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.Writeln("Page 1.");
builder.InsertBreak(BreakType.PageBreak);
builder.Writeln("Page 2.");
builder.InsertImage(ImageDir + "Logo.jpg");
builder.InsertBreak(BreakType.PageBreak);
builder.Writeln("Page 3.");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Jpeg);
// Set the "PageSet" to "1" to select the second page via
// the zero-based index to start rendering the document from.
options.PageSet = new PageSet(1);
// When we save the document to the JPEG format, Aspose.Words only renders one page.
// This image will contain one page starting from page two,
// which will just be the second page of the original document.
doc.Save(ArtifactsDir + "ImageSaveOptions.OnePage.jpg", options);Remarks
This property has effect only when rendering document pages. This property is ignored when rendering shapes to images.
PaperColor
Gets or sets the background (paper) color for the generated images.
The default value is System.Drawing.Color.White.
public Color PaperColor { get; set; }Property Value
Examples
Renders a page of a Word document into an image with transparent or colored background.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.Font.Name = "Times New Roman";
builder.Font.Size = 24;
builder.Writeln("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.");
builder.InsertImage(ImageDir + "Logo.jpg");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions imgOptions = new ImageSaveOptions(SaveFormat.Png);
// Set the "PaperColor" property to a transparent color to apply a transparent
// background to the document while rendering it to an image.
imgOptions.PaperColor = Color.Transparent;
doc.Save(ArtifactsDir + "ImageSaveOptions.PaperColor.Transparent.png", imgOptions);
// Set the "PaperColor" property to an opaque color to apply that color
// as the background of the document as we render it to an image.
imgOptions.PaperColor = Color.LightCoral;
doc.Save(ArtifactsDir + "ImageSaveOptions.PaperColor.LightCoral.png", imgOptions);Remarks
When rendering pages of a document that specifies its own background color, then the document background color will override the color specified by this property.
PixelFormat
Gets or sets the pixel format for the generated images.
public ImagePixelFormat PixelFormat { get; set; }Property Value
Examples
Shows how to select a bit-per-pixel rate with which to render a document to an image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an image, we can pass a SaveOptions object to
// select a pixel format for the image that the saving operation will generate.
// Various bit per pixel rates will affect the quality and file size of the generated image.
ImageSaveOptions imageSaveOptions = new ImageSaveOptions(SaveFormat.Png);
imageSaveOptions.PixelFormat = imagePixelFormat;
// We can clone ImageSaveOptions instances.
Assert.That(imageSaveOptions.Clone(), Is.Not.EqualTo(imageSaveOptions));
doc.Save(ArtifactsDir + "ImageSaveOptions.PixelFormat.png", imageSaveOptions);Remarks
This property has effect only when saving to raster image formats.
The default value is Aspose.Words.Saving.ImagePixelFormat.Format32BppArgb.
Pixel format of the output image may differ from the set value because of work of GDI+.
Resolution
Sets both horizontal and vertical resolution for the generated images, in dots per inch.
public float Resolution { set; }Property Value
Examples
Shows how to specify a resolution while rendering a document to PNG.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.Font.Name = "Times New Roman";
builder.Font.Size = 24;
builder.Writeln("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.");
builder.InsertImage(ImageDir + "Logo.jpg");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Png);
// Set the "Resolution" property to "72" to render the document in 72dpi.
options.Resolution = 72;
doc.Save(ArtifactsDir + "ImageSaveOptions.Resolution.72dpi.png", options);
// Set the "Resolution" property to "300" to render the document in 300dpi.
options.Resolution = 300;
doc.Save(ArtifactsDir + "ImageSaveOptions.Resolution.300dpi.png", options);Remarks
This property has effect only when saving to raster image formats.
SaveFormat
Specifies the format in which the rendered document pages or shapes will be saved if this save options object is used. Can be a raster Aspose.Words.SaveFormat.Tiff, Aspose.Words.SaveFormat.Png, Aspose.Words.SaveFormat.Bmp, Aspose.Words.SaveFormat.Jpeg or vector Aspose.Words.SaveFormat.Emf, Aspose.Words.SaveFormat.Eps, Aspose.Words.SaveFormat.WebP, Aspose.Words.SaveFormat.Svg.
public override SaveFormat SaveFormat { get; set; }Property Value
Examples
Shows how to edit the image while Aspose.Words converts a document to one.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an image, we can pass a SaveOptions object to
// edit the image while the saving operation renders it.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Png)
{
// We can adjust these properties to change the image's brightness and contrast.
// Both are on a 0-1 scale and are at 0.5 by default.
ImageBrightness = 0.3f,
ImageContrast = 0.7f,
// We can adjust horizontal and vertical resolution with these properties.
// This will affect the dimensions of the image.
// The default value for these properties is 96.0, for a resolution of 96dpi.
HorizontalResolution = 72f,
VerticalResolution = 72f,
// We can scale the image using this property. The default value is 1.0, for scaling of 100%.
// We can use this property to negate any changes in image dimensions that changing the resolution would cause.
Scale = 96f / 72f
};
doc.Save(ArtifactsDir + "ImageSaveOptions.EditImage.png", options);Remarks
The number of other options depends on the selected format.
Also, it is possible to save to SVG both via Aspose.Words.Saving.ImageSaveOptions and via Aspose.Words.Saving.SvgSaveOptions.
Scale
Gets or sets the zoom factor for the generated images.
public float Scale { get; set; }Property Value
Examples
Shows how to render an Office Math object into an image file in the local file system.
Document doc = new Document(MyDir + "Office math.docx");
OfficeMath math = (OfficeMath)doc.GetChild(NodeType.OfficeMath, 0, true);
// Create an "ImageSaveOptions" object to pass to the node renderer's "Save" method to modify
// how it renders the OfficeMath node into an image.
ImageSaveOptions saveOptions = new ImageSaveOptions(SaveFormat.Png);
// Set the "Scale" property to 5 to render the object to five times its original size.
saveOptions.Scale = 5;
math.GetMathRenderer().Save(ArtifactsDir + "Shape.RenderOfficeMath.png", saveOptions);Shows how to edit the image while Aspose.Words converts a document to one.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an image, we can pass a SaveOptions object to
// edit the image while the saving operation renders it.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Png)
{
// We can adjust these properties to change the image's brightness and contrast.
// Both are on a 0-1 scale and are at 0.5 by default.
ImageBrightness = 0.3f,
ImageContrast = 0.7f,
// We can adjust horizontal and vertical resolution with these properties.
// This will affect the dimensions of the image.
// The default value for these properties is 96.0, for a resolution of 96dpi.
HorizontalResolution = 72f,
VerticalResolution = 72f,
// We can scale the image using this property. The default value is 1.0, for scaling of 100%.
// We can use this property to negate any changes in image dimensions that changing the resolution would cause.
Scale = 96f / 72f
};
doc.Save(ArtifactsDir + "ImageSaveOptions.EditImage.png", options);Remarks
The default value is 1.0. The value must be greater than 0.
ThresholdForFloydSteinbergDithering
Gets or sets the threshold that determines the value of the binarization error in the Floyd-Steinberg method. when Aspose.Words.Saving.ImageBinarizationMethod is Aspose.Words.Saving.ImageBinarizationMethod.FloydSteinbergDithering.
public byte ThresholdForFloydSteinbergDithering { get; set; }Property Value
Examples
Shows how to set the TIFF binarization error threshold when using the Floyd-Steinberg method to render a TIFF image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as a TIFF, we can pass a SaveOptions object to
// adjust the dithering that Aspose.Words will apply when rendering this image.
// The default value of the "ThresholdForFloydSteinbergDithering" property is 128.
// Higher values tend to produce darker images.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Tiff)
{
TiffCompression = TiffCompression.Ccitt3,
TiffBinarizationMethod = ImageBinarizationMethod.FloydSteinbergDithering,
ThresholdForFloydSteinbergDithering = 240
};
doc.Save(ArtifactsDir + "ImageSaveOptions.FloydSteinbergDithering.tiff", options);Remarks
The default value is 128.
TiffBinarizationMethod
Gets or sets method used while converting images to 1 bpp format when Aspose.Words.Saving.ImageSaveOptions.SaveFormat is Aspose.Words.SaveFormat.Tiff and Aspose.Words.Saving.ImageSaveOptions.TiffCompression is equal to Aspose.Words.Saving.TiffCompression.Ccitt3 or Aspose.Words.Saving.TiffCompression.Ccitt4.
public ImageBinarizationMethod TiffBinarizationMethod { get; set; }Property Value
Examples
Shows how to set the TIFF binarization error threshold when using the Floyd-Steinberg method to render a TIFF image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as a TIFF, we can pass a SaveOptions object to
// adjust the dithering that Aspose.Words will apply when rendering this image.
// The default value of the "ThresholdForFloydSteinbergDithering" property is 128.
// Higher values tend to produce darker images.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Tiff)
{
TiffCompression = TiffCompression.Ccitt3,
TiffBinarizationMethod = ImageBinarizationMethod.FloydSteinbergDithering,
ThresholdForFloydSteinbergDithering = 240
};
doc.Save(ArtifactsDir + "ImageSaveOptions.FloydSteinbergDithering.tiff", options);Remarks
The default value is Aspose.Words.Saving.ImageBinarizationMethod.Threshold.
TiffCompression
Gets or sets the type of compression to apply when saving generated images to the TIFF format.
public TiffCompression TiffCompression { get; set; }Property Value
Examples
Shows how to select the compression scheme to apply to a document that we convert into a TIFF image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.InsertImage(ImageDir + "Logo.jpg");
// Create an "ImageSaveOptions" object which we can pass to the document's "Save" method
// to modify the way in which that method renders the document into an image.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Tiff);
// Set the "TiffCompression" property to "TiffCompression.None" to apply no compression while saving,
// which may result in a very large output file.
// Set the "TiffCompression" property to "TiffCompression.Rle" to apply RLE compression
// Set the "TiffCompression" property to "TiffCompression.Lzw" to apply LZW compression.
// Set the "TiffCompression" property to "TiffCompression.Ccitt3" to apply CCITT3 compression.
// Set the "TiffCompression" property to "TiffCompression.Ccitt4" to apply CCITT4 compression.
options.TiffCompression = tiffCompression;
doc.Save(ArtifactsDir + "ImageSaveOptions.TiffImageCompression.tiff", options);Remarks
Has effect only when saving to TIFF.
The default value is Aspose.Words.Saving.TiffCompression.Lzw.
UseGdiEmfRenderer
Gets or sets a value determining whether to use GDI+ or Aspose.Words metafile renderer when saving to EMF.
public bool UseGdiEmfRenderer { get; set; }Property Value
Examples
Shows how to choose a renderer when converting a document to .emf.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an EMF image, we can pass a SaveOptions object to select a renderer for the image.
// If we set the "UseGdiEmfRenderer" flag to "true", Aspose.Words will use the GDI+ renderer.
// If we set the "UseGdiEmfRenderer" flag to "false", Aspose.Words will use its own metafile renderer.
ImageSaveOptions saveOptions = new ImageSaveOptions(SaveFormat.Emf);
saveOptions.UseGdiEmfRenderer = useGdiEmfRenderer;
doc.Save(ArtifactsDir + "ImageSaveOptions.Renderer.emf", saveOptions);Remarks
If set to true GDI+ metafile renderer is used. I.e. content is written to GDI+ graphics
object and saved to metafile.
If set to false Aspose.Words metafile renderer is used. I.e. content is written directly
to the metafile format with Aspose.Words.
Has effect only when saving to EMF.
GDI+ saving works only on .NET.
The default value is true.
VerticalResolution
Gets or sets the vertical resolution for the generated images, in dots per inch.
public float VerticalResolution { get; set; }Property Value
Examples
Shows how to edit the image while Aspose.Words converts a document to one.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an image, we can pass a SaveOptions object to
// edit the image while the saving operation renders it.
ImageSaveOptions options = new ImageSaveOptions(SaveFormat.Png)
{
// We can adjust these properties to change the image's brightness and contrast.
// Both are on a 0-1 scale and are at 0.5 by default.
ImageBrightness = 0.3f,
ImageContrast = 0.7f,
// We can adjust horizontal and vertical resolution with these properties.
// This will affect the dimensions of the image.
// The default value for these properties is 96.0, for a resolution of 96dpi.
HorizontalResolution = 72f,
VerticalResolution = 72f,
// We can scale the image using this property. The default value is 1.0, for scaling of 100%.
// We can use this property to negate any changes in image dimensions that changing the resolution would cause.
Scale = 96f / 72f
};
doc.Save(ArtifactsDir + "ImageSaveOptions.EditImage.png", options);Remarks
This property has effect only when saving to raster image formats and affects the output size in pixels.
The default value is 96.
Methods
Clone()
Creates a deep clone of this object.
public ImageSaveOptions Clone()Returns
Examples
Shows how to select a bit-per-pixel rate with which to render a document to an image.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Hello world!");
builder.InsertImage(ImageDir + "Logo.jpg");
// When we save the document as an image, we can pass a SaveOptions object to
// select a pixel format for the image that the saving operation will generate.
// Various bit per pixel rates will affect the quality and file size of the generated image.
ImageSaveOptions imageSaveOptions = new ImageSaveOptions(SaveFormat.Png);
imageSaveOptions.PixelFormat = imagePixelFormat;
// We can clone ImageSaveOptions instances.
Assert.That(imageSaveOptions.Clone(), Is.Not.EqualTo(imageSaveOptions));
doc.Save(ArtifactsDir + "ImageSaveOptions.PixelFormat.png", imageSaveOptions);