Savoir si un PDF a besoin d’OCR

"""
Distinguer une couche texte utilisable d'une couche cassée, sur les pages qui
prétendent en avoir une.

Niveau N1. Le niveau N0 compte des caractères, et une couche texte faite des
mauvais caractères en compte tout autant : un PDF dont la police ne porte pas
de table de caractères, ou en porte une fausse, s'extrait en index de glyphes
lus comme de l'ASCII — « #$%&!*+,-./0123 » là où la page affiche un
paragraphe. N0 déclare cette page lisible, et elle ne l'est pas.

Distinguer la langue de cela, c'est le travail d'un modèle de caractères, et
c'est le plus petit qui existe : la fréquence de chaque paire de lettres.
« qu » et « es » sont fréquents en français, « q# » et « &! » ne le sont pas,
et une page se note à la ressemblance de ses paires avec celles des pages que
vous tenez déjà pour bonnes.

Rien n'est livré avec ce modèle. On donne à `fit` le texte de vos propres
pages lisibles — N0 vient de les lister —, si bien que la référence est faite
de vos documents, dans votre langue, avec votre vocabulaire. Le seuil vient du
même endroit : la note la plus basse du lot d'entraînement, avec une marge,
plutôt qu'un nombre choisi ici. `fit` refuse un lot vide : un modèle ajusté
sur rien déclarerait tout lisible, et c'est l'erreur coûteuse de cette fiche.

La marge, elle, est un réglage par défaut et non une constante. Une page du
lot d'entraînement passe son propre seuil par construction, donc elle ne dit
rien : le demi-nat vient de quatre pages de prose administrative française
retenues **hors** du lot — un avenant, un article du code civil, un accusé de
réception, un en-tête de facture —, qui notent entre −2,42 et −2,83 contre un
lot dont la pire page note −2,48. La plus éloignée est à 0,35 en dessous : à
trois dixièmes elle était refusée. Gardez quelques-unes de vos pages lisibles
hors de `fit`, notez-les, et déplacez ce nombre jusqu'à ce qu'elles passent
toutes : c'est le seul réglage qui dise quelque chose de vos documents.

Ce que cela ne sait pas faire, c'est lire. Une page de chiffres, un tableau de
montants, un formulaire à champs courts : ce sont de vrais textes qu'aucun
modèle de lettres n'appellera de la langue, et la note le dit. Il sépare les
lettres du bruit, pas le sens du non-sens.
"""

from __future__ import annotations

import math

# The letters this model counts. Anything else — digits, punctuation, symbols
# — becomes a single « other » class, which is exactly what a broken character
# map produces in quantity.
ALPHABET = "abcdefghijklmnopqrstuvwxyzàâäçéèêëîïôöùûüÿœæ "
OTHER = "#"
SYMBOLS = ALPHABET + OTHER

# How far below the worst training page a page may score before it is called
# unreadable.
#
# Half a nat per pair, and the number comes from pages that are NOT in the
# training set: four ordinary French administrative pages — an amendment, an
# article of the civil code, an acknowledgement letter, an invoice heading —
# score between −2.42 and −2.83 against a model fitted on six contract pages
# whose worst is −2.48. The furthest sits 0.35 below it, so three tenths would
# refuse it, and did. Half a nat clears it and still refuses an English page,
# 0.65 below, and a table of amounts, 1.66 below.
#
# It is a default, not a constant: it was measured on six training pages and
# four held-out ones, which is small. Keep a handful of your own readable pages
# out of `fit`, score them, and move this number until they all pass — that is
# the only calibration that says anything about your own documents.
MARGIN = 0.5


def normalise(text: str) -> str:
    """Lower case, and every symbol outside the alphabet folded into one."""
    return "".join(c if c in ALPHABET else OTHER for c in text.lower())


def fit(pages) -> dict:
    """Count the letter pairs of pages you trust, and set the threshold from them."""
    counts = {a: {b: 1 for b in SYMBOLS} for a in SYMBOLS}  # add-one smoothing
    for page in pages:
        clean = normalise(page)
        for first, second in zip(clean, clean[1:]):
            counts[first][second] += 1
    totals = {a: sum(row.values()) for a, row in counts.items()}
    model = {"log_probability": {a: {b: math.log(counts[a][b] / totals[a]) for b in SYMBOLS}
                                 for a in SYMBOLS}}
    scores = [score(page, model) for page in pages]
    if not scores:
        # A model fitted on nothing would answer « readable » to everything,
        # which is the expensive mistake of this entry: a page declared
        # readable that is not one goes into the index empty, and nobody looks
        # at it again.
        raise ValueError("fit needs at least one page you have read yourself")
    model["threshold"] = min(scores) - MARGIN
    return model


def score(text: str, model: dict) -> float:
    """Mean log probability of the letter pairs, or -inf on a page too short."""
    clean = normalise(text)
    pairs = list(zip(clean, clean[1:]))
    if not pairs:
        return float("-inf")
    table = model["log_probability"]
    return sum(table[a][b] for a, b in pairs) / len(pairs)


def is_readable(text: str, model: dict) -> dict:
    """Say whether this text layer looks like the pages the model was fitted on."""
    value = score(text, model)
    return {"readable": value >= model["threshold"], "score": value,
            "threshold": model["threshold"]}

/**
 * Distinguer une couche texte utilisable d'une couche cassée, sur les pages qui
 * prétendent en avoir une.
 *
 * Niveau N1. Le niveau N0 compte des caractères, et une couche texte faite des
 * mauvais caractères en compte tout autant : un PDF dont la police ne porte pas
 * de table de caractères, ou en porte une fausse, s'extrait en index de glyphes
 * lus comme de l'ASCII — « #$%&!*+,-./0123 » là où la page affiche un
 * paragraphe. N0 déclare cette page lisible, et elle ne l'est pas.
 *
 * Distinguer la langue de cela, c'est le travail d'un modèle de caractères, et
 * c'est le plus petit qui existe : la fréquence de chaque paire de lettres.
 * « qu » et « es » sont fréquents en français, « q# » et « &! » ne le sont pas,
 * et une page se note à la ressemblance de ses paires avec celles des pages que
 * vous tenez déjà pour bonnes.
 *
 * Rien n'est livré avec ce modèle. On donne à `fit` le texte de vos propres
 * pages lisibles — N0 vient de les lister —, si bien que la référence est faite
 * de vos documents, dans votre langue, avec votre vocabulaire. Le seuil vient du
 * même endroit : la note la plus basse du lot d'entraînement, avec une marge,
 * plutôt qu'un nombre choisi ici. `fit` refuse un lot vide : un modèle ajusté
 * sur rien déclarerait tout lisible, et c'est l'erreur coûteuse de cette fiche.
 *
 * La marge, elle, est un réglage par défaut et non une constante. Une page du
 * lot d'entraînement passe son propre seuil par construction, donc elle ne dit
 * rien : le demi-nat vient de quatre pages de prose administrative française
 * retenues **hors** du lot — un avenant, un article du code civil, un accusé de
 * réception, un en-tête de facture —, qui notent entre −2,42 et −2,83 contre un
 * lot dont la pire page note −2,48. La plus éloignée est à 0,35 en dessous : à
 * trois dixièmes elle était refusée. Gardez quelques-unes de vos pages lisibles
 * hors de `fit`, notez-les, et déplacez ce nombre jusqu'à ce qu'elles passent
 * toutes : c'est le seul réglage qui dise quelque chose de vos documents.
 *
 * Ce que cela ne sait pas faire, c'est lire. Une page de chiffres, un tableau de
 * montants, un formulaire à champs courts : ce sont de vrais textes qu'aucun
 * modèle de lettres n'appellera de la langue, et la note le dit. Il sépare les
 * lettres du bruit, pas le sens du non-sens.
 */

// The letters this model counts. Anything else — digits, punctuation, symbols
// — becomes a single « other » class, which is exactly what a broken character
// map produces in quantity.
export const ALPHABET = "abcdefghijklmnopqrstuvwxyzàâäçéèêëîïôöùûüÿœæ ";
export const OTHER = '#';
const SYMBOLS = [...(ALPHABET + OTHER)];

// How far below the worst training page a page may score before it is called
// unreadable.
//
// Half a nat per pair, and the number comes from pages that are NOT in the
// training set: four ordinary French administrative pages — an amendment, an
// article of the civil code, an acknowledgement letter, an invoice heading —
// score between −2.42 and −2.83 against a model fitted on six contract pages
// whose worst is −2.48. The furthest sits 0.35 below it, so three tenths would
// refuse it, and did. Half a nat clears it and still refuses an English page,
// 0.65 below, and a table of amounts, 1.66 below.
//
// It is a default, not a constant: it was measured on six training pages and
// four held-out ones, which is small. Keep a handful of your own readable
// pages out of `fit`, score them, and move this number until they all pass —
// that is the only calibration that says anything about your own documents.
export const MARGIN = 0.5;

/** Lower case, and every symbol outside the alphabet folded into one. */
export function normalise(text) {
  return [...text.toLowerCase()].map((c) => (ALPHABET.includes(c) ? c : OTHER)).join('');
}

/** Count the letter pairs of pages you trust, and set the threshold from them. */
export function fit(pages) {
  const counts = new Map(SYMBOLS.map((a) => [a, new Map(SYMBOLS.map((b) => [b, 1]))])); // add-one
  for (const page of pages) {
    const clean = normalise(page);
    for (let i = 0; i + 1 < clean.length; i += 1) {
      const row = counts.get(clean[i]);
      row.set(clean[i + 1], row.get(clean[i + 1]) + 1);
    }
  }
  const logProbability = new Map();
  for (const [a, row] of counts) {
    const total = [...row.values()].reduce((sum, n) => sum + n, 0);
    logProbability.set(a, new Map([...row].map(([b, n]) => [b, Math.log(n / total)])));
  }
  const model = { logProbability, threshold: -Infinity };
  const scores = pages.map((page) => score(page, model));
  if (scores.length === 0) {
    // A model fitted on nothing would answer « readable » to everything, which
    // is the expensive mistake of this entry: a page declared readable that is
    // not one goes into the index empty, and nobody looks at it again.
    throw new RangeError('fit needs at least one page you have read yourself');
  }
  model.threshold = Math.min(...scores) - MARGIN;
  return model;
}

/** Mean log probability of the letter pairs, or -Infinity on a page too short. */
export function score(text, model) {
  const clean = normalise(text);
  if (clean.length < 2) return -Infinity;
  let total = 0;
  for (let i = 0; i + 1 < clean.length; i += 1) {
    total += model.logProbability.get(clean[i]).get(clean[i + 1]);
  }
  return total / (clean.length - 1);
}

/** Say whether this text layer looks like the pages the model was fitted on. */
export function isReadable(text, model) {
  const value = score(text, model);
  return { readable: value >= model.threshold, score: value, threshold: model.threshold };
}