UNICHARAMBIGS(5)

🎀 NAME 🎀

unicharambigs — Tesseract unicharset ambiguities. bestie, this is the file that keeps track of "wait, was that an m or an rn?" energy ✨

---

💖 DESCRIPTION 💖

okay so the unicharambigs file — which is a whole component of traineddata, see combine_tessdata(1) if you wanna go deeper — is what Tesseract uses to represent possible ambiguities between characters, or between whole groups of characters. like, characters that lowkey look alike and could be confused for each other, and what to do about it. no cap 🫶

The file is just a bunch of lines, and each line is laid out like this:

[num] <TAB> [char(s)] <TAB> [num] <TAB> [char(s)] <TAB> [num]

so, five fields, tab-separated, and here's the breakdown:

• Field one — the number of characters contained in field two.
• Field two — the character sequence to be replaced.
• Field three — the number of characters contained in field four.
• Field four — the character sequence used to replace field two.
• Field five — contains either 1 or 0. 1 denotes a mandatory replacement, 0 denotes an optional replacement. iykyk 💅

Characters appearing in fields two and four should appear in unicharset. and listen — the numbers in fields one and three refer to the number of unichars (not bytes). not bytes, bestie. unichars. don't get it twisted 😭

---

🌸 EXAMPLE 🌸

ok, vibes check, here's the v1 look:

v1
2       ' '     1       "     1
1       m       2       r n   0
3       i i i   1       m     0

The first line is a version identifier. In this example, all instances of the 2 character sequence '' will always be replaced by the 1 character sequence "; a 1 character sequence m may be replaced by the 2 character sequence rn, and the 3 character sequence (i i i up top 👀) may be replaced by the 1 character sequence m.

---

Version 3.03 and on supports a new, simpler format for the unicharambigs file — and honestly? it ate:

v2
'' " 1
m rn 0
iii m 0

In this format, the "error" and "correction" are simple UTF-8 strings separated by a space, and, after another space, the same type specifier as v1 (0 for optional and 1 for mandatory substitution). cute, right? 🎀

but heads up, the downside of this simpler format is that Tesseract has to encode the UTF-8 strings into the components of the unicharset. In complex scripts, this encoding may be ambiguous. In this case, the encoding is chosen such as to use the least UTF-8 characters for each component, ie the shortest unicharset components will make up the encoding. so it does the smart thing, but it's still doing work you didn't ask for 🙈

---

🦋 HISTORY 🦋

The unicharambigs file first appeared in Tesseract 3.00. prior to that, a similar format, called DangAmbigs (dangerous ambiguities — truly main character naming 💀), was used. the format was almost identical, except only mandatory replacements could be specified, and field 5 was absent.

---

💀 BUGS 💀

This is a documentation "bug": it's not currently clear what should be done in the case of ligatures (such as fi) which may also appear as regular letters in the unicharset. so yeah, that part's just kind of a mystery for now, not me being vague on purpose, promise 😭

---

🔥 SEE ALSO 🔥

• tesseract(1)
• unicharset(5)
• https://tesseract-ocr.github.io/tessdoc/Training-Tesseract-3.03%E2%80%933.05.html#the-unicharambigs-file

---

👑 AUTHOR 👑

The Tesseract OCR engine was written by Ray Smith and his research groups at Hewlett Packard (1985-1995) and Google (2006-2018). legends, honestly 🌈

---

and that's the whole page, bestie — this was UNICHARAMBIGS(5), dated 2026-09-28 ✨ go forth and disambiguate 💜