Top Description Fields Constructors Methods
org.apache.pdfbox.text

public final Class TextPosition

extends Object
Class Inheritance
Imports
java.text.Normalizer, java.util.Arrays, .HashMap, .Map, .Objects, org.apache.commons.logging.Log, .LogFactory, org.apache.pdfbox.pdmodel.font.PDFont, org.apache.pdfbox.util.Matrix

This represents a string and a position on the screen of those characters.
Author
Ben Litchfield

Field Summary

Modifier and TypeField and Description
private final int[]
private static final Map<Integer, String>
private float
private final float
private final float
private final PDFont
private final float
private final int
private static final Log
private final float
private final float
private final float
private final int
private final Matrix
private String
private final float
private float[]
private final float
x

private final float
y

Constructor Summary

AccessConstructor and Description
public
TextPosition(int
rotation of the page that the text is located in
pageRotation
,
float
width of the page that the text is located in
pageWidth
,
float
height of the page that the text is located in
pageHeight
,
Matrix
text rendering matrix for start of text (in display units)
textMatrix
,
float
x coordinate of the end position
endX
,
float
y coordinate of the end position
endY
,
float
Maximum height of text (in display units)
maxHeight
,
float
The width of the given character/string. (in text units)
individualWidth
,
float
The width of the space character. (in display units)
spaceWidth
,
String
The string of Unicode characters to be displayed.
unicode
,
int[]
An array of the internal PDF character codes for the glyphs in this text.
charCodes
,
PDFont
The current font for this text position.
font
,
float
The new font size.
fontSize
,
int
The font size in pt units (see getFontSizeInPt() for details).
fontSizeInPt
)

Constructor.

Method Summary

Modifier and TypeMethod and Description
private String

Returns:

Normalized string
combineDiacritic
(String
String to normalize
str
)

Combine the diacritic, for example, convert non-combining diacritic characters to their combining counterparts.

public boolean

Returns:

True if tp2 is contained completely inside the bounding box of this text.
completelyContains
(TextPosition
The other TestPosition to compare against
tp2
)

Determine if this TextPosition perfectly contains another (i.e. the other TextPosition overlaps 100% with this one and fits entirely inside its bounding box when they are rendered on top of each other).

public boolean

Returns:

True if tp2 is contained in the bounding box of this text.
contains
(TextPosition
The other TestPosition to compare against
tp2
)

Determine if this TextPosition logically contains another (i.e. they overlap and should be rendered on top of each other).

private static Map<Integer, String>
public boolean
equals(Object
the reference object with which to compare.
o
)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public int[]

Returns:

an array of internal PDF character codes
getCharacterCodes
()

Return the internal PDF character codes of the glyphs in this text.

public float

Returns:

The direction of the text (0, 90, 180, or 270).
getDir
()

Return the direction/orientation of the string in this object based on its text matrix.

public float

Returns:

The unadjusted x coordinate of the end position
getEndX
()

This will get the x coordinate of the end position.

public float

Returns:

The unadjusted y coordinate of the end position
getEndY
()

This will get the y coordinate of the end position.

public PDFont

Returns:

The font size.
getFont
()

This will get the font for the text being drawn.

public float

Returns:

The font size.
getFontSize
()

This will get the font size that has been set with the "Tf" operator (Set text font and size).

public float

Returns:

The font size in pt.
getFontSizeInPt
()

This will get the font size in pt.

public float

Returns:

The maximum height of all characters in this string.
getHeight
()

This will get the maximum height of all characters in this string.

public float

Returns:

The maximum height of all characters in this string.
getHeightDir
()

This will get the maximum height of all characters in this string.

public float[]

Returns:

An array that has the same length as the CharacterCodes array.
getIndividualWidths
()

Get the widths of each individual character.

public float

Returns:

The unadjusted height of the page that the text is located in
getPageHeight
()

This will get the height of the page that the text is located in. This is the unadjusted value passed into the constructor.

public float

Returns:

The unadjusted width of the page that the text is located in
getPageWidth
()

This will get the width of the page that the text is located in. This is the unadjusted value passed into the constructor.

public int

Returns:

The unadjusted rotation of the page that the text is located in
getRotation
()

This will get the rotation of the page that the text is located in. This is the unadjusted value passed into the constructor.

public Matrix

Returns:

The Matrix containing the starting text position
getTextMatrix
()

The matrix containing the starting text position and scaling.

public String

Returns:

The string on the screen.
getUnicode
()

Return the string of characters stored in this object.

public String

Returns:

The string on the screen in visual order.
getVisuallyOrderedUnicode
()

Same as getUnicode() except that returned text is ensured to be visually ordered (i.e. same order you would see them displayed on screen when looking from left to right).

public float

Returns:

The width of the text in display units.
getWidth
()

This will get the width of the string when page rotation adjusted coordinates are used.

public float

Returns:

The width of the text in display units.
getWidthDirAdj
()

This will get the width of the string when text direction adjusted coordinates are used.

public float

Returns:

The width of a space character.
getWidthOfSpace
()

This will get the width of a space character.

private float

Returns:

Width of text in display units
getWidthRot
(float
Rotation that was used to determine coordinates (0,90,180,270)
rotation
)

Get the length or width of the text, based on a given rotation.

public float

Returns:

The x coordinate of the character.
getX
()

This will get the page rotation adjusted x position of the character.

public float

Returns:

The x coordinate of the text.
getXDirAdj
()

This will get the text direction adjusted x position of the character.

private float

Returns:

X coordinate
getXRot
(float
Rotation to apply (0, 90, 180, or 270). 0 will perform no adjustments.
rotation
)

Return the X starting coordinate of the text, adjusted by the given rotation amount.

public float

Returns:

The X scaling factor.
getXScale
()

This will get the X scaling factor.

public float

Returns:

The adjusted y coordinate of the character.
getY
()

This will get the page rotation adjusted x position of the character.

public float

Returns:

The adjusted y coordinate of the character.
getYDirAdj
()

This will get the y position of the text, adjusted so that 0,0 is upper left and it is adjusted based on the text direction.

private float

Returns:

The y coordinate of the text
getYLowerLeftRot
(float
Rotation to apply to text to adjust the 0,0 location (0,90,180,270)
rotation
)

This will get the y position of the character with 0,0 in lower left.

public float

Returns:

The Y scaling factor.
getYScale
()

This will get the Y scaling factor.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

private void
insertDiacritic(int
current character
i
,
TextPosition
The diacritic TextPosition
diacritic
)

Inserts the diacritic TextPosition to the str of this TextPosition and updates the widths array to include the extra character width.

public boolean

Returns:

True if the current character is a diacritic char.
isDiacritic
()

public void
mergeDiacritic(TextPosition
TextPosition to merge into the current TextPosition.
diacritic
)

Merge a single character TextPosition into the current object.

pack-priv void
setUnicode(String unicode)

public String

Returns:

A human readable form of this object.
toString
()

Overrides java.lang.Object.toString.

Show the string data for this text position.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

charCodesback to summary
private final int[] charCodes
DIACRITICSback to summary
private static final Map<Integer, String> DIACRITICS
directionback to summary
private float direction
endXback to summary
private final float endX
endYback to summary
private final float endY
fontback to summary
private final PDFont font
fontSizeback to summary
private final float fontSize
fontSizePtback to summary
private final int fontSizePt
LOGback to summary
private static final Log LOG
maxHeightback to summary
private final float maxHeight
pageHeightback to summary
private final float pageHeight
pageWidthback to summary
private final float pageWidth
rotationback to summary
private final int rotation
textMatrixback to summary
private final Matrix textMatrix
unicodeback to summary
private String unicode
widthOfSpaceback to summary
private final float widthOfSpace
widthsback to summary
private float[] widths
xback to summary
private final float x
yback to summary
private final float y

Constructor Detail

TextPositionback to summary
public TextPosition(int pageRotation, float pageWidth, float pageHeight, Matrix textMatrix, float endX, float endY, float maxHeight, float individualWidth, float spaceWidth, String unicode, int[] charCodes, PDFont font, float fontSize, int fontSizeInPt)

Constructor.

Parameters
pageRotation:int

rotation of the page that the text is located in

pageWidth:float

width of the page that the text is located in

pageHeight:float

height of the page that the text is located in

textMatrix:Matrix

text rendering matrix for start of text (in display units)

endX:float

x coordinate of the end position

endY:float

y coordinate of the end position

maxHeight:float

Maximum height of text (in display units)

individualWidth:float

The width of the given character/string. (in text units)

spaceWidth:float

The width of the space character. (in display units)

unicode:String

The string of Unicode characters to be displayed.

charCodes:int[]

An array of the internal PDF character codes for the glyphs in this text.

font:PDFont

The current font for this text position.

fontSize:float

The new font size.

fontSizeInPt:int

The font size in pt units (see getFontSizeInPt() for details).

Method Detail

combineDiacriticback to summary
private String combineDiacritic(String str)

Combine the diacritic, for example, convert non-combining diacritic characters to their combining counterparts.

Parameters
str:String

String to normalize

Returns:String

Normalized string

completelyContainsback to summary
public boolean completelyContains(TextPosition tp2)

Determine if this TextPosition perfectly contains another (i.e. the other TextPosition overlaps 100% with this one and fits entirely inside its bounding box when they are rendered on top of each other).

Parameters
tp2:TextPosition

The other TestPosition to compare against

Returns:boolean

True if tp2 is contained completely inside the bounding box of this text.

containsback to summary
public boolean contains(TextPosition tp2)

Determine if this TextPosition logically contains another (i.e. they overlap and should be rendered on top of each other).

Parameters
tp2:TextPosition

The other TestPosition to compare against

Returns:boolean

True if tp2 is contained in the bounding box of this text.

createDiacriticsback to summary
private static Map<Integer, String> createDiacritics()
equalsback to summary
public boolean equals(Object o)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
o:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getCharacterCodesback to summary
public int[] getCharacterCodes()

Return the internal PDF character codes of the glyphs in this text.

Returns:int[]

an array of internal PDF character codes

getDirback to summary
public float getDir()

Return the direction/orientation of the string in this object based on its text matrix. Only angles of 0, 90, 180, or 270 are supported. To get other angles, use this code:

TextPosition text = ...
Matrix m = text.getTextMatrix().clone();
m.concatenate(text.getFont().getFontMatrix());
int angle = (int) Math.round(Math.toDegrees(Math.atan2(m.getShearY(), m.getScaleY())));
Returns:float

The direction of the text (0, 90, 180, or 270).

getEndXback to summary
public float getEndX()

This will get the x coordinate of the end position. This is the unadjusted value passed into the constructor.

Returns:float

The unadjusted x coordinate of the end position

getEndYback to summary
public float getEndY()

This will get the y coordinate of the end position. This is the unadjusted value passed into the constructor.

Returns:float

The unadjusted y coordinate of the end position

getFontback to summary
public PDFont getFont()

This will get the font for the text being drawn.

Returns:PDFont

The font size.

getFontSizeback to summary
public float getFontSize()

This will get the font size that has been set with the "Tf" operator (Set text font and size). When the text is rendered, it may appear bigger or smaller depending on the current transformation matrix (set by the "cm" operator) and the text matrix (set by the "Tm" operator).

Returns:float

The font size.

getFontSizeInPtback to summary
public float getFontSizeInPt()

This will get the font size in pt. To get this size we have to multiply the font size from getFontSize() with the text matrix (set by the "Tm" operator) horizontal scaling factor and truncate the result to integer. The actual rendering may appear bigger or smaller depending on the current transformation matrix (set by the "cm" operator). To get the size in rendering, use getXScale().

Returns:float

The font size in pt.

getHeightback to summary
public float getHeight()

This will get the maximum height of all characters in this string.

Returns:float

The maximum height of all characters in this string.

getHeightDirback to summary
public float getHeightDir()

This will get the maximum height of all characters in this string.

Returns:float

The maximum height of all characters in this string.

getIndividualWidthsback to summary
public float[] getIndividualWidths()

Get the widths of each individual character.

Returns:float[]

An array that has the same length as the CharacterCodes array.

getPageHeightback to summary
public float getPageHeight()

This will get the height of the page that the text is located in. This is the unadjusted value passed into the constructor.

Returns:float

The unadjusted height of the page that the text is located in

getPageWidthback to summary
public float getPageWidth()

This will get the width of the page that the text is located in. This is the unadjusted value passed into the constructor.

Returns:float

The unadjusted width of the page that the text is located in

getRotationback to summary
public int getRotation()

This will get the rotation of the page that the text is located in. This is the unadjusted value passed into the constructor.

Returns:int

The unadjusted rotation of the page that the text is located in

getTextMatrixback to summary
public Matrix getTextMatrix()

The matrix containing the starting text position and scaling. Despite the name, it is not the text matrix set by the "Tm" operator, it is really the effective text rendering matrix (which is dependent on the current transformation matrix (set by the "cm" operator), the text matrix (set by the "Tm" operator), the font size (set by the "Tf" operator) and the page cropbox).

Returns:Matrix

The Matrix containing the starting text position

getUnicodeback to summary
public String getUnicode()

Return the string of characters stored in this object. The length can be different than the CharacterCodes length e.g. if ligatures are used ("fi", "fl", "ffl") where one glyph represents several unicode characters.

Returns:String

The string on the screen.

getVisuallyOrderedUnicodeback to summary
public String getVisuallyOrderedUnicode()

Same as getUnicode() except that returned text is ensured to be visually ordered (i.e. same order you would see them displayed on screen when looking from left to right). This is important for Arabic/Hebrew where several unicode characters can be composed in one glyph with logical order (the order in which it would be normally typed from right to left).

Returns:String

The string on the screen in visual order.

getWidthback to summary
public float getWidth()

This will get the width of the string when page rotation adjusted coordinates are used.

Returns:float

The width of the text in display units.

getWidthDirAdjback to summary
public float getWidthDirAdj()

This will get the width of the string when text direction adjusted coordinates are used.

Returns:float

The width of the text in display units.

getWidthOfSpaceback to summary
public float getWidthOfSpace()

This will get the width of a space character. This is useful for some algorithms such as the text stripper, that need to know the width of a space character.

Returns:float

The width of a space character.

getWidthRotback to summary
private float getWidthRot(float rotation)

Get the length or width of the text, based on a given rotation.

Parameters
rotation:float

Rotation that was used to determine coordinates (0,90,180,270)

Returns:float

Width of text in display units

getXback to summary
public float getX()

This will get the page rotation adjusted x position of the character. This is adjusted based on page rotation so that the upper left is 0,0 which is unlike PDF coordinates, which start at the bottom left. See also this answer by Michael Klink for further details and PDFBOX-4597 for a sample file.

Returns:float

The x coordinate of the character.

getXDirAdjback to summary
public float getXDirAdj()

This will get the text direction adjusted x position of the character. This is adjusted based on text direction so that the first character in that direction is in the upper left at 0,0. This method ignores the page rotation but takes the text rotation (see getDir()) and adjusts the coordinates to awt. This is useful when doing text extraction, to compare the glyph positions when imagining these to be horizontal. See also this answer by Michael Klink for further details and PDFBOX-4597 for a sample file.

Returns:float

The x coordinate of the text.

getXRotback to summary
private float getXRot(float rotation)

Return the X starting coordinate of the text, adjusted by the given rotation amount. The rotation adjusts where the 0,0 location is relative to the text.

Parameters
rotation:float

Rotation to apply (0, 90, 180, or 270). 0 will perform no adjustments.

Returns:float

X coordinate

getXScaleback to summary
public float getXScale()

This will get the X scaling factor. This is dependent on the current transformation matrix (set by the "cm" operator), the text matrix (set by the "Tm" operator) and the font size (set by the "Tf" operator).

Returns:float

The X scaling factor.

getYback to summary
public float getY()

This will get the page rotation adjusted x position of the character. This is adjusted based on page rotation so that the upper left is 0,0 which is unlike PDF coordinates, which start at the bottom left. See also this answer by Michael Klink for further details and PDFBOX-4597 for a sample file.

Returns:float

The adjusted y coordinate of the character.

getYDirAdjback to summary
public float getYDirAdj()

This will get the y position of the text, adjusted so that 0,0 is upper left and it is adjusted based on the text direction. This method ignores the page rotation but takes the text rotation and adjusts the coordinates to awt. This is useful when doing text extraction, to compare the glyph positions when imagining these to be horizontal. See also this answer by Michael Klink for further details and PDFBOX-4597 for a sample file.

Returns:float

The adjusted y coordinate of the character.

getYLowerLeftRotback to summary
private float getYLowerLeftRot(float rotation)

This will get the y position of the character with 0,0 in lower left. This will be adjusted by the given rotation.

Parameters
rotation:float

Rotation to apply to text to adjust the 0,0 location (0,90,180,270)

Returns:float

The y coordinate of the text

getYScaleback to summary
public float getYScale()

This will get the Y scaling factor. This is dependent on the current transformation matrix (set by the "cm" operator), the text matrix (set by the "Tm" operator) and the font size (set by the "Tf" operator).

Returns:float

The Y scaling factor.

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
insertDiacriticback to summary
private void insertDiacritic(int i, TextPosition diacritic)

Inserts the diacritic TextPosition to the str of this TextPosition and updates the widths array to include the extra character width.

Parameters
i:int

current character

diacritic:TextPosition

The diacritic TextPosition

isDiacriticback to summary
public boolean isDiacritic()
Returns:boolean

True if the current character is a diacritic char.

mergeDiacriticback to summary
public void mergeDiacritic(TextPosition diacritic)

Merge a single character TextPosition into the current object. This is to be used only for cases where we have a diacritic that overlaps an existing TextPosition. In a graphical display, we could overlay them, but for text extraction we need to merge them. Use the contains() method to test if two objects overlap.

Parameters
diacritic:TextPosition

TextPosition to merge into the current TextPosition.

setUnicodeback to summary
pack-priv void setUnicode(String unicode)
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Show the string data for this text position.

Returns:String

A human readable form of this object.

Annotations
@Override