Convert to Image

GcExcel allows you to convert a worksheet, any specified range, and various shape types to images using ToImage method. Hence, making it convenient to use the converted images directly in other documents, like Word, PDF or a PPT document. The supported image formats for conversion are PNG, JPG/JPEG, SVG, and GIF.

GcExcel also provides various properties in ImageSaveOptions class that can be used to modify and adjust the image when exporting a worksheet, a range, or a shape to an image file through their respective interfaces using ToImage method.

Following are the properties of ImageSaveOptions class, along with the scope in which they can be used:

Properties	Worksheet	Range	Shape	Description
ScaleX and ScaleY	Yes	Yes	Yes	Gets or sets the scale of exported image file.
Resolution	Yes	Yes	Yes	Gets or sets the jpeg file's DPI in exported image file.
BackgroundColor	Yes	Yes	Yes	Gets or sets the background color of the exported image file.
ShowRowHeadings	Yes	Yes	No	Gets or sets whether to display row headings in exported image file.
ShowColumnHeadings	Yes	Yes	No	Gets or sets whether to display column headings in exported image file.
ShowGridlines	Yes	Yes	No	Gets or sets whether to display gridlines in exported image file.
GridlineColor	Yes	Yes	No	Gets or sets the gridlines color in exported image file.
ShowDrawingObjects	Yes	Yes	No	Gets or sets whether to display drawing objects (charts, shapes, or pictures) in exported image file.
BlackAndWhite	Yes	Yes	Yes	Gets or sets whether to export black and white image.

Note: To convert images with transparency, the PNG image format should be used, as the GIF format doesn't support image transparency.

Convert Worksheet to Image

A worksheet can be converted to image using the ToImage method of IWorksheet interface. The converted image displays the rectangular area of the worksheet enclosed under cell A1 and the last cell where any data or shape is present. For eg, if a worksheet contains a shape or data in the range D5:F9, the converted image will display the area under the range A1:F9.

A blank worksheet cannot be converted to image.

Refer to the following example code to convert a worksheet to an image with or without ImageSaveOptions. In the following example code, the ImageSaveOptions modify the scale, display property of row and column headings, drawing objects, and gridlines, and change the background and gridline color.

// Create a new workbook
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.Worksheets[0];

// Add data     
worksheet.Range["A1"].Value = "Sales Report";
worksheet.Range["A1"].Font.Color = Color.FromArgb(56, 93, 171);
worksheet.Range["A1"].Font.Size = 24;
worksheet.Range["A1"].Font.Bold = true;
worksheet.Range["A3:E7"].Value = new object[,]
{
{"Date","Product","Customer","Amount","Show"},
{"1/1/2021","Bose 785593-0050","Fabrikam, Inc.","$1,886.00","1"},
{"1/3/2021","Canon EOS 1500D","Alpine Ski House","$4,022.00",""},
{"1/4/2021","Haier 394L 4Star","Coho Winery","$8,144.00",""},
{"1/7/2021","IFB 6.5 Kg FullyAuto","Southridge Video","$8,002.00","1"}
};
// Instantiate ImageSaveOptions and configure the properties
ImageSaveOptions options = new ImageSaveOptions();
options.ScaleX = 3.0;
options.ScaleY = 2.0;
options.ShowRowHeadings = true;
options.ShowColumnHeadings = false;
options.ShowDrawingObjects = true;
options.BackgroundColor = Color.FromArgb(226, 231, 243);
options.ShowGridlines = true;
options.GridlineColor = Color.FromArgb(145, 167, 214);

// Save worksheet to image without ImageSaveOptions
worksheet.ToImage("WorksheetToImage.png");

// Save worksheet to image using ImageSaveOptions
worksheet.ToImage("WorksheetToImage_UsingImageSaveOptions.png", options);

Refer to the following example code to convert a worksheet to an image with or without ImageSaveOptions from an existing file.

// Create a new workbook
var workbook = new GrapeCity.Documents.Excel.Workbook();

FileStream fileStream = new FileStream("Workbook.xlsx", FileMode.Open);

// Open a xlsx file 
workbook.Open(fileStream);
IWorksheet worksheet = workbook.Worksheets[0];

// Instantiate ImageSaveOptions and configure the properties
ImageSaveOptions options = new ImageSaveOptions();
options.ScaleX = 3.0;
options.ScaleY = 2.0;
options.ShowRowHeadings = true;
options.ShowColumnHeadings = false;
options.ShowDrawingObjects = true;
options.BackgroundColor = Color.FromArgb(226, 231, 243);
options.ShowGridlines = true;
options.GridlineColor = Color.FromArgb(145, 167, 214);

// Create a png file stream
FileStream outputStream = new FileStream("ConvertWorksheetToImage.png", FileMode.Create);

// Export the worksheet to image without ImageSaveOptions
worksheet.ToImage(outputStream, ImageType.PNG);

// Close the image stream
outputStream.Close();

// Create another png file stream
FileStream outputStreamoptions = new FileStream("ConvertWorksheetToImage_UsingImageSaveOptions.png", FileMode.Create);

//Export the worksheet to image using ImageSaveOptions
worksheet.ToImage(outputStreamoptions, ImageType.PNG, options);

// Close the image stream
outputStreamoptions.Close();

Convert Range to Image

A specific range in a worksheet can be converted to image using the ToImage method of the IRange interface. The resulting image displays the rectangular area of the worksheet enclosed under the specified range.

Refer to the following example code to convert a specified range to an image with or without ImageSaveOptions. In the following example code, the ImageSaveOptions modify the scale, display property of row and column headings, drawing objects, gridlines, and change the background and gridline color.

// Create a new workbook
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.Worksheets[0];

// Add data
worksheet.Range["D10:F10"].Value = new string[] { "Device", "Quantity", "Unit Price" };
worksheet.Range["D11:F14"].Value = new object[,]
{ { "T540p", 12, 9850 },
    { "T570", 5, 7460 },
    { "Y460", 6, 5400 },
    { "Y460F", 8, 6240 } };

IRange range = worksheet.Range["D10:F14"];

// Instantiate ImageSaveOptions and configure the properties
ImageSaveOptions options = new ImageSaveOptions();
options.ScaleX = 3.0;
options.ScaleY = 2.0;
options.ShowRowHeadings = true;
options.ShowColumnHeadings = false;
options.ShowDrawingObjects = true;
options.BackgroundColor = Color.FromArgb(226, 231, 243);
options.ShowGridlines = true;
options.GridlineColor = Color.FromArgb(145, 167, 214);

// Save range to image without ImageSaveOptions
range.ToImage("RangeToImage.png");

// Save range to image using ImageSaveOptions
range.ToImage("RangeToImage_UsingImageSaveOptions.png", options);

Refer to the following example code to convert a specified range to an image with or without ImageSaveOptions from an existing file.

// Create a new workbook
var workbook = new GrapeCity.Documents.Excel.Workbook();

FileStream fileStream = new FileStream("RangeWorkbook.xlsx", FileMode.Open);

// Open a xlsx file contains data in a range 
workbook.Open(fileStream);
IWorksheet worksheet = workbook.Worksheets[0];

// Instantiate ImageSaveOptions and configure the properties
ImageSaveOptions options = new ImageSaveOptions();
options.ScaleX = 3.0;
options.ScaleY = 2.0;
options.ShowRowHeadings = true;
options.ShowColumnHeadings = false;
options.ShowDrawingObjects = true;
options.BackgroundColor = Color.FromArgb(226, 231, 243);
options.ShowGridlines = true;
options.GridlineColor = Color.FromArgb(145, 167, 214);

// Create a png file stream
FileStream outputStream = new FileStream("ConvertRangeToImage.png", FileMode.Create);

// Export the range to image without ImageSaveOptions
worksheet.Range["A1:C5"].ToImage(outputStream, ImageType.PNG);

// Close the image stream
outputStream.Close();

// Create another png file stream
FileStream outputStreamoptions = new FileStream("ConvertRangeToImage_UsingImageSaveOptions.png", FileMode.Create);

// Export the range to image using ImageSaveOptions
worksheet.Range["A1:C5"].ToImage(outputStreamoptions, ImageType.PNG, options);

// Close the image stream
outputStreamoptions.Close();

Convert Shape to Image

GcExcel allows you to convert various shape types to image using the ToImage method of the IShape interface. The shape types include shapes like chart, picture, slicer and autoshape. The resulting image displays the rectangular area of the worksheet enclosed under the shape.

Refer to the following example code to convert an autoshape to an image with or without ImageSaveOptions. In the following example code, the ImageSaveOptions modify the scale and change the background color.

// Create a new workbook
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.Worksheets[0];

// Add an oval
IShape shape = worksheet.Shapes.AddShape(AutoShapeType.Oval, 20, 20, 200, 100);

// Instantiate ImageSaveOptions and configure the properties
ImageSaveOptions options = new ImageSaveOptions();
options.ScaleX = 3.0;
options.ScaleY = 2.0;
options.BackgroundColor = Color.Lime;

// Save shape to image without ImageSaveOptions
shape.ToImage("ShapeToImage.png");

// Save shape to image using ImageSaveOptions
shape.ToImage("ShapeToImage_UsingImageSaveOptions.png", options);

Refer to the following example code to convert an autoshape to an image with or without ImageSaveOptions from an existing file.

// Create a new workbook
var workbook = new GrapeCity.Documents.Excel.Workbook();

FileStream fileStream = new FileStream("ShapeWorkbook.xlsx", FileMode.Open);

// Open a xlsx file contains a group shape 
workbook.Open(fileStream);
IWorksheet worksheet = workbook.Worksheets[0];

// Instantiate ImageSaveOptions and configure the properties
ImageSaveOptions options = new ImageSaveOptions();
options.ScaleX = 3.0;
options.ScaleY = 2.0;
options.BackgroundColor = Color.Lime;

// Create a png file stream
FileStream outputStream = new FileStream("ConvertShapeToImage.png", FileMode.Create);

// Export the shape to image without ImageSaveOptions
worksheet.Shapes[0].ToImage(outputStream, ImageType.PNG);

// Close the image stream
outputStream.Close();

// Create another png file stream
FileStream outputStreamoptions = new FileStream("ConvertShapeToImage.png", FileMode.Create);

// Export the shape to image using ImageSaveOptions
worksheet.Shapes[0].ToImage(outputStreamoptions, ImageType.PNG, options);

// Close the image stream
outputStreamoptions.Close();

Refer to the following example code to convert a chart to image.

// Create a new workbook
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.Worksheets[0];

// Prepare data for chart
worksheet.Range["A1:D4"].Value = new object[,]
{
       {null, "Q1", "Q2", "Q3"},
       {"Mobile Phones", 1330, 2345, 3493},
       {"Laptops", 2032, 3632, 2197},
       {"Tablets", 6233, 3270, 2030}
};

worksheet.Range["A:D"].Columns.AutoFit();

// Add Area Chart
IShape shape = worksheet.Shapes.AddChart(ChartType.Area, 250, 20, 360, 230);

// Add series to SeriesCollection
shape.Chart.SeriesCollection.Add(worksheet.Range["A1:D4"], RowCol.Columns, true, true);

// Configure Chart Title 
shape.Chart.ChartTitle.TextFrame.TextRange.Paragraphs.Add("Annual Sales Record");

// Save chart to image
shape.ToImage("ConvertChartToImage.png");

Refer to the following example code to convert a chart to image from existing file.

// Create a png file stream
FileStream outputStream = new FileStream("ConvertChartToImage.png", FileMode.Create);

// Create a new workbook
var workbook = new GrapeCity.Documents.Excel.Workbook();

FileStream fileStream = new FileStream("ScatterChart.xlsx", FileMode.Open);

// Open a xlsx file contains a chart 
workbook.Open(fileStream);
IWorksheet worksheet = workbook.Worksheets[0];

// Export the chart to image
worksheet.Shapes[0].ToImage(outputStream, ImageType.PNG);

// Close the image stream
outputStream.Close();

Note: ToImage method does not support exporting images in EMF or WMF image formats.