insert_image method
insert_image(file_name)
Inserts an image from a file or URL into the document. The image is inserted inline and at 100% scale.
def insert_image(self, file_name: str):
...
| Parameter | Type | Description |
|---|---|---|
| file_name | str | The file with the image. Can be any valid local or remote URI. |
Remarks
This overload will automatically download the image before inserting into the document if you specify a remote URI.
You can change the image size, location, positioning method and other settings using the Shape object returned by this method.
Returns
The image node that was just inserted.
insert_image(stream)
Inserts an image from a stream into the document. The image is inserted inline and at 100% scale.
def insert_image(self, stream: io.BytesIO):
...
| Parameter | Type | Description |
|---|---|---|
| stream | io.BytesIO | The stream that contains the image. |
Remarks
You can change the image size, location, positioning method and other settings using the Shape object returned by this method.
Returns
The image node that was just inserted.
insert_image(image_bytes)
Inserts an image from a byte array into the document. The image is inserted inline and at 100% scale.
def insert_image(self, image_bytes: bytes):
...
| Parameter | Type | Description |
|---|---|---|
| image_bytes | bytes | The byte array that contains the image. |
Remarks
You can change the image size, location, positioning method and other settings using the Shape object returned by this method.
Returns
The image node that was just inserted.
insert_image(file_name, width, height)
Inserts an inline image from a file or URL into the document and scales it to the specified size.
def insert_image(self, file_name: str, width: float, height: float):
...
| Parameter | Type | Description |
|---|---|---|
| file_name | str | The file that contains the image. |
| width | float | The width of the image in points. Can be a negative or zero value to request 100% scale. |
| height | float | The height of the image in points. Can be a negative or zero value to request 100% scale. |
Remarks
You can change the image size, location, positioning method and other settings using the Shape object returned by this method.
Returns
The image node that was just inserted.
insert_image(stream, width, height)
Inserts an inline image from a stream into the document and scales it to the specified size.
def insert_image(self, stream: io.BytesIO, width: float, height: float):
...
| Parameter | Type | Description |
|---|---|---|
| stream | io.BytesIO | The stream that contains the image. |
| width | float | The width of the image in points. Can be a negative or zero value to request 100% scale. |
| height | float | The height of the image in points. Can be a negative or zero value to request 100% scale. |
Remarks
You can change the image size, location, positioning method and other settings using the Shape object returned by this method.
Returns
The image node that was just inserted.
insert_image(image_bytes, width, height)
Inserts an inline image from a byte array into the document and scales it to the specified size.
def insert_image(self, image_bytes: bytes, width: float, height: float):
...
| Parameter | Type | Description |
|---|---|---|
| image_bytes | bytes | The byte array that contains the image. |
| width | float | The width of the image in points. Can be a negative or zero value to request 100% scale. |
| height | float | The height of the image in points. Can be a negative or zero value to request 100% scale. |
Remarks
You can change the image size, location, positioning method and other settings using the Shape object returned by this method.
Returns
The image node that was just inserted.
insert_image(file_name, horz_pos, left, vert_pos, top, width, height, wrap_type)
Inserts an image from a file or URL at the specified position and size.
def insert_image(self, file_name: str, horz_pos: aspose.words.drawing.RelativeHorizontalPosition, left: float, vert_pos: aspose.words.drawing.RelativeVerticalPosition, top: float, width: float, height: float, wrap_type: aspose.words.drawing.WrapType):
...
| Parameter | Type | Description |
|---|---|---|
| file_name | str | The file that contains the image. |
| horz_pos | RelativeHorizontalPosition | Specifies where the distance to the image is measured from. |
| left | float | Distance in points from the origin to the left side of the image. |
| vert_pos | RelativeVerticalPosition | Specifies where the distance to the image measured from. |
| top | float | Distance in points from the origin to the top side of the image. |
| width | float | The width of the image in points. Can be a negative or zero value to request 100% scale. |
| height | float | The height of the image in points. Can be a negative or zero value to request 100% scale. |
| wrap_type | WrapType | Specifies how to wrap text around the image. |
Remarks
You can change the image size, location, positioning method and other settings using the Shape object returned by this method.
Returns
The image node that was just inserted.
insert_image(stream, horz_pos, left, vert_pos, top, width, height, wrap_type)
Inserts an image from a stream at the specified position and size.
def insert_image(self, stream: io.BytesIO, horz_pos: aspose.words.drawing.RelativeHorizontalPosition, left: float, vert_pos: aspose.words.drawing.RelativeVerticalPosition, top: float, width: float, height: float, wrap_type: aspose.words.drawing.WrapType):
...
| Parameter | Type | Description |
|---|---|---|
| stream | io.BytesIO | The stream that contains the image. |
| horz_pos | RelativeHorizontalPosition | Specifies where the distance to the image is measured from. |
| left | float | Distance in points from the origin to the left side of the image. |
| vert_pos | RelativeVerticalPosition | Specifies where the distance to the image measured from. |
| top | float | Distance in points from the origin to the top side of the image. |
| width | float | The width of the image in points. Can be a negative or zero value to request 100% scale. |
| height | float | The height of the image in points. Can be a negative or zero value to request 100% scale. |
| wrap_type | WrapType | Specifies how to wrap text around the image. |
Remarks
You can change the image size, location, positioning method and other settings using the Shape object returned by this method.
Returns
The image node that was just inserted.
insert_image(image_bytes, horz_pos, left, vert_pos, top, width, height, wrap_type)
Inserts an image from a byte array at the specified position and size.
def insert_image(self, image_bytes: bytes, horz_pos: aspose.words.drawing.RelativeHorizontalPosition, left: float, vert_pos: aspose.words.drawing.RelativeVerticalPosition, top: float, width: float, height: float, wrap_type: aspose.words.drawing.WrapType):
...
| Parameter | Type | Description |
|---|---|---|
| image_bytes | bytes | The byte array that contains the image. |
| horz_pos | RelativeHorizontalPosition | Specifies where the distance to the image is measured from. |
| left | float | Distance in points from the origin to the left side of the image. |
| vert_pos | RelativeVerticalPosition | Specifies where the distance to the image measured from. |
| top | float | Distance in points from the origin to the top side of the image. |
| width | float | The width of the image in points. Can be a negative or zero value to request 100% scale. |
| height | float | The height of the image in points. Can be a negative or zero value to request 100% scale. |
| wrap_type | WrapType | Specifies how to wrap text around the image. |
Remarks
You can change the image size, location, positioning method and other settings using the Shape object returned by this method.
Returns
The image node that was just inserted.
Examples
Shows how to determine which image will be inserted.
doc = aw.Document()
builder = aw.DocumentBuilder(doc=doc)
builder.insert_image(file_name=IMAGE_DIR + 'Scalable Vector Graphics.svg')
# Aspose.Words insert SVG image to the document as PNG with svgBlip extension
# that contains the original vector SVG image representation.
doc.save(file_name=ARTIFACTS_DIR + 'DocumentBuilderImages.InsertSvgImage.SvgWithSvgBlip.docx')
# Aspose.Words insert SVG image to the document as PNG, just like Microsoft Word does for old format.
doc.save(file_name=ARTIFACTS_DIR + 'DocumentBuilderImages.InsertSvgImage.Svg.doc')
doc.compatibility_options.optimize_for(aw.settings.MsWordVersion.WORD2003)
# Aspose.Words insert SVG image to the document as EMF metafile to keep the image in vector representation.
doc.save(file_name=ARTIFACTS_DIR + 'DocumentBuilderImages.InsertSvgImage.Emf.docx')
Shows how to insert gif image to the document.
builder = aw.DocumentBuilder()
# We can insert gif image using path or bytes array.
# It works only if DocumentBuilder optimized to Word version 2010 or higher.
# Note, that access to the image bytes causes conversion Gif to Png.
gif_image = builder.insert_image(file_name=IMAGE_DIR + 'Graphics Interchange Format.gif')
gif_image = builder.insert_image(image_bytes=system_helper.io.File.read_all_bytes(IMAGE_DIR + 'Graphics Interchange Format.gif'))
builder.document.save(file_name=ARTIFACTS_DIR + 'InsertGif.docx')
Shows how to insert an image from the local file system into a document.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
# Below are three ways of inserting an image from a local system filename.
# 1 - Inline shape with a default size based on the image's original dimensions:
builder.insert_image(IMAGE_DIR + 'Logo.jpg')
builder.insert_break(aw.BreakType.PAGE_BREAK)
# 2 - Inline shape with custom dimensions:
builder.insert_image(IMAGE_DIR + 'Transparent background logo.png', aw.ConvertUtil.pixel_to_point(250), aw.ConvertUtil.pixel_to_point(144))
builder.insert_break(aw.BreakType.PAGE_BREAK)
# 3 - Floating shape with custom dimensions:
builder.insert_image(IMAGE_DIR + 'Windows MetaFile.wmf', aw.drawing.RelativeHorizontalPosition.MARGIN, 100, aw.drawing.RelativeVerticalPosition.MARGIN, 100, 200, 100, aw.drawing.WrapType.SQUARE)
doc.save(ARTIFACTS_DIR + 'DocumentBuilderImages.insert_image_from_filename.docx')
Shows how to insert WebP image.
doc = aw.Document()
builder = aw.DocumentBuilder(doc=doc)
builder.insert_image(file_name=IMAGE_DIR + 'WebP image.webp')
doc.save(file_name=ARTIFACTS_DIR + 'Image.InsertWebpImage.docx')
Shows how to insert a shape with an image into a document.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
# Below are two locations where the document builder's "insert_image" method
# can source the image that the shape will display.
# 1 - Pass a local file system filename of an image file:
builder.write('Image from local file: ')
builder.insert_image(IMAGE_DIR + 'Logo.jpg')
builder.writeln()
# 2 - Pass a URL which points to an image.
builder.write('Image from a URL: ')
builder.insert_image(IMAGE_URL)
builder.writeln()
doc.save(ARTIFACTS_DIR + 'Image.from_url.docx')
Shows how to insert a floating image to the center of a page.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
# Insert a floating image that will appear behind the overlapping text and align it to the page's center.
shape = builder.insert_image(IMAGE_DIR + 'Logo.jpg')
shape.wrap_type = aw.drawing.WrapType.NONE
shape.behind_text = True
shape.relative_horizontal_position = aw.drawing.RelativeHorizontalPosition.PAGE
shape.relative_vertical_position = aw.drawing.RelativeVerticalPosition.PAGE
shape.horizontal_alignment = aw.drawing.HorizontalAlignment.CENTER
shape.vertical_alignment = aw.drawing.VerticalAlignment.CENTER
doc.save(ARTIFACTS_DIR + 'Image.create_floating_page_center.docx')
Shows how to insert an image from a stream into a document.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
with open(IMAGE_DIR + 'Logo.jpg', 'rb') as stream:
# Below are three ways of inserting an image from a stream.
# 1 - Inline shape with a default size based on the image's original dimensions:
builder.insert_image(stream)
builder.insert_break(aw.BreakType.PAGE_BREAK)
# 2 - Inline shape with custom dimensions:
builder.insert_image(stream, aw.ConvertUtil.pixel_to_point(250), aw.ConvertUtil.pixel_to_point(144))
builder.insert_break(aw.BreakType.PAGE_BREAK)
# 3 - Floating shape with custom dimensions:
builder.insert_image(stream, aw.drawing.RelativeHorizontalPosition.MARGIN, 100, aw.drawing.RelativeVerticalPosition.MARGIN, 100, 200, 100, aw.drawing.WrapType.SQUARE)
doc.save(ARTIFACTS_DIR + 'DocumentBuilderImages.insert_image_from_stream.docx')
Shows how to insert a shape with an image from a stream into a document.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
with open(IMAGE_DIR + 'Logo.jpg', 'rb') as stream:
builder.write('Image from stream: ')
builder.insert_image(stream)
doc.save(ARTIFACTS_DIR + 'Image.from_stream.docx')
Shows how to insert an image from a byte array into a document.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
image_byte_array = self.image_to_byte_array(IMAGE_DIR + 'Logo.jpg')
# Below are three ways of inserting an image from a byte array.
# 1 - Inline shape with a default size based on the image's original dimensions:
builder.insert_image(image_byte_array)
builder.insert_break(aw.BreakType.PAGE_BREAK)
# 2 - Inline shape with custom dimensions:
builder.insert_image(image_byte_array, aw.ConvertUtil.pixel_to_point(250), aw.ConvertUtil.pixel_to_point(144))
builder.insert_break(aw.BreakType.PAGE_BREAK)
# 3 - Floating shape with custom dimensions:
builder.insert_image(image_byte_array, aw.drawing.RelativeHorizontalPosition.MARGIN, 100, aw.drawing.RelativeVerticalPosition.MARGIN, 100, 200, 100, aw.drawing.WrapType.SQUARE)
doc.save(ARTIFACTS_DIR + 'DocumentBuilderImages.insert_image_from_byte_array.docx')
Shows how to insert an image.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
# There are two ways of using a document builder to source an image and then insert it as a floating shape.
# 1 - From a file in the local file system:
builder.insert_image(IMAGE_DIR + 'Transparent background logo.png', aw.drawing.RelativeHorizontalPosition.MARGIN, 100, aw.drawing.RelativeVerticalPosition.MARGIN, 0, 200, 200, aw.drawing.WrapType.SQUARE)
# 2 - From a URL:
builder.insert_image(IMAGE_URL, aw.drawing.RelativeHorizontalPosition.MARGIN, 100, aw.drawing.RelativeVerticalPosition.MARGIN, 250, 200, 200, aw.drawing.WrapType.SQUARE)
doc.save(ARTIFACTS_DIR + 'DocumentBuilder.insert_floating_image.docx')
Shows how to insert an image from the local file system into a document while preserving its dimensions.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
# The "insert_image" method creates a floating shape with the passed image in its image data.
# We can specify the dimensions of the shape can be passing them to this method.
image_shape = builder.insert_image(IMAGE_DIR + 'Logo.jpg', aw.drawing.RelativeHorizontalPosition.MARGIN, 0, aw.drawing.RelativeVerticalPosition.MARGIN, 0, -1, -1, aw.drawing.WrapType.SQUARE)
# Passing negative values as the intended dimensions will automatically define
# the shape's dimensions based on the dimensions of its image.
self.assertEqual(300.0, image_shape.width)
self.assertEqual(300.0, image_shape.height)
doc.save(ARTIFACTS_DIR + 'DocumentBuilder.insert_image_original_size.docx')
See Also
- module aspose.words
- class DocumentBuilder