Arabic Text Processing

Handle RTL text with proper coordinate normalization

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

Full 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