Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ragaeeb/kokokor/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Kokokor provides first-class support for right-to-left (RTL) languages like Arabic. The isRTL option flips x-coordinates to ensure proper text ordering and alignment.

​
RTL Processing Example

import { reconstructParagraphs } from 'kokokor';

const result = reconstructParagraphs(
  {
    observations: [
      {
        text: 'فمن هذه الملاحظات (٦):',
        bbox: { x: 772, y: 170, width: 290, height: 38 }
      },
      {
        text: '١- ص ١٩ اعتبر الأخ أبو الحسن صفة الأكل والشرب صفة كمال في المخلوق',
        bbox: { x: 142, y: 234, width: 917, height: 51 }
      },
      {
        text: 'وفي هذا نظر، فإنه يشارك الإنسان في ذلك أحط الحيوانات، ثم ما يعقب هذا الأكل',
        bbox: { x: 147, y: 298, width: 950, height: 44 }
      },
    ],
    page: {
      width: 1240,
      height: 1754,
      dpiX: 72,
      dpiY: 72,
    },
  },
  {
    line: {
      isRTL: true,  // Enable RTL processing
    },
  }
);

console.log(result.text);

​
How RTL Processing Works

1

Coordinate Flipping

When isRTL: true, Kokokor flips the x-axis by transforming each observation’s x-coordinate:
flippedX = imageWidth - (x + width)
This ensures that text on the right side of the page is processed first.
2

Normalization

X-coordinates are normalized using DPI information to ensure consistent alignment regardless of document resolution.
3

Line Grouping

Observations are grouped into lines based on vertical proximity, just like LTR text.
4

Horizontal Sorting

Within each line, observations are sorted by the flipped x-coordinate, ensuring proper RTL reading order.

​
Complete Arabic Document Example

import { reconstructParagraphs } from 'kokokor';

const arabicDocument = {
  observations: [
    {
      text: 'بسم الله الرحمن الرحيم',
      bbox: { x: 400, y: 100, width: 440, height: 35 }
    },
    {
      text: 'هذا مثال على نص',
      bbox: { x: 500, y: 160, width: 340, height: 30 }
    },
    {
      text: 'عربي يتم معالجته',
      bbox: { x: 480, y: 195, width: 360, height: 30 }
    },
    {
      text: 'بشكل صحيح.',
      bbox: { x: 640, y: 230, width: 200, height: 30 }
    },
    // New paragraph with vertical gap
    {
      text: 'الفقرة الثانية تبدأ',
      bbox: { x: 520, y: 290, width: 320, height: 30 }
    },
    {
      text: 'بعد مسافة عمودية.',
      bbox: { x: 540, y: 325, width: 300, height: 30 }
    },
  ],
  page: {
    width: 1240,
    height: 1754,
    dpiX: 72,
    dpiY: 72,
  },
};

const result = reconstructParagraphs(arabicDocument, {
  line: {
    isRTL: true,
    pixelTolerance: 5,
  },
  paragraph: {
    verticalJumpFactor: 2,
    widthTolerance: 0.85,
  },
});

console.log(result.text);
console.log('Lines detected:', result.lines.length);
console.log('Paragraphs detected:', result.paragraphs.length);

​
Configuration Options

​
line.isRTL
boolean
default:"false"
Enable RTL text processing. Set to true for Arabic, Hebrew, and other RTL languages.
​
line.pixelTolerance
number
default:"5"
Vertical tolerance in pixels (at 72 DPI) for grouping observations into lines.
​
line.poetryDetectionOptions
object
Options for detecting Arabic poetry patterns, including hemistichs.
​
line.poetryPairDelimiter
string
default:"' '"
Delimiter used when merging detected poetry hemistichs into a single line.

​
Important Notes

Coordinate System: When isRTL: true, ensure your OCR observations use the original coordinate system (not pre-flipped). Kokokor handles the transformation internally.
Arabic Numerals: Kokokor automatically handles Arabic-Indic numerals (٠-٩) and filters numeric-only tokens during poetry detection.
Tatweel Character: The tatweel character (ـ) is automatically removed during word count calculations to ensure accurate text analysis.

​
Advanced: Low-Level API

For more control, use the low-level API: 
import { 
  flipAndAlignObservations,
  mapObservationsToTextLines,
  mapTextLinesToParagraphs,
  formatTextBlocks
} from 'kokokor';

const page = {
  width: 1240,
  height: 1754,
  dpiX: 72,
  dpiY: 72,
};

// Step 1: Preprocess observations
const preprocessed = flipAndAlignObservations(
  observations,
  page.width,
  page.dpiX,
  { isRTL: true }
);

// Step 2: Group into lines
const lines = mapObservationsToTextLines(preprocessed, page, {
  isRTL: true,
});

// Step 3: Group into paragraphs
const paragraphs = mapTextLinesToParagraphs(lines);

// Step 4: Format as text
const text = formatTextBlocks(paragraphs);

​
See Also

Poetry Documents

Arabic poetry detection with hemistichs

Simple OCR

Basic LTR text processing

Build docs developers (and LLMs) love

Get started for freeTalk to us