How to use Range.CopyPicture in the xlwings API way

The Range.CopyPicture member in Excel’s object model allows you to copy a range of cells as a picture, which can then be pasted into other locations within Excel or into external applications. This is particularly useful for creating visual snapshots of data, charts, or formatted tables that need to be shared or used in reports, presentations, or dashboards. In xlwings, this functionality is accessible through the API, enabling automation of picture-copying tasks directly from Python scripts.

The syntax for CopyPicture in xlwings follows the Excel object model closely. It is a method that can be called on a Range object. The method takes two parameters: Appearance and Format. These parameters determine how the picture is copied, affecting its visual quality and file format. In xlwings, you invoke it as range_object.api.CopyPicture(Appearance, Format), where range_object is an instance of xlwings’ Range class. The parameters are optional in Excel, but when specified in xlwings, they should be passed as constants or integer values.

The Appearance parameter controls whether the picture is copied as it appears on screen or as it would look when printed. It accepts two primary values: xlScreen (value 1) for screen appearance, which is the default, and xlPrinter (value 2) for printer appearance, which may include higher resolution or print-specific settings. The Format parameter defines the picture format, with key options being xlPicture (value -4147) for bitmap format and xlBitmap (value 2) for a bitmap image. In practice, xlPicture is commonly used for copying ranges as pictures in Excel. If parameters are omitted, Excel uses default values, typically xlScreen and xlPicture.

Here is a table summarizing the parameter options:

To use CopyPicture in xlwings, you first need to establish a connection to an Excel application and workbook. After copying the range as a picture, you can paste it elsewhere using the Paste method on a destination range or sheet. Below is a code example that demonstrates this process:

import xlwings as xw

# Connect to the active Excel instance or create a new one
app = xw.apps.active
wb = app.books.active
sheet = wb.sheets['Sheet1']

# Define the source range to copy as a picture (e.g., cells A1 to D10)
source_range = sheet.range('A1:D10')

# Copy the range as a picture with screen appearance and picture format
source_range.api.CopyPicture(Appearance=1, Format=-4147) # Using integer values for clarity

# Specify a destination range to paste the picture (e.g., starting at cell F1)
dest_range = sheet.range('F1')
sheet.api.Paste(Destination=dest_range.api) # Paste the picture at the destination

# Alternatively, you can use constants from the xlwings.constants module for better readability
import xlwings.constants as win32c
source_range.api.CopyPicture(Appearance=win32c.xlScreen, Format=win32c.xlPicture)
sheet.api.Paste(Destination=dest_range.api)

# Save the workbook if needed
wb.save()