PDF Bounding Box Coordinate System and Format in OpenDataLoader

OpenDataLoader-PDF uses the PDF user-space coordinate system with the origin at the lower-left corner, measuring in points, and formats bounding boxes as [left, bottom, right, top] arrays.

The BoundingBox class in the opendataloader-pdf repository (imported from org.verapdf.wcag.algorithms.entities.geometry) implements standard PDF coordinate conventions for representing rectangular regions on a page. Understanding this bounding box coordinate system is essential for correctly interpreting spatial data when extracting or manipulating PDF content programmatically.

PDF User-Space Coordinate System

The library adheres strictly to the PDF specification for user-space coordinates.

Origin and Units

According to the source code implementation, the coordinate system defines:

• Origin: The lower-left corner of the page serves as the (0,0) reference point
• Units: All measurements are in points, where 1 point equals 1/72 of an inch

This convention means that as Y-values increase, the position moves upward on the page, and as X-values increase, the position moves rightward.

Bounding Box Format and Structure

The BoundingBox class uses a specific array format to define rectangular extents.

Array Ordering [left, bottom, right, top]

A bounding box is defined by four extents representing the rectangle's boundaries:

[leftX, bottomY, rightX, topY]

As documented in XYCutPlusPlusSorterTest.java at line 420, this ordering remains consistent throughout the codebase and JSON serialization outputs (line 594).

Constructor Signature

When instantiating a BoundingBox programmatically, the constructor requires the page number followed by the four coordinates:

new BoundingBox(pageNumber, leftX, bottomY, rightX, topY);

This signature is confirmed in XYCutPlusPlusSorterTest.java at line 709, where test cases demonstrate the expected parameter order.

JSON Serialization

When bounding boxes are serialized to JSON, they appear as arrays of four numbers maintaining the same [left, bottom, right, top] ordering. The JSON representation excludes the page number, which is typically handled by the parent object's structure.

Code Examples

Creating a BoundingBox in Java

The following example demonstrates creating a bounding box on page 0 with specific coordinates:

import org.verapdf.wcag.algorithms.entities.geometry.BoundingBox;

// Create a bounding box on page 0
BoundingBox box = new BoundingBox(
        0,          // page number
        10.0,       // left X (left)
        20.0,       // bottom Y (bottom)
        150.0,      // right X (right)
        200.0);     // top Y (top)

JSON Output Representation

When the same box is emitted as JSON via the library's serializers, it appears as:

[10.0, 20.0, 150.0, 200.0]

Both the constructor and the JSON representation respect the [left, bottom, right, top] ordering established by the PDF user-space coordinate system.

Summary

• Coordinate System: PDF user-space with origin at lower-left corner, measuring in points (1/72 inch)
• Array Format: [leftX, bottomY, rightX, topY] for both internal representation and JSON serialization
• Constructor Pattern: new BoundingBox(pageNumber, leftX, bottomY, rightX, topY) as implemented in XYCutPlusPlusSorterTest.java
• Source Reference: Implementation verified in opendataloader-pdf/java/opendataloader-pdf-core/src/test/java/org/opendataloader/pdf/processors/readingorder/XYCutPlusPlusSorterTest.java

Frequently Asked Questions

What coordinate system does OpenDataLoader-PDF use for bounding boxes?

OpenDataLoader-PDF uses the standard PDF user-space coordinate system where the origin (0,0) is located at the lower-left corner of the page. All measurements are in points, where one point equals 1/72 of an inch. This means X-values increase toward the right edge and Y-values increase toward the top edge of the page.

How are bounding boxes formatted in OpenDataLoader-PDF?

Bounding boxes are formatted as arrays of four double values in the order [left, bottom, right, top]. This format applies both to the internal Java representation and to JSON serialization outputs. The constructor for the BoundingBox class takes these values as parameters following the page number: new BoundingBox(pageNumber, leftX, bottomY, rightX, topY).

Does the JSON representation include the page number?

No, the JSON representation of a bounding box contains only the four coordinate values [left, bottom, right, top]. The page number is handled separately by the parent object structure in the JSON hierarchy. When constructing a BoundingBox object in Java, you must provide the page number as the first argument to the constructor, but this is not included in the coordinate array itself.

Where is the bounding box implementation defined in the source code?

The BoundingBox class is imported from org.verapdf.wcag.algorithms.entities.geometry and is used throughout the opendataloader-pdf codebase. The specific array format and constructor usage is documented and tested in XYCutPlusPlusSorterTest.java at lines 420, 594, and 709, where the test cases verify the [left, bottom, right, top] ordering for both code construction and JSON serialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}