# Image Class

> An image resource can either be an image XObject or inline image found in a page's content stream.

- Product: Adobe PDF Library 21
- Language: Modern C++
- Version: 21.4.0
- HTML page: https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image
- Version index: https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/llms.txt

```cpp
class Image : Element
```

**Namespace:** `datalogics_interface`

**Inherits from:** [`Element`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Element.md)

## Description

An image resource can either be an image XObject or inline image found in a page's content stream.

An Image Xobject is stored separately from the graphics content stream in a PDF, and so can be used multiple times in the document, even across pages. The image is described in the /Xobject entry in the resources dictionary on the PDF page.

Image size and resoultion: For images that are imported from raster image files, the design width and height are stored in the Image object's Matrix, in the A (width) and D (depth) Matrix members, when the image is imported. These are stored in PDF units.

To derive the effective resolution of an image imported from a raster image file:

Horizontal resolution: divide the Image Width by the Image's Matrix A member and multiply by 72 to scale to DPI (dots per inch).

Vertical resolution: divide the Image Height by the Image's Matrix D member and multiply by 72 to scale to DPI (dots per inch).

**Referenced by:** [`Image`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image.md), [`ImageCollection`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/ImageCollection.md), [`Page`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Page.md)

**Uses types:** [`Clip`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Clip.md), [`ColorSpace`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/ColorSpace.md), [`CompressionCode`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/CompressionCode.md), [`Element`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Element.md), [`ElementCloneFlags`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/ElementCloneFlags.md), [`ElementType`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/ElementType.md), [`GraphicState`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/GraphicState.md), [`Image`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image.md), [`ImageData`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/ImageData.md), [`ImageType`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/ImageType.md), [`Matrix`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/struct/Matrix.md), [`Rect`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/struct/Rect.md)

## Constructors

### Image

```cpp
datalogics_interface::Image::Image(const std::string &file_name)
```

*constructor*

**Parameters**

- `file_name` (`const std::string &`): the filename of the image file.

Create a new Image from an existing physical file. This file can be a bitmap, gif, jpeg, png, or a tiff file. An exception will be thrown if the image file is not any of the above.

NOTICE on tiff files: If the tiff file is multi-paged, then the first "page" only of the file will be converted to an Image. See ImageCollection to convert each page in a multi-page tiff file to an Image.

### Image

```cpp
datalogics_interface::Image::Image(const std::string &file_name, class Document &document)
```

*constructor*

**Parameters**

- `file_name` (`const std::string &`): the filename of the image file.
- `document` ([`class Document &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Document.md))

Create a new Image from an existing physical file. This file can be a bitmap, gif, jpeg, png, or a tiff file. An exception will be thrown if the image file is not any of the above.

NOTICE on tiff files: If the tiff file is multi-paged, then the first "page" only of the file will be converted to an Image. See ImageCollection to convert each page in a multi-page tiff file to an Image.

### Image

```cpp
datalogics_interface::Image::Image(const std::vector< unsigned char > &buffer, int width, int height, const ColorSpace &color_space)
```

*constructor*

**Parameters**

- `buffer` (`const std::vector< unsigned char > &`): the filename of the image file.
- `width` (`int`)
- `height` (`int`)
- `color_space` ([`const ColorSpace &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/ColorSpace.md))

Create a new Image from an existing physical file. This file can be a bitmap, gif, jpeg, png, or a tiff file. An exception will be thrown if the image file is not any of the above.

NOTICE on tiff files: If the tiff file is multi-paged, then the first "page" only of the file will be converted to an Image. See ImageCollection to convert each page in a multi-page tiff file to an Image.

### Image

```cpp
datalogics_interface::Image::Image(Image &&) noexcept
```

*constructor*

**Parameters**

- (unnamed) ([`Image &&`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image.md))

### Image

```cpp
datalogics_interface::Image::Image(std::istream &input_stream)
```

*constructor*

**Parameters**

- `input_stream` (`std::istream &`)

Create an Image from an input stream containing image data. Supports TIFF, JPEG, BMP, PNG, GIF formats. The stream only needs to remain valid for the duration of construction.

### Image

```cpp
datalogics_interface::Image::Image(std::istream &input_stream, Document &document)
```

*constructor*

**Parameters**

- `input_stream` (`std::istream &`)
- `document` ([`Document &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Document.md))

Create an Image from an input stream, optimized for a specific document.

### ~Image

```cpp
datalogics_interface::Image::~Image() override
```

*destructor*

## Methods

### change_resolution

```cpp
Image datalogics_interface::Image::change_resolution(int dpi)
```

**Parameters**

- `dpi` (`int`): - the new resolution

**Returns:** [`Image`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image.md)

newimage - the original image modified to the new resolution.

Create a new image from an existing one modifying the resolution (dots per inch)

### clone

```cpp
std::unique_ptr< Element > datalogics_interface::Element::clone(ElementCloneFlags flags) const
```

**Parameters**

- `flags` ([`ElementCloneFlags`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/ElementCloneFlags.md))

**Returns:** [`std::unique_ptr< Element >`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Element.md)

The copied element.

Makes a copy of the element.

Make a copy of an element to obtain a new element that has a distinct set of attributes.

Note: TextRun objects may not be cloned.

### clone

```cpp
std::unique_ptr< Image > datalogics_interface::Image::clone() const
```

**Returns:** [`std::unique_ptr< Image >`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image.md)

The copied image.

Makes a copy of the image.

Make a copy of an image to obtain a new image that has a distinct set of attributes.

### get_bits_per_component

```cpp
int datalogics_interface::Image::get_bits_per_component() const
```

**Returns:** `int`

The number of bits per component (e.g. 1, 2, 4, 8, or 16).

The number of bits per component in the image.

### get_bounding_box

```cpp
Rect datalogics_interface::Element::get_bounding_box() const
```

**Returns:** [`Rect`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/struct/Rect.md)

The bounding box for this element. The coordinates of the bounding box are specified in user space coordinates, relative to the element's Content. Note that user space coordinates correspond to unrotated pages; any rotation specified in the page dictionary is not taken into account.

The bounding box for this element.

The bounding box is a rectangle that is guaranteed to encompass the element, but it is not guaranteed to be the smallest box that could contain the element. For example, if the element is a Path that contains an arc, the bounding box encompasses the bezier control points, and not just the curve itself.

### get_clip

```cpp
std::unique_ptr< Clip > datalogics_interface::Element::get_clip()
```

**Returns:** [`std::unique_ptr< Clip >`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Clip.md)

The current Clip for this Element, or NULL if no clip is set.

Gets the current Clip for an Element.

### get_color_space

```cpp
std::unique_ptr< ColorSpace > datalogics_interface::Image::get_color_space() const
```

**Returns:** [`std::unique_ptr< ColorSpace >`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/ColorSpace.md)

return the ColorSpace with which this Image was created.

### get_compression

```cpp
CompressionCode datalogics_interface::Image::get_compression() const
```

**Returns:** [`CompressionCode`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/CompressionCode.md)

A compression code which represents the filter used in the image data.

The compression filter applied to the image data.

### get_data

```cpp
std::vector< unsigned char > datalogics_interface::Image::get_data() const
```

**Returns:** `std::vector< unsigned char >`

A byte array containing the raw image data.

The actual bytes that make up the image, exactly as they appear in the image data.

### get_did_warnings_occur_during_import

```cpp
bool datalogics_interface::Image::get_did_warnings_occur_during_import() const
```

**Returns:** `bool`

true if warnings were generated during the image import process, false otherwise.

Indicates whether warnings occurred during import of the raster image file.

### get_element_type

```cpp
ElementType datalogics_interface::Element::get_element_type() const
```

**Returns:** [`ElementType`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/ElementType.md)

Returns the runtime type of this element.

### get_graphic_state

```cpp
GraphicState datalogics_interface::Image::get_graphic_state()
```

**Returns:** [`GraphicState`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/GraphicState.md)

The GraphicState associated with this image element.

The graphic state of the current element.

### get_height

```cpp
int datalogics_interface::Image::get_height() const
```

**Returns:** `int`

The height of the image in pixels.

The height of the image in pixels.

### get_intent

```cpp
std::string datalogics_interface::Image::get_intent() const
```

**Returns:** `std::string`

The rendering intent name as a string.

The color rendering intent for the image.

### get_is_image_mask

```cpp
bool datalogics_interface::Image::get_is_image_mask() const
```

**Returns:** `bool`

true if the image is an image mask, false otherwise.

Indicates whether this image is an image mask.

An image mask is a 1-bit-per-pixel image used to select painting in the current color rather than displaying image samples.

### get_large_data

```cpp
std::vector< ImageData > datalogics_interface::Image::get_large_data()
```

**Returns:** [`std::vector< ImageData >`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/ImageData.md)

A list of ImageData chunks containing the decompressed image data.

Gets the decompressed image data from very large images.

NOTE: This function is only supported in 64-bit, only if enough contiguous memory is available. The data size must exceed nearly 2GB, otherwise an exception is thrown and you would use the Data member instead to access the image data. The first members of the list returned contain a close to 2GB chunk of the data, but the last member containing the remaining data will be smaller in size. This facilitates retrieving the data in .NET and Java which have 2GB limits on object sizes.

### get_matrix

```cpp
Matrix datalogics_interface::Element::get_matrix() const
```

**Returns:** [`Matrix`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/struct/Matrix.md)

The current transformation matrix applied to this element.

The transformation matrix for the element.

### get_number_components

```cpp
int datalogics_interface::Image::get_number_components() const
```

**Returns:** `int`

The number of color components (e.g. 1 for grayscale, 3 for RGB, 4 for CMYK).

The number of color components in the image.

### get_soft_mask

```cpp
std::unique_ptr< Image > datalogics_interface::Image::get_soft_mask() const
```

**Returns:** [`std::unique_ptr< Image >`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image.md)

image - an image, the soft mask

Gets, for this image, the soft mask (also an image).

### get_width

```cpp
int datalogics_interface::Image::get_width() const
```

**Returns:** `int`

The width of the image in pixels.

The width of the image in pixels.

### get_xmp_metadata

```cpp
std::string datalogics_interface::Image::get_xmp_metadata() const
```

**Returns:** `std::string`

Returns XMP metadata from the image's stream dictionary, or empty string if none.

### operator=

```cpp
Image & datalogics_interface::Image::operator=(Image &&) noexcept
```

**Parameters**

- (unnamed) ([`Image &&`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image.md))

**Returns:** [`Image &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image.md)

### rotate

```cpp
void datalogics_interface::Element::rotate(double theta)
```

**Parameters**

- `theta` (`double`): The rotation angle in degrees.

**Returns:** `void`

Rotate an element by theta degrees counterclockwise using the matrix [ cos T sin T -sin T cos T 0 0 ].

### save

```cpp
void datalogics_interface::Image::save(const std::string &filename, ImageType type)
```

**Parameters**

- `filename` (`const std::string &`): - The physical image file which will be created.
- `type` ([`ImageType`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/ImageType.md)): - The ImageType used for saving the image.

**Returns:** `void`

Save an image into a particular file format with the given parameters for saving.

### save

```cpp
void datalogics_interface::Image::save(const std::string &filename, ImageType type, const ImageSaveParams &params)
```

**Parameters**

- `filename` (`const std::string &`): - The physical image file which will be created.
- `type` ([`ImageType`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/ImageType.md)): - The ImageType used for saving the image.
- `params` ([`const ImageSaveParams &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/ImageSaveParams.md)): - The ImageSaveParams for saving the image.

**Returns:** `void`

Save an image into a particular file format with the given parameters for saving.

### scale

```cpp
void datalogics_interface::Element::scale(double sx, double sy)
```

**Parameters**

- `sx` (`double`): The horizontal scale factor.
- `sy` (`double`): The vertical scale factor.

**Returns:** `void`

Scale an element by (sx,sy) units using the matrix [ sx 0 0 sy 0 0 ].

### set_clip

```cpp
void datalogics_interface::Element::set_clip(Clip &clip)
```

**Parameters**

- `clip` ([`Clip &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Clip.md)): The clip to set as the current clip for this element, or NULL to remove clipping.

**Returns:** `void`

Sets the current Clip for an Element.

### set_compression

```cpp
void datalogics_interface::Image::set_compression(CompressionCode code)
```

**Parameters**

- `code` ([`CompressionCode`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/enum/CompressionCode.md)): The new new compression scheme to be applied.

**Returns:** `void`

Set a Compression scheme for the image data.

To apply a G3 or G4 filter, the image must be bi-color (black and white) and 1 bit per pixel.

### set_graphic_state

```cpp
void datalogics_interface::Image::set_graphic_state(GraphicState gs)
```

**Parameters**

- `gs` ([`GraphicState`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/GraphicState.md)): - the new/updated Graphic State for the element.

**Returns:** `void`

Set the Graphic State of the current element.

### set_intent

```cpp
void datalogics_interface::Image::set_intent(const std::string &intent)
```

**Parameters**

- `intent` (`const std::string &`): the intent name

**Returns:** `void`

SetIntent allows to set color rendering intent for the image.

### set_matrix

```cpp
void datalogics_interface::Element::set_matrix(const Matrix &matrix)
```

**Parameters**

- `matrix` ([`const Matrix &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/struct/Matrix.md)): The transformation matrix for the element.

**Returns:** `void`

Set the transformation matrix for the element.

### set_soft_mask

```cpp
void datalogics_interface::Image::set_soft_mask(Image &mask)
```

**Parameters**

- `mask` ([`Image &`](https://docs.datalogics.com/apdfl21/ModernCPP/21.4.0/class/Image.md)): - an image, the soft mask. If set to NULL, the soft mask is removed.

**Returns:** `void`

Sets, for this image, the soft mask (also an image).

### translate

```cpp
void datalogics_interface::Element::translate(double tx, double ty)
```

**Parameters**

- `tx` (`double`): The horizontal translation distance in user space units.
- `ty` (`double`): The vertical translation distance in user space units.

**Returns:** `void`

Translate an element by (tx,ty) units using the matrix [ 1 0 0 1 tx ty ].

### try_as

```cpp
T * datalogics_interface::Element::try_as()
```

**Parameters**

- (unnamed) (`typename T`)

**Returns:** `T *`

Attempt to downcast this element to a derived type. Returns a pointer to the derived type, or nullptr if the type doesn't match.

### try_as

```cpp
const T * datalogics_interface::Element::try_as() const
```

**Parameters**

- (unnamed) (`typename T`)

**Returns:** `const T *`

Const overload of try_as(). Returns a const pointer, or nullptr.