A shape object represents a single element in the PDF document.
There are three fundamental types of shapes:
- Text: Represents textual content within a document. In most PDF documents, paragraphs are composed of multiple text shapes, each representing anything from individual characters to partial word fragments, or entire lines of text.
- Image: Represents raster or bitmap graphics embedded in the document
- Path: Represents vector graphics, such as lines, curves, and geometric shapes
A shape object has the following properties. Some properties are only applicable to specific shape types, as described in the following sections.
type (string)
Represents one of the three base types that a shape can have: text, image and path.
Examples:
shape.type = "text" shape.type = "image" shape.type = "path"
page (page object)
The page property returns a page object as described in the article page object.
font (font)
The font property returns a font object of a text shape as described in the article font object.
text (string)
Represents the text value of a text shape.
Note that a word or a line in a PDF document often consists of many individual shapes. In such cases, the text property does not evaluate the text of the entire word or line, but always refers to a single shape object.
Example:
shape.text = "hello"
left, right, top, bottom (double)
These four properties return the coordinates of a shape relative to the entire document, in points.
The coordinate origin in a PDF document is located at the bottom-left corner. Document coordinates extend from the bottom-left corner of the last page to the top-right corner of the first page.
Examples:
shape.left = 20.0 // Note: equivalent to shape.docBBox.left = 20.0 shape.right = 200.0 // Note: equivalent to shape.docBBox.right = 200.0 shape.top = 500.0 // Note: equivalent to shape.docBBox.top = 500.0 shape.bottom = 30.0 // Note: equivalent to shape.docBBox.bottom = 30.0
width, height (double)
These two properties return the width and the height of a shape in points.
Examples:
shape.width = 200.0 shape.height = 34.0
lineWidth (double)
Returns the line width of a path shape in points.
Example:
shape.lineWidth = 0.5
fill, stroke (color)
These two properties return the fill and the stroke color of a text or path shape.
Examples:
shape.fill = #0000FF shape.stroke = #000000
pageBBox (rectangle)
Returns the bounding box coordinates of a shape object as a rectangle, relative to its page.
Page coordinates are measured in points and extend from the bottom-left corner to the top-right corner of the page.
A single shape object always belongs to one page and therefore has exactly one pageBBox.
Example: Selects shapes on every page of the document that match the specified coordinates exactly:
shape.pageBBox = Rectangle(60.0, 590.0, 400.0, 700.0)
left, right, top, bottom (double)
These four properties return the coordinates of a shape relative to its page, in points.
Example: Selects shapes on every page of the document whose bottom coordinate is greater than 500 points, measured from the bottom of its page:
shape.pageBBox.bottom > 500
width, height (double)
These two properties return the width and height of the pageBBox object, in points.
Examples:
shape.pageBBox.width < 600 shape.pageBBox.height > 800
docBBox (rectangle)
Returns the bounding box coordinates of a shape as a rectangle, relative to the entire document.
Document coordinates are measured in points and use a coordinate system where the origin is located at the bottom-left corner of the last page, extending to the top-right corner of the first page.
Example 1: This selects shapes that match the specified coordinates exactly, measured from the bottom of the last page:
shape.docBBox = Rectangle(60.0, 590.0, 400.0, 700.0)
Example 2: This selects all shapes whose bottom coordinate is greater than 500 points, measured from the bottom of the last page:
shape.docBBox.bottom > 500 // equivalent to shape.bottom > 500
Example 3:
item.docBBox inside Rectangle(40.0, 20.0, 250.0, 400.0) // is equivalent to: item.left >= 40.0 and item.bottom >= 20.0 and item.right <= 250.0 and item.top <= 400.0