# PDF Bounding Box Coordinate System and Format in OpenDataLoader

> Understand the PDF bounding box coordinate system used by OpenDataLoader. Learn its origin, units, and the [left, bottom, right, top] array format for precise data extraction.

- Repository: [opendataloader-project/opendataloader-pdf](https://github.com/opendataloader-project/opendataloader-pdf)
- Tags: internals
- Published: 2026-03-20

---

**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`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/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:

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

```

This signature is confirmed in [`XYCutPlusPlusSorterTest.java`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/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:

```java
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:

```json
[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`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/XYCutPlusPlusSorterTest.java)
- **Source Reference**: Implementation verified in [`opendataloader-pdf/java/opendataloader-pdf-core/src/test/java/org/opendataloader/pdf/processors/readingorder/XYCutPlusPlusSorterTest.java`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/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`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/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.