Skip to content

About

Turn photos and scans of handwriting (PNG, JPG, HEIC, PDF) into native .goodnotes notebooks with editable pen strokes, not flattened images. Keeps stroke shape, width, colour and page layout.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

Repository files navigation

gndigitize: handwriting photos → native .goodnotes

goodnotes-digitize turns photos and scans of handwriting or drawings (PNG, JPG/JPEG, HEIC, PDF, plus TIFF/WebP/BMP) into native GoodNotes notebooks with editable pen strokes. It does not embed a flattened picture. Every line becomes a real GoodNotes ink stroke that you can select, recolour, resize, erase and lasso. Each stroke keeps its geometry (smooth Bézier curves with sharp corners preserved), its pen width, its ink colour and its position on the page.

goodnotes-digitize notes.jpg page2.heic worksheet.pdf -o notes.goodnotes

Then import notes.goodnotes in GoodNotes (Files / AirDrop → Open in GoodNotes, or Import inside the app).

Install

Python 3.11+.

python3 -m venv .venv
.venv/bin/pip install -e .

This installs the goodnotes-digitize command (alias gndigitize) and the goodnotes-digitize-gui desktop app. The GoodNotes container writer (gnnote, MIT, pure Python) is pulled from GitHub at a pinned commit, because it is not on PyPI.

Desktop app

goodnotes-digitize-gui            # or: goodnotes-digitize gui [files…]

To convert in the window:

  1. Add photos, scans, PDFs or whole folders.
  2. Choose one combined notebook or one per file, and where to save it.
  3. Set the common options: page size, ruled-line removal, ink colours, photo flattening, lighting, fills, highlighters, and more under Advanced.
  4. Press Convert (⌘↩).

Each page shows up as it finishes, as your photo next to the reconstructed editable strokes, with progress, a log and a Cancel button. Show in Finder opens the result. The window runs exactly the same conversion as the command line, and the Log tab shows the equivalent command. It uses Tkinter, so it needs no extra packages. On macOS, use a python.org or Homebrew (python-tk) Python.

How it works

Stage What happens Built on
Load EXIF rotation, alpha → white, HEIC via pillow-heif (falls back to macOS sips), PDF pages rendered at up to 300 dpi Pillow, pillow-heif, PyMuPDF
Vector PDF ink Ink annotations and stroked paths already in a PDF are copied exactly, with no tracing PyMuPDF
Page detection A photographed sheet on a darker background is found and perspective-flattened OpenCV
Illumination Background division removes shadows and vignetting and white-balances the ink. Evenly lit scans keep a flat white point OpenCV
Segmentation Ink strength = CIELAB distance from paper white (one measure for black, coloured and light ink), Otsu midpoint + hysteresis, pen-relative speck removal, optional ruled-line removal scikit-image, OpenCV
Resolution Thin pens are traced on an upscaled copy (pen ≈ 7 px) so skeleton artefacts stay far smaller than the letters
Pens / colours k-means in CIELAB on stroke cores, merging of near-identical clusters; fringe pixels inherit their nearest core's pen. Near-black snaps to black; wide, light, saturated pens become highlighters; light dot grids are recognised as paper and dropped OpenCV, SciPy
Centre lines Zhang skeleton → minimal 8-connected skeleton → pixel graph. Crossings are contracted, spurs pruned (tip-radius aware, so a "t" keeps its bar), strokes paired through junctions by tangent continuity, sharp corners and rounded stroke ends restored scikit-image (the skan / AutoTrace centre-line approach)
Width Distance transform along the centre line, corrected by the pen's ink mass for anti-aliasing, then unified per pen (a real pen has one width)
Solid fills Compact filled areas (■ ▲ ◆, coloured-in regions) become an inset outline plus hatch strokes instead of a meaningless skeleton
Curves Arc-length resampling, Gaussian smoothing per corner-free piece, Schneider least-squares cubic Bézier fitting within a pixel tolerance
Paper furniture The sheet is found and everything around it is ignored (desk, mouse, cables). Printed ruled lines and margin lines are removed while writing that touches them is kept, a spiral binding is recognised from its regular ring pitch, and punched holes, edge shadows and faint printed residue are dropped OpenCV
Layout Strokes in PDF points on a page matching the image aspect (or A4/Letter/A5, or physical size from DPI). PDFs keep their page size
Write .goodnotes ZIP: protobuf records, LZ4-compressed TPL stroke geometry, event log, paper templates. The file is read back and checked after writing gnnote

GoodNotes' flat pen has one width per stroke, so per-point pressure is not representable. Width is measured per pen, and per stroke with --variable-width.

Usage

# combine several inputs into one notebook (one page per image / PDF page)
goodnotes-digitize a.jpg b.png c.heic scan.pdf -o lecture.goodnotes --title "Lecture 4"

# one notebook per input, written to a folder
goodnotes-digitize photos/ --separate -o out/

# check the result: SVG + side-by-side PNG (source | reconstruction) per page
goodnotes-digitize page.jpg -o page.goodnotes --preview preview/

# notebook paper: remove ruled/grid lines; everything in black; fit onto A4 with margins
goodnotes-digitize page.jpg --remove-lines --colors black --page a4 --margin 30

# summarise any .goodnotes file
goodnotes-digitize inspect page.goodnotes

Each converted page reports its stroke count, ink coverage and precision (re-rendered strokes vs. detected ink), pen width in pt, and the detected pens.

Useful options (see goodnotes-digitize convert --help for all):

Option Default Meaning
--page auto|image|a4|letter|a5 auto page size; auto = width --page-width (A4 width), height from the image aspect
--perspective auto|on|off auto flatten a photographed sheet
--background auto|local|flat|none auto shadow / uneven-light correction
--remove-lines auto|on|off auto remove printed ruled / margin lines (auto: when ruled paper is detected)
--keep-binding off keep marks a detected spiral binding would otherwise drop
--colors auto|N|mono|black auto pen detection
--per-stroke-color off colour each stroke individually
--threshold 0-1 auto ink-strength threshold
--tolerance PX 0.8 Bézier fit tolerance (smaller = more faithful, more nodes)
--smoothing 1.0 centre-line smoothing (0 = off)
--width-scale 1.0 thicker / thinner strokes
--variable-width off keep each stroke's own measured width
--no-fills off don't hatch solid areas
--keep-original off also put the cleaned photo under the ink, as a reference image
--pdf-mode auto|raster|vector auto copy vector ink from PDFs when present

Examples and tests

examples/ holds synthetic inputs (a clean drawing, the same sheet "photographed" in perspective with uneven light as JPG and HEIC, a scanned PDF, and a vector-ink PDF), plus demo.goodnotes generated from them and preview/ comparisons. Regenerate them with python tests/synth.py examples.

The project page lives in docs/ (static HTML, served by GitHub Pages). Its figures come from a real run of the converter: .venv/bin/python tools/site_assets.py regenerates them.

.venv/bin/pip install pytest && .venv/bin/python -m pytest

The tests check centre lines against ground truth (median error ≈ 0.3 px), plus corners, crossings, T-junctions, pen colours and widths, perspective correction, exact vector-PDF import, every input format, and a write → read-back round trip of the .goodnotes file.

Limitations

  • Strokes are recovered from shape, not from time. Stroke direction and order are heuristic (reading order, left-to-right), and where two strokes touch or cross, the tracer decides by tangent continuity which pieces belong together.
  • Very small, dense writing (letters only a few pen widths tall) can merge into clumps. Higher resolution photos help a lot.
  • Pencil texture and heavily shaded areas come out as many short strokes.
  • On ruled paper, pen marks as faint as the printed lines (very light bullets "–") can be removed with the lines, and a few short leftover dashes can remain in blank areas.
  • Pressure-varying width is reduced to one width per stroke (a GoodNotes format constraint).
  • The .goodnotes writer is a clean-room implementation (gnnote). GoodNotes may change its format, and the files are written in the GoodNotes 5/6 schema-24 shape that gnnote documents.

Credits

  • gnnote / notability-goodnotes (MIT): GoodNotes container writer and reader.
  • Approaches drawn from AutoTrace (centre-line tracing), skan / scikit-image (skeleton graphs), Handwriting2Ink (photo → ink), Schneider's Graphics Gems curve fitter, and parser-for-goodnotes (used to cross-check the output).

License

MIT. See LICENSE.

About

Turn photos and scans of handwriting (PNG, JPG, HEIC, PDF) into native .goodnotes notebooks with editable pen strokes, not flattened images. Keeps stroke shape, width, colour and page layout.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages