XMP Annotations in C# .NET

GdPicture.NET SDK allows you to create XMP annotations with the XML-based syntax. They can be added to PDF, JPG, and TIFF files. The XMP annotations are handled by the AnnotationManager class. The list below shows all possible XMP annotation types:

  • Text annotation

  • Rubber stamp

  • Geometric — An annotation represented as a geometric figure (line, arrow, ellipse, polygon, and so on).

  • Free hand — A freely drawn line.

  • Comment annotation — An annotation linked to an already existing annotation.

  • Sticky note — A text annotation confined in a colored rectangular area with borders.

Adding an XMP Annotation

To add an XMP annotation, follow these steps:

  1. Create an AnnotationManager object.

  2. Load a file to the AnnotationManager object. For more information, refer to the guide on loading a file to the AnnotationManager object.

  3. Optional: Specify the page where to add the XMP annotation with the SelectPage method. This step is only required for PDF and TIFF files.

  4. Use any method from the AnnotationManager class that starts with Add... to add an XMP annotation. Alternatively, create a new annotation by using the specific annotation class — for example, the AnnotationEllipse class.

  5. Optional: Set the XMP annotation’s properties.

  6. Save the newly created annotation to the page with the SaveAnnotationsToPage method.

  7. Optional: Flatten the XMP annotation into the file with the BurnAnnotationsToPage method. Flattened annotations are no longer editable.

  8. Save the file. For more information, refer to the guide on saving a file from the AnnotationManager object.

To add an ellipse XMP annotation and flatten it into to a JPG file, use the following code:

using AnnotationManager annotationManager = new AnnotationManager();
// Load an image to the `AnnotationManager` object.
annotationManager.InitFromFile(@"C:\temp\source.jpg");
// Create a new `AnnotationEllipse` object.
AnnotationEllipse annotEllipse = annotationManager.AddEllipseAnnot(GdPictureColor.Aqua, 2, 1, 4, 2);
// Set the `Author` property of the annotation.
annotEllipse.Author = "PSPDFKit";
// Save the annotation to the image.
annotationManager.SaveAnnotationsToPage();
// Flatten the annotation.
annotationManager.BurnAnnotationsToPage(false);
// Save the image with the annotation to a file.
annotationManager.SaveDocumentToJPEG(@"C:\temp\output.jpg", 75);
Using annotationManager As AnnotationManager = New AnnotationManager()
    ' Load an image to the `AnnotationManager` object.
    annotationManager.InitFromFile("C:\temp\source.jpg")
    ' Create a new `AnnotationEllipse` object.
    Dim annotEllipse As AnnotationEllipse = annotationManager.AddEllipseAnnot(GdPictureColor.Aqua, 2, 1, 4, 2)
    ' Set the `Author` property of the annotation.
    annotEllipse.Author = "PSPDFKit"
    ' Save the annotation to the image.
    annotationManager.SaveAnnotationsToPage()
    ' Flatten the annotation.
    annotationManager.BurnAnnotationsToPage(False)
    ' Save the image with the annotation to a file.
    annotationManager.SaveDocumentToJPEG("C:\temp\output.jpg", 75)
End Using
Used Methods

Related Topics

XMP Annotation Object Properties

Each XMP annotation contains generic annotation properties and sometimes contains properties specific to the annotation type. To get or modify these properties, use the SetAnnotationPropertyValue method.

Information

If you created an XMP annotation with the specific annotation class — for example, the AnnotationEllipse class — you can access its properties directly from the used annotation object.

To set the author of a newly created XMP annotation, use the following code:

using AnnotationManager annotationManager = new AnnotationManager();
// Load an image to the `AnnotationManager` object.
annotationManager.InitFromFile(@"C:\temp\source.jpg");
// Add an ellipse annotation.
annotationManager.AddEllipseAnnot(GdPictureColor.Aqua, 2, 1, 4, 2);
// Set the `Author` property of the annotation.
annotationManager.SetAnnotationPropertyValue(0, "Author", "PSPDFKit");
// Save the annotation to the image.
annotationManager.SaveAnnotationsToPage();
// Save the image with the annotation to a file.
annotationManager.SaveDocumentToJPEG(@"C:\temp\output.jpg", 75);
Using annotationManager As AnnotationManager = New AnnotationManager()
    ' Load an image to the `AnnotationManager` object.
    annotationManager.InitFromFile("C:\temp\source.jpg")
    ' Add an ellipse annotation.
    annotationManager.AddEllipseAnnot(GdPictureColor.Aqua, 2, 1, 4, 2)
    ' Set the `Author` property of the annotation.
    annotationManager.SetAnnotationPropertyValue(0, "Author", "PSPDFKit")
    ' Save the annotation to the image.
    annotationManager.SaveAnnotationsToPage()
    ' Save the image with the annotation to a file.
    annotationManager.SaveDocumentToJPEG("C:\temp\output.jpg", 75)
End Using
Used Methods

Related Topics

Finding an Existing XMP Annotation

There are three different ways to find an existing XMP annotation:

  • Get its index number.

  • Get the whole XMP annotation object.

  • Get the annotation’s XML content in a string form.

The method you use depends on which operations you perform on the annotation.

Getting the Index Number

To get the XMP annotation’s index number, follow these steps:

  1. Create an AnnotationManager object.

  2. Load a file to the AnnotationManager object. For more information, refer to the guide on loading a file to the AnnotationManager object.

  3. Optional: Specify the page where to add the XMP annotation with the SelectPage method. This step is only required for PDF and TIFF files.

  4. Get the total amount of annotations with the GetAnnotationCount method.

  5. Loop through all annotations.

  6. Find the annotation that meets your search parameters. For example, use the GetAnnotationType or the GetAnnotationPropertyValue methods.

using AnnotationManager annotationManager = new AnnotationManager();
// Load an image to the `AnnotationManager` object.
annotationManager.InitFromFile(@"C:\temp\source.jpg");
// Get the total amount of XMP annotations.
int annotCount = annotationManager.GetAnnotationCount();
for(int i = 0; i < annotCount; i++)
{
    // Check if the current annotation is of the ellipse type.
    if(annotationManager.GetAnnotationType(i) == GdPictureAnnotationType.AnnotationTypeEllipse)
    {
        // Get the current annotation index number.
        Console.WriteLine("Index Number: {0}", i);
    }
}
Using annotationManager As AnnotationManager = New AnnotationManager()
    ' Load an image to the `AnnotationManager` object.
    annotationManager.InitFromFile("C:\temp\source.jpg")
    ' Get the total amount of XMP annotations.
    Dim annotCount As Integer = annotationManager.GetAnnotationCount()
    For i = 0 To annotCount - 1
        ' Check if the current annotation is of the ellipse type.
        If annotationManager.GetAnnotationType(i) Is GdPictureAnnotationType.AnnotationTypeEllipse Then
            ' Get the current annotation index number.
            Console.WriteLine("Index Number: {0}", i)
        End If
    Next
End Using
Used Methods

Getting the XMP Annotation Object

To get an existing XMP annotation object, use the GetAnnotationFromIdx method. It requires the annotation’s index number.

The following example changes the author property of all ellipse annotations:

using AnnotationManager annotationManager = new AnnotationManager();
// Load an image to the `AnnotationManager` object.
annotationManager.InitFromFile(@"C:\temp\source.jpg");
// Get the total amount of XMP annotations.
int annotCount = annotationManager.GetAnnotationCount();
for(int i = 0; i < annotCount; i++)
{
    // Check if the current annotation is of the ellipse type.
    if(annotationManager.GetAnnotationType(i) == GdPictureAnnotationType.AnnotationTypeEllipse)
    {
        // Save the current annotation to an object.
        Annotation annot = annotationManager.GetAnnotationFromIdx(i);
        // Change the `Author` property.
        annot.Author = "PSPDFKit";
    }
}
Using annotationManager As AnnotationManager = New AnnotationManager()
    ' Load an image to the `AnnotationManager` object.
    annotationManager.InitFromFile("C:\temp\source.jpg")
    ' Get the total amount of XMP annotations.
    Dim annotCount As Integer = annotationManager.GetAnnotationCount()
    For i = 0 To annotCount - 1
        ' Check if the current annotation is of the ellipse type.
        If annotationManager.GetAnnotationType(i) Is GdPictureAnnotationType.AnnotationTypeEllipse Then
            ' Save the current annotation to an object.
            Dim annot As Annotation = annotationManager.GetAnnotationFromIdx(i)
            ' Change the `Author` property.
            annot.Author = "PSPDFKit"
        End If
    Next
End Using
Used Methods

Getting the Annotation XML Content

To get the annotation’s XML content, use the GetAnnotationXML method. It requires the annotation’s index number.

The following example gets the annotation’s XML content from the first page of a PDF document and creates new annotations on the rest of the pages based on the copied XML code:

using AnnotationManager annotationManager = new AnnotationManager();
// Load an image to the `AnnotationManager` object.
annotationManager.InitFromFile(@"C:\temp\source.pdf");
// Select the first PDF page.
annotationManager.SelectPage(1);
// Get the total number of XMP annotations.
int annotCount = annotationManager.GetAnnotationCount();
string annotXML = "";
for (int i = 0; i < annotCount; i++)
{
    // Check if the current annotation is of the ellipse type.
    if (annotationManager.GetAnnotationType(i) == GdPictureAnnotationType.AnnotationTypeEllipse)
    {
        // Get the XML content of the current annotation.
        annotXML = annotationManager.GetAnnotationXML(i);
        break;
    }
}
// Get the PDF page count.
int pageCount = annotationManager.PageCount;
// Loop through all PDF pages.
for (int p= 2; p <= pageCount; p++)
{
    // Select the next page.
    annotationManager.SelectPage(p);
    // Add the annotation from XML.
    annotationManager.AddAnnotationFromXML(annotXML);
    // Save the annotation to the current page.
    annotationManager.SaveAnnotationsToPage();
}
annotationManager.SaveDocumentToPDF(@"C:\temp\output.pdf");
Using annotationManager As AnnotationManager = New AnnotationManager()
    ' Load an image to the `AnnotationManager` object.
    annotationManager.InitFromFile("C:\temp\source.pdf")
    ' Select the first PDF page.
    annotationManager.SelectPage(1)
    ' Get the total amount of XMP annotations.
    Dim annotCount As Integer = annotationManager.GetAnnotationCount()
    Dim annotXML = ""
    For i = 0 To annotCount - 1
        ' Check if the current annotation is of the ellipse type.
        If annotationManager.GetAnnotationType(i) Is GdPictureAnnotationType.AnnotationTypeEllipse Then
            ' Get the XML content of the current annotation.
            annotXML = annotationManager.GetAnnotationXML(i)
            Exit For
        End If
    Next
    ' Get the PDF page count.
    Dim pageCount As Integer = annotationManager.PageCount
    ' Loop through all PDF pages.
    For p = 2 To pageCount
        ' Select the next page.
        annotationManager.SelectPage(p)
        ' Add the annotation from XML.
        annotationManager.AddAnnotationFromXML(annotXML)
        ' Save the annotation to the current page.
        annotationManager.SaveAnnotationsToPage()
    Next
    annotationManager.SaveDocumentToPDF("C:\temp\output.pdf")
End Using
Used Methods

Related Topics