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

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:

using Nutrient;

Working with shape annotations

Open the document with using statements(opens in a new tab) 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.

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

    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:

    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.

    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.

    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.

    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:

    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.