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.goodnotesThen import notes.goodnotes in GoodNotes (Files / AirDrop → Open in GoodNotes, or
Import inside the app).
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.
goodnotes-digitize-gui # or: goodnotes-digitize gui [files…]To convert in the window:
- Add photos, scans, PDFs or whole folders.
- Choose one combined notebook or one per file, and where to save it.
- Set the common options: page size, ruled-line removal, ink colours, photo flattening, lighting, fills, highlighters, and more under Advanced.
- 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.
| 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.
# 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.goodnotesEach 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/ 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 pytestThe 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.
- 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
.goodnoteswriter 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.
- 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).
MIT. See LICENSE.