Esa Kataja
46ae7e813a
The handoff was written as a message to relay information; several decisions lived only there. Split into permanent homes: - docs/spec.md — scope, geometry model, pipeline order, detection, levels, editor, project file, markers, bundle format, noteman's changes, reference values - ADR 0002 — raster only in release 1; SVG slices measured at 40x WebP naive, 2.6x with a bounding-box cull, deferred on risk not size - ADR 0003 — lossless WebP with levels and 16-level alpha; every lossy option and alternative format measured larger for line art - ADR 0004 — detection proposes, the human disposes; no unattended mode - ADR 0005 — PyMuPDF for all PDF access, accepting AGPL - ADR 0006 — systems are found by vertical brackets, not row-darkness gaps, which miscount every page of a 6-voice score Also from testing against the hardest score in the repertoire: scanned PDFs carry their scan as an embedded image and must be extracted at native resolution rather than re-rendered at 600 DPI, and per-page deskew is mandatory (skew varies -2.6 to +1.2 within one PDF).
62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
# noteman-slicer
|
||
|
||
Turns a score PDF into the ordered slice images [noteman](../noteman) consumes,
|
||
plus the navigation markers that sit on them.
|
||
|
||
A slice is one *system* — one full line of music across all voices, typically
|
||
4–12 bars with lyrics intact. noteman displays them as a continuous vertical
|
||
scroll, so the slicer's job is to cut a printed page into systems, clean them up
|
||
enough to read on a tablet, and tag them with the score's navigation symbols.
|
||
|
||
**Status: design only.** No code yet. The design is settled; see below.
|
||
|
||
## How it works
|
||
|
||
Open a PDF, and the tool proposes cuts between systems, a skew correction, and a
|
||
content rectangle. You correct all of it — source quality varies too much for
|
||
unattended processing, so detection is an accelerator that nothing depends on
|
||
being right. You mark the header and footer regions discarded, set black and
|
||
white points until the paper disappears and the notes go solid, place the
|
||
rehearsal letters and jump markers, fill in the title block, and export.
|
||
|
||
Out comes one zip: the slices in order, their markers, the original PDF, and the
|
||
song metadata. That bundle is the only channel to noteman — there's no API
|
||
between the two tools.
|
||
|
||
Erasing previous-owner pencil marks, chord letters and breath marks stays in
|
||
GIMP. That's the irreducible manual part, and GIMP with a stylus is already good
|
||
at it.
|
||
|
||
## Installation
|
||
|
||
Not yet installable. When it is:
|
||
|
||
```
|
||
uv tool install --editable .
|
||
```
|
||
|
||
That puts a `noteman-slicer` command on PATH which runs from any directory — no venv to
|
||
activate. Dependencies (PyMuPDF, PySide6, OpenCV, numpy) are all wheels; nothing
|
||
needs a system package.
|
||
|
||
## Documentation
|
||
|
||
| | |
|
||
|---|---|
|
||
| [CONTEXT.md](CONTEXT.md) | Glossary. What a slice, cut, discard, bundle and song scale actually mean here. Start here. |
|
||
| [docs/spec.md](docs/spec.md) | The specification: pipeline, geometry model, detection, editor, bundle format, and what noteman has to change. |
|
||
|
||
Deferred work is tracked as issues and milestones on the Gitea repo, not in this
|
||
tree.
|
||
|
||
Decisions that were expensive to reach, each with the evidence behind it:
|
||
|
||
| | |
|
||
|---|---|
|
||
| [ADR 0001](docs/adr/0001-slicer-owns-image-processing-bundle-is-the-only-channel.md) | The slicer owns all image processing; the bundle is the only channel to noteman. |
|
||
| [ADR 0002](docs/adr/0002-raster-only-svg-renderer-deferred.md) | Raster only in release 1 — measured SVG slice sizes and what they showed. |
|
||
| [ADR 0003](docs/adr/0003-lossless-webp-with-levels-and-alpha-quantisation.md) | Lossless WebP beats every lossy option and every alternative format here. |
|
||
| [ADR 0004](docs/adr/0004-detection-proposes-the-human-disposes.md) | No unattended mode: detection suggests, a human confirms. |
|
||
| [ADR 0005](docs/adr/0005-pymupdf-for-all-pdf-access.md) | PyMuPDF for all PDF access, accepting AGPL. |
|
||
| [ADR 0006](docs/adr/0006-systems-are-found-by-brackets-not-row-gaps.md) | Systems are found by vertical brackets; row-darkness gaps get it wrong. |
|