Summary: Nested Classes | Constants | Ctors | Methods | Inherited Methods | [Expand All]
public class

# TextExtractor

extends Object
implements AutoCloseable

java.lang.Object
↳ | com.pdftron.pdf.TextExtractor

## Class Overview

`TextExtractor` is used to analyze a PDF page and extract words and logical structures that are visible within a given region. The resulting list of lines and words can be traversed element by element or accessed as a string buffer. The class also includes utility methods to extract PDF text as HTML or XML.

Possible use case scenarios for `TextExtractor` include:

- Converting PDF pages to text or XML for content repurposing.
- Searching PDF pages for specific words or keywords.
- Indexing large PDF repositories for indexing or content retrieval purposes (i.e. implementing a PDF search engine).
- Classifying or summarizing PDF documents based on their text content.
- Finding specific words for content editing purposes (such as splitting pages based on keywords etc).

The main task of `TextExtractor` is to interpret PDF pages and offer a simple to use API to:

- Normalize all text content to Unicode.
- Extract inferred logical structure (word by word, line by line, or paragraph by paragraph).
- Extract positioning information for every line, word, or a glyph.
- Extract style information (such as information about the font, font size, font styles, etc) for every line, word, or a glyph.
- Control the content analysis process. A number of options (such as removal of text obscured by images) is available to let the user direct the flow of content recognition algorithms that will meet their requirements.
- Offer utility methods to convert PDF page content to text, XML, or HTML.

Note: `TextExtractor` is analyzing only textual content of the page. This means that the rasterized (e.g. in scanned pages) or vectorized text (where glyphs are converted to path outlines) will not be recognized as text. Please note that it is still possible to extract this content using `ElementReader` interface.

In some cases `TextExtractor` may extract text that does not appear to be on the visible page (e.g. when text is obscured by an image or a rectangle). In these situations it is possible to use processing flags such as `'e_remove_hidden_text'` and `'e_no_invisible_text'` to remove hidden text.

A sample use case:

>      ... Initialize PDFNet ...
>      PDFDoc doc = new PDFDoc(filein);
>      doc.initSecurityHandler();
>      Page page = doc.pageBegin().current();
>      TextExtractor txt = new TextExtractor();
>      txt.begin(page, 0, TextExtractor.ProcessingFlags.e_remove_hidden_text);
>      string text = txt.getAsText();
>      // or traverse words one by one...
>      TextExtractor.Word word;
>      for (TextExtractor.Line line = txt.GetFirstLine(); line.IsValid(); line=line.GetNextLine()) {
>        for (word=line.GetFirstWord(); word.IsValid(); word=word.GetNextWord()) {
>          string w = word.GetString();

>      }
>      }

For full sample code, please take a look at TextExtract sample sample project.

## Summary

Nested Classes
class | TextExtractor.CharRange | TextExtractor.CharRange object represents a range of text based on Unicode character indices.
class | TextExtractor.Compat | Compatibility layer API.
class | TextExtractor.Line |
class | TextExtractor.Style | A class representing predominant text style associated with a given Line, a Word, or a Glyph.
class | TextExtractor.Word |

Constants
int | e_extract_using_zorder | Use Z-order as reading order for text
int | e_no_dup_remove | Disables removing duplicated text that is frequently used to achieve visual effects of drop shadow and fake bold.
int | e_no_invisible_text | Enables removing text that uses rendering mode 3 (i.e.
int | e_no_ligature_exp | Disables expanding of ligatures using a predefined mapping.
int | e_no_watermarks | Enables removal of text that is marked as part of a Watermark layer
int | e_output_bbox | Include bounding box information for each XML element.
int | e_output_style_info | Include font and styling information.
int | e_punct_break | Treat punctuation (e.g.
int | e_remove_hidden_text | Enables removal of text that is obscured by images or rectangles.
int | e_words_as_elements | Output words as XML elements instead of inline text.

Public Constructors
| TextExtractor() Constructor.

Public Methods
void | begin(Page page, Rect clip_ptr) Start reading the page.
void | begin(Page page, Rect clip_ptr, int flags) Start reading the page.
void | begin(Page page) Start reading the page.
void | close() Frees the native memory of the object.
void | destroy() Frees the native memory of the object.
String | getAsText() Get all words in the current selection as a single string.
String | getAsText(boolean dehyphen) Get all words in the current selection as a single string.
String | getAsXML() Get text content in a form of an XML string.
String | getAsXML(int xml_output_flags) Get text content in a form of an XML string.
TextExtractor.Line | getFirstLine() Get the first line.
Highlights | getHighlights(CharRange[] char_ranges) Get a Highlights object based on an array of character ranges.
int | getNumLines() Get the number lines.
boolean | getRightToLeftLanguage() Checkes if text extractor works in right-to-left language mode.
String | getTextUnderAnnot(Annot annot) Get all the characters that intersect an annotation.
int | getWordCount() Get the word count.
void | setOCGContext(Context ctx) Set the Optional Content Group (OCG) context that should be used when rendering the page.
void | setRightToLeftLanguage(boolean right_2_left) Sets text extractor to work in right-to-left language mode.

[Expand] Inherited Methods
From class java.lang.Object
boolean | equals(Object arg0)
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()
From interface java.lang.AutoCloseable
abstract void | close()

## Constants

#### public static final int e_extract_using_zorder

Use Z-order as reading order for text

Constant Value: 256 (0x00000100)

#### public static final int e_no_dup_remove

Disables removing duplicated text that is frequently used to achieve visual effects of drop shadow and fake bold.

Constant Value: 2 (0x00000002)

#### public static final int e_no_invisible_text

Enables removing text that uses rendering mode 3 (i.e. invisible text). Invisible text is usually used in 'PDF Searchable Images' (i.e. scanned pages with a corresponding OCR text). As a result, invisible text will be extracted by default.

Constant Value: 16 (0x00000010)

#### public static final int e_no_ligature_exp

Disables expanding of ligatures using a predefined mapping. Default ligatures are: fi, ff, fl, ffi, ffl, ch, cl, ct, ll, ss, fs, st, oe, OE.

Constant Value: 1 (0x00000001)

#### public static final int e_no_watermarks

Enables removal of text that is marked as part of a Watermark layer

Constant Value: 128 (0x00000080)

#### public static final int e_output_bbox

Include bounding box information for each XML element. The bounding box information will be stored as 'bbox' attribute.

Constant Value: 2 (0x00000002)

#### public static final int e_output_style_info

Include font and styling information.

Constant Value: 4 (0x00000004)

#### public static final int e_punct_break

Treat punctuation (e.g. full stop, comma, semicolon, etc.) as word break characters.

Constant Value: 4 (0x00000004)

#### public static final int e_remove_hidden_text

Enables removal of text that is obscured by images or rectangles. Since this option has small performance penalty on performance of text extraction, by default it is not enabled.

Constant Value: 8 (0x00000008)

#### public static final int e_words_as_elements

Output words as XML elements instead of inline text.

Constant Value: 1 (0x00000001)

## Public Constructors

#### public TextExtractor ()

Constructor. Instantiate new TextExtractor.

## Public Methods

#### public void begin (Page page, Rect clip_ptr)

Start reading the page.

##### Parameters

page | Page to read.
clip_ptr | A pointer to the optional clipping rectangle. This parameter can be used to selectively read text from a given rectangle.

#### public void begin (Page page, Rect clip_ptr, int flags)

Start reading the page.

##### Parameters

page | Page to read.
clip_ptr | A pointer to the optional clipping rectangle. This parameter can be used to selectively read text from a given rectangle.
flags | A list of ProcessingFlags used to control text extraction algorithm.

#### public void begin (Page page)

Start reading the page.

##### Parameters

page | Page to read.

#### public void close ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

#### public void destroy ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

#### public String getAsText ()

Get all words in the current selection as a single string.

##### Returns

- The string containing all words in the current selection. Words will be separated with space (i.e. ' ') or new line (i.e. '\n') characters.

#### public String getAsText (boolean dehyphen)

Get all words in the current selection as a single string.

##### Parameters

dehyphen | If true, finds and removes hyphens that split words across two lines. Hyphens are often used a the end of lines as an indicator that a word spans two lines. Hyphen detection enables removal of hyphen character and merging of text runs to form a single word. This option has no effect on Tagged PDF files.

##### Returns

- The string containing all words in the current selection. Words will be separated with space (i.e. ' ') or new line (i.e. '\n') characters.

#### public String getAsXML ()

Get text content in a form of an XML string.

Note: This method returns the same as if calling `getAsXML(0)`. Please see `getAsXML(int)` for more information.

##### Returns

- The string containing XML output.

#### public String getAsXML (int xml_output_flags)

Get text content in a form of an XML string.

Note: XML output will be encoded in UTF-8 and will have the following structure:

     <Page num="1 crop_box="0, 0, 612, 792" media_box="0, 0, 612, 792" rotate="0">
      <Flow id="1">
       <Para id="1">
        <Line box="72, 708.075, 467.895, 10.02" style="font-family:Calibri; font-size:10.02; color: #000000;">
         <Word box="72, 708.075, 30.7614, 10.02">PDFNet</Word>
         <Word box="106.188, 708.075, 15.9318, 10.02">SDK</Word>
         <Word box="125.617, 708.075, 6.22242, 10.02">is</Word>
          ...
        </Line>
       </Para>
      </Flow>
     </Page>

The above XML output was generated by passing the following union of flags: `e_words_as_elements | e_output_bbox | e_output_style_info`.

In case `'xml_output_flags'` was not specified, the default XML output would look as follows:

     <Page num="1 crop_box="0, 0, 612, 792" media_box="0, 0, 612, 792" rotate="0">
      <Flow id="1">
       <Para id="1">
        <Line>PDFNet SDK is an amazingly comprehensive, high-quality PDF developer toolkit...</Line>
        <Line>levels. Using the PDFNet PDF library, ...</Line>
         ...
       </Para>
      </Flow>
     </Page>

##### Parameters

xml_output_flags | flags controlling XML output.

#### public TextExtractor.Line getFirstLine ()

Get the first line.

Note: To traverse the list of all text lines on the page use `getNextLine()`. To traverse the list of all word on a given line use `getFirstWord()`.

##### Returns

- The first line of text on the selected page.

#### public Highlights getHighlights (CharRange[] char_ranges)

Get a Highlights object based on an array of character ranges.

##### Parameters

char_ranges | an array of character ranges to be highlighted

##### Returns

- a Highlights object containing the selected characters

#### public int getNumLines ()

Get the number lines.

##### Returns

- The number of lines of text on the selected page.

#### public boolean getRightToLeftLanguage ()

Checkes if text extractor works in right-to-left language mode.

#### public String getTextUnderAnnot (Annot annot)

Get all the characters that intersect an annotation.

##### Parameters

annot | The annotation to intersect with.

#### public int getWordCount ()

Get the word count.

##### Returns

- the number of words on the page.

#### public void setOCGContext (Context ctx)

Set the Optional Content Group (OCG) context that should be used when rendering the page. This function can be used to selectively render optional content (such as PDF layers) based on the states of optional content groups in the given context.

##### Parameters

ctx | Optional Content Group (OCG) context, or NULL if TextExtractor should process all content on the page.

#### public void setRightToLeftLanguage (boolean right_2_left)

Sets text extractor to work in right-to-left language mode.

##### Parameters

right_2_left | If `true`, text extractor is set to right-to-left language mode.