Getting Annotation Information

In this chapter….

you will learn how to…

Annotations include notes, text, audio, stamps, form fields (widgets), files, pencil marks, rectangles, ellipses, lines, highlights, cross outs (strikethroughs), and underlines. The figure below shows the annotation information on the first page of the sample ApUtilsSample.pdf file supplied with APGetInfo.

Annotations found on page 1 of Sample file

Retrieving a Simple List of Annotations

Use the -annot option to retrieve a simple list of annotations from the document. The annotation list includes the following information:

  • A detailed description of each annotation in the document, including the annotation type, title, creation date, and contents
  • A summary showing the total number of annotations and the number of annotations by type

Command

$apgetinfo -annot inPDFFile

Windows Example

$apgetinfo -annot C:\Appligent\APGetInfo\samples\ApUtilsSample.pdf

UNIX/Macintosh Example

$./apgetinfo -annot /Appligent/APGetInfo/samples/ApUtilsSample.pdf

Result

The figure below shows the results of running apgetinfo with the -annot option on the ApUtilsSample.pdf file. The first section of the listing describes each annotation in detail: one text, one highlight, one ink, one attachment, and eight widgets (form fields). Following the detailed descriptions is a summary of all the annotations in the document. The summary indicates that the document contains 17 annotations, but only 13 of these are included in the detailed descriptions.

Note: The annotation popups and link are not included in the detailed descriptions. For more information, see Adding Popup Details to the Annotation List and Adding Link Details to the Annotation List.

Results from -annot

Displaying the Color of Each Annotation

Use the -color option with the -annot option to retrieve the RGB color value of each annotation in the document.

The color of each annotation is displayed as an RGB value. Each RGB value is composed of a red, green, and blue component:

RGB Color

The value of each component indicates how much of that component is included in the annotation color:

  • 1.000000 indicates that 100% of that component is included in the annotation color.
  • 0.000000 indicates that none of that component is included in the annotation color.
  • A value in between indicates that some of that component is included in the annotation color. The following are some examples of RGB values and the colors they represent:
RGB Value Color Composed of
0.000000 0.000000 0.000000 Black No red, no green, and no blue
1.000000 1.000000 1.000000 White 100% red, 100% green, and 100% blue
1.000000 0.000000 0.000000 Red 100% red, no green, and no blue
0.000000 1.000000 0.000000 Green No red, 100% green, and no blue
0.312850 0.611980 0.067990 Light Green 31.285% red, 61.198% green, and 6.799% blue

Command

$apgetinfo -annot -color inPDFFile

Windows Example

$apgetinfo -annot -color C:\Appligent\APGetInfo\samples\ApUtilsSample.pdf

UNIX/Macintosh Example

$./apgetinfo -annot -color /Appligent/APGetInfo/samples/ApUtilsSample.pdf

Result

The figure below shows the results of running apgetinfo on the ApUtilsSample.pdf file when using the -color option with the -annot option. Only the first page results are shown.

Results from -color

Adding Popup Details to the Annotation List

The figure below shows the popups associated with the annotations on the first page of the ApUtilsSample.pdf file. When you use the -annot option by itself, APGetInfo lists the total number of annotation popups, but does not include any detailed information about them. To obtain a description of each annotation popup in the document, use the -popup option with the -annot option.

Annotation popups on first page of ApUtilsSample.pdf file

Command

$apgetinfo -annot -popup inPDFFile

Windows Example

$apgetinfo -annot -popup C:\Appligent\APGetInfo\samples\ApUtilsSample.pdf

UNIX/Macintosh Example

$./apgetinfo -annot -popup /Appligent/APGetInfo/samples/ApUtilsSample.pdf

Result

The figure below shows the results of running apgetinfo on the ApUtilsSample.pdf file when using the -popup option with the -annot option. Only the first page results are shown. (Only the first page of the document contains popups.) Note that the popup is listed directly after the annotation it is associated with, but any popup text (content) is listed with the annotation, not the popup.

Results from -popup

Displaying the Size and Location of Each Annotation

Use the -rect option with the -annot option to display the size and location of each annotation in the document.

Command

$apgetinfo -annot -rect inPDFFile

Windows Example

$apgetinfo -annot -rect C:\Appligent\APGetInfo\samples\ApUtilsSample.pdf

UNIX/Macintosh Example

$./apgetinfo -annot -rect/Appligent/APGetInfo/samples/ApUtilsSample.pdf

Result

The figure below shows the results of running apgetinfo on the ApUtilsSample.pdf file when using the -rect option with the -annot option. Only the first page results are shown.

For each annotation, four coordinates define the size of the annotation rectangle and its position on the cropped page, in points. (The cropped page, also called the CropBox, is the printable page area. It is the full page size minus any cropping, or margins.) The left and right coordinates are measured from the left of the cropped page. The bottom and top coordinates are measured from the bottom of the cropped page. For example, the rectangle for the Text annotation in the figure below is 18 points wide (from 460.138 to 478.138 points from the left of the cropped page) and 22 points high (from 202.254 to 224.254 points from the bottom of the cropped page).

Results from -rect

Adding Link Details to the Annotation List

Links are commonly found within documents for jumping to another page or section of the document, opening a file, or opening a web page. You can also use links to initiate actions, such as playing a sound or movie file, or to submit forms. The figure below shows the only link in the ApUtilsSample.pdf file.

Link on first page of ApUtilsSample.pdf file

When you use the -annot option by itself, APGetInfo displays the total number of link annotations, but does not include any detailed information about those links. To obtain a description of each link in the document, use the -link option with the -annot option.

Command

$apgetinfo -annot -link inPDFFile

Windows Example

$apgetinfo -annot -link C:\Appligent\APGetInfo\samples\ApUtilsSample.pdf

UNIX/Macintosh Example

$./apgetinfo -annot -link /Appligent/APGetInfo/samples/ApUtilsSample.pdf

Result

The figure below shows the results of running apgetinfo on the ApUtilsSample.pdf file when using the -link option with the -annot option. Only the first page results are shown. (The only link in the document is on the first page.)

Results from -link

Getting Multiple Types of Annotation Information

You can use two or more options in combination to list multiple types of annotation information.

Command

$apgetinfo [annotation options] inPDFFile

Windows Example

$apgetinfo -annot -link -color C:\Appligent\APGetInfo\samples\ApUtilsSample.pdf

UNIX/Macintosh Example

$./apgetinfo -annot -link -color /Appligent/APGetInfo/samples/ApUtilsSample.pdf

Result

The figure below shows the results of running apgetinfo with the -annot-link, and -color options on the ApUtilsSample.pdf file. Only the first page results are shown. The -link option causes the link information to be displayed. The -color option causes the RGB value of the annotations and the link to be displayed.

results from -color -link