---
title: "Add shape annotations in C# | Nutrient .NET SDK"
canonical_url: "https://www.nutrient.io/guides/dotnet/csharp/editor/add-shape-annotations-to-pdf/"
md_url: "https://www.nutrient.io/guides/dotnet/csharp/editor/add-shape-annotations-to-pdf.md"
last_updated: "2026-10-08T00:00:00.000Z"
description: "How to add shape annotations to a PDF using Nutrient .NET SDK."
---

# Adding shape annotations to a PDF document

Use shape annotations to add structured visual markup to PDF files.

Common use cases include:

- Architectural markups

- Diagram and technical drawing tools

- Review workflows with callouts

- Region highlighting and boundary marking

In this guide, you’ll add:

- Lines with configurable ending styles

- Circles and ellipses

- Squares and rectangles

- Custom colors and line widths

[Download sample](https://www.nutrient.io/downloads/samples/csharp/add-shape-annotations-to-pdf.zip)

## How Nutrient helps

Nutrient.NET SDK handles shape annotation structures and rendering.

The SDK handles:

- Parsing shape annotation dictionaries and path construction

- Managing stroke and fill operations with appearance streams

- Handling geometric calculations and coordinate transformations

- Complex line ending styles and cap rendering

## Complete implementation

This example adds multiple shape annotations to a PDF file:

```csharp

using Nutrient;

```

## Working with shape annotations

Open the document with [using statements](https://learn.microsoft.com/dotnet/csharp/language-reference/statements/using) to ensure cleanup after processing.

Then:

- Create a PDF editor.

- Get the page collection.

- Add a letter-size page (`612 × 792`) if the document is empty.

- Get the annotation collection from the first page.

```csharp

try
{
    using Document document = Document.Open("input.pdf");
    using PdfEditor editor = PdfEditor.Edit(document);
    PdfPageCollection pages = editor.PageCollection;

    if (pages.Count == 0)
    {
        pages.Add(612.0f, 792.0f);
    }

    PdfPage page = pages.First?? throw new InvalidOperationException("The document has no pages.");
    PdfAnnotationCollection annotations = page.AnnotationCollection;

```

## Adding a line annotation

Create a line with `AddLine(startX, startY, endX, endY, author, contents)`.

This example adds a horizontal line from `(50, 700)` to `(200, 700)`:

By default, the SDK uses:

- Black stroke color (`ARGB 255, 0, 0, 0`)

- `1.0` point line width

```csharp

    PdfLineAnnotation line = annotations.AddLine(
        50.0f, 700.0f, 200.0f, 700.0f, // startX, startY, endX, endY
        "Author",
        "Simple horizontal line"
    );

```

## Adding a line with arrow endings

Create a second line and customize its style.

This example:

- Draws a diagonal line from `(50, 650)` to `(200, 600)`.

- Sets the end cap to `PdfLineEndingStyle.ClosedArrow`.

- Sets the color to blue with `Color.FromArgb(255, 0, 0, 255)`.

- Sets the line width to `2.0` with the `BorderWidth` property.

Set ending styles on both `StartCap` and `EndCap`:

```csharp

    PdfLineAnnotation arrow = annotations.AddLine(
        50.0f, 650.0f, 200.0f, 600.0f, // startX, startY, endX, endY
        "Reviewer",
        "Arrow pointing to important area"
    );
    // Optionally customize the line
    arrow.EndCap = PdfLineEndingStyle.ClosedArrow;
    arrow.Color = Color.FromArgb(255, 0, 0, 255);
    arrow.BorderWidth = 2.0f;

```

Available line ending styles from the `PdfLineEndingStyle` enumeration include:

- `None` — No ending (default)

- `Square` — Square ending for boundary indicators

- `Circle` — Circular ending for connection points

- `Diamond` — Diamond shape for decision points

- `OpenArrow` — Open arrowhead for directional indicators

- `ClosedArrow` — Filled arrowhead for emphasis

- `Butt` — Perpendicular line for measurement marks

- `ReverseOpenArrow` — Reverse open arrow for backward direction

- `ReverseClosedArrow` — Reverse closed arrow for backward emphasis

- `Slash` — Slash mark for termination indicators

## Adding a circle annotation

Create a circle with `AddCircle(x, y, width, height, author, contents)`.

In this sample:

- The bounds are `x=250`, `y=550`, `width=100`, and `height=100`.

- Equal width and height produce a circle.

- Unequal values produce an ellipse.

- The style is updated to green and a `2.0` point line width.

```csharp

    PdfCircleAnnotation circle = annotations.AddCircle(
        250.0f, 550.0f, 100.0f, 100.0f, // x, y, width, height
        "Editor",
        "Area of interest"
    );
    // Optionally customize the appearance
    circle.Color = Color.FromArgb(255, 0, 128, 0);
    circle.BorderWidth = 2.0f;

```

## Adding a square annotation

Create a square or rectangle with `AddSquare(x, y, width, height, author, contents)`.

In this sample:

- The bounds are `x=400`, `y=550`, `width=150`, and `height=100`.

- Equal width and height produce a square.

- Unequal values produce a rectangle.

- The style is updated to purple and a `2.0` point line width.

```csharp

    PdfSquareAnnotation square = annotations.AddSquare(
        400.0f, 550.0f, 150.0f, 100.0f, // x, y, width, height
        "Reviewer",
        "Section to review"
    );
    // Optionally customize the appearance
    square.Color = Color.FromArgb(255, 128, 0, 128);
    square.BorderWidth = 2.0f;

```

## Combining multiple shapes

Use consistent styling across multiple shapes to build one markup set.

This sample creates:

- A callout line with an open arrow

- An ellipse highlight

- A rectangular selection box

All three use:

- An orange stroke (`ARGB 255, 255, 165, 0`).

- `1.5` point line width.

```csharp

    PdfLineAnnotation calloutLine = annotations.AddLine(
        50.0f, 500.0f, 150.0f, 450.0f, // startX, startY, endX, endY
        "Author", "Callout line"
    );
    calloutLine.EndCap = PdfLineEndingStyle.OpenArrow;
    calloutLine.Color = Color.FromArgb(255, 255, 165, 0);
    calloutLine.BorderWidth = 1.5f;

    PdfCircleAnnotation highlightCircle = annotations.AddCircle(
        150.0f, 420.0f, 100.0f, 60.0f, // x, y, width, height
        "Author", "Highlighted area"
    );
    highlightCircle.Color = Color.FromArgb(255, 255, 165, 0);
    highlightCircle.BorderWidth = 1.5f;

    PdfSquareAnnotation selectionBox = annotations.AddSquare(
        260.0f, 420.0f, 100.0f, 60.0f, // x, y, width, height
        "Author", "Selection box"
    );
    selectionBox.Color = Color.FromArgb(255, 255, 165, 0);
    selectionBox.BorderWidth = 1.5f;

```

## Saving the document

Save the output PDF.

The `catch` block catches `NutrientException` if processing fails:

```csharp

    editor.SaveAs("output.pdf");
    Console.WriteLine("Successfully saved output.pdf");
}
catch (NutrientException e)
{
    Console.Error.WriteLine($"Error: {e.Message}");
    Environment.Exit(1);
}

```

## Conclusion

Use this workflow to add shape annotations:

1. Open the document with `using` statements for automatic resource cleanup.

2. Create an editor and access the page collection.

3. Ensure at least one page exists by adding a letter-size page if needed.

4. Retrieve the annotation collection from the target page.

5. Create line annotations with `AddLine()` specifying start and end coordinates.

6. Customize line endings using `StartCap` and `EndCap` with `PdfLineEndingStyle` values.

7. Create circle annotations with `AddCircle()` for highlighting regions (equal dimensions create perfect circles).

8. Create square annotations with `AddSquare()` for boundary marking (equal dimensions create perfect squares).

9. Combine multiple shapes with consistent styling for unified visual markup systems.

10. Save the document — the `using` statements release the native handles.

For related annotation workflows, refer to the [.NET SDK annotation guides](https://www.nutrient.io/guides/dotnet/csharp/editor.md).
---

## Related pages

- [Nutrient .NET SDK editor guides](/guides/dotnet/csharp/editor.md)
- [Adding annotations to a PDF document](/guides/dotnet/csharp/editor/add-annotations-to-pdf.md)
- [Adding a custom page to a PDF document](/guides/dotnet/csharp/editor/add-custom-page-to-pdf.md)
- [Adding interactive form fields to a PDF document](/guides/dotnet/csharp/editor/add-form-fields-to-pdf.md)
- [Adding free text annotations to a PDF document](/guides/dotnet/csharp/editor/add-freetext-annotations-to-pdf.md)
- [Adding invisible digital signatures to a PDF document](/guides/dotnet/csharp/editor/add-invisible-signature-to-pdf.md)
- [Adding link annotations to a PDF document](/guides/dotnet/csharp/editor/add-link-annotations-to-pdf.md)
- [Adding redaction annotations to a PDF document](/guides/dotnet/csharp/editor/add-redaction-annotations-to-pdf.md)
- [Adding stamp annotations to a PDF document](/guides/dotnet/csharp/editor/add-stamp-annotations-to-pdf.md)
- [Adding sticky note annotations to a PDF document](/guides/dotnet/csharp/editor/add-sticky-note-annotations-to-pdf.md)
- [Adding text markup annotations to a PDF document](/guides/dotnet/csharp/editor/add-text-markup-annotations-to-pdf.md)
- [Adding visible digital signatures to a PDF document](/guides/dotnet/csharp/editor/add-visible-signature-to-pdf.md)
- [Advanced digital signature workflows](/guides/dotnet/csharp/editor/advanced-digital-signatures.md)
- [Detecting and adding form fields to a PDF document](/guides/dotnet/csharp/editor/detect-and-add-form-fields.md)
- [Editing PDF form fields](/guides/dotnet/csharp/editor/editing-pdf-form-fields.md)
- [Editing PDF metadata with Nutrient .NET SDK](/guides/dotnet/csharp/editor/editing-pdf-metadata.md)
- [Filling PDF form fields](/guides/dotnet/csharp/editor/fill-pdf-form.md)
- [Managing PDF page order](/guides/dotnet/csharp/editor/manage-pdf-page-order.md)
- [Merging PDFs](/guides/dotnet/csharp/editor/merge-pdf-into-other-pdf.md)