A shape tree object is a hierarchical data structure that represents a collection of content shapes within a document. These shapes are organized into containers, which can themselves contain other containers, forming a multi-level, nested structure.
Each shape tree consists of:
- Shape objects: The individual content elements from the document
- Containers: Logical groupings of shapes that can encapsulate other containers or shapes, enabling hierarchical organization
This structure allows complex documents to be represented as trees, where elements can be accessed, grouped, and processed efficiently.
Shape trees serve as the primary objects processed by most nodes in axesFlip.
The way a shape tree is referenced depends on the input port of the node. In most cases, the relevant input port is named items. In this context, each shape tree within the input sequence is accessed using the variable item, which represents one shape tree at a time during processing.
To navigate within a shape tree and select specific shapes or containers, a Path language is used. This enables precise targeting of elements within the hierarchical structure.
A shape tree object provides the following properties.
pages (sequence of page objects)
Returns a sequence of page objects, where each entry represents a page containing shapes from the shape tree object. Use the sequence indexer [] (zero-based) to access a specific page within the sequence.
All properties of the page object are described in the article page object.
Example:
item.pages[0] // returns the index of the first page containing shapes from the shape tree item.pages[item.pages.count - 1] // returns the index of the last page containing shapes from the shape tree
text (string)
Represents the complete text content of a shape tree, rather than the text of an individual shape.
If a shape tree contains multiple text shapes, the text value is calculated by combining the text from all those shapes into a single aggregated string.
Example:
item.text match "This is an example paragraph derived from multiple text shapes."
left, right, top, bottom (double)
These four properties return the coordinates of a shape tree 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:
item.left = 40.0 // Note: equivalent to item.docBBox.left = 40.0 item.right = 250.0 // Note: equivalent to item.docBBox.right = 250.0 item.top = 400.0 // Note: equivalent to item.docBBox.top = 400.0 item.bottom = 20.0 // Note: equivalent to item.docBBox.bottom = 20.0
width, height (double)
These two properties return the width and the height of a shape tree in points.
Examples:
item.width = 400.0 item.height = 70.0
pageBBoxes (sequence of pageBBox rectangles)
Returns the bounding box coordinates of a shape tree object as a sequence of rectangles, relative to their pages.
Page coordinates are measured in points and extend from the bottom-left corner to the top-right corner of the page.
For shape trees (groups of shapes), multiple bounding boxes may exist if the shapes span across different pages. In this case, each page has its own bounding box. Use the sequence indexer [] (zero-based) to access a specific pageBBox within the sequence.
Examples:
item.pageBBoxes[0] // returns the first bounding box of a shape tree item.pageBBoxes[item.pageBBoxes.count - 1] // returns the last bounding box of a shape tree item.pageBBoxes[0] inside Rectangle(60.0, 590.0, 400.0, 700.0) ? true : false // Checks whether the first bounding box of a shape tree lies completely // within the specified rectangle.
left, right, top, bottom (double)
These four properties return the coordinates of a shape tree relative to its page, in points.
Example: Selects shapes trees on every page of the document whose first bounding box has a bottom coordinate greater than 500 points, measured from the bottom of its page:
item.pageBBoxes[0].bottom > 500
width, height (double)
These two properties return the width and height of a pageBBox rectangle, in points.
Examples:
item.pageBBoxes[2].width > 600 item.pageBBoxes[2].height < 800
docBBox (rectangle)
Returns the bounding box coordinates of a shape tree object 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.
Examples:
item.docBBox = Rectangle(40.0, 20.0, 250.0, 400.0) item.docBBox.left = 40.0 // equivalent to item.left = 40.0 item.docBBox.bottom = 20.0 // equivalent to item.bottom = 20.0 item.docBBox.right = 250.0 // equivalent to item.right = 250.0 item.docBBox.top = 400.0 // equivalent to item.top = 400.0