Issues with flattening free text annotations

We have found a couple of issues with flattening free text annotations. We have a process that takes in uploaded PDF documents that can include annotations. We do some processing and when we are done, we need to flatten all annotations. We are having some issues with text annotations.

First, we get documents with free text annotations where the Default Appearance is set as an encoded string, but that have no appearance dictionary. These annotations render correctly in Adobe Reader. When we flatten these annotations, it seems that Aspose uses the TextStyle property which gets initialized with some default values (Helvetica, 12pt). This causes the annotation to appear to change from the source. We’re working around this by manually setting the TextStyle to be the DefaultAppearance (see code below) but I have no idea if that’s a good long-term workaround. It also produced another error that I’ll detail below. I’ve attached an example PDF (annotation with no appearance dictionary.pdf)

        if (annotation is FreeTextAnnotation)
          var fta = annotation as FreeTextAnnotation;
          if (!String.IsNullOrEmpty(fta.Contents))
            fta.TextStyle.FontSize = fta.DefaultAppearanceObject.FontSize;
            fta.TextStyle.FontName = fta.DefaultAppearanceObject.FontName;
            fta.TextStyle.Color = fta.DefaultAppearanceObject.TextColor;

Second, we sometimes get an IndexOutOfRangeException when setting TextStyle.FontSize on an annotation. This appears to have to do with a text annotation with a 0 area bounding rectangle and empty contents. I have attached a sample PDF (no length annotation.pdf) with this type of annotation. This may not be a valid annotation, but we have little control over the state of the incoming documents to our application and Adobe Reader is able to render it. We are filtering out these text annotations for now.

I think I messed up one of the attachments in my first post. This is the right file to demonstrate the first issue with: annotation with no appearance dictionary.pdf (28.3 KB)

It also demonstrates another issue we’ve noticed. When Aspose flattens the text annotation, it seems to be applying a margin that does not appear in the source document. Here’s an example of the final flattened document, with the fix I detailed with manually setting the TextStyle: flattened annotation moves.pdf (58.3 KB)

If I create a text annotation with the same bounding box and characteristics in Aspose, it has the same margin.
I think this is the case of Aspose assuming/initializing a value with some defaults even when it is not present in the source annotation. Is there a way for me to set/reset this margin value manually before I flatten it? The TextStyle margin property was the only thing I could find, and it had 0’s for every margin setting.


Thanks for contacting support.

We were able to replicate both issues in our environment and logged them in our issue tracking system as following:

PDFNET-45984 - Content Size of Free Text Annotation is changing after flattening it
PDFNET-45985 - Margin Value of Free Text Annotation is changing after flattening it

We will definitely look into details of these issues and keep you posted with the status of their correction. Please be patient and spare us little time.

We were unable to notice above issue in our environment and checked the PDF file also where we were not able to find any annotation. Would you please share a screenshot showing the annotation location over PDF Page. We will again test the scenario in our environment and address it accordingly.

We are sorry for the inconvenience.

The annotation is not noticeable visually in the PDF file, but it is in the file’s metadata. If you open it in Aspose, you will see an annotation in the first page’s annotion collection.

When I run the following code against it using Aspose 19.1, I get a System.ArgumentOutOfRangeException. You do not get the same?

static void Main(string[] args)
  using (var licenseFile = File.Open(LicensePath, FileMode.Open))
    var license = new License();

  const string FilePath = @"..\..\docs\no length annotation.pdf";
  string flattenedFilePath = Path.Combine(Path.GetDirectoryName(Path.GetFullPath(FilePath)), "results", $"{Path.GetFileNameWithoutExtension(FilePath)}-flattened.pdf");

  using (var doc = new Document(FilePath))



This is the exception I get:

System.ArgumentOutOfRangeException: ‘Index was out of range. Must be non-negative and less than the size of the collection.
Parameter name: index’


Thanks for providing these details.

We have tested the scenario in our environment and were able to notice the similar issue as you mentioned. Please note that the Document.Flatten() method is used to remove form fields from PDF document and place their values at their place instead. In case you want to flatten the annotations, you can flatten them using Annotation.Flatten() method.

Document doc = new Document(dataDir + "no length annotation.pdf");
foreach(Page page in doc.Pages)
 foreach(Annotation annot in page.Annotations)
  if(annot is FreeTextAnnotation)

Above code snippet executed fine in our environment and produced no error. You may try this code in your environment and in case you still face any issue or have any other concerns, please let us know.

The issues you have found earlier (filed as PDFNET-45989) have been fixed in Aspose.PDF for .NET 22.11.