Data Models

The newspaper.utils module defines key data structures used throughout the newspaper processing workflow. These models represent bounding boxes, articles, pages, and IIIF manifests.

YOLOBox

A YOLOBox represents a detected region or element on a page (such as text blocks, headings, or images) along with its geometric polygon coordinates, classification, and optional text or ordering details.

Attributes

Attribute Type Description

name

str

Unique identifier for the box.

type

str

Category/class label of the detected bounding box element.

polygon

list[list[int]]

List of [x, y] coordinates defining the polygonal contour of the box.

confidence

float

Detection confidence score.

text

str | None

Optional OCR/extracted text contained within this box.

order

int | None

Optional sequence index indicating the reading order position.

Properties & Methods

  • geometry (Polygon): Computes and caches a Shapely Polygon instance representing the box’s geometry.

  • overlap(other: Polygon) → float: Calculates the proportion of the target polygon (other) covered by this box. Returns 0.0 if there is no intersection or if either geometry is invalid.

  • format_polygon(width: int, height: int) → list[int]: Converts and normalizes polygon coordinates relative to the image dimensions (width and height) into a standard bounding box format suitable for layout reading models.

JSON Example

{
  "name": "box_001",
  "type": "ARTICLE-TITLE",
  "polygon": [
    [120, 300],
    [850, 300],
    [850, 350],
    [120, 350]
  ],
  "confidence": 0.94,
  "text": "LA GAZETTE DU MATIN",
  "order": 1
}

Article

An Article represents a logical document entity composed of multiple detected layout parts across pages.

Attributes

Attribute Type Description

name

str

Name or identifier of the article.

parts

list[YOLOBox]

List of YOLOBox instances that make up the article content.

JSON Example

{
  "name": "1",
  "parts": [
    {
      "name": "box_001",
      "type": "ARTICLE-TITLE",
      "polygon": [[120, 300], [850, 300], [850, 350], [120, 350]],
      "confidence": 0.94,
      "text": "LA GAZETTE DU MATIN",
      "order": 1
    },
    {
      "name": "box_002",
      "type": "ARTICLE-TEXT",
      "polygon": [[120, 360], [480, 360], [480, 750], [120, 750]],
      "confidence": 0.89,
      "text": "Le grand évènement d'hier a réuni...",
      "order": 2
    }
  ]
}

Page

A Page represents a single page from a publication, holding reference metadata, image information, and associated layout detections.

Attributes

Attribute Type Description

name

str

Page identifier or page number label.

url

str

IIIF image URL for the page resource.

size

tuple[int, int] | None

Optional tuple specifying (width, height) of the page image.

path

Path | None

Optional local file path where the page image or metadata is stored.

boxes

list[YOLOBox]

Collection of YOLOBox elements detected on this page.

Methods

  • cast_for_reading_order(reader_classes: list[str]) → ReadingPage: Transforms the page and its boxes into a ReadingPage structure compatible with layout_reader algorithms.

JSON Example

{
  "name": "1",
  "url": "https://gallica.bnf.fr/iiif/ark:/12148/bpt6k41008602/f1/full/,2500/0/native.jpg",
  "size": [1765, 2500],
  "path": "/tmp/manifest/images/1.jpg",
  "boxes": [
    {
      "name": "box_001",
      "type": "ARTICLE-TITLE",
      "polygon": [[120, 300], [850, 300], [850, 350], [120, 350]],
      "confidence": 0.94,
      "text": "LA GAZETTE DU MATIN",
      "order": 1
    }
  ]
}

Manifest

A Manifest manages top-level IIIF document manifest data, representing a complete publication volume or issue.

Attributes

Attribute Type Description

url

str

Remote URL of the IIIF manifest JSON.

hash

str | None

Optional hash string for caching or version verification.

path

Path | None

Optional local path where the downloaded manifest JSON is saved.

pages

list[Page]

List of Page instances parsed from the manifest sequence.

articles

list[Article]

List of Article entities identified across the pages.

Methods

  • parse(image_height: int) → None: Downloads the remote IIIF manifest from url (if not already local), parses the canvas sequence, and populates the pages list with IIIF image URLs formatted to the specified image_height.

JSON Example

{
  "url": "https://gallica.bnf.fr/iiif/ark:/12148/bpt6k41008602/manifest.json",
  "hash": "4d5ab18d8f53e386153b06295ab45a0d",
  "path": "/tmp/4d5ab18d8f53e386153b06295ab45a0d/manifest.json",
  "pages": [
    {
      "name": "1",
      "url": "https://gallica.bnf.fr/iiif/ark:/12148/bpt6k41008602/f1/full/,2500/0/native.jpg",
      "size": [1765, 2500],
      "path": "/tmp/4d5ab18d8f53e386153b06295ab45a0d/images/1.jpg",
      "boxes": [
        {
          "name": "box_001",
          "type": "ARTICLE-TITLE",
          "polygon": [[120, 300], [850, 300], [850, 350], [120, 350]],
          "confidence": 0.94,
          "text": "LA GAZETTE DU MATIN",
          "order": 1
        }
      ]
    }
  ],
  "articles": [
    {
      "name": "1",
      "parts": [
        {
          "name": "box_001",
          "type": "ARTICLE-TITLE",
          "polygon": [[120, 300], [850, 300], [850, 350], [120, 350]],
          "confidence": 0.94,
          "text": "LA GAZETTE DU MATIN",
          "order": 1
        }
      ]
    }
  ]
}