Python Word Document: Inserting Images from a Folder

Aspose.Words for Python offers a robust and versatile way to manipulate Word documents programmatically. A common task when working with documents is inserting images. This article will guide you through the process of inserting images from a folder into your Word documents using Python and Aspose.Words, enhancing your document creation and automation capabilities.

Inserting Images into Word Documents

Aspose.Words’ DocumentBuilder class is your primary tool for programmatically building documents. It provides the insert_image method, which offers several overloaded options to insert images, whether inline with text or floating freely on the page. Notably, if you insert an EMF or WMF metafile, Aspose.Words smartly retains it in metafile format within the document. For all other image types, they are automatically converted and stored as PNG for optimal document compatibility.

The insert_image method is flexible, allowing you to source your images from various locations:

• Directly from a file path or a web URL by providing a string.
• From an existing stream of image data using a Stream parameter.
• From an in-memory byte array by passing a byte array parameter.

Each insert_image method overload provides further customization options:

• Insertion as an inline image or as a floating image at a precise position on the page.
• Control over image scaling using percentages or specific dimensions.

Furthermore, DocumentBuilder.insert_image conveniently returns a Shape object representing the newly inserted image. This allows you to further modify the image’s properties using the extensive Shape object model.

Inserting Inline Images

To insert an image inline with the text flow at the current cursor position, simply provide the file path of the image to the insert_image method.

doc = aw.Document()
builder = aw.DocumentBuilder(doc)
builder.insert_image(docs_base.images_dir + "Logo.jpg")
doc.save(docs_base.artifacts_dir+"WorkingWithImages.document_builder_insert_inline_image.docx")

This code snippet demonstrates how straightforward it is to embed an image seamlessly within your document’s text.

Inserting Floating Images (Absolutely Positioned)

For more precise control over image placement, you can insert floating images. This allows you to position the image at absolute coordinates on the page, independent of the text flow. The following example demonstrates inserting a floating image from a file or URL, specifying its position and size:

doc = aw.Document()
builder = aw.DocumentBuilder(doc)
builder.insert_image(docs_base.images_dir + "Logo.jpg",
                    aw.drawing.RelativeHorizontalPosition.MARGIN, 100,
                    aw.drawing.RelativeVerticalPosition.MARGIN, 100,
                    200, 100, aw.drawing.WrapType.SQUARE)
doc.save(docs_base.artifacts_dir+"WorkingWithImages.document_builder_insert_floating_image.docx")

This code snippet showcases how to insert an image that floats above the text, positioned 100 points from both the horizontal and vertical margins, with a width of 200 points and a height of 100 points.

Extracting Images from a Word Document

Beyond inserting images, Aspose.Words allows you to programmatically extract images that are already embedded within a Word document. All images in an Aspose.Words Document are stored as Shape nodes. To extract all images, or filter for specific image types, follow these steps:

1. Use Document.get_child_nodes(aw.NodeType.SHAPE, True) to retrieve a collection of all Shape nodes within the document. The True parameter ensures deep traversal, including shapes within groups.
2. Iterate through the resulting collection of nodes.
3. For each node, check the Shape.has_image boolean property. If True, the shape contains an image.
4. Access the image data through the Shape.image_data property.
5. Utilize methods like ImageData.save() to save the extracted image data to a file.

def extract_images_to_files():
    doc = aw.Document(docs_base.data_dir + "Images.docx")
    shapes = doc.get_child_nodes(aw.NodeType.SHAPE, True)
    image_index = 0
    for shape in shapes:
        shape = shape.as_shape()
        if shape.has_image:
            image_data = shape.image_data
            image_file_name = (f"Image.ExportImages.{image_index}_{image_data.suggested_file_name}")
            image_data.save(docs_base.artifacts_dir + image_file_name)
            image_index += 1

extract_images_to_files()

This Python code efficiently extracts all images from the “Images.docx” document (available in Aspose.Words examples) and saves them as individual files.

Maintaining Image Aspect Ratio

The aspect ratio of an image is the ratio of its width to its height. Preserving the aspect ratio is often crucial to prevent image distortion. Aspose.Words allows you to control this through the aspect_ratio_locked property of the Shape object.

By default, for ShapeType.IMAGE shapes, aspect_ratio_locked is set to True, ensuring that the aspect ratio is maintained during resizing. For other shape types, the default is False.

doc = aw.Document()
builder = aw.DocumentBuilder(doc)
shape = builder.insert_image(docs_base.images_dir + "Logo.jpg")
shape.aspect_ratio_locked = False
doc.save(docs_base.artifacts_dir+"WorkingWithImages.set_aspect_ratio_locked.docx")

This example demonstrates how to unlock the aspect ratio, allowing you to freely scale the image width and height independently.

Retrieving Actual Shape Bounds in Points

To determine the rendered size and position of a shape on the page, Aspose.Words provides the bounds_in_points property. This is particularly useful when you need to know the precise layout dimensions of shapes after document rendering.

doc = aw.Document()
builder = aw.DocumentBuilder(doc)
shape = builder.insert_image(docs_base.images_dir + "Logo.jpg")
shape.aspect_ratio_locked = False

print("nGets the actual bounds of the shape in points.")
rect = shape.get_shape_renderer().bounds_in_points
print(f"{rect.x}, {rect.y}, {rect.width}, {rect.height}")

This code snippet retrieves the bounding box of the inserted image in points, giving you the exact dimensions and location as rendered in the document.

Cropping Images Programmatically

Image cropping is a valuable technique for refining image composition and focusing on specific areas. Aspose.Words enables you to programmatically crop images within your Word documents using the ImageData.crop_left, ImageData.crop_right, ImageData.crop_top, and ImageData.crop_bottom properties. These properties accept values as a fraction of the image’s width or height (from 0.0 to 1.0).

@staticmethod
def crop_image(in_path: str, out_path: str, left: int, top: int, width: int, height: int):
    doc = aw.Document()
    builder = aw.DocumentBuilder(doc)
    cropped_image = builder.insert_image(in_path)

    src_width_points = cropped_image.width
    src_height_points = cropped_image.height

    cropped_image.width = aw.ConvertUtil.pixel_to_point(width)
    cropped_image.height = aw.ConvertUtil.pixel_to_point(height)

    width_ratio = cropped_image.width / src_width_points
    height_ratio = cropped_image.height / src_height_points

    if (width_ratio < 1):
        cropped_image.image_data.crop_right = 1 - width_ratio
    if (height_ratio < 1):
        cropped_image.image_data.crop_bottom = 1 - height_ratio

    left_to_width = aw.ConvertUtil.pixel_to_point(left) / src_width_points
    top_to_height = aw.ConvertUtil.pixel_to_point(top) / src_height_points

    cropped_image.image_data.crop_left = left_to_width
    cropped_image.image_data.crop_right = cropped_image.image_data.crop_right - left_to_width
    cropped_image.image_data.crop_top = top_to_height
    cropped_image.image_data.crop_bottom = cropped_image.image_data.crop_bottom - top_to_height

    cropped_image.get_shape_renderer().save(out_path, aw.saving.ImageSaveOptions(aw.SaveFormat.JPEG))


input_path = docs_base.images_dir + "Logo.jpg"
output_path = docs_base.artifacts_dir + "cropped_logo.jpg"
crop_image(input_path, output_path, 100, 90, 200, 200)

This example demonstrates a crop_image function that takes an input image path, output path, and cropping parameters (left, top, width, height in pixels). It then crops the image and saves the cropped portion.

Conclusion

Aspose.Words for Python provides a comprehensive set of tools for working with images in Word documents. From simple insertion of inline or floating images from folders to advanced manipulations like extraction, aspect ratio control, and cropping, Aspose.Words empowers you to automate and enhance your document processing workflows involving images. By leveraging these features, you can create dynamic and visually rich Word documents programmatically using Python.