InsertImage

InsertImage(Image)

Inserts an image from a .NET Image object into the document. The image is inserted inline and at 100% scale.

public Shape InsertImage(Image image)
ParameterTypeDescription
imageImageThe image to insert into the document.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image from an object into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

string imageFile = ImageDir + "Logo.jpg";

// Below are three ways of inserting an image from an Image object instance.
// 1 -  Inline shape with a default size based on the image's original dimensions:
builder.InsertImage(imageFile);

builder.InsertBreak(BreakType.PageBreak);

// 2 -  Inline shape with custom dimensions:
builder.InsertImage(imageFile, ConvertUtil.PixelToPoint(250), ConvertUtil.PixelToPoint(144));

builder.InsertBreak(BreakType.PageBreak);

// 3 -  Floating shape with custom dimensions:
builder.InsertImage(imageFile, RelativeHorizontalPosition.Margin, 100, RelativeVerticalPosition.Margin,
100, 200, 100, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromImageObject.docx");

See Also


InsertImage(string)

Inserts an image from a file or URL into the document. The image is inserted inline and at 100% scale.

public Shape InsertImage(string fileName)
ParameterTypeDescription
fileNameStringThe file with the image. Can be any valid local or remote URI.

Return Value

The image node that was just inserted.

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.

Examples

Shows how to insert WebP image (only .NetStandard)

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.InsertImage(ImageDir + "WebP image.webp");

doc.Save(ArtifactsDir + "Image.InsertWebpImage.docx");

Shows how to insert gif image to the document.

DocumentBuilder builder = new 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.
Shape gifImage = builder.InsertImage(ImageDir + "Graphics Interchange Format.gif");

gifImage = builder.InsertImage(File.ReadAllBytes(ImageDir + "Graphics Interchange Format.gif"));

builder.Document.Save(ArtifactsDir + "InsertGif.docx");

Shows how to insert a shape with an image into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Below are two locations where the document builder's "InsertShape" 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.InsertImage(ImageDir + "Logo.jpg");
builder.Writeln();

// 2 -  Pass a URL which points to an image.
builder.Write("Image from a URL: ");
builder.InsertImage(ImageUrl);
builder.Writeln();

doc.Save(ArtifactsDir + "Image.FromUrl.docx");

Shows how to insert a floating image to the center of a page.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
Shape shape = builder.InsertImage(ImageDir + "Logo.jpg");
shape.WrapType = WrapType.None;
shape.BehindText = true;
shape.RelativeHorizontalPosition = RelativeHorizontalPosition.Page;
shape.RelativeVerticalPosition = RelativeVerticalPosition.Page;
shape.HorizontalAlignment = HorizontalAlignment.Center;
shape.VerticalAlignment = VerticalAlignment.Center;

doc.Save(ArtifactsDir + "Image.CreateFloatingPageCenter.docx");

Shows how to determine which image will be inserted.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.InsertImage(ImageDir + "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(ArtifactsDir + "DocumentBuilderImages.InsertSvgImage.SvgWithSvgBlip.docx");

// Aspose.Words insert SVG image to the document as PNG, just like Microsoft Word does for old format.
doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertSvgImage.Svg.doc");

doc.CompatibilityOptions.OptimizeFor(MsWordVersion.Word2003);

// Aspose.Words insert SVG image to the document as EMF metafile to keep the image in vector representation.
doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertSvgImage.Emf.docx");

Shows how to insert an image from the local file system into a document.

Document doc = new Document();
DocumentBuilder builder = new 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.InsertImage(ImageDir + "Logo.jpg");

builder.InsertBreak(BreakType.PageBreak);

// 2 -  Inline shape with custom dimensions:
builder.InsertImage(ImageDir + "Transparent background logo.png", ConvertUtil.PixelToPoint(250),
    ConvertUtil.PixelToPoint(144));

builder.InsertBreak(BreakType.PageBreak);

// 3 -  Floating shape with custom dimensions:
builder.InsertImage(ImageDir + "Windows MetaFile.wmf", RelativeHorizontalPosition.Margin, 100, 
    RelativeVerticalPosition.Margin, 100, 200, 100, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromFilename.docx");

See Also


InsertImage(Stream)

Inserts an image from a stream into the document. The image is inserted inline and at 100% scale.

public Shape InsertImage(Stream stream)
ParameterTypeDescription
streamStreamThe stream that contains the image.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert a shape with an image from a stream into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

using (Stream stream = File.OpenRead(ImageDir + "Logo.jpg"))
{
    builder.Write("Image from stream: ");
    builder.InsertImage(stream);
}

doc.Save(ArtifactsDir + "Image.FromStream.docx");

Shows how to insert an image from a stream into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

using (Stream stream = File.OpenRead(ImageDir + "Logo.jpg"))
{
    // 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.InsertImage(stream);

    builder.InsertBreak(BreakType.PageBreak);

    // 2 -  Inline shape with custom dimensions:
    builder.InsertImage(stream, ConvertUtil.PixelToPoint(250), ConvertUtil.PixelToPoint(144));

    builder.InsertBreak(BreakType.PageBreak);

    // 3 -  Floating shape with custom dimensions:
    builder.InsertImage(stream, RelativeHorizontalPosition.Margin, 100, RelativeVerticalPosition.Margin,
        100, 200, 100, WrapType.Square);
}

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromStream.docx");

See Also


InsertImage(byte[])

Inserts an image from a byte array into the document. The image is inserted inline and at 100% scale.

public Shape InsertImage(byte[] imageBytes)
ParameterTypeDescription
imageBytesByte[]The byte array that contains the image.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image from a byte array into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

byte[] imageByteArray = File.ReadAllBytes(ImageDir + "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.InsertImage(imageByteArray);

builder.InsertBreak(BreakType.PageBreak);

// 2 -  Inline shape with custom dimensions:
builder.InsertImage(imageByteArray, ConvertUtil.PixelToPoint(250), ConvertUtil.PixelToPoint(144));

builder.InsertBreak(BreakType.PageBreak);

// 3 -  Floating shape with custom dimensions:
builder.InsertImage(imageByteArray, RelativeHorizontalPosition.Margin, 100, RelativeVerticalPosition.Margin,
100, 200, 100, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromByteArray.docx");

See Also


InsertImage(Image, double, double)

Inserts an inline image from a .NET Image object into the document and scales it to the specified size.

public Shape InsertImage(Image image, double width, double height)
ParameterTypeDescription
imageImageThe image to insert into the document.
widthDoubleThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightDoubleThe height of the image in points. Can be a negative or zero value to request 100% scale.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image from an object into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

string imageFile = ImageDir + "Logo.jpg";

// Below are three ways of inserting an image from an Image object instance.
// 1 -  Inline shape with a default size based on the image's original dimensions:
builder.InsertImage(imageFile);

builder.InsertBreak(BreakType.PageBreak);

// 2 -  Inline shape with custom dimensions:
builder.InsertImage(imageFile, ConvertUtil.PixelToPoint(250), ConvertUtil.PixelToPoint(144));

builder.InsertBreak(BreakType.PageBreak);

// 3 -  Floating shape with custom dimensions:
builder.InsertImage(imageFile, RelativeHorizontalPosition.Margin, 100, RelativeVerticalPosition.Margin,
100, 200, 100, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromImageObject.docx");

See Also


InsertImage(string, double, double)

Inserts an inline image from a file or URL into the document and scales it to the specified size.

public Shape InsertImage(string fileName, double width, double height)
ParameterTypeDescription
fileNameStringThe file that contains the image.
widthDoubleThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightDoubleThe height of the image in points. Can be a negative or zero value to request 100% scale.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image from the local file system into a document.

Document doc = new Document();
DocumentBuilder builder = new 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.InsertImage(ImageDir + "Logo.jpg");

builder.InsertBreak(BreakType.PageBreak);

// 2 -  Inline shape with custom dimensions:
builder.InsertImage(ImageDir + "Transparent background logo.png", ConvertUtil.PixelToPoint(250),
    ConvertUtil.PixelToPoint(144));

builder.InsertBreak(BreakType.PageBreak);

// 3 -  Floating shape with custom dimensions:
builder.InsertImage(ImageDir + "Windows MetaFile.wmf", RelativeHorizontalPosition.Margin, 100, 
    RelativeVerticalPosition.Margin, 100, 200, 100, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromFilename.docx");

See Also


InsertImage(Stream, double, double)

Inserts an inline image from a stream into the document and scales it to the specified size.

public Shape InsertImage(Stream stream, double width, double height)
ParameterTypeDescription
streamStreamThe stream that contains the image.
widthDoubleThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightDoubleThe height of the image in points. Can be a negative or zero value to request 100% scale.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image from a stream into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

using (Stream stream = File.OpenRead(ImageDir + "Logo.jpg"))
{
    // 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.InsertImage(stream);

    builder.InsertBreak(BreakType.PageBreak);

    // 2 -  Inline shape with custom dimensions:
    builder.InsertImage(stream, ConvertUtil.PixelToPoint(250), ConvertUtil.PixelToPoint(144));

    builder.InsertBreak(BreakType.PageBreak);

    // 3 -  Floating shape with custom dimensions:
    builder.InsertImage(stream, RelativeHorizontalPosition.Margin, 100, RelativeVerticalPosition.Margin,
        100, 200, 100, WrapType.Square);
}

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromStream.docx");

See Also


InsertImage(byte[], double, double)

Inserts an inline image from a byte array into the document and scales it to the specified size.

public Shape InsertImage(byte[] imageBytes, double width, double height)
ParameterTypeDescription
imageBytesByte[]The byte array that contains the image.
widthDoubleThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightDoubleThe height of the image in points. Can be a negative or zero value to request 100% scale.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image from a byte array into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

byte[] imageByteArray = File.ReadAllBytes(ImageDir + "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.InsertImage(imageByteArray);

builder.InsertBreak(BreakType.PageBreak);

// 2 -  Inline shape with custom dimensions:
builder.InsertImage(imageByteArray, ConvertUtil.PixelToPoint(250), ConvertUtil.PixelToPoint(144));

builder.InsertBreak(BreakType.PageBreak);

// 3 -  Floating shape with custom dimensions:
builder.InsertImage(imageByteArray, RelativeHorizontalPosition.Margin, 100, RelativeVerticalPosition.Margin,
100, 200, 100, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromByteArray.docx");

See Also


InsertImage(Image, RelativeHorizontalPosition, double, RelativeVerticalPosition, double, double, double, WrapType)

Inserts an image from a .NET Image object at the specified position and size.

public Shape InsertImage(Image image, RelativeHorizontalPosition horzPos, double left, 
    RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
ParameterTypeDescription
imageImageThe image to insert into the document.
horzPosRelativeHorizontalPositionSpecifies where the distance to the image is measured from.
leftDoubleDistance in points from the origin to the left side of the image.
vertPosRelativeVerticalPositionSpecifies where the distance to the image measured from.
topDoubleDistance in points from the origin to the top side of the image.
widthDoubleThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightDoubleThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeWrapTypeSpecifies how to wrap text around the image.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image from an object into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

string imageFile = ImageDir + "Logo.jpg";

// Below are three ways of inserting an image from an Image object instance.
// 1 -  Inline shape with a default size based on the image's original dimensions:
builder.InsertImage(imageFile);

builder.InsertBreak(BreakType.PageBreak);

// 2 -  Inline shape with custom dimensions:
builder.InsertImage(imageFile, ConvertUtil.PixelToPoint(250), ConvertUtil.PixelToPoint(144));

builder.InsertBreak(BreakType.PageBreak);

// 3 -  Floating shape with custom dimensions:
builder.InsertImage(imageFile, RelativeHorizontalPosition.Margin, 100, RelativeVerticalPosition.Margin,
100, 200, 100, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromImageObject.docx");

See Also


InsertImage(string, RelativeHorizontalPosition, double, RelativeVerticalPosition, double, double, double, WrapType)

Inserts an image from a file or URL at the specified position and size.

public Shape InsertImage(string fileName, RelativeHorizontalPosition horzPos, double left, 
    RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
ParameterTypeDescription
fileNameStringThe file that contains the image.
horzPosRelativeHorizontalPositionSpecifies where the distance to the image is measured from.
leftDoubleDistance in points from the origin to the left side of the image.
vertPosRelativeVerticalPositionSpecifies where the distance to the image measured from.
topDoubleDistance in points from the origin to the top side of the image.
widthDoubleThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightDoubleThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeWrapTypeSpecifies how to wrap text around the image.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image.

Document doc = new Document();
DocumentBuilder builder = new 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.InsertImage(ImageDir + "Transparent background logo.png", RelativeHorizontalPosition.Margin, 100,
    RelativeVerticalPosition.Margin, 0, 200, 200, WrapType.Square);

// 2 -  From a URL:
builder.InsertImage(ImageUrl, RelativeHorizontalPosition.Margin, 100,
    RelativeVerticalPosition.Margin, 250, 200, 200, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilder.InsertFloatingImage.docx");

Shows how to insert an image from the local file system into a document while preserving its dimensions.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// The InsertImage 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.
Shape imageShape = builder.InsertImage(ImageDir + "Logo.jpg", RelativeHorizontalPosition.Margin, 0,
    RelativeVerticalPosition.Margin, 0, -1, -1, WrapType.Square);

// Passing negative values as the intended dimensions will automatically define
// the shape's dimensions based on the dimensions of its image.
Assert.AreEqual(300.0d, imageShape.Width);
Assert.AreEqual(300.0d, imageShape.Height);

doc.Save(ArtifactsDir + "DocumentBuilder.InsertImageOriginalSize.docx");

Shows how to insert an image from the local file system into a document.

Document doc = new Document();
DocumentBuilder builder = new 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.InsertImage(ImageDir + "Logo.jpg");

builder.InsertBreak(BreakType.PageBreak);

// 2 -  Inline shape with custom dimensions:
builder.InsertImage(ImageDir + "Transparent background logo.png", ConvertUtil.PixelToPoint(250),
    ConvertUtil.PixelToPoint(144));

builder.InsertBreak(BreakType.PageBreak);

// 3 -  Floating shape with custom dimensions:
builder.InsertImage(ImageDir + "Windows MetaFile.wmf", RelativeHorizontalPosition.Margin, 100, 
    RelativeVerticalPosition.Margin, 100, 200, 100, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromFilename.docx");

See Also


InsertImage(Stream, RelativeHorizontalPosition, double, RelativeVerticalPosition, double, double, double, WrapType)

Inserts an image from a stream at the specified position and size.

public Shape InsertImage(Stream stream, RelativeHorizontalPosition horzPos, double left, 
    RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
ParameterTypeDescription
streamStreamThe stream that contains the image.
horzPosRelativeHorizontalPositionSpecifies where the distance to the image is measured from.
leftDoubleDistance in points from the origin to the left side of the image.
vertPosRelativeVerticalPositionSpecifies where the distance to the image measured from.
topDoubleDistance in points from the origin to the top side of the image.
widthDoubleThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightDoubleThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeWrapTypeSpecifies how to wrap text around the image.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image from a stream into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

using (Stream stream = File.OpenRead(ImageDir + "Logo.jpg"))
{
    // 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.InsertImage(stream);

    builder.InsertBreak(BreakType.PageBreak);

    // 2 -  Inline shape with custom dimensions:
    builder.InsertImage(stream, ConvertUtil.PixelToPoint(250), ConvertUtil.PixelToPoint(144));

    builder.InsertBreak(BreakType.PageBreak);

    // 3 -  Floating shape with custom dimensions:
    builder.InsertImage(stream, RelativeHorizontalPosition.Margin, 100, RelativeVerticalPosition.Margin,
        100, 200, 100, WrapType.Square);
}

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromStream.docx");

See Also


InsertImage(byte[], RelativeHorizontalPosition, double, RelativeVerticalPosition, double, double, double, WrapType)

Inserts an image from a byte array at the specified position and size.

public Shape InsertImage(byte[] imageBytes, RelativeHorizontalPosition horzPos, double left, 
    RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
ParameterTypeDescription
imageBytesByte[]The byte array that contains the image.
horzPosRelativeHorizontalPositionSpecifies where the distance to the image is measured from.
leftDoubleDistance in points from the origin to the left side of the image.
vertPosRelativeVerticalPositionSpecifies where the distance to the image measured from.
topDoubleDistance in points from the origin to the top side of the image.
widthDoubleThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightDoubleThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeWrapTypeSpecifies how to wrap text around the image.

Return Value

The image node that was just inserted.

Remarks

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Examples

Shows how to insert an image from a byte array into a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

byte[] imageByteArray = File.ReadAllBytes(ImageDir + "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.InsertImage(imageByteArray);

builder.InsertBreak(BreakType.PageBreak);

// 2 -  Inline shape with custom dimensions:
builder.InsertImage(imageByteArray, ConvertUtil.PixelToPoint(250), ConvertUtil.PixelToPoint(144));

builder.InsertBreak(BreakType.PageBreak);

// 3 -  Floating shape with custom dimensions:
builder.InsertImage(imageByteArray, RelativeHorizontalPosition.Margin, 100, RelativeVerticalPosition.Margin,
100, 200, 100, WrapType.Square);

doc.Save(ArtifactsDir + "DocumentBuilderImages.InsertImageFromByteArray.docx");

See Also