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].index // returns the index of the first page containing shapes from the shape tree item.pages[item.pages.count - 1].index // returns the index of the last page containing shapes from the shape tree item.pages::index // returns the indexes of all pages containing shapes from the shape tree
fonts (sequence of font objects)
Returns a sequence of all unique font objects used by the text shapes within a shape tree.
Use the collect operator :: to retrieve a sequence of all unique values of a single font property within a shape tree.
If the shape tree does not contain any text shapes, an empty sequence is returned.
All properties of the font object are described in the article font object.
Examples:
item.fonts::name // returns a sequence of all unique font names within the shape tree item.fonts::size // returns a sequence of all unique font sizes within the shape tree "Arial" in item.fonts::name // checks whether the font "Arial" is used within the shape tree
text (string)
Returns 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
fills, strokes (sequence of colors)
These two properties return a sequence of all unique fill colors and stroke colors of the text and path shapes within a shape tree.
If the shape tree does not contain any text or path shapes, an empty sequence is returned.
Examples:
item.fills = [#000000, #FFFFFF, #0000FF] item.strokes = [#000000, #0000FF] [#000000] in item.fills // checks whether black is used as a fill color within the shape tree
pageBBoxes (sequence of 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) // 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 shape 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