Aspose::Words::Drawing::ImageData Class Reference

Defines an image for a shape.

Use the ImageData property to access and modify the image inside a shape. You do not create instances of the ImageData class directly.

An image can be stored inside a shape, linked to external file or both (linked and stored in the document).

Regardless of whether the image is stored inside the shape or linked, you can always access the actual image using the ToByteArray, ToStream, ToImage or Save() methods. If the image is stored inside the shape, you can also directly access it using the ImageBytes property.

To store an image inside a shape use the SetImage() method. To link an image to a shape, set the SourceFullName property.

Examples

Shows how to extract images from a document, and save them to the local file system as individual files.

auto doc = MakeObject<Document>(MyDir + u"Images.docx");
 
// Get the collection of shapes from the document,
// and save the image data of every shape with an image as a file to the local file system.
SharedPtr<NodeCollection> shapes = doc->GetChildNodes(NodeType::Shape, true);
 
ASSERT_EQ(9, shapes->LINQ_Count([](SharedPtr<Node> s) { return (System::DynamicCast<Shape>(s))->get_HasImage(); }));
 
int imageIndex = 0;
for (const auto& shape : System::IterateOver(shapes->LINQ_OfType<SharedPtr<Shape>>()))
{
    if (shape->get_HasImage())
    {
        // The image data of shapes may contain images of many possible image formats.
        // We can determine a file extension for each image automatically, based on its format.
        String imageFileName =
            String::Format(u"File.ExtractImages.{0}{1}", imageIndex, FileFormatUtil::ImageTypeToExtension(shape->get_ImageData()->get_ImageType()));
        shape->get_ImageData()->Save(ArtifactsDir + imageFileName);
        imageIndex++;
    }
}

Shows how to insert a linked image into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
String imageFileName = ImageDir + u"Windows MetaFile.wmf";
 
// Below are two ways of applying an image to a shape so that it can display it.
// 1 -  Set the shape to contain the image.
auto shape = MakeObject<Shape>(builder->get_Document(), ShapeType::Image);
shape->set_WrapType(WrapType::Inline);
shape->get_ImageData()->SetImage(imageFileName);
 
builder->InsertNode(shape);
 
doc->Save(ArtifactsDir + u"Image.CreateLinkedImage.Embedded.docx");
 
// Every image that we store in shape will increase the size of our document.
ASSERT_TRUE(70000 < MakeObject<System::IO::FileInfo>(ArtifactsDir + u"Image.CreateLinkedImage.Embedded.docx")->get_Length());
 
doc->get_FirstSection()->get_Body()->get_FirstParagraph()->RemoveAllChildren();
 
// 2 -  Set the shape to link to an image file in the local file system.
shape = MakeObject<Shape>(builder->get_Document(), ShapeType::Image);
shape->set_WrapType(WrapType::Inline);
shape->get_ImageData()->set_SourceFullName(imageFileName);
 
builder->InsertNode(shape);
doc->Save(ArtifactsDir + u"Image.CreateLinkedImage.Linked.docx");
 
// Linking to images will save space and result in a smaller document.
// However, the document can only display the image correctly while
// the image file is present at the location that the shape's "SourceFullName" property points to.
ASSERT_TRUE(10000 > MakeObject<System::IO::FileInfo>(ArtifactsDir + u"Image.CreateLinkedImage.Linked.docx")->get_Length());

#include <Aspose.Words.Cpp/Drawing/ImageData.h>

Inheritance diagram for Aspose::Words::Drawing::ImageData:

Public Member Functions
bool	get_BiLevel ()
	Determines whether an image will be displayed in black and white. More...
SharedPtr< BorderCollection >	get_Borders ()
	Gets the collection of borders of the image. Borders only have effect for inline images. More...
double	get_Brightness ()
	Gets or sets the brightness of the picture. The value for this property must be a number from 0.0 (dimmest) to 1.0 (brightest). More...
Color	get_ChromaKey ()
	Defines the color value of the image that will be treated as transparent. More...
double	get_Contrast ()
	Gets or sets the contrast for the specified picture. The value for this property must be a number from 0.0 (the least contrast) to 1.0 (the greatest contrast). More...
double	get_CropBottom ()
	Defines the fraction of picture removal from the bottom side. More...
double	get_CropLeft ()
	Defines the fraction of picture removal from the left side. More...
double	get_CropRight ()
	Defines the fraction of picture removal from the right side. More...
double	get_CropTop ()
	Defines the fraction of picture removal from the top side. More...
bool	get_GrayScale ()
	Determines whether a picture will display in grayscale mode. More...
bool	get_HasImage ()
	Returns true if the shape has image bytes or links an image. More...
ArrayPtr< uint8_t >	get_ImageBytes ()
	Gets or sets the raw bytes of the image stored in the shape. More...
SharedPtr< ImageSize >	get_ImageSize ()
	Gets the information about image size and resolution. More...
ImageType	get_ImageType ()
	Gets the type of the image. More...
bool	get_IsLink ()
	Returns true if the image is linked to the shape (when SourceFullName is specified). More...
bool	get_IsLinkOnly ()
	Returns true if the image is linked and not stored in the document. More...
String	get_SourceFullName ()
	Gets or sets the path and name of the source file for the linked image. More...
String	get_Title ()
	Defines the title of an image. More...
virtual const TypeInfo &	GetType () const override
virtual bool	Is (const TypeInfo &target) const override
void	Save (SharedPtr< Stream > stream)
	Saves the image into the specified stream. More...
void	Save (String fileName)
	Saves the image into a file. More...
void	set_BiLevel (bool value)
	Setter for get_BiLevel. More...
void	set_Brightness (double value)
	Setter for get_Brightness. More...
void	set_ChromaKey (Color value)
	Setter for get_ChromaKey. More...
void	set_Contrast (double value)
	Setter for get_Contrast. More...
void	set_CropBottom (double value)
	Setter for get_CropBottom. More...
void	set_CropLeft (double value)
	Setter for get_CropLeft. More...
void	set_CropRight (double value)
	Setter for get_CropRight. More...
void	set_CropTop (double value)
	Setter for get_CropTop. More...
void	set_GrayScale (bool value)
	Setter for get_GrayScale. More...
void	set_ImageBytes (ArrayPtr< uint8_t > value)
	Setter for get_ImageBytes. More...
void	set_SourceFullName (String value)
	Setter for get_SourceFullName. More...
void	set_Title (String value)
	Setter for get_Title. More...
void	SetImage (SharedPtr< Image > image)
	Sets the image that the shape displays. More...
void	SetImage (SharedPtr< Stream > stream)
	Sets the image that the shape displays. More...
void	SetImage (String fileName)
	Sets the image that the shape displays. More...
ArrayPtr< uint8_t >	ToByteArray ()
	Returns image bytes for any image regardless whether the image is stored or linked. More...
SharedPtr< Image >	ToImage ()
	Gets the image stored in the shape as a Image object. More...
SharedPtr< Stream >	ToStream ()
	Creates and returns a stream that contains the image bytes. More...

Static Public Member Functions
static const TypeInfo &	Type ()

Member Function Documentation

get_BiLevel()

bool Aspose::Words::Drawing::ImageData::get_BiLevel

(

)

Determines whether an image will be displayed in black and white.

The default value is false.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_Borders()

System::SharedPtr<Aspose::Words::BorderCollection> Aspose::Words::Drawing::ImageData::get_Borders

(

)

Gets the collection of borders of the image. Borders only have effect for inline images.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_Brightness()

double Aspose::Words::Drawing::ImageData::get_Brightness

(

)

Gets or sets the brightness of the picture. The value for this property must be a number from 0.0 (dimmest) to 1.0 (brightest).

The default value is 0.5.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_ChromaKey()

System::Drawing::Color Aspose::Words::Drawing::ImageData::get_ChromaKey

(

)

Defines the color value of the image that will be treated as transparent.

The default value is 0.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_Contrast()

double Aspose::Words::Drawing::ImageData::get_Contrast

(

)

Gets or sets the contrast for the specified picture. The value for this property must be a number from 0.0 (the least contrast) to 1.0 (the greatest contrast).

The default value is 0.5.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_CropBottom()

double Aspose::Words::Drawing::ImageData::get_CropBottom

(

)

Defines the fraction of picture removal from the bottom side.

The amount of cropping can range from -1.0 to 1.0. The default value is 0. Note that a value of 1 will display no picture at all. Negative values will result in the picture being squeezed inward from the edge being cropped (the empty space between the picture and the cropped edge will be filled by the fill color of the shape). Positive values less than 1 will result in the remaining picture being stretched to fit the shape.

The default value is 0.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_CropLeft()

double Aspose::Words::Drawing::ImageData::get_CropLeft

(

)

Defines the fraction of picture removal from the left side.

The amount of cropping can range from -1.0 to 1.0. The default value is 0. Note that a value of 1 will display no picture at all. Negative values will result in the picture being squeezed inward from the edge being cropped (the empty space between the picture and the cropped edge will be filled by the fill color of the shape). Positive values less than 1 will result in the remaining picture being stretched to fit the shape.

The default value is 0.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_CropRight()

double Aspose::Words::Drawing::ImageData::get_CropRight

(

)

Defines the fraction of picture removal from the right side.

The amount of cropping can range from -1.0 to 1.0. The default value is 0. Note that a value of 1 will display no picture at all. Negative values will result in the picture being squeezed inward from the edge being cropped (the empty space between the picture and the cropped edge will be filled by the fill color of the shape). Positive values less than 1 will result in the remaining picture being stretched to fit the shape.

The default value is 0.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_CropTop()

double Aspose::Words::Drawing::ImageData::get_CropTop

(

)

Defines the fraction of picture removal from the top side.

The amount of cropping can range from -1.0 to 1.0. The default value is 0. Note that a value of 1 will display no picture at all. Negative values will result in the picture being squeezed inward from the edge being cropped (the empty space between the picture and the cropped edge will be filled by the fill color of the shape). Positive values less than 1 will result in the remaining picture being stretched to fit the shape.

The default value is 0.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_GrayScale()

bool Aspose::Words::Drawing::ImageData::get_GrayScale

(

)

Determines whether a picture will display in grayscale mode.

The default value is false.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_HasImage()

bool Aspose::Words::Drawing::ImageData::get_HasImage

(

)

Returns true if the shape has image bytes or links an image.

Examples

Shows how to save all images from a document to the file system.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
 
// Shapes with the "HasImage" flag set store and display all the document's images.
auto shapesWithImages =
    imgSourceDoc->GetChildNodes(NodeType::Shape, true)->LINQ_Cast<SharedPtr<Shape>>()->LINQ_Where([](SharedPtr<Shape> s) { return s->get_HasImage(); });
 
// Go through each shape and save its image.
auto formatConverter = MakeObject<System::Drawing::ImageFormatConverter>();
 
{
    SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<Shape>>> enumerator = shapesWithImages->GetEnumerator();
    int shapeIndex = 0;
 
    while (enumerator->MoveNext())
    {
        SharedPtr<ImageData> imageData = enumerator->get_Current()->get_ImageData();
        SharedPtr<System::Drawing::Imaging::ImageFormat> format = imageData->ToImage()->get_RawFormat();
        String fileExtension = formatConverter->ConvertToString(format);
 
        {
            SharedPtr<System::IO::FileStream> fileStream =
                System::IO::File::Create(ArtifactsDir + String::Format(u"Drawing.SaveAllImages.{0}.{1}", ++shapeIndex, fileExtension));
            imageData->Save(fileStream);
        }
    }
}

get_ImageBytes()

System::ArrayPtr<uint8_t> Aspose::Words::Drawing::ImageData::get_ImageBytes

(

)

Gets or sets the raw bytes of the image stored in the shape.

Setting the value to null or an empty array will remove the image from the shape.

Returns null if the image is not stored in the document (e.g the image is probably linked in this case).

See also

Aspose::Words::Drawing::ImageData::SetImage(System::String)

Aspose::Words::Drawing::ImageData::ToByteArray

Aspose::Words::Drawing::ImageData::ToImage

Aspose::Words::Drawing::ImageData::ToStream

Aspose::Words::Drawing::ImageData::Save(System::String)

Examples

Shows how to create an image file from a shape's raw image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
 
auto imgShape = System::DynamicCast<Shape>(imgSourceDoc->GetChild(NodeType::Shape, 0, true));
 
ASSERT_TRUE(imgShape->get_HasImage());
 
// ToByteArray() returns the array stored in the ImageBytes property.
ASPOSE_ASSERT_EQ(imgShape->get_ImageData()->get_ImageBytes(), imgShape->get_ImageData()->ToByteArray());
 
// Save the shape's image data to an image file in the local file system.
{
    SharedPtr<System::IO::Stream> imgStream = imgShape->get_ImageData()->ToStream();
    {
        auto outStream = MakeObject<System::IO::FileStream>(ArtifactsDir + u"Drawing.GetDataFromImage.png", System::IO::FileMode::Create,
                                                            System::IO::FileAccess::ReadWrite);
        imgStream->CopyTo(outStream);
    }
}

get_ImageSize()

System::SharedPtr<Aspose::Words::Drawing::ImageSize> Aspose::Words::Drawing::ImageData::get_ImageSize

(

)

Gets the information about image size and resolution.

If the image is linked only and not stored in the document, returns zero size.

Examples

Shows how to resize a shape with an image.

// When we insert an image using the "InsertImage" method, the builder scales the shape that displays the image so that,
// when we view the document using 100% zoom in Microsoft Word, the shape displays the image in its actual size.
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertImage(ImageDir + u"Logo.jpg");
 
// A 400x400 image will create an ImageData object with an image size of 300x300pt.
SharedPtr<ImageSize> imageSize = shape->get_ImageData()->get_ImageSize();
 
ASPOSE_ASSERT_EQ(300.0, imageSize->get_WidthPoints());
ASPOSE_ASSERT_EQ(300.0, imageSize->get_HeightPoints());
 
// If a shape's dimensions match the image data's dimensions,
// then the shape is displaying the image in its original size.
ASPOSE_ASSERT_EQ(300.0, shape->get_Width());
ASPOSE_ASSERT_EQ(300.0, shape->get_Height());
 
// Reduce the overall size of the shape by 50%.
System::setter_mul_wrap(shape.GetPointer(), &ShapeBase::get_Width, &ShapeBase::set_Width, 0.5);
 
// Scaling factors apply to both the width and the height at the same time to preserve the shape's proportions.
ASPOSE_ASSERT_EQ(150.0, shape->get_Width());
ASPOSE_ASSERT_EQ(150.0, shape->get_Height());
 
// When we resize the shape, the size of the image data remains the same.
ASPOSE_ASSERT_EQ(300.0, imageSize->get_WidthPoints());
ASPOSE_ASSERT_EQ(300.0, imageSize->get_HeightPoints());
 
// We can reference the image data dimensions to apply a scaling based on the size of the image.
shape->set_Width(imageSize->get_WidthPoints() * 1.1);
 
ASPOSE_ASSERT_EQ(330.0, shape->get_Width());
ASPOSE_ASSERT_EQ(330.0, shape->get_Height());
 
doc->Save(ArtifactsDir + u"Image.ScaleImage.docx");

get_ImageType()

Aspose::Words::Drawing::ImageType Aspose::Words::Drawing::ImageData::get_ImageType

(

)

Gets the type of the image.

Examples

Shows how to extract images from a document, and save them to the local file system as individual files.

auto doc = MakeObject<Document>(MyDir + u"Images.docx");
 
// Get the collection of shapes from the document,
// and save the image data of every shape with an image as a file to the local file system.
SharedPtr<NodeCollection> shapes = doc->GetChildNodes(NodeType::Shape, true);
 
ASSERT_EQ(9, shapes->LINQ_Count([](SharedPtr<Node> s) { return (System::DynamicCast<Shape>(s))->get_HasImage(); }));
 
int imageIndex = 0;
for (const auto& shape : System::IterateOver(shapes->LINQ_OfType<SharedPtr<Shape>>()))
{
    if (shape->get_HasImage())
    {
        // The image data of shapes may contain images of many possible image formats.
        // We can determine a file extension for each image automatically, based on its format.
        String imageFileName =
            String::Format(u"File.ExtractImages.{0}{1}", imageIndex, FileFormatUtil::ImageTypeToExtension(shape->get_ImageData()->get_ImageType()));
        shape->get_ImageData()->Save(ArtifactsDir + imageFileName);
        imageIndex++;
    }
}

get_IsLink()

bool Aspose::Words::Drawing::ImageData::get_IsLink

(

)

Returns true if the image is linked to the shape (when SourceFullName is specified).

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_IsLinkOnly()

bool Aspose::Words::Drawing::ImageData::get_IsLinkOnly

(

)

Returns true if the image is linked and not stored in the document.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

get_SourceFullName()

System::String Aspose::Words::Drawing::ImageData::get_SourceFullName

(

)

Gets or sets the path and name of the source file for the linked image.

The default value is an empty string.

If SourceFullName is not an empty string, the image is linked.

Examples

Shows how to insert a linked image into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
String imageFileName = ImageDir + u"Windows MetaFile.wmf";
 
// Below are two ways of applying an image to a shape so that it can display it.
// 1 -  Set the shape to contain the image.
auto shape = MakeObject<Shape>(builder->get_Document(), ShapeType::Image);
shape->set_WrapType(WrapType::Inline);
shape->get_ImageData()->SetImage(imageFileName);
 
builder->InsertNode(shape);
 
doc->Save(ArtifactsDir + u"Image.CreateLinkedImage.Embedded.docx");
 
// Every image that we store in shape will increase the size of our document.
ASSERT_TRUE(70000 < MakeObject<System::IO::FileInfo>(ArtifactsDir + u"Image.CreateLinkedImage.Embedded.docx")->get_Length());
 
doc->get_FirstSection()->get_Body()->get_FirstParagraph()->RemoveAllChildren();
 
// 2 -  Set the shape to link to an image file in the local file system.
shape = MakeObject<Shape>(builder->get_Document(), ShapeType::Image);
shape->set_WrapType(WrapType::Inline);
shape->get_ImageData()->set_SourceFullName(imageFileName);
 
builder->InsertNode(shape);
doc->Save(ArtifactsDir + u"Image.CreateLinkedImage.Linked.docx");
 
// Linking to images will save space and result in a smaller document.
// However, the document can only display the image correctly while
// the image file is present at the location that the shape's "SourceFullName" property points to.
ASSERT_TRUE(10000 > MakeObject<System::IO::FileInfo>(ArtifactsDir + u"Image.CreateLinkedImage.Linked.docx")->get_Length());

get_Title()

System::String Aspose::Words::Drawing::ImageData::get_Title

(

)

Defines the title of an image.

The default value is an empty string.

Examples

Shows how to edit a shape's image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
auto sourceShape = System::DynamicCast<Shape>(imgSourceDoc->GetChildNodes(NodeType::Shape, true)->idx_get(0));
 
auto dstDoc = MakeObject<Document>();
 
// Import a shape from the source document and append it to the first paragraph.
auto importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
// The imported shape contains an image. We can access the image's properties and raw data via the ImageData object.
SharedPtr<ImageData> imageData = importedShape->get_ImageData();
imageData->set_Title(u"Imported Image");
 
ASSERT_TRUE(imageData->get_HasImage());
 
// If an image has no borders, its ImageData object will define the border color as empty.
ASSERT_EQ(4, imageData->get_Borders()->get_Count());
ASPOSE_ASSERT_EQ(System::Drawing::Color::Empty, imageData->get_Borders()->idx_get(0)->get_Color());
 
// This image does not link to another shape or image file in the local file system.
ASSERT_FALSE(imageData->get_IsLink());
ASSERT_FALSE(imageData->get_IsLinkOnly());
 
// The "Brightness" and "Contrast" properties define image brightness and contrast
// on a 0-1 scale, with the default value at 0.5.
imageData->set_Brightness(0.8);
imageData->set_Contrast(1.0);
 
// The above brightness and contrast values have created an image with a lot of white.
// We can select a color with the ChromaKey property to replace with transparency, such as white.
imageData->set_ChromaKey(System::Drawing::Color::get_White());
 
// Import the source shape again and set the image to monochrome.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_GrayScale(true);
 
// Import the source shape again to create a third image and set it to BiLevel.
// BiLevel sets every pixel to either black or white, whichever is closer to the original color.
importedShape = System::DynamicCast<Shape>(dstDoc->ImportNode(sourceShape, true));
dstDoc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(importedShape);
 
importedShape->get_ImageData()->set_BiLevel(true);
 
// Cropping is determined on a 0-1 scale. Cropping a side by 0.3
// will crop 30% of the image out at the cropped side.
importedShape->get_ImageData()->set_CropBottom(0.3);
importedShape->get_ImageData()->set_CropLeft(0.3);
importedShape->get_ImageData()->set_CropTop(0.3);
importedShape->get_ImageData()->set_CropRight(0.3);
 
dstDoc->Save(ArtifactsDir + u"Drawing.ImageData.docx");

GetType()

virtual const System::TypeInfo& Aspose::Words::Drawing::ImageData::GetType ( ) const

overridevirtual

Is()

virtual bool Aspose::Words::Drawing::ImageData::Is ( const System::TypeInfo &  target ) const

overridevirtual

Save() [1/2]

void Aspose::Words::Drawing::ImageData::Save

(

System::SharedPtr< System::IO::Stream >

stream

)

Saves the image into the specified stream.

Is it the responsibility of the caller to dispose the stream object.

Parameters

stream

The stream where to save the image to.

Examples

Shows how to save all images from a document to the file system.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
 
// Shapes with the "HasImage" flag set store and display all the document's images.
auto shapesWithImages =
    imgSourceDoc->GetChildNodes(NodeType::Shape, true)->LINQ_Cast<SharedPtr<Shape>>()->LINQ_Where([](SharedPtr<Shape> s) { return s->get_HasImage(); });
 
// Go through each shape and save its image.
auto formatConverter = MakeObject<System::Drawing::ImageFormatConverter>();
 
{
    SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<Shape>>> enumerator = shapesWithImages->GetEnumerator();
    int shapeIndex = 0;
 
    while (enumerator->MoveNext())
    {
        SharedPtr<ImageData> imageData = enumerator->get_Current()->get_ImageData();
        SharedPtr<System::Drawing::Imaging::ImageFormat> format = imageData->ToImage()->get_RawFormat();
        String fileExtension = formatConverter->ConvertToString(format);
 
        {
            SharedPtr<System::IO::FileStream> fileStream =
                System::IO::File::Create(ArtifactsDir + String::Format(u"Drawing.SaveAllImages.{0}.{1}", ++shapeIndex, fileExtension));
            imageData->Save(fileStream);
        }
    }
}

Save() [2/2]

void Aspose::Words::Drawing::ImageData::Save

(

System::String

fileName

)

Saves the image into a file.

Parameters

fileName

The file name where to save the image.

Examples

Shows how to extract images from a document, and save them to the local file system as individual files.

auto doc = MakeObject<Document>(MyDir + u"Images.docx");
 
// Get the collection of shapes from the document,
// and save the image data of every shape with an image as a file to the local file system.
SharedPtr<NodeCollection> shapes = doc->GetChildNodes(NodeType::Shape, true);
 
ASSERT_EQ(9, shapes->LINQ_Count([](SharedPtr<Node> s) { return (System::DynamicCast<Shape>(s))->get_HasImage(); }));
 
int imageIndex = 0;
for (const auto& shape : System::IterateOver(shapes->LINQ_OfType<SharedPtr<Shape>>()))
{
    if (shape->get_HasImage())
    {
        // The image data of shapes may contain images of many possible image formats.
        // We can determine a file extension for each image automatically, based on its format.
        String imageFileName =
            String::Format(u"File.ExtractImages.{0}{1}", imageIndex, FileFormatUtil::ImageTypeToExtension(shape->get_ImageData()->get_ImageType()));
        shape->get_ImageData()->Save(ArtifactsDir + imageFileName);
        imageIndex++;
    }
}

set_BiLevel()

void Aspose::Words::Drawing::ImageData::set_BiLevel

(

bool

value

)

Setter for Aspose::Words::Drawing::ImageData::get_BiLevel.

set_Brightness()

void Aspose::Words::Drawing::ImageData::set_Brightness

(

double

value

)

Setter for Aspose::Words::Drawing::ImageData::get_Brightness.

set_ChromaKey()

void Aspose::Words::Drawing::ImageData::set_ChromaKey

(

System::Drawing::Color

value

)

Setter for Aspose::Words::Drawing::ImageData::get_ChromaKey.

set_Contrast()

void Aspose::Words::Drawing::ImageData::set_Contrast

(

double

value

)

Setter for Aspose::Words::Drawing::ImageData::get_Contrast.

set_CropBottom()

void Aspose::Words::Drawing::ImageData::set_CropBottom

(

double

value

)

Setter for Aspose::Words::Drawing::ImageData::get_CropBottom.

set_CropLeft()

void Aspose::Words::Drawing::ImageData::set_CropLeft

(

double

value

)

Setter for Aspose::Words::Drawing::ImageData::get_CropLeft.

set_CropRight()

void Aspose::Words::Drawing::ImageData::set_CropRight

(

double

value

)

Setter for Aspose::Words::Drawing::ImageData::get_CropRight.

set_CropTop()

void Aspose::Words::Drawing::ImageData::set_CropTop

(

double

value

)

Setter for Aspose::Words::Drawing::ImageData::get_CropTop.

set_GrayScale()

void Aspose::Words::Drawing::ImageData::set_GrayScale

(

bool

value

)

Setter for Aspose::Words::Drawing::ImageData::get_GrayScale.

set_ImageBytes()

void Aspose::Words::Drawing::ImageData::set_ImageBytes

(

System::ArrayPtr< uint8_t >

value

)

Setter for Aspose::Words::Drawing::ImageData::get_ImageBytes.

set_SourceFullName()

void Aspose::Words::Drawing::ImageData::set_SourceFullName

(

System::String

value

)

Setter for Aspose::Words::Drawing::ImageData::get_SourceFullName.

set_Title()

void Aspose::Words::Drawing::ImageData::set_Title

(

System::String

value

)

Setter for Aspose::Words::Drawing::ImageData::get_Title.

SetImage() [1/3]

void Aspose::Words::Drawing::ImageData::SetImage

(

System::SharedPtr< System::Drawing::Image >

image

)

Sets the image that the shape displays.

Parameters

image

The image object.

Examples

Shows how to display images from the local file system in a document.

auto doc = MakeObject<Document>();
 
// To display an image in a document, we will need to create a shape
// which will contain an image, and then append it to the document's body.
SharedPtr<Shape> imgShape;
 
// Below are two ways of getting an image from a file in the local file system.
// 1 -  Create an image object from an image file:
{
    SharedPtr<System::Drawing::Image> srcImage = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
    imgShape = MakeObject<Shape>(doc, ShapeType::Image);
    doc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(imgShape);
    imgShape->get_ImageData()->SetImage(srcImage);
}
 
// 2 -  Open an image file from the local file system using a stream:
{
    SharedPtr<System::IO::Stream> stream =
        MakeObject<System::IO::FileStream>(ImageDir + u"Logo.jpg", System::IO::FileMode::Open, System::IO::FileAccess::Read);
    imgShape = MakeObject<Shape>(doc, ShapeType::Image);
    doc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(imgShape);
    imgShape->get_ImageData()->SetImage(stream);
    imgShape->set_Left(150.0f);
}
 
doc->Save(ArtifactsDir + u"Drawing.ImportImage.docx");

SetImage() [2/3]

void Aspose::Words::Drawing::ImageData::SetImage

(

System::SharedPtr< System::IO::Stream >

stream

)

Sets the image that the shape displays.

Parameters

stream

The stream that contains the image.

Examples

Shows how to display images from the local file system in a document.

auto doc = MakeObject<Document>();
 
// To display an image in a document, we will need to create a shape
// which will contain an image, and then append it to the document's body.
SharedPtr<Shape> imgShape;
 
// Below are two ways of getting an image from a file in the local file system.
// 1 -  Create an image object from an image file:
{
    SharedPtr<System::Drawing::Image> srcImage = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
    imgShape = MakeObject<Shape>(doc, ShapeType::Image);
    doc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(imgShape);
    imgShape->get_ImageData()->SetImage(srcImage);
}
 
// 2 -  Open an image file from the local file system using a stream:
{
    SharedPtr<System::IO::Stream> stream =
        MakeObject<System::IO::FileStream>(ImageDir + u"Logo.jpg", System::IO::FileMode::Open, System::IO::FileAccess::Read);
    imgShape = MakeObject<Shape>(doc, ShapeType::Image);
    doc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(imgShape);
    imgShape->get_ImageData()->SetImage(stream);
    imgShape->set_Left(150.0f);
}
 
doc->Save(ArtifactsDir + u"Drawing.ImportImage.docx");

SetImage() [3/3]

void Aspose::Words::Drawing::ImageData::SetImage

(

System::String

fileName

)

Sets the image that the shape displays.

Parameters

fileName

The image file. Can be a file name or a URL.

Examples

Shows how to insert a linked image into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
String imageFileName = ImageDir + u"Windows MetaFile.wmf";
 
// Below are two ways of applying an image to a shape so that it can display it.
// 1 -  Set the shape to contain the image.
auto shape = MakeObject<Shape>(builder->get_Document(), ShapeType::Image);
shape->set_WrapType(WrapType::Inline);
shape->get_ImageData()->SetImage(imageFileName);
 
builder->InsertNode(shape);
 
doc->Save(ArtifactsDir + u"Image.CreateLinkedImage.Embedded.docx");
 
// Every image that we store in shape will increase the size of our document.
ASSERT_TRUE(70000 < MakeObject<System::IO::FileInfo>(ArtifactsDir + u"Image.CreateLinkedImage.Embedded.docx")->get_Length());
 
doc->get_FirstSection()->get_Body()->get_FirstParagraph()->RemoveAllChildren();
 
// 2 -  Set the shape to link to an image file in the local file system.
shape = MakeObject<Shape>(builder->get_Document(), ShapeType::Image);
shape->set_WrapType(WrapType::Inline);
shape->get_ImageData()->set_SourceFullName(imageFileName);
 
builder->InsertNode(shape);
doc->Save(ArtifactsDir + u"Image.CreateLinkedImage.Linked.docx");
 
// Linking to images will save space and result in a smaller document.
// However, the document can only display the image correctly while
// the image file is present at the location that the shape's "SourceFullName" property points to.
ASSERT_TRUE(10000 > MakeObject<System::IO::FileInfo>(ArtifactsDir + u"Image.CreateLinkedImage.Linked.docx")->get_Length());

ToByteArray()

System::ArrayPtr<uint8_t> Aspose::Words::Drawing::ImageData::ToByteArray

(

)

Returns image bytes for any image regardless whether the image is stored or linked.

If the image is linked, downloads the image every time it is called.

See also

Aspose::Words::Drawing::ImageData::get_ImageBytes

Examples

Shows how to create an image file from a shape's raw image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
 
auto imgShape = System::DynamicCast<Shape>(imgSourceDoc->GetChild(NodeType::Shape, 0, true));
 
ASSERT_TRUE(imgShape->get_HasImage());
 
// ToByteArray() returns the array stored in the ImageBytes property.
ASPOSE_ASSERT_EQ(imgShape->get_ImageData()->get_ImageBytes(), imgShape->get_ImageData()->ToByteArray());
 
// Save the shape's image data to an image file in the local file system.
{
    SharedPtr<System::IO::Stream> imgStream = imgShape->get_ImageData()->ToStream();
    {
        auto outStream = MakeObject<System::IO::FileStream>(ArtifactsDir + u"Drawing.GetDataFromImage.png", System::IO::FileMode::Create,
                                                            System::IO::FileAccess::ReadWrite);
        imgStream->CopyTo(outStream);
    }
}

ToImage()

System::SharedPtr<System::Drawing::Image> Aspose::Words::Drawing::ImageData::ToImage

(

)

Gets the image stored in the shape as a Image object.

A new Image object is created every time this method is called.

It is the responsibility of the caller to dispose the image object.

Examples

Shows how to save all images from a document to the file system.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
 
// Shapes with the "HasImage" flag set store and display all the document's images.
auto shapesWithImages =
    imgSourceDoc->GetChildNodes(NodeType::Shape, true)->LINQ_Cast<SharedPtr<Shape>>()->LINQ_Where([](SharedPtr<Shape> s) { return s->get_HasImage(); });
 
// Go through each shape and save its image.
auto formatConverter = MakeObject<System::Drawing::ImageFormatConverter>();
 
{
    SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<Shape>>> enumerator = shapesWithImages->GetEnumerator();
    int shapeIndex = 0;
 
    while (enumerator->MoveNext())
    {
        SharedPtr<ImageData> imageData = enumerator->get_Current()->get_ImageData();
        SharedPtr<System::Drawing::Imaging::ImageFormat> format = imageData->ToImage()->get_RawFormat();
        String fileExtension = formatConverter->ConvertToString(format);
 
        {
            SharedPtr<System::IO::FileStream> fileStream =
                System::IO::File::Create(ArtifactsDir + String::Format(u"Drawing.SaveAllImages.{0}.{1}", ++shapeIndex, fileExtension));
            imageData->Save(fileStream);
        }
    }
}

ToStream()

System::SharedPtr<System::IO::Stream> Aspose::Words::Drawing::ImageData::ToStream

(

)

Creates and returns a stream that contains the image bytes.

If the image bytes are stored in the shape, creates and returns a MemoryStream object.

If the image is linked and stored in a file, opens the file and returns a FileStream object.

If the image is linked and stored in an external URL, downloads the file and returns a MemoryStream object.

Is it the responsibility of the caller to dispose the stream object.

Examples

Shows how to create an image file from a shape's raw image data.

auto imgSourceDoc = MakeObject<Document>(MyDir + u"Images.docx");
 
auto imgShape = System::DynamicCast<Shape>(imgSourceDoc->GetChild(NodeType::Shape, 0, true));
 
ASSERT_TRUE(imgShape->get_HasImage());
 
// ToByteArray() returns the array stored in the ImageBytes property.
ASPOSE_ASSERT_EQ(imgShape->get_ImageData()->get_ImageBytes(), imgShape->get_ImageData()->ToByteArray());
 
// Save the shape's image data to an image file in the local file system.
{
    SharedPtr<System::IO::Stream> imgStream = imgShape->get_ImageData()->ToStream();
    {
        auto outStream = MakeObject<System::IO::FileStream>(ArtifactsDir + u"Drawing.GetDataFromImage.png", System::IO::FileMode::Create,
                                                            System::IO::FileAccess::ReadWrite);
        imgStream->CopyTo(outStream);
    }
}

Type()

static const System::TypeInfo& Aspose::Words::Drawing::ImageData::Type ( )

static