topaz-gregg-shorthand-61m-gguf
This is the GGUF version of Topaz-61M.
The text below this line is AI-generated.
Files
| File | Contents |
|---|---|
gregg |
The executable: Linux x86-64, statically linked, needs a CPU with AVX2 and FMA (most x86 CPUs since 2013) |
gregg.gguf |
Recognizer weights in 16-bit floats (BatchNorm folded into the convolutions), line-finder weights in 32-bit floats, the 73-token vocabulary, the outline dictionary and the LLM prompt (130 MB) |
source/ |
The C++ source gregg was built from, the converter that wrote gregg.gguf, and the tests that check both against PyTorch and OpenCV |
Usage
chmod +x gregg
./gregg page.jpg # writes page.txt next to the image
./gregg -o out/ *.png # outputs in out/
./gregg --lines line1.png line2.png # each image is a single, already cropped line
./gregg --with-prompt notes.jpg # notes.txt = LLM prompt, blank line, "Transcript:", then the lines
Each output line holds one line of shorthand: every outline in Grascii followed by its dictionary suggestions, e.g.
I-K (I can/why can) G (good/go) TH (the/their/there) N (in/not) TH (the/their/there) R (are/our/hour)
Punctuation and numbers are written as they are.
| Option | Meaning |
|---|---|
-m FILE |
model (default: gregg.gguf next to the executable) |
-o DIR |
output directory, created if needed (default: next to each input) |
-t N |
threads (default: all cores) |
--lines |
treat every input as one line (no line finding) |
--classic |
a simpler projection-profile line finder instead of the learned one (assumes level lines) |
--with-prompt |
start each .txt with the LLM prompt, a blank line and Transcript: |
-q |
quiet |
Inputs are PNG, JPEG or BMP. JPEG EXIF orientation is applied.
Speed and memory
Measured on a small cloud CPU (Xeon 2.0 GHz, 1 core with 2 hyperthreads, -t 2):
| Time | |
|---|---|
| one line (500 px wide) | about 1 s |
| one line (950 px wide) | about 2 s |
| a page of 31 lines | about 40 s (2.4 s of it finding the lines) |
Peak memory is about 200 MB for single lines and 260 MB for pages. Most of the time goes into the recognizer's convolutions; on this CPU the executable is about 2x slower than PyTorch, which uses a faster matrix library. More cores help almost linearly.
Building from source
gregg is a Release build of source/ with ggml v0.9.9 (commit a04eea07, fetched by CMake) and the default options:
cmake -S source -B build # -DGREGG_NATIVE=ON tunes for the build machine's CPU
make -C build -j gregg # -> build/gregg (static; -DGREGG_STATIC=OFF links glibc dynamically)
You need CMake 3.16 or later, a C++17 compiler and git. source/convert.py wrote gregg.gguf from the PyTorch checkpoint (--type f16); it runs in the training repository's Python environment, since it reads the dictionary from the lexicon there. source/README.md has the details, including the parity tests.
Agreement with PyTorch
With the current model (training step 92,000), gregg gave the same Grascii and dictionary suggestions as the PyTorch code on 30 of 30 book lines, and the same Grascii on 66 of 70 lines of two scanned pages read with both line finders; the other 4 differed by a stroke or two. Those differences come from storing the recognizer in 16 bits: in earlier testing, a 32-bit conversion matched PyTorch exactly on every line of three test pages (197 lines) and 50 book lines, with identical line crops, and the 16-bit file matched on 196 of those 197 lines. The dictionary lookup matched the Python implementation on 889 of 889 test lines.
Known differences
- JPEG decoding uses stb_image rather than libjpeg-turbo; about 1.5% of pixels can differ by one grey level, which can very occasionally change a stroke. PNG input decodes identically.
- Lines are read one at a time. The PyTorch package does the same; batching lines of different widths together (as some training-repo scripts do) changes a few readings, because padding affects the features at a line's right edge.
License
MIT, as the PyTorch release.