> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/core/create/document-creation-api/images-and-shapes.md).

# Images and shapes

Us the document creation API to add images and shapes to a doc.

Images and vector shapes are inline content: they are added to a [paragraph](/core/create/document-creation-api/paragraphs-and-text.md) and participate in the text flow. In fact an image *is* a shape - `AddImage` creates a shape and sets the image as its background.

## Images

`AddImage` takes the display size in points and either a file path or a filter. The image is scaled to the requested size.

{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
Paragraph para = doc.AddParagraph();
para.SetJustificationMode(Paragraph.TextJustification.e_center);
para.AddImage(120, 90, input_path + "butterfly.png");
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
Paragraph para = doc.AddParagraph();
para.SetJustificationMode(Paragraph::e_text_justify_center);
para.AddImage(120, 90, input_path + "butterfly.png");
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
para := doc.AddParagraph()
para.SetJustificationMode(ParagraphE_text_justify_center)
para.AddImage(120, 90, inputPath+"butterfly.png")
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
Paragraph para = doc.addParagraph();
para.setJustificationMode(Paragraph.TextJustification.e_text_justify_center);
para.addImage(120, 90, input_path + "butterfly.png");
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const para = await doc.addParagraph();
para.setJustificationMode(PDFNet.Paragraph.TextJustification.e_text_justify_center);
await para.addImage(120, 90, inputPath + 'butterfly.png');
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objectivec
PTParagraph* para = [doc AddParagraph];
[para SetJustificationMode:e_ptpara_text_justify_center];
[para AddImageWithPath:120 height:90
                  path:[input_path stringByAppendingString:@"butterfly.png"]];
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$para = $doc->AddParagraph();
$para->SetJustificationMode(Paragraph::e_text_justify_center);
$para->AddImage(120, 90, $input_path."butterfly.png");
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
para = doc.AddParagraph()
para.SetJustificationMode(Paragraph.e_text_justify_center)
para.AddImage(120, 90, input_path + "butterfly.png")
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
para = doc.AddParagraph()
para.SetJustificationMode(Paragraph::E_text_justify_center)
para.AddImage(120, 90, input_path + "butterfly.png")
```

{% endcode %}
{% endtab %}
{% endtabs %}

<figure><img src="https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2FTjKBSfZZlp7FbcpA2vgX%2Fimage_basic.png?alt=media&amp;token=ae0d2dbf-ddde-47e9-833a-13ad744a15e2" alt="Image of a blue butterfly."><figcaption></figcaption></figure>

Because images are inline, they can sit in the middle of running text - useful for logos, icons and signatures.

{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
Paragraph para = doc.AddParagraph();
para.AddText("Images are inline content, so they sit in the text flow ");
para.AddImage(16, 16, input_path + "logo_red.png");
para.AddText(" just like any other run, and the surrounding text wraps around them.");
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
Paragraph para = doc.AddParagraph();
para.AddText("Images are inline content, so they sit in the text flow ");
para.AddImage(16, 16, input_path + "logo_red.png");
para.AddText(" just like any other run, and the surrounding text wraps around them.");
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
para := doc.AddParagraph()
para.AddText("Images are inline content, so they sit in the text flow ")
para.AddImage(16, 16, inputPath+"logo_red.png")
para.AddText(" just like any other run, and the surrounding text wraps around them.")
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
Paragraph para = doc.addParagraph();
para.addText("Images are inline content, so they sit in the text flow ");
para.addImage(16, 16, input_path + "logo_red.png");
para.addText(" just like any other run, and the surrounding text wraps around them.");
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const para = await doc.addParagraph();
await para.addText('Images are inline content, so they sit in the text flow ');
await para.addImage(16, 16, inputPath + 'logo_red.png');
await para.addText(' just like any other run, and the surrounding text wraps around them.');
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objectivec
PTParagraph* para = [doc AddParagraph];
[para AddText:@"Images are inline content, so they sit in the text flow "];
[para AddImageWithPath:16 height:16
                  path:[input_path stringByAppendingString:@"logo_red.png"]];
[para AddText:@" just like any other run, and the surrounding text wraps around them."];
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$para = $doc->AddParagraph();
$para->AddText("Images are inline content, so they sit in the text flow ");
$para->AddImage(16, 16, $input_path."logo_red.png");
$para->AddText(" just like any other run, and the surrounding text wraps around them.");
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
para = doc.AddParagraph()
para.AddText("Images are inline content, so they sit in the text flow ")
para.AddImage(16, 16, input_path + "logo_red.png")
para.AddText(" just like any other run, and the surrounding text wraps around them.")
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
para = doc.AddParagraph()
para.AddText("Images are inline content, so they sit in the text flow ")
para.AddImage(16, 16, input_path + "logo_red.png")
para.AddText(" just like any other run, and the surrounding text wraps around them.")
```

{% endcode %}
{% endtab %}
{% endtabs %}

<figure><img src="https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2F1LH3t9fUiIh9bCnAs0h7%2Fimage_inline.png?alt=media&amp;token=7d9ca934-f10b-447c-b0bd-e64fea78b1f1" alt="An icon inline with text."><figcaption></figcaption></figure>

An overload of `AddImage` accepts a filter, so the image data can come from memory rather than disk. To place an image outside the text flow, pinned to a page position with text wrapping around it, put it in a [float](/core/create/document-creation-api/floats.md).

## Shape types

`AddShape` takes a shape type and a size. Type-specific properties such as the corner radius and the arrow head size are ignored by shapes for which they do not apply.

{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
Shape shape = para.AddShape(Shape.ShapeType.e_rectangle_rounded_corners, 60, 40);
shape.SetCornerRadius(8);
shape.SetBackgroundColor(219, 233, 248);
shape.SetOutlineColor(0, 51, 102);
shape.SetOutlineThickness(1);
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
Shape shape = para.AddShape(Shape::e_rectangle_rounded_corners, 60, 40);
shape.SetCornerRadius(8);
shape.SetBackgroundColor(219, 233, 248);
shape.SetOutlineColor(0, 51, 102);
shape.SetOutlineThickness(1);
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
shape := para.AddShape(ShapeE_rectangle_rounded_corners, 60, 40)
shape.SetCornerRadius(8)
shape.SetBackgroundColor(219, 233, 248)
shape.SetOutlineColor(0, 51, 102)
shape.SetOutlineThickness(1)
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
Shape shape = para.addShape(Shape.ShapeType.e_rectangle_rounded_corners, 60, 40);
shape.setCornerRadius(8);
shape.setBackgroundColor(219, 233, 248);
shape.setOutlineColor(0, 51, 102);
shape.setOutlineThickness(1);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const shape = await para.addShape(PDFNet.Shape.Type.e_rectangle_rounded_corners, 60, 40);
shape.setCornerRadius(8);
shape.setBackgroundColor(219, 233, 248);
shape.setOutlineColor(0, 51, 102);
shape.setOutlineThickness(1);
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objectivec
PTShape* shape = [para AddShape:e_ptshape_rectangle_rounded_corners
                          width:60 height:40];
[shape SetCornerRadius:8];
[shape SetBackgroundColor:219 green:233 blue:248];
[shape SetOutlineColor:0 green:51 blue:102];
[shape SetOutlineThickness:1];
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$shape = $para->AddShape(Shape::e_rectangle_rounded_corners, 60, 40);
$shape->SetCornerRadius(8);
$shape->SetBackgroundColor(219, 233, 248);
$shape->SetOutlineColor(0, 51, 102);
$shape->SetOutlineThickness(1);
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
shape = para.AddShape(Shape.e_rectangle_rounded_corners, 60, 40)
shape.SetCornerRadius(8)
shape.SetBackgroundColor(219, 233, 248)
shape.SetOutlineColor(0, 51, 102)
shape.SetOutlineThickness(1)
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
shape = para.AddShape(Shape::E_rectangle_rounded_corners, 60, 40)
shape.SetCornerRadius(8)
shape.SetBackgroundColor(219, 233, 248)
shape.SetOutlineColor(0, 51, 102)
shape.SetOutlineThickness(1)
```

{% endcode %}
{% endtab %}
{% endtabs %}

<figure><img src="https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2FFHMAFlyLMTVnfyqUUbn7%2Fshape_types.png?alt=media&amp;token=39132cae-8d87-4f96-a4f6-a63728a891cd" alt="Examples of shapes like a square, oval, and arrow."><figcaption></figcaption></figure>

Shape values include:

<table data-search="false"><thead><tr><th>Value</th><th>Shape</th></tr></thead><tbody><tr><td><code>e_line</code></td><td>Plain line</td></tr><tr><td><code>e_line_arrow</code></td><td>Line with an arrow head at one end</td></tr><tr><td><code>e_line_double_arrow</code></td><td>Line with arrow heads at both ends</td></tr><tr><td><code>e_rectangle</code></td><td>Rectangle</td></tr><tr><td><code>e_rectangle_rounded_corners</code></td><td>Rectangle with rounded corners</td></tr><tr><td><code>e_oval</code></td><td>Ellipse</td></tr><tr><td><code>e_arrow</code></td><td>Solid arrow</td></tr></tbody></table>

## Shape text boxes

Every shape exposes a `ContentContainer` through `GetTextBox`. Anything you can put in a document can go inside a shape, which is how mastheads, callouts, and pull quotes are built.

{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
Shape box = para.AddShape(Shape.ShapeType.e_rectangle_rounded_corners, 260, 70);
box.SetCornerRadius(10);
box.SetBackgroundColor(0, 51, 102);

ContentContainer text = box.GetTextBox();

Paragraph title = text.AddParagraph("The Monthly Dispatch");
title.SetJustificationMode(Paragraph.TextJustification.e_center);

TextStyledElement titleStyle = title.GetTextStyledElement();
titleStyle.SetFontSize(18);
titleStyle.SetBold(true);
titleStyle.SetTextColor(255, 255, 255);
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
Shape box = para.AddShape(Shape::e_rectangle_rounded_corners, 260, 70);
box.SetCornerRadius(10);
box.SetBackgroundColor(0, 51, 102);

ContentContainer text = box.GetTextBox();

Paragraph title = text.AddParagraph("The Monthly Dispatch");
title.SetJustificationMode(Paragraph::e_text_justify_center);

TextStyledElement title_style = title.GetTextStyledElement();
title_style.SetFontSize(18);
title_style.SetBold(true);
title_style.SetTextColor(255, 255, 255);
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
box := para.AddShape(ShapeE_rectangle_rounded_corners, 260, 70)
box.SetCornerRadius(10)
box.SetBackgroundColor(0, 51, 102)

text := box.GetTextBox()

title := text.AddParagraph("The Monthly Dispatch")
title.SetJustificationMode(ParagraphE_text_justify_center)

titleStyle := title.GetTextStyledElement()
titleStyle.SetFontSize(18)
titleStyle.SetBold(true)
titleStyle.SetTextColor(255, 255, 255)
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
Shape box = para.addShape(Shape.ShapeType.e_rectangle_rounded_corners, 260, 70);
box.setCornerRadius(10);
box.setBackgroundColor(0, 51, 102);

ContentContainer text = box.getTextBox();

Paragraph title = text.addParagraph("The Monthly Dispatch");
title.setJustificationMode(Paragraph.TextJustification.e_text_justify_center);

TextStyledElement titleStyle = title.getTextStyledElement();
titleStyle.setFontSize(18);
titleStyle.setBold(true);
titleStyle.setTextColor(255, 255, 255);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const box = await para.addShape(PDFNet.Shape.Type.e_rectangle_rounded_corners, 260, 70);
box.setCornerRadius(10);
box.setBackgroundColor(0, 51, 102);

const text = await box.getTextBox();

const title = await text.addParagraphWithText('The Monthly Dispatch');
title.setJustificationMode(PDFNet.Paragraph.TextJustification.e_text_justify_center);

const titleStyle = await title.getTextStyledElement();
titleStyle.setFontSize(18);
titleStyle.setBold(true);
titleStyle.setTextColor(255, 255, 255);
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objectivec
PTShape* box = [para AddShape:e_ptshape_rectangle_rounded_corners
                        width:260 height:70];
[box SetCornerRadius:10];
[box SetBackgroundColor:0 green:51 blue:102];

PTContentContainer* text = [box GetTextBox];

PTParagraph* title = [text AddParagraphWithText:@"The Monthly Dispatch"];
[title SetJustificationMode:e_ptpara_text_justify_center];

PTTextStyledElement* title_style = [title GetTextStyledElement];
[title_style SetFontSize:18];
[title_style SetBold:YES];
[title_style SetTextColor:255 green:255 blue:255];
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$box = $para->AddShape(Shape::e_rectangle_rounded_corners, 260, 70);
$box->SetCornerRadius(10);
$box->SetBackgroundColor(0, 51, 102);

$text = $box->GetTextBox();

$title = $text->AddParagraph("The Monthly Dispatch");
$title->SetJustificationMode(Paragraph::e_text_justify_center);

$title_style = $title->GetTextStyledElement();
$title_style->SetFontSize(18);
$title_style->SetBold(true);
$title_style->SetTextColor(255, 255, 255);
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
box = para.AddShape(Shape.e_rectangle_rounded_corners, 260, 70)
box.SetCornerRadius(10)
box.SetBackgroundColor(0, 51, 102)

text = box.GetTextBox()

title = text.AddParagraph("The Monthly Dispatch")
title.SetJustificationMode(Paragraph.e_text_justify_center)

title_style = title.GetTextStyledElement()
title_style.SetFontSize(18)
title_style.SetBold(True)
title_style.SetTextColor(255, 255, 255)
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
box = para.AddShape(Shape::E_rectangle_rounded_corners, 260, 70)
box.SetCornerRadius(10)
box.SetBackgroundColor(0, 51, 102)

text = box.GetTextBox()

title = text.AddParagraph("The Monthly Dispatch")
title.SetJustificationMode(Paragraph::E_text_justify_center)

title_style = title.GetTextStyledElement()
title_style.SetFontSize(18)
title_style.SetBold(true)
title_style.SetTextColor(255, 255, 255)
```

{% endcode %}
{% endtab %}
{% endtabs %}

<figure><img src="https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2FAymcIqB9sp5LrGN4pvvi%2Fshape_text_box.png?alt=media&amp;token=7bca9c19-5191-4576-9c28-d6294881718c" alt="Blue container with The Monthly Dispatch written in white."><figcaption></figcaption></figure>

{% hint style="info" %}
**Info**

A shape does not grow to fit its text box. Size the shape for the content you expect, or keep the text short.
{% endhint %}

## Rotation and flipping

`SetRotation` rotates a shape, together with its text box and background image, around its center. `SetFlipHorizontal` and `SetFlipVertical` mirror it.

{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
Shape shape = para.AddShape(Shape.ShapeType.e_arrow, 70, 40);
shape.SetRotation(30);              // degrees
shape.SetArrowHeadSize(16);
shape.SetBackgroundColor(0, 153, 102);
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
Shape shape = para.AddShape(Shape::e_arrow, 70, 40);
shape.SetRotation(30);              // degrees
shape.SetArrowHeadSize(16);
shape.SetBackgroundColor(0, 153, 102);
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
shape := para.AddShape(ShapeE_arrow, 70, 40)
shape.SetRotation(30)              // degrees
shape.SetArrowHeadSize(16)
shape.SetBackgroundColor(0, 153, 102)
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
Shape shape = para.addShape(Shape.ShapeType.e_arrow, 70, 40);
shape.setRotation(30);              // degrees
shape.setArrowHeadSize(16);
shape.setBackgroundColor(0, 153, 102);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const shape = await para.addShape(PDFNet.Shape.Type.e_arrow, 70, 40);
shape.setRotation(30);              // degrees
shape.setArrowHeadSize(16);
shape.setBackgroundColor(0, 153, 102);
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objectivec
PTShape* shape = [para AddShape:e_ptshape_arrow width:70 height:40];
[shape SetRotation:30];              // degrees
[shape SetArrowHeadSize:16];
[shape SetBackgroundColor:0 green:153 blue:102];
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$shape = $para->AddShape(Shape::e_arrow, 70, 40);
$shape->SetRotation(30);              // degrees
$shape->SetArrowHeadSize(16);
$shape->SetBackgroundColor(0, 153, 102);
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
shape = para.AddShape(Shape.e_arrow, 70, 40)
shape.SetRotation(30)              # degrees
shape.SetArrowHeadSize(16)
shape.SetBackgroundColor(0, 153, 102)
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
shape = para.AddShape(Shape::E_arrow, 70, 40)
shape.SetRotation(30)              # degrees
shape.SetArrowHeadSize(16)
shape.SetBackgroundColor(0, 153, 102)
```

{% endcode %}
{% endtab %}
{% endtabs %}

<figure><img src="https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2FIhJ7GIGmQlaEA8pTioLf%2Fshape_rotation.png?alt=media&amp;token=53520b40-5bd9-44a9-aacd-8035f1cfdfc8" alt="Green arrows that are rotated, pointing in different directions."><figcaption></figcaption></figure>

## Further Reading

* [Floats](/core/create/document-creation-api/floats.md) for taking an image or shape out of the text flow.
* [Paragraphs and text](/core/create/document-creation-api/paragraphs-and-text.md) for the paragraph that hosts inline images and shapes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apryse.com/core/create/document-creation-api/images-and-shapes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.