Getting Annotation Information
In this chapter….
you will learn how to…
- Retrieve a simple list of annotations (-annot option) — Reports a list of all annotations in the PDF
- Display the color of each annotation (-color option) — Retrieve the RGB color value for each annotation
- Add popup details to the annotation list (-popup option) — Include popup information of annotations
- Display the size and location of each annotation (-rect option) — Reports the location of each annotation
- Add link details to the annotation list (-link option) — Description of each link in the document
- Get more that one type of annotation information at one time (multiple options) — Examples of running multiple options at one time
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.
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.
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:
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.
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.
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.
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).
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.
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.)
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.
