Basic Usage

Learn how to use Kokokor’s recommended API to reconstruct paragraphs from OCR output

Overview

Kokokor provides a simple, one-shot API called reconstructParagraphs that handles the complete pipeline of converting OCR observations into properly formatted text with intelligent paragraph breaks.

Quick Start

The recommended way to use Kokokor is through the reconstructParagraphs function:

import { reconstructParagraphs } from 'kokokor';

const result = reconstructParagraphs({
  observations: ocrObservations,
  page: {
    width: 2480,
    height: 3508,
    dpiX: 300,
    dpiY: 300
  }
});

console.log(result.text);

Input Format

The reconstructParagraphs function expects two main inputs:

Observations

An array of OCR text observations, where each observation contains:

text · string · required

The recognized text content

bbox · BoundingBox · required

The bounding box defining position and dimensions

Show BoundingBox properties

x · number

X-coordinate of top-left corner (pixels)

y · number

Y-coordinate of top-left corner (pixels)

width · number

Width of the bounding box (pixels)

height · number

Height of the bounding box (pixels)

Page Context

Page metadata required for accurate reconstruction:

width · number · required

Page width in pixels

height · number · required

Page height in pixels

dpiX · number · required

Horizontal DPI (dots per inch)

dpiY · number · required

Vertical DPI (dots per inch)

Output Structure

The reconstructParagraphs function returns a comprehensive result object:

type ReconstructResult = {
  lines: TextBlock[];      // Intermediate line-level blocks
  paragraphs: TextBlock[]; // Final paragraph-level blocks
  text: string;           // Formatted plain text output
};

Lines

An array of TextBlock objects representing individual text lines with metadata:

• text - The line content
• bbox - Position and dimensions
• isCentered - Whether the line is centered
• isHeading - Whether it’s identified as a heading
• isFootnote - Whether it’s identified as a footnote
• isPoetic - Whether it’s identified as poetry

Paragraphs

An array of TextBlock objects where consecutive prose lines have been merged into paragraphs. Poetry lines remain separate to preserve formatting.

Text

The final formatted text output as a string, with:

• Proper paragraph breaks (double newlines)
• Poetry lines preserved individually
• Headings followed by blank lines
• Optional footer symbols before footnotes

Complete Example

Here’s a complete example from OCR output to formatted text:

import { reconstructParagraphs } from 'kokokor';

// Example OCR result from your OCR engine
const ocrResult = {
  dpi: { x: 300, y: 300 },
  page: { width: 2480, height: 3508 },
  observations: [
    {
      text: 'This is the first',
      bbox: { x: 100, y: 100, width: 200, height: 20 }
    },
    {
      text: 'line of text.',
      bbox: { x: 310, y: 100, width: 150, height: 20 }
    },
    {
      text: 'This is a new paragraph.',
      bbox: { x: 100, y: 150, width: 300, height: 20 }
    },
  ],
};

// Reconstruct paragraphs
const result = reconstructParagraphs({
  observations: ocrResult.observations,
  page: {
    dpiX: ocrResult.dpi.x,
    dpiY: ocrResult.dpi.y,
    height: ocrResult.page.height,
    width: ocrResult.page.width,
  },
});

console.log(result.text);
// Output:
// This is the first line of text.
// This is a new paragraph.

// Access intermediate data
console.log(`Detected ${result.lines.length} lines`);
console.log(`Grouped into ${result.paragraphs.length} paragraphs`);

The reconstructParagraphs API is recommended for most use cases as it handles the complete pipeline automatically. For advanced use cases requiring fine-grained control, see the Advanced Configuration guide.

Next Steps

Advanced Configuration

Fine-tune line detection, paragraph grouping, and poetry detection

Surya Integration

Convert Surya OCR output to Kokokor format